create-pmos 0.30.1 → 0.31.1

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/payload/scripts/workflow-state.js

@@ -333,6 +333,7 @@ function firstAppearance(root, range, rel) {
 function buildCommits(root, range, lane, opts) {
   if (!range.ok) return { unknown: true };
   const id = opts && opts.id;
+  const recordIdx = opts && opts.recordIdx;
   const whole = !!range.wholeHistory;
 
   // Over the trunk, the id must be attributable before any commit counts. The index is built once
@@ -373,6 +374,19 @@ function buildCommits(root, range, lane, opts) {
     // answerable at all. `--name-only` lists no files for a true merge commit, so a branch-attributed
     // initiative is counted from its merge subject below rather than from this per-file loop.
     if (whole && id && !commitNamesId(range, i, id)) continue;
+    /* Inside a PR RANGE the id filter above does not apply, because a pull request was assumed to
+     * carry one initiative and everything in it to be that initiative's build. A branch carrying
+     * several breaks that: PR #287 held five, and the FIRST commit on it — a D01 propagation touching
+     * supabase/functions/mcp/index.ts — was attributed to `sink-discipline-backport`, whose record did
+     * not yet exist. The gate reported ORDER VIOLATION, spec-after-build, for an initiative whose spec
+     * demonstrably preceded its build by three commits.
+     *
+     * A commit made BEFORE an initiative's record first appeared cannot be that initiative's
+     * implementation — the initiative did not exist to be built. That is the whole rule, and it is
+     * narrow on purpose: an implementation commit landing AFTER the record but BEFORE the PRD still
+     * fails, which is the case D13 actually exists to catch. This removes a false violation without
+     * removing a true one. */
+    if (!whole && recordIdx != null && recordIdx !== undefined && recordIdx >= 0 && i < recordIdx) continue;
     count++;
     if (first === null) { first = i; sample = hit; }
   }
@@ -574,6 +588,9 @@ function computeWorkflow(id, opts) {
   const prdIdx = prd ? firstAppearance(root, range, prd) : null;
   const build = buildCommits(root, range, effLane, {
     id,
+    // Where this initiative's own record first appears in the range — the earliest commit that could
+    // possibly be its build. See the note in buildCommits' attribution loop.
+    recordIdx: firstAppearance(root, range, recRel),
     deliveryIndex: opts && opts.deliveryIndex,
     declaredDelivery: fm.delivered_by,
   });
@@ -945,6 +962,50 @@ function computeWorkflow(id, opts) {
     }
   }
 
+  /* ── outcome ─ D57: did the bet pay off? A SECOND verdict, at a second time ───────────────────
+   *
+   * This rung did not exist, and its absence is why the loop never ran: `outcome_metric` is optional
+   * in D57, nothing ever asked for it, and 0 of ~170 records declared one. An optional field with no
+   * prompt and no surface is a field that does not exist.
+   *
+   * `na` is a first-class, non-failing state on purpose. Most work is not a bet, and a rung that
+   * renders red for every initiative without a metric becomes noise and gets ignored — which is how
+   * you end up with a board nobody reads. */
+  {
+    const metric = String(fm.outcome_metric || '').trim();
+    const horizon = String(fm.outcome_horizon || '').trim();
+    const checks = readJsonl(path.join(L.runsDir, 'outcome_checks.jsonl'))
+      .filter((c) => c && c.initiative_id === id && ['validated', 'refuted', 'inconclusive'].includes(c.disposition));
+    const latest = checks.length ? checks[checks.length - 1] : null;
+    const today = new Date().toISOString().slice(0, 10);
+
+    if (!metric) {
+      steps.push(step('outcome', 'outcome', 'na', 'no outcome declared — most work is not a bet (D57)'));
+    } else if (!horizon) {
+      /* A metric with no horizon can never come due, so it reads as diligence for ever while
+       * committing to nothing. That is worse than declaring nothing at all. */
+      steps.push(step('outcome', 'outcome', 'blocked',
+        `outcome_metric declared with NO outcome_horizon — a bet that can never come due`,
+        'add outcome_horizon: YYYY-MM-DD to the initiative record, or remove the metric', { rule: 'D57' }));
+    } else if (latest) {
+      /* A refuted bet is a COMPLETED check and an UNSUCCESSFUL bet. The rung says both — rendering
+       * it as a plain green tick is the same watermelon the review rung was fixed for. */
+      const done = latest.disposition === 'refuted' ? 'blocked' : 'done';
+      steps.push(step('outcome', 'outcome', done,
+        `${latest.disposition}${latest.evidence ? ` — ${String(latest.evidence).slice(0, 60)}` : ''}`,
+        latest.disposition === 'refuted'
+          ? 'the check is complete and the bet did not pay off — that is a result, not a failure to record'
+          : undefined));
+    } else if (horizon <= today) {
+      steps.push(step('outcome', 'outcome', 'blocked',
+        `outcome check DUE — horizon ${horizon} has passed and no disposition is recorded`,
+        'dispose it: node scripts/record-outcome.js (validated | refuted | inconclusive, evidence required)',
+        { rule: 'D57' }));
+    } else {
+      steps.push(step('outcome', 'outcome', 'pending', `outcome pending — horizon ${horizon}`));
+    }
+  }
+
   // ── stage, derived from what the steps found ─────────────────────────────────────────────────
   const by = Object.fromEntries(steps.map((s) => [s.key, s]));
   let stage = 'intake';

package/workspace/lib/engine/workflow-state.js

@@ -333,6 +333,7 @@ function firstAppearance(root, range, rel) {
 function buildCommits(root, range, lane, opts) {
   if (!range.ok) return { unknown: true };
   const id = opts && opts.id;
+  const recordIdx = opts && opts.recordIdx;
   const whole = !!range.wholeHistory;
 
   // Over the trunk, the id must be attributable before any commit counts. The index is built once
@@ -373,6 +374,19 @@ function buildCommits(root, range, lane, opts) {
     // answerable at all. `--name-only` lists no files for a true merge commit, so a branch-attributed
     // initiative is counted from its merge subject below rather than from this per-file loop.
     if (whole && id && !commitNamesId(range, i, id)) continue;
+    /* Inside a PR RANGE the id filter above does not apply, because a pull request was assumed to
+     * carry one initiative and everything in it to be that initiative's build. A branch carrying
+     * several breaks that: PR #287 held five, and the FIRST commit on it — a D01 propagation touching
+     * supabase/functions/mcp/index.ts — was attributed to `sink-discipline-backport`, whose record did
+     * not yet exist. The gate reported ORDER VIOLATION, spec-after-build, for an initiative whose spec
+     * demonstrably preceded its build by three commits.
+     *
+     * A commit made BEFORE an initiative's record first appeared cannot be that initiative's
+     * implementation — the initiative did not exist to be built. That is the whole rule, and it is
+     * narrow on purpose: an implementation commit landing AFTER the record but BEFORE the PRD still
+     * fails, which is the case D13 actually exists to catch. This removes a false violation without
+     * removing a true one. */
+    if (!whole && recordIdx != null && recordIdx !== undefined && recordIdx >= 0 && i < recordIdx) continue;
     count++;
     if (first === null) { first = i; sample = hit; }
   }
@@ -574,6 +588,9 @@ function computeWorkflow(id, opts) {
   const prdIdx = prd ? firstAppearance(root, range, prd) : null;
   const build = buildCommits(root, range, effLane, {
     id,
+    // Where this initiative's own record first appears in the range — the earliest commit that could
+    // possibly be its build. See the note in buildCommits' attribution loop.
+    recordIdx: firstAppearance(root, range, recRel),
     deliveryIndex: opts && opts.deliveryIndex,
     declaredDelivery: fm.delivered_by,
   });
@@ -945,6 +962,50 @@ function computeWorkflow(id, opts) {
     }
   }
 
+  /* ── outcome ─ D57: did the bet pay off? A SECOND verdict, at a second time ───────────────────
+   *
+   * This rung did not exist, and its absence is why the loop never ran: `outcome_metric` is optional
+   * in D57, nothing ever asked for it, and 0 of ~170 records declared one. An optional field with no
+   * prompt and no surface is a field that does not exist.
+   *
+   * `na` is a first-class, non-failing state on purpose. Most work is not a bet, and a rung that
+   * renders red for every initiative without a metric becomes noise and gets ignored — which is how
+   * you end up with a board nobody reads. */
+  {
+    const metric = String(fm.outcome_metric || '').trim();
+    const horizon = String(fm.outcome_horizon || '').trim();
+    const checks = readJsonl(path.join(L.runsDir, 'outcome_checks.jsonl'))
+      .filter((c) => c && c.initiative_id === id && ['validated', 'refuted', 'inconclusive'].includes(c.disposition));
+    const latest = checks.length ? checks[checks.length - 1] : null;
+    const today = new Date().toISOString().slice(0, 10);
+
+    if (!metric) {
+      steps.push(step('outcome', 'outcome', 'na', 'no outcome declared — most work is not a bet (D57)'));
+    } else if (!horizon) {
+      /* A metric with no horizon can never come due, so it reads as diligence for ever while
+       * committing to nothing. That is worse than declaring nothing at all. */
+      steps.push(step('outcome', 'outcome', 'blocked',
+        `outcome_metric declared with NO outcome_horizon — a bet that can never come due`,
+        'add outcome_horizon: YYYY-MM-DD to the initiative record, or remove the metric', { rule: 'D57' }));
+    } else if (latest) {
+      /* A refuted bet is a COMPLETED check and an UNSUCCESSFUL bet. The rung says both — rendering
+       * it as a plain green tick is the same watermelon the review rung was fixed for. */
+      const done = latest.disposition === 'refuted' ? 'blocked' : 'done';
+      steps.push(step('outcome', 'outcome', done,
+        `${latest.disposition}${latest.evidence ? ` — ${String(latest.evidence).slice(0, 60)}` : ''}`,
+        latest.disposition === 'refuted'
+          ? 'the check is complete and the bet did not pay off — that is a result, not a failure to record'
+          : undefined));
+    } else if (horizon <= today) {
+      steps.push(step('outcome', 'outcome', 'blocked',
+        `outcome check DUE — horizon ${horizon} has passed and no disposition is recorded`,
+        'dispose it: node scripts/record-outcome.js (validated | refuted | inconclusive, evidence required)',
+        { rule: 'D57' }));
+    } else {
+      steps.push(step('outcome', 'outcome', 'pending', `outcome pending — horizon ${horizon}`));
+    }
+  }
+
   // ── stage, derived from what the steps found ─────────────────────────────────────────────────
   const by = Object.fromEntries(steps.map((s) => [s.key, s]));
   let stage = 'intake';

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 };
+});

package/workspace/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pmos-workspace",
-  "version": "0.30.1",
+  "version": "0.31.1",
   "private": true,
   "description": "PMOS Terminal Workspace \u2014 local companion hosting real PTYs beside the library and gates (D62)",
   "license": "MIT",

package/workspace/public/index.html

@@ -53,6 +53,10 @@
      opinion about what an .html file is would mean the endpoint and the pane disagreeing about the
      same document. Classic script (a UMD), like the three above. -->
 <script src="/lib/preview-kind.js"></script>
+<!-- The newline normalizer behind the doc tab's `normalize` action (markdown-newlines). The same
+     file scripts/md-newlines.js requires, loaded here as window.MdNormalize, so the one-click
+     repair and the CI ratchet can never disagree about what a normalized document is. -->
+<script src="/lib/md-normalize.js"></script>
 <link rel="preload" href="/vendor/ibm-plex-mono-500.woff2" as="font" type="font/woff2" crossorigin />
 </head>
 <body>