create-pmos 0.31.0 → 0.32.0

package/payload/scripts/md-normalize.js

@@ -0,0 +1,223 @@
+/* md-normalize — a newline in a PMOS document means what it says.
+ *
+ * ONE implementation, used on three sides, in the idiom `preview-kind.js` established for exactly
+ * this reason:
+ *   - scripts/md-newlines.js requires it (the check, the --fix, the CI ratchet)
+ *   - workspace/server.js requires it (the doc tab's `normalize` action)
+ *   - the browser loads it as /lib/md-normalize.js (window.MdNormalize)
+ * so the command, the gate and the button can never disagree about what a normalized file is.
+ *
+ * ── WHAT IT IS FOR ─────────────────────────────────────────────────────────────────────────────
+ * PMOS hard-wraps prose at ~100 columns: 30,345 continuation lines across 1,013 of 1,022 tracked
+ * files. A single newline inside a paragraph is NOT a line break in markdown — CommonMark joins the
+ * lines, GitHub joins them, the workspace's own renderer joins them — so this looks right everywhere
+ * inside PMOS. It stops looking right the moment a file is published: Jira wiki markup treats a
+ * newline as a line break, a Google Doc keeps every newline, and several markdown→ADF converters
+ * emit a hard break per `\n`. The paragraph arrives as a stack of ragged short lines, and no
+ * converter can undo it, because an accidental wrap and a deliberate break are THE SAME BYTE in the
+ * source. The only place the distinction still exists is the file.
+ *
+ * ── WHAT IT REFUSES TO TOUCH ───────────────────────────────────────────────────────────────────
+ * Frontmatter, fenced code (including unterminated), indented code, table rows, headings, rules,
+ * link-reference definitions, HTML blocks, a line ending in two spaces or a backslash (a DELIBERATE
+ * hard break — an author's intent, not a wrap), and a line followed by a setext underline. Joining
+ * inside any of those changes what the document MEANS rather than how it wraps, and a repair tool
+ * that damages a file is worse than the defect it repairs.
+ *
+ * ── THE CORRECTNESS PROPERTY ───────────────────────────────────────────────────────────────────
+ * Idempotence: normalize(normalize(x)) === normalize(x), asserted over all 1,022 tracked files
+ * rather than over fixtures. The ratchet, the button and an adopter's repair run are all
+ * untrustworthy without it.
+ */
+'use strict';
+(function (root, factory) {
+  const api = factory();
+  if (typeof module !== 'undefined' && module.exports) module.exports = api;
+  else root.MdNormalize = api;
+})(typeof self !== 'undefined' ? self : this, function () {
+  const FENCE = /^(\s*)(`{3,}|~{3,})/;
+  const HEADING = /^\s{0,3}#{1,6}(\s|$)/;
+  const RULE = /^\s{0,3}(?:-{3,}|\*{3,}|_{3,})\s*$/;
+  const ITEM = /^(\s*)([-*+]|\d{1,9}[.)])(\s+)(\S.*)$/;
+  const QUOTE = /^(\s{0,3}>\s?)(.*)$/;
+  const TABLE_DELIM = /^\s*\|?[\s:|-]*-[\s:|-]*\|?\s*$/;
+  const SETEXT = /^\s{0,3}(=+|-+)\s*$/;
+  const REF_DEF = /^\s{0,3}\[[^\]]+\]:\s/;
+  const HTML_BLOCK = /^\s{0,3}<[a-zA-Z!/?]/;
+  const INDENTED_CODE = /^(?: {4,}|\t)\S/;
+  /* A break the AUTHOR asked for. Markdown spells it two trailing spaces or a trailing backslash,
+   * and it is the one newline in a paragraph that is not an accident — eating it would be removing
+   * intent, which is the failure this tool exists to avoid, not to commit. */
+  const HARD_BREAK = /(?: {2,}|\\)$/;
+
+  const isBlank = (l) => !l.trim();
+
+  /** A table's header row: this line has a pipe and the NEXT line is the delimiter. */
+  const isTableHeader = (lines, i) =>
+    lines[i].includes('|') && TABLE_DELIM.test(lines[i + 1] || '') && (lines[i + 1] || '').includes('-');
+
+  /** A row inside a table body — a pipe line in a run that began with a header. */
+  function tableRunEnd(lines, i) {
+    let j = i + 2;
+    while (j < lines.length && lines[j].includes('|') && lines[j].trim()) j++;
+    return j;
+  }
+
+  /**
+   * A line that can never be joined ONTO the previous one — it opens a block of its own. This is
+   * the list the blank-line rule is derived from too, so "what needs a blank line above it" and
+   * "what stops a paragraph" cannot drift apart.
+   */
+  function opensBlock(lines, i) {
+    const l = lines[i];
+    return HEADING.test(l) || RULE.test(l) || FENCE.test(l) || ITEM.test(l) || QUOTE.test(l)
+      || REF_DEF.test(l) || HTML_BLOCK.test(l) || INDENTED_CODE.test(l) || isTableHeader(lines, i)
+      || SETEXT.test(l);
+  }
+
+  /**
+   * Normalize `src`.
+   *
+   * Returns `{ text, changed, joins, blanks }` — the bytes, whether anything moved, how many lines
+   * were joined into a paragraph or an item, and how many blank lines were inserted above a block.
+   * The counts are what the CLI reports per file: a tool that says "changed" without saying what it
+   * changed is asking to be trusted rather than read.
+   */
+  function normalize(src) {
+    const input = String(src == null ? '' : src);
+    const nl = input.indexOf('\r\n') >= 0 ? '\r\n' : '\n';
+    const lines = input.replace(/\r\n?/g, '\n').split('\n');
+    const out = [];
+    let joins = 0;
+    let blanks = 0;
+    let i = 0;
+
+    // ── frontmatter: copied through, never parsed and never joined ──────────────────────────────
+    if (lines[0] === '---') {
+      let j = 1;
+      while (j < lines.length && lines[j] !== '---') j++;
+      if (j < lines.length) { for (let k = 0; k <= j; k++) out.push(lines[k]); i = j + 1; }
+    }
+
+    /* A continuation line, left-trimmed. Trailing whitespace is dropped ONLY when it is not a hard
+     * break: `.trim()` would eat the author's two trailing spaces mid-paragraph, which is the one
+     * newline in a paragraph that was asked for. */
+    const piece = (l) => {
+      const s2 = l.replace(/^\s+/, '');
+      return HARD_BREAK.test(s2) ? s2 : s2.replace(/\s+$/, '');
+    };
+
+    /** The blank line a block construct needs above it, when prose is what sits there. */
+    const blankAbove = () => {
+      const prev = out.length ? out[out.length - 1] : '';
+      if (!out.length || isBlank(prev)) return;
+      // Only prose gets a blank inserted after it. Two adjacent list items, a table row under its
+      // header, a fence closing — none of those want one, and inserting it would restructure the
+      // document rather than repair its wrapping.
+      if (ITEM.test(prev) || QUOTE.test(prev) || prev.includes('|') || HEADING.test(prev)) return;
+      out.push('');
+      blanks++;
+    };
+
+    while (i < lines.length) {
+      const line = lines[i];
+
+      if (isBlank(line)) { out.push(line); i++; continue; }
+
+      // fenced code — verbatim, to the closing fence or to EOF
+      const fence = FENCE.exec(line);
+      if (fence) {
+        blankAbove();
+        const close = new RegExp('^\\s*' + fence[2][0] + '{' + fence[2].length + ',}\\s*$');
+        out.push(line); i++;
+        while (i < lines.length && !close.test(lines[i])) { out.push(lines[i]); i++; }
+        if (i < lines.length) { out.push(lines[i]); i++; }
+        continue;
+      }
+
+      // indented code, headings, rules, reference definitions, HTML — one line, untouched
+      if (INDENTED_CODE.test(line) || HEADING.test(line) || RULE.test(line) || REF_DEF.test(line)
+        || HTML_BLOCK.test(line) || SETEXT.test(line)) {
+        /* A blank is NEVER inserted above a `---`/`===` line. Directly under prose that is a SETEXT
+         * HEADING, not a rule, and separating it would turn one heading into a paragraph and a
+         * horizontal rule — the untouchable rule wins over the blank-line rule wherever they meet. */
+        if (HEADING.test(line)) blankAbove();
+        out.push(line); i++;
+        continue;
+      }
+
+      // a table: its header, its delimiter and its rows are records — never joined, never reflowed
+      if (isTableHeader(lines, i)) {
+        blankAbove();
+        const end = tableRunEnd(lines, i);
+        for (let k = i; k < end; k++) out.push(lines[k]);
+        i = end;
+        continue;
+      }
+
+      // a list item, plus the continuation lines that belong to it
+      const item = ITEM.exec(line);
+      if (item) {
+        blankAbove();
+        /* INSIDE a list item, four spaces is not code — it is the item's own text column. The
+         * generic `opensBlock` test calls an indented continuation an indented code block and stops,
+         * which left every nested item's wrapped line un-joined. Code inside an item starts four
+         * columns further in than the item's CONTENT does, so that is the line this measures. */
+        const contentCol = item[1].length + item[2].length + item[3].length;
+        const isItemCode = (l) => (l.match(/^[ \t]*/)[0].replace(/\t/g, '    ').length) >= contentCol + 4;
+        let body = line;
+        i++;
+        while (i < lines.length && !isBlank(lines[i]) && !HARD_BREAK.test(body)
+          && /^\s+\S/.test(lines[i]) && !isItemCode(lines[i])
+          && !(HEADING.test(lines[i]) || RULE.test(lines[i]) || FENCE.test(lines[i])
+            || ITEM.test(lines[i]) || QUOTE.test(lines[i]) || isTableHeader(lines, i))) {
+          body += ' ' + piece(lines[i]);
+          joins++; i++;
+        }
+        out.push(body);
+        continue;
+      }
+
+      // a blockquote line, plus its lazy continuations
+      const quote = QUOTE.exec(line);
+      if (quote) {
+        /* A `>` with nothing after it is the blank line INSIDE a quote — it is what separates two
+         * quoted paragraphs. Joining the next paragraph onto it deletes the separator, silently
+         * turns two paragraphs into one, and (because the result then joins again on the next run)
+         * is how this tool would fail its own idempotence property. Found by running the proof over
+         * the real corpus rather than over fixtures: 50 files did exactly this. */
+        if (!quote[2].trim()) { out.push(line); i++; continue; }
+        let body = line;
+        i++;
+        while (i < lines.length && !isBlank(lines[i]) && !HARD_BREAK.test(body)) {
+          const q = QUOTE.exec(lines[i]);
+          const inner = q ? q[2] : lines[i];
+          if (!inner.trim()) break;                                     // a blank quote line ends it
+          if (q && (HEADING.test(inner) || ITEM.test(inner) || RULE.test(inner) || FENCE.test(inner))) break;
+          if (!q && opensBlock(lines, i)) break;                        // lazy continuation, but not a new block
+          body += ' ' + piece(inner);
+          joins++; i++;
+        }
+        out.push(body);
+        continue;
+      }
+
+      // prose — the case the whole tool is about
+      let para = line;
+      i++;
+      while (i < lines.length && !isBlank(lines[i]) && !opensBlock(lines, i) && !HARD_BREAK.test(para)) {
+        para += ' ' + piece(lines[i]);
+        joins++; i++;
+      }
+      out.push(para);
+    }
+
+    const text = out.join(nl);
+    return { text, changed: text !== input, joins, blanks };
+  }
+
+  /** True when the file is already normalized — the check half, with no allocation of a new string. */
+  const isNormalized = (src) => !normalize(src).changed;
+
+  return { normalize, isNormalized };
+});

package/workspace/lib/drive-guard.js

@@ -61,6 +61,7 @@
  * something does adopt it, it will not adopt seven bypasses with it.
  */
 
+const fs = require('fs');
 const path = require('path');
 
 class ForbiddenWrite extends Error {
@@ -117,29 +118,69 @@ const ALLOWED_DIR_PREFIXES = Object.freeze([
 const ALLOWED_FILES = Object.freeze([
   'planning/runs/agent-runs.jsonl',
   'planning/runs/verify-queue.jsonl',
-  'planning/runs/work-items.jsonl',
+  /* `planning/work-items.jsonl`, NOT `planning/runs/work-items.jsonl`. The latter was allowlisted
+   * here for weeks and has never existed — scripts/work-item.js records that directly. An allowlist
+   * entry for a path that does not exist permits nothing and protects nothing; what it does is make
+   * the list look like it covers the factory's ledger when it does not. Found by an independent pass
+   * comparing this list against pmos/graph-membership.json, which is the whole argument for the
+   * derivation below: two enumerations of the same thing disagree, and nothing notices. */
+  'planning/work-items.jsonl',
   'discoveries.md',
 ]);
 
 /** Kept for the refusal message only — never for deciding permission. */
 const ALLOWED_BASENAMES = Object.freeze(ALLOWED_FILES.map((f) => path.posix.basename(f)));
 
-/** Named explicitly so the refusal says WHY, rather than "not on the allowlist". Each of these
- *  would otherwise be caught by the allowlist anyway — the value here is the message. */
-const HUMAN_DECISION_SINKS = Object.freeze({
-  // The module argues that a DIRECTORY prefix "would admit the FOURTH ledger somebody adds next year
-  // without anyone deciding to — exactly the class-failure this rewrite exists to close" — and then
-  // allows `planning/evals/` as a prefix, which admits the PM's own override log and any future
-  // planning/evals/*.jsonl. The argument is right; it just was not applied to its own second
-  // directory. These two are the PM's calibration record, not the driver's scratch space.
-  'eval-calibration.md': 'the PM\'s log of every override of an evaluator verdict is the PM\'s (D40)',
-  'calibration-status.md': 'the declared calibration state is the PM\'s to assert, not the driver\'s',
-  'acceptances.jsonl': 'the Acceptance Gate is the PM\'s and non-delegable (D12)',
-  'evals.jsonl': 'a Review-Gate verdict on the driver\'s own work is self-grading — the driver may not record one (D40)',
-  'outcome_checks.jsonl': 'whether the bet paid off is the PM\'s judgement (D57)',
-  'DECISIONS.md': 'an architectural decision is the PM\'s (D45)',
-  'pm-decisions.md': 'the PM\'s decision journal is the PM\'s',
-});
+/** ── DERIVED FROM THE REGISTRY, NOT RESTATED ────────────────────────────────────────────────────
+ *
+ *  This was an inline map of seven basenames to reasons — a second enumeration of exactly the
+ *  control-graph classification that `pmos/graph-membership.json` holds, with the D-numbers mirrored
+ *  in both. Two copies of a rule are two places for it to be wrong, and these two ALREADY disagreed:
+ *  the allowlist above named a ledger that has never existed while the registry named the real one.
+ *
+ *  So the reasons come from the registry's `why` for every record it classifies `control`. Keyed by
+ *  basename, because that is what the refusal path looks up.
+ *
+ *  FAIL-OPEN IS NOT A RISK HERE, and it is worth saying why rather than trusting it: this map only
+ *  supplies the REASON in a refusal message. Permission is decided by `onAllowlist` below, which
+ *  refuses everything not sanctioned whether or not a reason was found. If the registry is missing —
+ *  a vendored kit, a partial checkout — the write is still refused; the message is just the generic
+ *  one. A guard whose enforcement depended on a file it might not have would be a different and much
+ *  worse design. */
+let REGISTRY_UNAVAILABLE = null;
+function loadHumanDecisionSinks() {
+  const out = {};
+  try {
+    /* TWO LAYOUTS, the same two-path resolution scripts/md-newlines.js uses for its normalizer.
+     *
+     * In a checkout this file is `<repo>/workspace/lib/`, so the registry is two levels up. In an
+     * npm install the workspace app is bundled BESIDE the vendored kit, not inside it, so the
+     * registry — if the adopter has one — is `<install>/pmos/graph-membership.json`. Neither path
+     * is guaranteed, and that is fine: this map only supplies the REASON in a refusal message.
+     * The write is refused either way by `onAllowlist` below. */
+    const tried = [
+      path.join(__dirname, '..', '..', 'pmos', 'graph-membership.json'),   // a checkout
+      path.join(__dirname, '..', '..', '..', 'pmos', 'graph-membership.json'), // beside a vendored kit
+    ];
+    const found = tried.find((f) => { try { return fs.statSync(f).isFile(); } catch { return false; } });
+    if (!found) throw new Error(`no graph-membership.json in: ${tried.join(', ')}`);
+    const raw = fs.readFileSync(found, 'utf8');
+    for (const r of (JSON.parse(raw).records || [])) {
+      if (!r || r.graph !== 'control' || typeof r.path !== 'string' || r.path.endsWith('/')) continue;
+      const base = path.posix.basename(r.path);
+      if (ALLOWED_BASENAMES.includes(base)) continue;   // the driver's own sanctioned ledgers
+      if (!out[base]) out[base] = String(r.why || 'a control-graph record — the PM\'s, not the driver\'s');
+    }
+  } catch (e) {
+    /* RECORDED, not swallowed. The first version caught silently, and a missing `require('fs')` in
+     * this very file turned into an empty map with no signal at all — every reasoned refusal quietly
+     * became the generic one and two suite assertions were the only thing that noticed. A catch that
+     * hides its own cause is how a degradation becomes permanent. */
+    REGISTRY_UNAVAILABLE = e && e.message ? e.message : String(e);
+  }
+  return out;
+}
+const HUMAN_DECISION_SINKS = Object.freeze(loadHumanDecisionSinks());
 
 /** Disposition tokens (D60), widened to the bare verbs bypass 4 slipped through, and anchored so a
  *  status VALUE that begins with one is a disposition while prose mentioning one is not. */
@@ -530,5 +571,6 @@ function guardedWriter(write) {
 
 module.exports = {
   assertWritable, guardedWriter, carriesApproval, carriesDisposition, isDisposition, PROSE_LEAD, ForbiddenWrite,
-  ALLOWED_DIR_PREFIXES, ALLOWED_BASENAMES, HUMAN_DECISION_SINKS, DISPOSITION_RE,
+  ALLOWED_DIR_PREFIXES, ALLOWED_FILES, ALLOWED_BASENAMES, HUMAN_DECISION_SINKS, DISPOSITION_RE,
+  registryUnavailable: () => REGISTRY_UNAVAILABLE,
 };

package/workspace/lib/engine/anchor-resolve.js

@@ -196,8 +196,31 @@ function readBudgets(root) {
  * `index` comes from parseOkrIndex; `budgets` from readBudgets (optional — omit to skip the
  * registry check, which callers that only need the FORM can do).
  */
+/** Strip ONE layer of matching surrounding quotes.
+ *
+ *  `parent_kr` is a YAML scalar, and a value whose prose contains a colon-space MUST be quoted or
+ *  the document does not parse. The flat frontmatter reader hands the value through with its quotes
+ *  intact, so a legitimately-quoted anchor arrived here as `"health:security …` and matched no form.
+ *
+ *  This defect occurred TWICE — `sink-discipline-backport` on 2026-08-04 and
+ *  `separation-invariant-enforcement` on 2026-08-05 — and the first time it was fixed by unquoting
+ *  the one file. That is the wave's own lesson landing on the person who wrote it down: the unit of
+ *  attention was the file, the unit of the defect was the rule. "Do not quote it" is a rule that
+ *  lives in prose and depends on an author remembering; tolerating the quoting is a rule that lives
+ *  in code.
+ *
+ *  Only a MATCHING outer pair, and only one layer: a stray leading quote is still malformed, and
+ *  reporting it as such is the point. */
+function unquote(s) {
+  const t = s.trim();
+  if (t.length >= 2 && ((t[0] === '"' && t[t.length - 1] === '"') || (t[0] === "'" && t[t.length - 1] === "'"))) {
+    return t.slice(1, -1).trim();
+  }
+  return t;
+}
+
 function resolveAnchor(raw, index, budgets) {
-  const original = String(raw == null ? '' : raw).trim();
+  const original = unquote(String(raw == null ? '' : raw).trim());
   const base = { raw: original, kind: 'empty', status: 'empty', objective: null, kr: null, budget: null, period: null, form: null, reason: null };
   if (!original) return Object.assign(base, { reason: 'parent_kr is empty — unanchored work is rejected (D59)' });
 
@@ -269,6 +292,7 @@ function canonical(resolved, fallbackPeriod) {
 }
 
 module.exports = {
+  unquote,
   parseOkrIndex, readBudgets, resolveAnchor, canonical,
   objectiveId, krId, stripCommentary, listOkrFiles,
   ACCEPTED_FORMS,

package/workspace/lib/md-normalize.js

@@ -0,0 +1,223 @@
+/* md-normalize — a newline in a PMOS document means what it says.
+ *
+ * ONE implementation, used on three sides, in the idiom `preview-kind.js` established for exactly
+ * this reason:
+ *   - scripts/md-newlines.js requires it (the check, the --fix, the CI ratchet)
+ *   - workspace/server.js requires it (the doc tab's `normalize` action)
+ *   - the browser loads it as /lib/md-normalize.js (window.MdNormalize)
+ * so the command, the gate and the button can never disagree about what a normalized file is.
+ *
+ * ── WHAT IT IS FOR ─────────────────────────────────────────────────────────────────────────────
+ * PMOS hard-wraps prose at ~100 columns: 30,345 continuation lines across 1,013 of 1,022 tracked
+ * files. A single newline inside a paragraph is NOT a line break in markdown — CommonMark joins the
+ * lines, GitHub joins them, the workspace's own renderer joins them — so this looks right everywhere
+ * inside PMOS. It stops looking right the moment a file is published: Jira wiki markup treats a
+ * newline as a line break, a Google Doc keeps every newline, and several markdown→ADF converters
+ * emit a hard break per `\n`. The paragraph arrives as a stack of ragged short lines, and no
+ * converter can undo it, because an accidental wrap and a deliberate break are THE SAME BYTE in the
+ * source. The only place the distinction still exists is the file.
+ *
+ * ── WHAT IT REFUSES TO TOUCH ───────────────────────────────────────────────────────────────────
+ * Frontmatter, fenced code (including unterminated), indented code, table rows, headings, rules,
+ * link-reference definitions, HTML blocks, a line ending in two spaces or a backslash (a DELIBERATE
+ * hard break — an author's intent, not a wrap), and a line followed by a setext underline. Joining
+ * inside any of those changes what the document MEANS rather than how it wraps, and a repair tool
+ * that damages a file is worse than the defect it repairs.
+ *
+ * ── THE CORRECTNESS PROPERTY ───────────────────────────────────────────────────────────────────
+ * Idempotence: normalize(normalize(x)) === normalize(x), asserted over all 1,022 tracked files
+ * rather than over fixtures. The ratchet, the button and an adopter's repair run are all
+ * untrustworthy without it.
+ */
+'use strict';
+(function (root, factory) {
+  const api = factory();
+  if (typeof module !== 'undefined' && module.exports) module.exports = api;
+  else root.MdNormalize = api;
+})(typeof self !== 'undefined' ? self : this, function () {
+  const FENCE = /^(\s*)(`{3,}|~{3,})/;
+  const HEADING = /^\s{0,3}#{1,6}(\s|$)/;
+  const RULE = /^\s{0,3}(?:-{3,}|\*{3,}|_{3,})\s*$/;
+  const ITEM = /^(\s*)([-*+]|\d{1,9}[.)])(\s+)(\S.*)$/;
+  const QUOTE = /^(\s{0,3}>\s?)(.*)$/;
+  const TABLE_DELIM = /^\s*\|?[\s:|-]*-[\s:|-]*\|?\s*$/;
+  const SETEXT = /^\s{0,3}(=+|-+)\s*$/;
+  const REF_DEF = /^\s{0,3}\[[^\]]+\]:\s/;
+  const HTML_BLOCK = /^\s{0,3}<[a-zA-Z!/?]/;
+  const INDENTED_CODE = /^(?: {4,}|\t)\S/;
+  /* A break the AUTHOR asked for. Markdown spells it two trailing spaces or a trailing backslash,
+   * and it is the one newline in a paragraph that is not an accident — eating it would be removing
+   * intent, which is the failure this tool exists to avoid, not to commit. */
+  const HARD_BREAK = /(?: {2,}|\\)$/;
+
+  const isBlank = (l) => !l.trim();
+
+  /** A table's header row: this line has a pipe and the NEXT line is the delimiter. */
+  const isTableHeader = (lines, i) =>
+    lines[i].includes('|') && TABLE_DELIM.test(lines[i + 1] || '') && (lines[i + 1] || '').includes('-');
+
+  /** A row inside a table body — a pipe line in a run that began with a header. */
+  function tableRunEnd(lines, i) {
+    let j = i + 2;
+    while (j < lines.length && lines[j].includes('|') && lines[j].trim()) j++;
+    return j;
+  }
+
+  /**
+   * A line that can never be joined ONTO the previous one — it opens a block of its own. This is
+   * the list the blank-line rule is derived from too, so "what needs a blank line above it" and
+   * "what stops a paragraph" cannot drift apart.
+   */
+  function opensBlock(lines, i) {
+    const l = lines[i];
+    return HEADING.test(l) || RULE.test(l) || FENCE.test(l) || ITEM.test(l) || QUOTE.test(l)
+      || REF_DEF.test(l) || HTML_BLOCK.test(l) || INDENTED_CODE.test(l) || isTableHeader(lines, i)
+      || SETEXT.test(l);
+  }
+
+  /**
+   * Normalize `src`.
+   *
+   * Returns `{ text, changed, joins, blanks }` — the bytes, whether anything moved, how many lines
+   * were joined into a paragraph or an item, and how many blank lines were inserted above a block.
+   * The counts are what the CLI reports per file: a tool that says "changed" without saying what it
+   * changed is asking to be trusted rather than read.
+   */
+  function normalize(src) {
+    const input = String(src == null ? '' : src);
+    const nl = input.indexOf('\r\n') >= 0 ? '\r\n' : '\n';
+    const lines = input.replace(/\r\n?/g, '\n').split('\n');
+    const out = [];
+    let joins = 0;
+    let blanks = 0;
+    let i = 0;
+
+    // ── frontmatter: copied through, never parsed and never joined ──────────────────────────────
+    if (lines[0] === '---') {
+      let j = 1;
+      while (j < lines.length && lines[j] !== '---') j++;
+      if (j < lines.length) { for (let k = 0; k <= j; k++) out.push(lines[k]); i = j + 1; }
+    }
+
+    /* A continuation line, left-trimmed. Trailing whitespace is dropped ONLY when it is not a hard
+     * break: `.trim()` would eat the author's two trailing spaces mid-paragraph, which is the one
+     * newline in a paragraph that was asked for. */
+    const piece = (l) => {
+      const s2 = l.replace(/^\s+/, '');
+      return HARD_BREAK.test(s2) ? s2 : s2.replace(/\s+$/, '');
+    };
+
+    /** The blank line a block construct needs above it, when prose is what sits there. */
+    const blankAbove = () => {
+      const prev = out.length ? out[out.length - 1] : '';
+      if (!out.length || isBlank(prev)) return;
+      // Only prose gets a blank inserted after it. Two adjacent list items, a table row under its
+      // header, a fence closing — none of those want one, and inserting it would restructure the
+      // document rather than repair its wrapping.
+      if (ITEM.test(prev) || QUOTE.test(prev) || prev.includes('|') || HEADING.test(prev)) return;
+      out.push('');
+      blanks++;
+    };
+
+    while (i < lines.length) {
+      const line = lines[i];
+
+      if (isBlank(line)) { out.push(line); i++; continue; }
+
+      // fenced code — verbatim, to the closing fence or to EOF
+      const fence = FENCE.exec(line);
+      if (fence) {
+        blankAbove();
+        const close = new RegExp('^\\s*' + fence[2][0] + '{' + fence[2].length + ',}\\s*$');
+        out.push(line); i++;
+        while (i < lines.length && !close.test(lines[i])) { out.push(lines[i]); i++; }
+        if (i < lines.length) { out.push(lines[i]); i++; }
+        continue;
+      }
+
+      // indented code, headings, rules, reference definitions, HTML — one line, untouched
+      if (INDENTED_CODE.test(line) || HEADING.test(line) || RULE.test(line) || REF_DEF.test(line)
+        || HTML_BLOCK.test(line) || SETEXT.test(line)) {
+        /* A blank is NEVER inserted above a `---`/`===` line. Directly under prose that is a SETEXT
+         * HEADING, not a rule, and separating it would turn one heading into a paragraph and a
+         * horizontal rule — the untouchable rule wins over the blank-line rule wherever they meet. */
+        if (HEADING.test(line)) blankAbove();
+        out.push(line); i++;
+        continue;
+      }
+
+      // a table: its header, its delimiter and its rows are records — never joined, never reflowed
+      if (isTableHeader(lines, i)) {
+        blankAbove();
+        const end = tableRunEnd(lines, i);
+        for (let k = i; k < end; k++) out.push(lines[k]);
+        i = end;
+        continue;
+      }
+
+      // a list item, plus the continuation lines that belong to it
+      const item = ITEM.exec(line);
+      if (item) {
+        blankAbove();
+        /* INSIDE a list item, four spaces is not code — it is the item's own text column. The
+         * generic `opensBlock` test calls an indented continuation an indented code block and stops,
+         * which left every nested item's wrapped line un-joined. Code inside an item starts four
+         * columns further in than the item's CONTENT does, so that is the line this measures. */
+        const contentCol = item[1].length + item[2].length + item[3].length;
+        const isItemCode = (l) => (l.match(/^[ \t]*/)[0].replace(/\t/g, '    ').length) >= contentCol + 4;
+        let body = line;
+        i++;
+        while (i < lines.length && !isBlank(lines[i]) && !HARD_BREAK.test(body)
+          && /^\s+\S/.test(lines[i]) && !isItemCode(lines[i])
+          && !(HEADING.test(lines[i]) || RULE.test(lines[i]) || FENCE.test(lines[i])
+            || ITEM.test(lines[i]) || QUOTE.test(lines[i]) || isTableHeader(lines, i))) {
+          body += ' ' + piece(lines[i]);
+          joins++; i++;
+        }
+        out.push(body);
+        continue;
+      }
+
+      // a blockquote line, plus its lazy continuations
+      const quote = QUOTE.exec(line);
+      if (quote) {
+        /* A `>` with nothing after it is the blank line INSIDE a quote — it is what separates two
+         * quoted paragraphs. Joining the next paragraph onto it deletes the separator, silently
+         * turns two paragraphs into one, and (because the result then joins again on the next run)
+         * is how this tool would fail its own idempotence property. Found by running the proof over
+         * the real corpus rather than over fixtures: 50 files did exactly this. */
+        if (!quote[2].trim()) { out.push(line); i++; continue; }
+        let body = line;
+        i++;
+        while (i < lines.length && !isBlank(lines[i]) && !HARD_BREAK.test(body)) {
+          const q = QUOTE.exec(lines[i]);
+          const inner = q ? q[2] : lines[i];
+          if (!inner.trim()) break;                                     // a blank quote line ends it
+          if (q && (HEADING.test(inner) || ITEM.test(inner) || RULE.test(inner) || FENCE.test(inner))) break;
+          if (!q && opensBlock(lines, i)) break;                        // lazy continuation, but not a new block
+          body += ' ' + piece(inner);
+          joins++; i++;
+        }
+        out.push(body);
+        continue;
+      }
+
+      // prose — the case the whole tool is about
+      let para = line;
+      i++;
+      while (i < lines.length && !isBlank(lines[i]) && !opensBlock(lines, i) && !HARD_BREAK.test(para)) {
+        para += ' ' + piece(lines[i]);
+        joins++; i++;
+      }
+      out.push(para);
+    }
+
+    const text = out.join(nl);
+    return { text, changed: text !== input, joins, blanks };
+  }
+
+  /** True when the file is already normalized — the check half, with no allocation of a new string. */
+  const isNormalized = (src) => !normalize(src).changed;
+
+  return { normalize, isNormalized };
+});