dflow-sdd-ddd 0.13.0 → 0.15.0

package/lib/doctor-checks.js

@@ -0,0 +1,2654 @@
+// PROPOSAL-058: pure, shippable drift-detection helpers for `dflow doctor`.
+//
+// The dev-only cross-ref resolver (scripts/check-cross-refs.mjs, PROPOSAL-055)
+// is not part of the npm package, so the runtime checks reimplement the narrow
+// subset doctor needs: fence-aware heading extraction, "<file> § Heading"
+// reference extraction with soft-wrap joining, tolerant heading matching, and
+// template-shape comparison. Everything here is I/O-free — callers read the
+// files and pass contents — which keeps the checks unit-testable.
+
+'use strict';
+
+// Machine-readable context lines. Shared with lib/init.js inference so the
+// doctor "machine format" checks can never drift from what inference actually
+// parses: inferGitPolicy / inferAiCommitMarker / inferProseLanguage read
+// _conventions.md; inferTechStackSummary / inferMigrationContext read the
+// `| Tech stack |` / `| Migration / legacy context |` rows of the guide's
+// "## Project Context" table (PROPOSAL-076 — no packaged _overview.md template
+// ever carried those rows).
+const GIT_POLICY_LINE_RE = /Selected Git policy:\s*`([^`]+)`/;
+const AI_COMMIT_MARKER_LINE_RE = /AI commit marker:\s*`([^`]+)`/;
+const PROSE_LANGUAGE_LINE_RE = /Project prose language:\s*`([^`]+)`/;
+// The row values accept Markdown-escaped pipes (`\|`) so a cell like
+// `Node \| Express` is captured whole; parseContextLine unescapes them
+// (PROPOSAL-076 gate G1 — a bare `[^|\n]` capture silently truncated at the
+// escaped pipe while doctor still called the row machine-readable).
+const TECH_STACK_ROW_RE = /\|\s*Tech stack\s*\|\s*((?:\\\||[^|\n])+?)\s*\|/i;
+const MIGRATION_CONTEXT_ROW_RE = /\|\s*Migration \/ legacy context\s*\|\s*((?:\\\||[^|\n])+?)\s*\|/i;
+
+const GIT_POLICY_VALUES = new Set(['gitflow', 'trunk']);
+const AI_COMMIT_MARKER_VALUES = new Set(['none', 'co-authored-by', 'prefix']);
+
+// Trimmed capture of a machine-readable context line, or null when the line is
+// absent or its value is whitespace-only. Inference and the doctor checks must
+// both parse through this helper: a value doctor accepts has to be the exact
+// value configure-agents consumes (e.g. a stray space inside the backticks
+// would otherwise pass doctor's trimmed validation yet miss strict comparisons
+// like buildSubstitutionMap's `gitflow` check downstream).
+function parseContextLine(content, re) {
+  // ⚠ Read only text a reader can see. A commented-out
+  // `<!-- AI commit marker: `prefix` -->` was parsed as though it were the live
+  // setting, so doctor reported the policy satisfied by a line the user had
+  // deliberately switched off — silent pass (`p082-b3-k1`). Callers pass whole
+  // files and single rows alike; a row with no HTML block in it is unchanged.
+  //
+  // ⚠⚠ THE TYPE CHECK IS PART OF THAT FIX, NOT TIDINESS. This function used to
+  // reach `content.match(re)` directly, so a caller handing it `undefined` got a
+  // loud TypeError. Routing through the projection would have swallowed that:
+  // `classifiedVisible` calls `String(content)`, turning `undefined` into the
+  // four-character text "undefined", which matches nothing and returns null —
+  // and null here means "the policy line is absent", a finding about the user's
+  // file caused by a bug in ours. Trading a crash for a silent wrong answer is
+  // the exact direction this module exists to avoid, so the crash is kept.
+  if (typeof content !== 'string') {
+    throw new TypeError(`parseContextLine expects a string, got ${typeof content}`);
+  }
+  const match = visibleTextLines(content).join('\n').match(re);
+  if (!match) return null;
+  // Unescape Markdown-escaped pipes captured by the table-row patterns; the
+  // backtick context lines never contain `\|`, so this is a no-op for them.
+  const value = match[1].replace(/\\\|/g, '|').trim();
+  return value === '' ? null : value;
+}
+
+// CommonMark's line-ending definition, and the reason it is a named constant:
+// every splitter in this file must use the SAME one. `/\r?\n/` handled LF and
+// CRLF but not a lone CR, while the sibling checks in `lib/init.js` match with
+// the `m` flag — and JS's `m` treats a lone `\r` as a line terminator. So a
+// CR-only file was one giant line to this module and a normal file to them, and
+// the two reported different things about it (`p082-b3-g1` finding 3).
+const LINE_SPLIT_RE = /\r\n|\r|\n/;
+
+// A thematic break: three or more `-`, `_` or `*`, optionally separated by
+// spaces or tabs.
+//
+// ⚠ `-` is a thematic break at 3+ and a setext underline at ANY length, so the
+// two roles overlap and callers must not treat this as "is an underline".
+// `=` is NOT here on purpose: a lone `=+` run is not a thematic break at all —
+// at a block start it is ordinary paragraph text, which is exactly the
+// asymmetry the old combined `(=+|-+)` pattern erased.
+//
+// ⚠ WHICH of the two roles wins is not decided here, and that is the shape of
+// the whole rewrite. `classifyLines` decides it from block context, in one
+// place: when a document-level paragraph is open the setext reading wins
+// (CommonMark 4.3); otherwise this one does. Two predicates each answering that
+// question from a line's own shape is what produced this module's defect class.
+//
+// An ATX heading's opening sequence is 1-6 hashes followed by a space or tab.
+// `[ \t]` and NOT `\s`: CommonMark accepts only a space or tab there, while JS
+// `\s` also matches U+00A0, form feed and vertical tab. A line sitting in that
+// gap was neither a paragraph nor a heading, so a following `---` could not
+// close the section and it ran on — silent pass (`p082-b3-g3`, `p082-b3-g4`).
+// U+00A0 is the realistic input: it arrives by copy-paste from a web page or a
+// word processor.
+//
+// ⚠ There is no literal U+00A0 anywhere in this file. The paragraph above used
+// to demonstrate the defect with a real one, which is indistinguishable from a
+// space in a diff and which an editor may silently normalize away.
+// `test/upgrade-drift.mjs` builds these characters with `String.fromCharCode`
+// for precisely that reason, and this file had been ignoring its own advice.
+// `test/upgrade-drift.mjs` now asserts the absence rather than trusting this
+// sentence.
+//
+// ⚠ There is exactly ONE ATX expression in this module now, and that is a
+// deliberate outcome of the debt-12 rewrite. There used to be FOUR — this
+// constant plus a full-line copy inside `headingAt`, `extractHeadings` and
+// `extractH2Headings` — and three separate review rounds found them disagreeing
+// with each other. A shared constant that only two of the four copies read is
+// not a single source of truth.
+const ATX_HEADING_RE = /^ {0,3}(#{1,6})([ \t].*)?$/;
+
+// The `{ level, text }` of an ATX heading line, or null.
+//
+// ⚠ The closing sequence is stripped in a SECOND step rather than by an
+// optional group in the same expression, and that is a correctness fix, not a
+// style preference. The old one-expression form
+// `(?:[ \t]+(.*?))?(?:[ \t]+#+)?[ \t]*$` gave `## #` the text `#`: the lazy
+// capture backtracks into the closing sequence, so the group meant to absorb it
+// never gets the chance. CommonMark says that heading's content is EMPTY. Two
+// steps cannot express the ambiguity, so they simply get it right — while still
+// keeping `## Git Policy#` as the text `Git Policy#`, because the closing
+// sequence must be PRECEDED by whitespace (`p082-b3-g2` finding 2 paid for
+// that, and `test/upgrade-drift.mjs` pins both).
+//
+// An EMPTY heading (`#`, `## `, `## #`) is a real heading and really does end a
+// section, so it is reported as one. `headingResolves` must go on refusing to
+// resolve a reference against it — `''` prefix-matches every reference, which
+// silently satisfied every cross-ref in the guide (`p082-b3-g5` finding 1).
+function parseAtxHeading(line) {
+  const m = line.match(ATX_HEADING_RE);
+  if (!m) return null;
+  const rest = (m[2] || '').replace(/[ \t]+#+[ \t]*$/, '');
+  // Through `stripSpaceTab`, not a second copy of the same expression: this used
+  // to spell the rule inline while the setext branch used `.trim()`, and the two
+  // heading kinds then disagreed about a trailing U+00A0.
+  return { level: m[1].length, text: stripSpaceTab(rest), setext: false };
+}
+
+function isThematicBreak(line) {
+  return /^ {0,3}(-[ \t]*){3,}$/.test(line)
+    || /^ {0,3}(\*[ \t]*){3,}$/.test(line)
+    || /^ {0,3}(_[ \t]*){3,}$/.test(line);
+}
+
+// A fenced-code marker: three or more backticks, or three or more tildes.
+const FENCE_MARKER = '(```+|~~~+)';
+const FENCE_OPEN_RE = new RegExp(`^ {0,3}${FENCE_MARKER}(.*)$`);
+const FENCE_CLOSE_RE = new RegExp(`^ {0,3}${FENCE_MARKER}[ \\t]*$`);
+
+// Blank out fenced code blocks (``` / ~~~) line-by-line so headings and § refs
+// inside examples are never extracted. Line positions are preserved. CommonMark
+// close rules (PROPOSAL-076 gates G4/G6): a block closes only on the same fence
+// character repeated at least the opening length, indented at most three
+// spaces, with nothing but whitespace after — so a three-backtick line inside a
+// four-backtick example, or an info-string line like ```js inside an open
+// fence, is content and does not end the block early.
+//
+// This is the module's ONLY line splitter; everything downstream works on its
+// output, which is what makes `LINE_SPLIT_RE` a single point of control.
+//
+// ⚠ The fence marker is spelled ONCE, in `FENCE_MARKER`. The open and close
+// tests are genuinely different rules — a close must have nothing after it,
+// while an open takes an info string — but they must agree about what a fence
+// LOOKS like, and two literals cannot be relied on to. Same reason as
+// `ATX_HEADING_RE` and `BULLET_MARKER`.
+function blankFencedBlocks(content) {
+  const lines = content.split(LINE_SPLIT_RE);
+  const out = [];
+  let fenceChar = null;
+  let fenceLen = 0;
+  for (const line of lines) {
+    if (fenceChar) {
+      out.push('');
+      const close = line.match(FENCE_CLOSE_RE);
+      if (close && close[1][0] === fenceChar && close[1].length >= fenceLen) {
+        fenceChar = null;
+        fenceLen = 0;
+      }
+      continue;
+    }
+    // CommonMark: at most three SPACES of indent (a tab is four columns, so a
+    // tab-indented fence is indented code, not a fence), and a BACKTICK fence's
+    // info string may not contain a backtick. Accepting either opened a
+    // pseudo-fence that blanked real headings, so a stale section ran on past
+    // its own end - silent pass (`p082-b3-g4` finding 2).
+    const open = line.match(FENCE_OPEN_RE);
+    if (open && open[1][0] === '`' && open[2].includes('`')) {
+      out.push(line);
+      continue;
+    }
+    if (open) {
+      fenceChar = open[1][0];
+      fenceLen = open[1].length;
+      out.push('');
+      continue;
+    }
+    out.push(line);
+  }
+  return out;
+}
+
+// All Markdown heading texts (any level), fence-aware.
+//
+// ⚠ These two used to carry their own full-line ATX expression — two of the four
+// copies that disagreed with each other. They read the classification now, which
+// means three behaviours arrived here for free rather than being argued about
+// one at a time:
+//   - the 0-3 space indent, which was first left out here on the argument that
+//     packaged inputs are generated and never indented, and which measuring
+//     against the reference retired;
+//   - SETEXT headings, which neither of these ever saw. A `§ Heading` reference
+//     to one was reported dangling and a template section written that way
+//     counted as missing — both false positives, both invisible to the pins,
+//     because the pins only ever fed these functions ATX;
+//   - the empty-heading and closing-sequence rules, which now cannot drift from
+//     what the section walker uses, because there is nothing left to drift from.
+function extractHeadings(content) {
+  const lines = blankFencedBlocks(content);
+  return classifyLines(lines).filter((c) => c.heading).map((c) => c.heading.text);
+}
+
+// H2 heading texts only, fence-aware — the section shape of a template.
+// Level 2 covers both `## X` and a `---`-underlined setext heading.
+function extractH2Headings(content) {
+  const lines = blankFencedBlocks(content);
+  return classifyLines(lines).filter((c) => c.heading && c.heading.level === 2).map((c) => c.heading.text);
+}
+
+
+// `<file>.md § Heading` references whose file basename is `targetBasename`.
+// A soft-wrapped heading name is captured by joining the next line; a match
+// anchored beyond the current line is left to that line's own iteration.
+function extractSectionRefs(content, targetBasename) {
+  // ⚠ `visibleTextLines`, not `blankFencedBlocks`: a `<file>.md § Heading`
+  // written inside an HTML comment was reported as a dangling reference, and the
+  // captured heading text carried the trailing `-->` into the message.
+  const lines = visibleTextLines(content);
+  const refs = [];
+  lines.forEach((line, i) => {
+    const firstLen = line.replace(/\s+$/, '').length;
+    const joined = line.replace(/\s+$/, '') + ' ' + (lines[i + 1] || '').replace(/^\s+/, '');
+    for (const m of joined.matchAll(/`?([A-Za-z0-9._/-]+\.md)`?\s*§\s*"?([^."`)\n]+)/g)) {
+      if (m.index > firstLen) continue;
+      const base = m[1].split('/').pop();
+      if (base !== targetBasename) continue;
+      refs.push({ line: i + 1, headingText: m[2].trim() });
+    }
+  });
+  return refs;
+}
+
+// ⚠⚠ `.trim()` HERE IS DELIBERATE, AND IT IS NOT THE `.trim()` DEFECT CLASS.
+// This was briefly "fixed" to `stripSpaceTab` on the reasoning that one rule
+// should have one spelling, and that broke real files — the measurement is in
+// the pins below `normalizeHeading` in `test/upgrade-drift.mjs`. Two different
+// questions were being read as one:
+//
+//   `stripSpaceTab` answers **what the heading text IS** — block structure,
+//   spec-following, deliberately strict, because a U+00A0 is not whitespace to
+//   CommonMark and a section boundary must not move because of one.
+//
+//   `normalizeHeading` answers **whether two heading strings NAME the same
+//   section** — an identity comparison over text a human retyped or pasted. It
+//   is tolerant BY CONSTRUCTION and already does three things CommonMark would
+//   never do: it strips ``, `*` and `_`, and (through `headingKey`) it folds
+//   case. Tightening it to the block-structure rule aligned the wrong function.
+//
+// What tightening it actually did: `## Ceremony Scaling (Project Application)`
+// with a copy-pasted trailing U+00A0 stopped matching the fingerprint, so doctor
+// reported `missing` on a file that carries the rule — and `missingTemplateSections`
+// reported a section absent that was present. Loud, not silent, but wrong, and
+// `CONVENTIONS_FINGERPRINTS` already records this exact false `missing` happening
+// once before, for case rather than for whitespace. Reproduces for U+00A0, form
+// feed, vertical tab, U+2002 and U+FEFF, leading and trailing.
+//
+// ⚠ `extractSectionRefs` also calls `.trim()` on the *reference* side of the
+// `headingResolves` comparison. That is the same rule on both sides, which is
+// the property to keep: tightening one side only is what made `§ Workflow_`
+// stop resolving.
+function normalizeHeading(text) {
+  return text.replace(/[`*_]/g, '').trim();
+}
+
+// Tolerant heading resolution: a reference resolves when it prefix-matches a
+// real heading in either direction (covers soft wraps like "§ Workflow" for
+// "Workflow Transparency" and shorthand references).
+// ⚠ `headingKey`, not `normalizeHeading` — the difference is case folding, and
+// this consumer used to be the odd one out. `CONVENTIONS_FINGERPRINTS` states
+// the rule ("a heading an adopter retyped in different case is the same
+// section") and `conventionsSectionBodies` implemented it, while this function
+// and `missingTemplateSections` did not: `## filling the templates` was found by
+// one and reported missing by the other, from the same document. One normaliser
+// with three consumers, two of which skipped half of it.
+function headingResolves(referenceText, headings) {
+  const want = headingKey(referenceText);
+  if (!want) return true;
+  return headings.some((heading) => {
+    const have = headingKey(heading);
+    // An EMPTY heading resolves nothing. Making empty ATX headings real (so they
+    // close a section, which CommonMark says they do) put `''` into this list,
+    // and `want.startsWith('')` is true for every reference — so one stray `## `
+    // in a guide silently satisfied every `<file> § Heading` cross-reference and
+    // doctor stopped reporting dangling ones (`p082-b3-g5` finding 1). A fix in
+    // one consumer of a shared list has to be checked against the others.
+    if (!have) return false;
+    return have.startsWith(want) || want.startsWith(have);
+  });
+}
+
+// Which of the template's H2 sections are missing from a filled document — the
+// "created from an older template shape" signal.
+function missingTemplateSections(templateContent, documentContent) {
+  // ⚠ `headingKey`, not `normalizeHeading`: same case-folding rule as
+  // `headingResolves` above and `conventionsSectionBodies` below. This one is
+  // user-facing — a case difference here produced doctor's "looks like an older
+  // `_index.md` template shape" on a document that has the section.
+  //
+  // ⚠⚠ A COUNTED multiset, not a `Set`. With a `Set`, a template carrying two
+  // H2s that fold to the same key — `## Filling the Templates` and
+  // `## FILLING THE TEMPLATES` — was fully satisfied by ONE of them appearing in
+  // the document, so a genuinely missing section went unreported. Silent, and it
+  // arrived with the case folding: before folding, the two keys were distinct.
+  // The packaged `_index.md` has no colliding pair today, so this is latent —
+  // which is exactly why it needs to be code and not a comment.
+  const have = new Map();
+  for (const heading of extractH2Headings(documentContent)) {
+    const key = headingKey(heading);
+    have.set(key, (have.get(key) || 0) + 1);
+  }
+  return extractH2Headings(templateContent).filter((heading) => {
+    const key = headingKey(heading);
+    const left = have.get(key) || 0;
+    if (left === 0) return true;
+    have.set(key, left - 1);
+    return false;
+  });
+}
+
+// True when `content` matches `templateContent` up to placeholder substitution:
+// every single-line `{...}` placeholder in the template may match any text.
+// Distinguishes "pristine current starter" from "edited or older starter"
+// without knowing the values init substituted.
+function matchesTemplateWithPlaceholders(content, templateContent) {
+  // Split/join through the module's single line-ending definition rather than
+  // a second hand-rolled CRLF replacement: a lone CR left the template and the
+  // document normalized differently, so a pristine starter compared as edited.
+  const normalize = (s) => String(s).split(LINE_SPLIT_RE).join('\n').replace(/\s+$/, '');
+  const parts = normalize(templateContent).split(/\{[^}\n]*\}/);
+  const pattern = `^${parts.map(escapeRegExp).join('[\\s\\S]*?')}$`;
+  try {
+    return new RegExp(pattern).test(normalize(content));
+  } catch {
+    return false;
+  }
+}
+
+function escapeRegExp(s) {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+// PROPOSAL-078 phase 1: the table-cell formatting convention (P-072) ships
+// as an HTML comment at every template head, so docs seeded before 0.13 —
+// or written from scratch — hold tables with no in-file reminder and tend
+// to grow run-on cell walls. Detection is info-only; doctor never edits
+// user-authored specs. The snippet is matched anywhere in the file (the
+// _index.md template places it mid-file, after its usage comment), and a
+// table counts only outside code fences. The delimiter-row regex accepts
+// any row with an internal pipe (`|---|---|`, `---|---`) plus the
+// single-column form with BOTH outer pipes (`|---|`); a bare `---` is a
+// thematic break / frontmatter fence and never matches — the one shape
+// deliberately missed is a single-column delimiter written without outer
+// pipes, which is indistinguishable from a thematic break anyway (the
+// check is a nudge, not a gate).
+const SPEC_FORMATTING_CONVENTION_SNIPPET = 'Formatting convention: keep table cells concise';
+const TABLE_DELIMITER_ROW_RE = /^ {0,3}(?:\|?[ \t]*:?-{2,}:?[ \t]*(?:\|[ \t]*:?-{2,}:?[ \t]*)+\|?|\|[ \t]*:?-{2,}:?[ \t]*\|)[ \t]*$/;
+
+// ⚠ This asks the classification for a table rather than grepping for a
+// delimiter row, so it now agrees with the section walker about what a table is.
+// The two used to answer differently: a delimiter row with no header line above
+// it counted as a table HERE while the walker treated it as a thematic break or
+// prose. Neither shape occurs in a packaged template — `test/upgrade-drift.mjs`
+// pins the packaged verdicts — but "two places in this file decide the same
+// question with different code" is the defect class, and it does not stop being
+// the defect class because the current inputs happen not to hit it.
+function hasTableWithoutConventionComment(content) {
+  if (String(content).includes(SPEC_FORMATTING_CONVENTION_SNIPPET)) {
+    return false;
+  }
+  const lines = blankFencedBlocks(String(content));
+  return classifyLines(lines).some((c) => c.type === 'table');
+}
+
+// --- PROPOSAL-082 G5 / PROPOSAL-083 §4: `_conventions.md` staleness -----------
+//
+// `_conventions.md` is user-owned. `dflow init` writes it once and neither init
+// nor `configure-agents` ever rewrites it, so a project keeps the shape it was
+// created with forever. Doctor reporting is the ONLY way an adopter learns their
+// copy predates a contract change — which is why this reports and never edits.
+//
+// Every fingerprint is SECTION-LOCAL. A whole-file grep would pass the moment
+// the phrase appeared anywhere in the document, including inside a section the
+// adopter pasted in from somewhere else; the claim being checked is "THIS
+// section carries this rule", so that is what gets read.
+//
+// Three states, and the middle one is the whole point:
+//
+//   missing  — the section is not in the file at all. Reported, never silently
+//              passed: MAINTAINERS § Cross-Model Review (P083 batch 2, g16) —
+//              "a gate that silently accepts absence is worse than no gate: it
+//              reports success". The previous attempt at this check was pulled
+//              for exactly that, because against the then-broken projection it
+//              could only ever report success.
+//   stale    — section present, rule absent. This is the actionable one: the
+//              project's own conventions state something the shipped flows no
+//              longer do.
+//   current  — section present, rule present.
+// Heading detection has to cover more than `^#{1,6} `, because every shape it
+// misses becomes a section that never ends — and an over-running body reports
+// the WRONG section as current, which is the silent-success direction:
+//   - ATX indented 1-3 spaces is still a heading (CommonMark).
+//   - A setext heading (text line + `===` / `---` underline) is a heading, and
+//     missing it let a body run on into every following section. `---` is only
+//     setext when it directly follows a non-blank, non-heading line; otherwise
+//     it is a thematic break, which `_conventions.md` uses.
+// Comparison is case-insensitive: a heading an adopter retyped in different
+// case is the same section, and treating it as absent produced a false
+// `missing` on a file that had the rule.
+// A setext underline may only close a PARAGRAPH (CommonMark 4.3). After a list
+// item, a table row, a blockquote or another heading it is not a heading at all
+// — `- foo` / `---` is a list plus a thematic break. Treating those as headings
+// ended sections early and, worse, made the caller pop a real content line out
+// of the body: a marker sitting on the last list item or table row vanished and
+// the section reported `stale`. That is the same false-warn-on-an-ordinary-edit
+// class the soft-wrap fix removed.
+//
+// ⚠ A `---` directly after a plain paragraph line IS a setext heading, and the
+// section really does end there — that is CommonMark, not a quirk of this
+// parser. An adopter who wants a horizontal rule needs a blank line before it.
+// ---------------------------------------------------------------------------
+// THE BLOCK CLASSIFICATION PASS — PROPOSAL-082/083 debt 12.
+//
+// WHAT THIS REPLACED, AND WHY IT IS NOT A FIFTH PATCH. Five predicates used to
+// live here — `isTableLine`, `closesOwnBlock`, `blockStartIndex`,
+// `isParagraphLine` and `headingAt` — and each re-derived Markdown block
+// structure from one line's shape, using backward scans and mutual recursion in
+// place of the state a block parser keeps. But what a line IS depends on which
+// block it sits inside, which a per-line predicate cannot see, so the five
+// disagreed with one another. Six consecutive review rounds each found one more
+// place where they did, and THREE of those rounds found a disagreement that the
+// previous round's fix had introduced. Every widening of the arbiter's shape set
+// found more: 30 -> 51 -> 57 -> 73 -> 79 shapes, each stage having measured
+// clean at the stage before.
+//
+// So: one forward pass labels every line exactly once, and the former predicates
+// become lookups into that label. CommonMark block parsing IS a forward pass;
+// the backward scans existed only to reconstruct state that had been thrown
+// away. A consequence worth having — the old `isParagraphLine` /
+// `closesOwnBlock` mutual recursion was explicitly NOT linear (its own comment
+// said so, and warned callers off large documents). This is O(lines).
+//
+// ⚠ THE RULE THAT REPLACES "do not add a fifth predicate": exactly one function
+// decides block structure and this is it. Callers read labels. If you find
+// yourself writing a regex against a raw line ANYWHERE else in order to decide
+// what kind of line it is, that is this defect class growing back, and
+// `test/upgrade-drift.mjs`'s class guard is meant to fail on it.
+//
+// ⚠ WHAT THIS DELIBERATELY DOES NOT IMPLEMENT — stated so the gaps are known
+// rather than discovered by the next round:
+//   - HTML block type 7 (a complete tag whose name is not in the type-6 list,
+//     alone on a line). It is the only type that cannot interrupt a paragraph
+//     and recognizing it needs a real tag parser.
+//     `commonmark-differential.mjs` carries a row for it, so the divergence is
+//     MEASURED rather than assumed harmless.
+//   - GFM's rule that a delimiter row must have the same cell count as its
+//     header row. `test/upgrade-drift.mjs` pins `| A |` + `|---|---|` as a
+//     table, which is the looser reading, and tightening it would also move the
+//     P-078 formatting-convention check.
+//   - Nested container CONTENT. A blockquote or list item's interior is not
+//     parsed as its own block sequence. Knowing the document-level block is not
+//     a paragraph is enough for every question this module asks, and
+//     `_conventions.md` is a small hand-written file.
+//   - ⚠⚠ INLINE HTML COMMENTS — the one gap here whose direction is SILENT PASS,
+//     so it is the one that matters. This pass is LINE-level: a line that STARTS
+//     with `<!--` opens an HTML block and its text is correctly treated as unseen
+//     by a reader. A comment that begins part-way through a line is not a block
+//     at all — it is an inline span — and every consumer therefore counts its
+//     contents as live document text. Measured, with controls, on 2026-08-05:
+//
+//       `prose <!-- cascade result is a floor -->`  -> doctor reports `current`
+//       `- item <!-- ... -->` / `> quote <!-- ... -->` -> same
+//       `<!-- a --> <!-- cascade result is a floor -->` -> same (only the FIRST
+//       span is masked; the tail is never re-scanned)
+//
+//     So a rule a user commented out mid-line still reads as present, which is
+//     the exact question `doctor` exists to answer. PRE-EXISTING — it was true
+//     before the visibility rule was added and the rule did not touch it; what
+//     the rule closed was the line-level half.
+//
+//     ⚠ NOT fixed here on purpose (maintainer decision, 2026-08-05). Hiding
+//     spans needs an inline layer in a module that is deliberately line-level,
+//     and the obvious version is WRONG in the content-loss direction: a comment
+//     inside a CODE SPAN — `` `<!-- example -->` `` — is rendered and a reader
+//     DOES see it, so "mask everything between the delimiters" deletes visible
+//     content. That is a span tokenizer, with generated cases, as its own piece
+//     of work — not a fourth patch on a boundary predicate, which is how this
+//     module earned every defect it has. `p082-b3-k4` recommended exactly that.
+//     PROPOSAL-084 carries it as a detectable shape in the meantime: "this file
+//     contains an inline HTML comment" needs none of the boundary logic that
+//     could be wrong, which is what makes it warnable.
+// ---------------------------------------------------------------------------
+
+// HTML blocks (CommonMark 4.6). Types 1-5 pair a start with an end condition and
+// close ON the line matching it — that line belongs to the block. Type 6 closes
+// at the next blank line, which does NOT belong to it.
+//
+// ⚠ Type 2 is the one that forced this rewrite. The old code opened an HTML
+// block on any `<!--` line but only ever closed a SINGLE-LINE `<!-- ... -->`, so
+// a comment spanning two lines never closed: the section walker stopped inside
+// it, dropped the list item that followed, and `findConventionsDrift` reported
+// `ceremony-escalate-only:stale` against a file that was current — the
+// content-loss direction (`p082-b3-g5` finding 4). It could not be patched
+// per-line, because an HTML block's extent is cross-line state. That is the
+// whole argument for this pass in one example.
+// ⚠ NAMED because PROPOSAL-084's inline-comment detector also needs to know what
+// a comment-block OPENER looks like, and the first draft of it hand-wrote
+// `/^ {0,3}<!--/` a second time — a fresh copy of a block rule living outside the
+// one place allowed to spell it, which is this module's whole recurring defect.
+// One constant, two readers.
+const HTML_COMMENT_OPEN_RE = /^ {0,3}<!--/;
+
+// ⚠ The type-1 tag names, spelled ONCE. `HTML_BLOCK_TYPES` composes them into the
+// start condition, `htmlBlockStart` derives the matching end tag from that capture,
+// and `htmlBlockType7Line` needs the same list
+// because CommonMark §4.6 EXCLUDES these four names from type 7 — type 1 wins.
+// Naming it out of `HTML_BLOCK_TYPES` is the move `HTML_COMMENT_OPEN_RE` already
+// made, for the same reason: the alternative is a third copy of the list, and the
+// list being written twice inside this very constant is what let the type-7
+// detector fire on `<pre/>` for a round (`p084-xv8` finding 4).
+const HTML_TYPE1_TAGS = 'script|pre|style|textarea';
+const HTML_TYPE1_NAME_RE = new RegExp(`^(?:${HTML_TYPE1_TAGS})$`, 'i');
+
+const HTML_BLOCK_TYPES = [
+  [new RegExp(`^ {0,3}<(${HTML_TYPE1_TAGS})([ \\t>]|$)`, 'i'), null],
+  [HTML_COMMENT_OPEN_RE, /-->/],
+  [/^ {0,3}<\?/, /\?>/],
+  [/^ {0,3}<![A-Za-z]/, />/],
+  [/^ {0,3}<!\[CDATA\[/, /\]\]>/]
+];
+
+// Type 6's tag list, verbatim from the spec. Order inside the alternation does
+// not matter because the tail anchors on a delimiter, so `p` cannot swallow the
+// `param` case.
+const HTML_BLOCK_TAGS = 'address|article|aside|base|basefont|blockquote|body|caption|center|col|colgroup|dd|details|dialog|dir|div|dl|dt|fieldset|figcaption|figure|footer|form|frame|frameset|h1|h2|h3|h4|h5|h6|head|header|hr|html|iframe|legend|li|link|main|menu|menuitem|nav|noframes|ol|optgroup|option|p|param|search|section|summary|table|tbody|td|tfoot|th|thead|title|tr|track|ul';
+const HTML_BLOCK_TYPE6_RE = new RegExp(`^ {0,3}</?(?:${HTML_BLOCK_TAGS})(?:[ \\t]|/?>|$)`, 'i');
+
+// Leaf-block openers. Spelled `[ \t]` throughout, never `\s`, for the reason
+// given at `ATX_HEADING_RE`.
+//
+// ⚠ `\d{1,9}`: CommonMark caps an ordered marker at nine digits, so a ten-digit
+// run is paragraph text and NOT a list (`p082-b3-g5` finding 3).
+// ⚠ `([ \t]|$)` and not `[ \t]`: a marker with nothing after it is an EMPTY list
+// item, not prose (`p082-b3-g1` finding 6).
+// ⚠ The two marker shapes are spelled ONCE and the three predicates are built
+// from them. The first draft of this block wrote `[-*+]` twice and
+// `\d{1,9}[.)]` twice across four separate literals, which is the module's own
+// defect class — change the digit cap in one and the "is this an empty item"
+// test silently keeps the old one. Same reason `ATX_HEADING_RE` is a constant.
+const BULLET_MARKER = '[-*+]';
+// The delimiter set is its own fragment because THREE expressions need it and
+// one of them used to hand-write it: `INTERRUPTING_ITEM_RE` spelled `1[.)]`
+// while claiming to be derived, so widening `ORDERED_MARKER` would have left the
+// paragraph-interrupt rule silently on the old set. Unbroken at the time, and
+// load-bearing — which is the only reason it is worth fixing before it breaks.
+const ORDERED_DELIM = '[.)]';
+const ORDERED_MARKER = `\\d{1,9}${ORDERED_DELIM}`;
+// Opens a list wherever it appears, including an EMPTY item.
+const LIST_ITEM_RE = new RegExp(`^ {0,3}(?:${BULLET_MARKER}|${ORDERED_MARKER})([ \\t]|$)`);
+// An item with nothing after the marker. CommonMark 5.2: a list may interrupt a
+// paragraph only if its first line is non-blank, so this shape may not.
+const EMPTY_LIST_ITEM_RE = new RegExp(`^ {0,3}(?:${BULLET_MARKER}|${ORDERED_MARKER})[ \\t]*$`);
+// The markers that CAN interrupt a paragraph: any bullet, or an ordered marker
+// starting at 1. Any other ordered marker is paragraph text.
+const INTERRUPTING_ITEM_RE = new RegExp(`^ {0,3}(?:${BULLET_MARKER}|1${ORDERED_DELIM})([ \\t]|$)`);
+
+// A BLANK LINE — spaces and tabs only (CommonMark 2.1).
+//
+// ⚠⚠ THIS EXISTS BECAUSE `.trim()` IS THE GUARDED DEFECT CLASS IN A DIFFERENT
+// SPELLING, and the guard was blind to it. `\s` was swept out of every block
+// predicate; `line.trim()` was not, and `.trim()` strips the SAME set — U+00A0,
+// form feed, vertical tab, U+2000-200B, U+FEFF — while containing no `\s` for
+// the guard to find. A line holding only a non-breaking space was therefore a
+// blank line here and a paragraph to CommonMark, so `para` / NBSP / `---` made
+// `---` a thematic break instead of a setext underline, the section ran on, and
+// a stale `_conventions.md` reported `current`. SILENT PASS, the worst
+// direction, measured. Four more shapes flipped the other way.
+//
+// The guard now bans `.trim(` in block-structure code for this reason. Strip
+// with `stripSpaceTab` where a value needs trimming.
+const BLANK_LINE_RE = /^[ \t]*$/;
+
+// Strip leading and trailing SPACES AND TABS only — the CommonMark rule for
+// heading content, and the same rule `parseAtxHeading` applies. The setext
+// branch used to call `.trim()` here, so the two heading kinds disagreed about
+// a trailing U+00A0: `## Title<NBSP>` kept it and `Title<NBSP>` / `---` did not,
+// which made `isRecognizableDflowGuide` reject one form and accept the other.
+//
+// ⚠ This DIVERGES from commonmark.js, which calls JS `.trim()` in its inline
+// parser and so strips U+00A0 too. The spec says spaces and tabs; the reference
+// implementation is broader. We follow the spec.
+//
+// ⚠⚠ BE PRECISE ABOUT WHICH HALF IS IN THIS REPO. An earlier version of this
+// comment said the divergence "is carried as a named row in
+// `atx-differential.mjs`" — a file that **does not exist anywhere under this
+// repo**. It lives in the maintainer's repo-external review folder, so a reader
+// following that sentence finds nothing, and nothing in the tree re-derives the
+// claim. The divergence is pinned HERE instead, in `test/upgrade-drift.mjs`
+// pin (k).
+//
+// ⚠⚠ AND BE PRECISE ABOUT WHAT (k) COVERS, because the sentence that replaced
+// the bad one was itself an over-claim: it said the pins ran "against every
+// character the class covers" while (k) pinned **U+00A0 trailing, alone**. Form
+// feed and vertical tab were pinned at the ATX *opener*, not at heading-text
+// trimming, and no consumer consequence was pinned at all. Two corrections in a
+// row, both widening a claim past what the tree checks — so what (k) covers
+// today is stated exactly: five characters (U+00A0, form feed, vertical tab,
+// U+2002, U+FEFF), both leading and trailing, on both heading kinds. Widen the
+// claim only by widening the loop.
+function stripSpaceTab(text) {
+  return text.replace(/^[ \t]+|[ \t]+$/g, '');
+}
+// Split for measuring a list item's CONTENT COLUMN: indent, marker, gap.
+const LIST_ITEM_PREFIX_RE = new RegExp(`^( {0,3})(${BULLET_MARKER}|${ORDERED_MARKER})([ \\t]*)`);
+const BLOCKQUOTE_RE = /^ {0,3}>/;
+// (`INDENTED_CODE_RE` was deleted rather than fixed. It was the only raw-line
+// spelling of a question `indentWidth` already answers correctly, and keeping a
+// corrected copy would have left two expressions for one rule — the shape this
+// module keeps paying for.)
+const SETEXT_UNDERLINE_RE = /^ {0,3}(=+|-+)[ \t]*$/;
+
+// Columns of leading whitespace, a tab advancing to the next multiple of four
+// (CommonMark 2.2). Spaces and tabs only — anything else ends the indent, which
+// is the `[ \t]`-not-`\s` rule in yet another place.
+function indentWidth(line) {
+  let col = 0;
+  for (const ch of line) {
+    if (ch === ' ') col += 1;
+    else if (ch === '\t') col += 4 - (col % 4);
+    else break;
+  }
+  return col;
+}
+
+// The column a list item's CONTENT starts at — the indent, the marker, and the
+// gap after it. CommonMark 5.2: a gap of 1-4 spaces sets the content column
+// directly; an empty item, or a gap of five or more (which would start indented
+// code), puts the content one column after the marker.
+//
+// ⚠ This exists because a blank line does NOT end a list. A line indented to at
+// least this column after a blank is still the item's content, and reading it as
+// a document-level paragraph made `- a` / blank / `  b` / `---` end the section
+// where CommonMark reads a thematic break — content loss, the pop deleting the
+// line that carries the rule. Measured against the reference; the first version
+// of this pass closed every block on a blank line and got it wrong.
+function listContentColumn(line) {
+  const m = line.match(LIST_ITEM_PREFIX_RE);
+  if (!m) return null;
+  const markerEnd = m[1].length + m[2].length;
+  let gap = 0;
+  for (const ch of m[3]) gap += ch === '\t' ? 4 - ((markerEnd + gap) % 4) : 1;
+  return gap === 0 || gap > 4 ? markerEnd + 1 : markerEnd + gap;
+}
+
+// Convert the classifier's visual column into the UTF-16 offset String#slice
+// expects. A tab advances to a four-column stop but occupies one code unit; using
+// the visual column as an offset cuts into nested content after `-\t` / `- \t`.
+function stringIndexAtVisualColumn(line, targetColumn) {
+  let column = 0;
+  let index = 0;
+  while (index < line.length && column < targetColumn) {
+    column += line[index] === '\t' ? 4 - (column % 4) : 1;
+    index += 1;
+  }
+  return index;
+}
+
+// `{ endRe }` when the line opens an HTML block, else null. `endRe: null` means
+// type 6 — closed by a blank line rather than by a pattern.
+// ⚠ `invisible` answers a DIFFERENT question from the rest of this function, and
+// keeping them apart matters: `endRe` is about where the block ENDS (block
+// structure), `invisible` is about whether a reader ever SEES the text inside it
+// (content). The module got the first right and never asked the second, so a
+// rule commented out with `<!-- … -->` counted as present and a stale file
+// reported `current` — silent pass, reachable by one edit a person actually
+// makes (`p082-b3-k1`).
+//
+// Which types a reader cannot see, and why each:
+//   type 2 `<!-- -->`      a comment. Never rendered.
+//   type 3 `<? ?>`         a processing instruction. Never rendered.
+//   type 4 `<!DOCTYPE>`    a declaration. Never rendered.
+//   type 5 `<![CDATA[ ]]>` ignored by HTML parsers.
+//   type 1                 ONLY `script` and `style`. ⚠ `pre` and `textarea`
+//                          share type 1's start condition but their text IS
+//                          shown — treating all four alike would delete real
+//                          convention prose out of a `<pre>` block, which is
+//                          the content-loss direction.
+//   type 6 / type 7        ordinary tags; the text between them renders.
+// The list is spelled here and nowhere else, for the same reason `ORDERED_DELIM`
+// is: two copies of a rule is this module's defect class.
+const HTML_TYPE1_INVISIBLE_TAGS = /^(script|style)$/i;
+
+// ⚠⚠ A THIRD STATE, and missing it shipped a false positive AND a repair that
+// made things worse (`p084-xv4` finding 1). `invisible` splits type 1 into "the
+// reader sees nothing" (`script`, `style`) and "the reader sees the text"
+// (`pre`, `textarea`) — but for an HTML COMMENT those two are not the same
+// question, because it asks whether the reader sees the COMMENT, not the text.
+//   `<pre>`      interior is parsed as HTML, so a comment in it is a comment and
+//                is NOT displayed → hiding really happens → worth reporting.
+//   `<textarea>` interior is RAW TEXT (RCDATA), so `<!-- x -->` is DISPLAYED
+//                verbatim, brackets and all → nothing is hidden from anyone →
+//                reporting it is noise, and the repair for it is actively
+//                harmful: moving the line below `</textarea>` turns a comment
+//                the reader could see into one they cannot.
+// Matched against the shared type-1 opener rather than a fresh regex, for the
+// same reason `HTML_COMMENT_OPEN_RE` exists — two copies of a rule is this
+// module's defect class.
+// ⚠⚠⚠ THERE IS NO TEXTAREA EXEMPTION HERE, AND THAT IS THE DESIGN DECISION —
+// not an oversight, and not something to helpfully add back.
+//
+// `<textarea>` holds raw text, so a comment inside one IS displayed to the reader
+// and reporting it is a false positive. Three rounds were spent trying to suppress
+// exactly that, and **all three attempts produced a silent pass** — the failure this
+// entire proposal exists to remove:
+//   `p084-xv4` → exemption added, keyed on the enclosing block.
+//   `p084-xv5` → it could not see a nested `<textarea>`; kept, advice neutralised.
+//   `p084-xv9` → it skipped the WHOLE LINE, so a comment after a same-line
+//                `</textarea>` was exempted although it really is hidden. Doctor
+//                read a policy out of it under `All checks passed`.
+//   `p084-xv10` → the column version accepted `</textarea >` while the classifier
+//                closes only on `</textarea>`. **Two consumers, one rule, no shared
+//                spelling** — this module's own oldest defect, reintroduced by the
+//                repair. A later exact close then suppressed the unclosed fallback,
+//                so nothing fired at all.
+//
+// This repo's rule is that a check rewritten three times is a design question, not
+// a fourth patch. The design answer: **the exemption is not worth having.** It
+// suppresses a rare false positive at the cost of a defect class that has landed
+// three times running, in the one direction this module must never fail in. Without
+// it a `<textarea>` comment is merely REPORTED — the noisy direction, which the
+// module's own direction rule allows and which the maintainer has twice chosen
+// (2026-08-09, for nested `<textarea>` and for container-nested fences).
+//
+// What replaces it is a sentence, not code: `comment-inside-container`'s action and
+// both explainer pages open by telling the reader that a comment inside a
+// `<textarea>` is already visible and should be left alone. That is pinned.
+// ⚠ It also removes an inconsistency nobody could have explained: the document-level
+// `<textarea>` was exempt while a nested one was not.
+function htmlBlockStart(line) {
+  for (let t = 0; t < HTML_BLOCK_TYPES.length; t += 1) {
+    const [startRe, endRe] = HTML_BLOCK_TYPES[t];
+    const m = startRe.exec(line);
+    if (m) {
+      const invisible = t === 0 ? HTML_TYPE1_INVISIBLE_TAGS.test(m[1]) : true;
+      // Marked, which powers `dflow render`, keeps a type-1 raw block open until
+      // the tag that opened it closes. A shared `script|pre|style|textarea` end
+      // regex lets `</script>` close `<pre>` and makes doctor read hidden content.
+      const matchingEnd = t === 0 ? new RegExp(`<\\/${m[1]}>`, 'i') : endRe;
+      return { endRe: matchingEnd, invisible };
+    }
+  }
+  if (HTML_BLOCK_TYPE6_RE.test(line)) return { endRe: null, invisible: false };
+  return null;
+}
+
+// Remove explicit container openers until the line reaches the content that
+// CommonMark parses inside them. Continuation indentation for an open outer list
+// is removed by the caller first; this loop handles nested `> - ...` openers.
+function stripNestedContainerOpeners(line, paragraphOpen = false, priorQuoteDepth = 0) {
+  let rest = line;
+  let quoteDepth = 0;
+  let listOpened = false;
+  while (true) {
+    const quote = /^ {0,3}>[ \t]?/.exec(rest);
+    if (quote) {
+      quoteDepth += 1;
+      rest = rest.slice(quote[0].length);
+      continue;
+    }
+    // Repeating the same explicit quote chain continues its inner block. Moving
+    // into or out of a quote chain starts a different block sequence instead.
+    if (quoteDepth !== priorQuoteDepth) paragraphOpen = false;
+    if (LIST_ITEM_RE.test(rest)) {
+      const canInterrupt = INTERRUPTING_ITEM_RE.test(rest) && !EMPTY_LIST_ITEM_RE.test(rest);
+      // An ordered marker beginning above 1 cannot interrupt an open paragraph.
+      // Leaving it in `rest` is load-bearing: `<details>` later on that same
+      // visible paragraph is not a raw-HTML opener.
+      if (paragraphOpen && !canInterrupt) return { content: rest, quoteDepth, listOpened };
+      const contentCol = listContentColumn(rest);
+      if (contentCol !== null) {
+        listOpened = true;
+        rest = rest.slice(stringIndexAtVisualColumn(rest, contentCol));
+        paragraphOpen = false;
+        continue;
+      }
+    }
+    return { content: rest, quoteDepth, listOpened };
+  }
+}
+
+function nestedParagraphOpens(line, rawHtml) {
+  if (rawHtml || BLANK_LINE_RE.test(line)) return false;
+  if (parseAtxHeading(line) || SETEXT_UNDERLINE_RE.test(line) || isThematicBreak(line)) return false;
+  if (FENCE_OPEN_RE.test(line) || indentWidth(line) >= 4) return false;
+  return true;
+}
+
+function nestedContainerContext(
+  line,
+  htmlState,
+  paragraphOpen = false,
+  quoteDepth = 0,
+  htmlInList = false,
+  outerList = false
+) {
+  const stripped = stripNestedContainerOpeners(line, paragraphOpen, quoteDepth);
+  // A deeper quote remains inside the raw block opened by its outer quote, but
+  // moving to a shallower still-quoted line exits the inner block sequence.
+  // Carrying that state downward made visible escaped comments look hidden; the
+  // suggested column-0 repair would then hide text the reader could already see.
+  const activeHtml = stripped.quoteDepth < quoteDepth ? null : htmlState;
+  const html = nestedRawHtmlContext(stripped.content, activeHtml);
+  // Track what owns THIS raw-HTML state, not merely whether some earlier line
+  // contained a list marker. A markerless continuation may omit both the list
+  // indent and an outer quote marker; Marked still keeps raw HTML open only when
+  // the state belongs to a list item. A bare blockquote's state must instead be
+  // dropped at that boundary. When an existing state survives, its owner does;
+  // a newly opened state gets its owner from the current container chain.
+  const nextHtmlInList = html.next
+    ? (activeHtml ? htmlInList : outerList || stripped.listOpened)
+    : false;
+  return {
+    rawHtml: html.rawHtml,
+    nextHtml: html.next,
+    nextParagraph: nestedParagraphOpens(stripped.content, html.rawHtml),
+    nextQuoteDepth: stripped.quoteDepth,
+    nextHtmlInList
+  };
+}
+
+// Track raw HTML after a list / blockquote prefix has been removed. The main
+// classifier intentionally labels the OUTERMOST block; comment opener selection
+// also needs to know whether inline Markdown syntax applies inside that block.
+// Reuse htmlBlockStart and its end conditions rather than spelling HTML types a
+// second time. `rawHtml` includes the opening/closing line; `next` is the state
+// carried to the following line.
+function nestedRawHtmlContext(line, state) {
+  if (state) {
+    if (!state.endRe) {
+      if (BLANK_LINE_RE.test(line)) return { rawHtml: false, next: null };
+      return { rawHtml: true, next: state };
+    }
+    return { rawHtml: true, next: state.endRe.test(line) ? null : state };
+  }
+  const html = htmlBlockStart(line);
+  if (!html) return { rawHtml: false, next: null };
+  const selfEnds = html.endRe && html.endRe.test(line);
+  return {
+    rawHtml: true,
+    next: selfEnds ? null : { endRe: html.endRe }
+  };
+}
+
+// One label per line, in one pass.
+//
+// Each entry is `{ type, heading }`. `type` is one of `blank`, `heading`,
+// `thematic-break`, `paragraph`, `list`, `blockquote`, `code`, `html`, `table`.
+// `heading` is null except on a heading line, where it is
+// `{ level, text, setext, start }` — `start` being the first line of the
+// underlined paragraph for a setext heading, and the heading's own index for an
+// ATX one. Callers that pop a setext heading's text out of a body need `start`,
+// and getting it from the classification is why a soft-wrapped setext heading
+// now works: the old code assumed the text was exactly one line.
+//
+// ⚠ Fenced code is already gone by the time this runs — `blankFencedBlocks` has
+// replaced those lines with empty ones, preserving positions. That is why there
+// is no fence state here. Keep calling this on that function's output; handing
+// it raw content would read headings out of fenced examples, which is the
+// PROPOSAL-076 G1 defect.
+function classifyLines(lines) {
+  const out = new Array(lines.length);
+  let open = null; // { kind, start, endRe } — the open DOCUMENT-LEVEL block
+
+  for (let i = 0; i < lines.length; i += 1) {
+    const line = lines[i];
+
+    // (1) Inside an HTML block. Its extent is exactly the cross-line state the
+    //     old per-line predicates could not hold.
+    //
+    // ⚠⚠ `blockStart` — WHICH LINE OPENED THIS BLOCK. It is carried here because
+    // reconstructing it from the outside is not reliably possible, and that was
+    // established the expensive way: `checkGuideProjectContextFormat` needs it to
+    // tell an adopter which `<!--` or `<details>` is hiding their
+    // `## Project Context`, and THREE consecutive review rounds each defeated a
+    // reverse-scan approximation of it (`debt212223-xv1` F2, `xv2` F1, `xv3` F1).
+    // Walking back over contiguous `html` lines crosses into the block before it;
+    // and tag- or comment-shaped lines INSIDE an open block (`<p>x</p>`,
+    // `prose <!-- y`) are indistinguishable from openers when you only look at the
+    // line, because whether a line can open a block at all depends on cross-line
+    // state that only this loop holds. Three rounds on one predicate is this repo's
+    // own signal to stop patching and change the shape. The field is additive, like
+    // `unclosed` and `invisible` before it — every existing consumer reads `.type`
+    // and `.heading`.
+    if (open && open.kind === 'html') {
+      if (open.endRe) {
+        // ⚠ `visibleFrom`: an end condition can leave text AFTER it on the same
+        // line, and that text is rendered. `<!-- note --> rest of the line` puts
+        // `rest of the line` in the output, so blanking the whole line loses
+        // real content — measured as a SILENT PASS one commit after the
+        // visibility rule landed (`p082-b3-k3` finding 2): a retired string
+        // sitting after a `-->` stopped being reported.
+        const end = open.endRe.exec(line);
+        out[i] = { type: 'html', heading: null, invisible: open.invisible, blockStart: open.start, blockEndsOnBlank: false };
+        if (end) {
+          if (open.invisible) out[i].visibleFrom = end.index + end[0].length;
+          open = null;
+        }
+        continue;
+      }
+      if (BLANK_LINE_RE.test(line)) { out[i] = { type: 'blank', heading: null }; open = null; continue; }
+      // ⚠ THE SECOND OF THE TWO in-block assignments, and it is the one a
+      // whitespace-differing `replace_all` missed when `blockStart` was added: this
+      // branch serves blocks with NO end condition, which in this parser means
+      // **type 6 only** (`<details>`, `<div>`) — type 7 is deliberately not
+      // implemented, see the § above, and `<span>` classifies as a paragraph
+      // (`debt212223-xv5`, which probed it). Those are exactly the blocks the guide
+      // finding had to be able to name. Adding
+      // the field to the `endRe` branch alone left `<details>` reporting no opener
+      // at all, and the caller's fallback then pointed at the heading itself.
+      // ⚠⚠ `blockEndsOnBlank` rides along for the same reason `blockStart` does
+      // (`debt212223-y4` finding 1): **how you close a block is not visible from
+      // its opening line**. A caller that saw `<details>` and advised "close it"
+      // was wrong — `</details>` does not end a type-6 block, only a blank line
+      // does, measured — while `</script>` / `]]>` / `?>` really do end types 1/3/5.
+      // The distinction is `endRe`, which lives here and nowhere else, so it is
+      // carried out rather than re-derived at the caller. Re-deriving block
+      // structure outside this function is what cost three rounds already.
+      out[i] = { type: 'html', heading: null, invisible: open.invisible, blockStart: open.start, blockEndsOnBlank: true };
+      continue;
+    }
+
+    // (2) A blank line closes every document-level block — EXCEPT a list, whose
+    //     item can continue after it (a "loose" list). Measured: closing the
+    //     list here made `- a` / blank / `  b` / `---` end the section, while
+    //     CommonMark keeps the item open and reads `---` as a thematic break.
+    //     Content-loss direction — the walker pops the line carrying the rule.
+    //     A BLOCKQUOTE really does close, which is not symmetry but measurement:
+    //     `> q` / blank / `  more` ends the section in the reference too.
+    if (BLANK_LINE_RE.test(line)) {
+      out[i] = { type: 'blank', heading: null };
+      if (open && open.kind === 'list') {
+        open.blankSeen = true;
+        // A blank ends type-6 raw HTML but NOT type 1-5. Let the same transition
+        // function that owns those end conditions decide instead of clearing
+        // every nested block at the loose-list boundary.
+        open.nestedHtml = nestedRawHtmlContext('', open.nestedHtml).next;
+        if (!open.nestedHtml) open.nestedHtmlInList = false;
+        open.nestedParagraph = false;
+        open.nestedQuoteDepth = 0;
+      }
+      else open = null;
+      continue;
+    }
+
+    // (2.5) A line indented to the open list item's content column belongs to
+    //       that item — including a heading, which is then a heading INSIDE the
+    //       list and not a document-level one. This is checked before every
+    //       block-start test below, because otherwise `  ## Heading` inside an
+    //       item would end the section.
+    if (open && open.kind === 'list') {
+      if (indentWidth(line) >= open.contentCol) {
+        const nested = nestedContainerContext(
+          line.slice(stringIndexAtVisualColumn(line, open.contentCol)),
+          open.nestedHtml,
+          open.nestedParagraph,
+          open.nestedQuoteDepth,
+          open.nestedHtmlInList,
+          true
+        );
+        out[i] = { type: 'list', heading: null };
+        if (nested.rawHtml) out[i].rawHtml = true;
+        open.nestedHtml = nested.nextHtml;
+        open.nestedParagraph = nested.nextParagraph;
+        open.nestedQuoteDepth = nested.nextQuoteDepth;
+        open.nestedHtmlInList = nested.nextHtmlInList;
+        open.blankSeen = false;
+        continue;
+      }
+      // Not indented into the item, and a blank line intervened: the list ended
+      // at that blank and this line starts something new.
+      if (open.blankSeen) open = null;
+    }
+
+    const paraOpen = open !== null && open.kind === 'paragraph';
+
+    // (3) A setext underline — but ONLY when there is a paragraph to underline.
+    //     This single test is the arbitration the old code spread across
+    //     `closesOwnBlock`, `blockStartIndex` and `isParagraphLine`, which is
+    //     why they could contradict each other about the same line.
+    //     ⚠ It is tested BEFORE the thematic break on purpose: CommonMark 4.3
+    //     gives the setext heading precedence where both readings are possible,
+    //     so `para` + `---` is a heading while a bare `---` is a break.
+    if (paraOpen && SETEXT_UNDERLINE_RE.test(line)) {
+      const marker = line.match(SETEXT_UNDERLINE_RE)[1];
+      const text = stripSpaceTab(lines.slice(open.start, i).map(stripSpaceTab).join(' '));
+      out[i] = {
+        type: 'heading',
+        heading: { level: marker[0] === '=' ? 1 : 2, text, setext: true, start: open.start }
+      };
+      open = null;
+      continue;
+    }
+
+    // (4) Shapes that open their own block wherever they appear.
+    const atx = parseAtxHeading(line);
+    if (atx) {
+      out[i] = { type: 'heading', heading: { ...atx, start: i } };
+      open = null;
+      continue;
+    }
+
+    if (isThematicBreak(line)) {
+      out[i] = { type: 'thematic-break', heading: null };
+      open = null;
+      continue;
+    }
+
+    // HTML blocks of types 1-6 can all interrupt a paragraph, so this sits
+    // above the continuation logic rather than inside the block-start branch.
+    const html = htmlBlockStart(line);
+    if (html) {
+      out[i] = { type: 'html', heading: null, invisible: html.invisible, blockStart: i, blockEndsOnBlank: !html.endRe };
+      // ⚠ The end condition is checked on the OPENING line too (CommonMark 4.6:
+      // "the block ends at the first line matching the end condition", which
+      // includes the line that started it). Leaving it out meant a single-line
+      // `<!-- Seeded by Dflow. -->` — the comment at the head of every packaged
+      // template — opened a block that never closed, and every heading in the
+      // file after it disappeared. The existing pins caught it immediately,
+      // which is the argument for having run them before widening anything.
+      // Same rule on the opening line, which may also be the closing one:
+      // `<!-- a --> b` renders ` b`.
+      const selfEnd = html.endRe && html.endRe.exec(line);
+      if (selfEnd) {
+        if (html.invisible) out[i].visibleFrom = selfEnd.index + selfEnd[0].length;
+        open = null;
+      } else {
+        open = { kind: 'html', start: i, endRe: html.endRe, invisible: html.invisible };
+      }
+      continue;
+    }
+
+    if (BLOCKQUOTE_RE.test(line)) {
+      const sameQuote = open && open.kind === 'blockquote';
+      const nested = nestedContainerContext(
+        line,
+        sameQuote ? open.nestedHtml : null,
+        sameQuote ? open.nestedParagraph : false,
+        sameQuote ? open.nestedQuoteDepth : 0,
+        sameQuote ? open.nestedHtmlInList : false
+      );
+      out[i] = { type: 'blockquote', heading: null };
+      if (nested.rawHtml) out[i].rawHtml = true;
+      open = {
+        kind: 'blockquote',
+        start: open && open.kind === 'blockquote' ? open.start : i,
+        nestedHtml: nested.nextHtml,
+        nestedParagraph: nested.nextParagraph,
+        nestedQuoteDepth: nested.nextQuoteDepth,
+        nestedHtmlInList: nested.nextHtmlInList
+      };
+      continue;
+    }
+
+    // A list interrupts an open paragraph only when it is a bullet, or an
+    // ordered marker starting at 1, AND its first line is non-blank
+    // (CommonMark 5.2). Any other ordered marker — and an empty item — is
+    // paragraph text. Reading those as block starts is the divergence `g1` found
+    // by widening the arbiter, in the silent-pass direction.
+    if (LIST_ITEM_RE.test(line)) {
+      const canInterrupt = INTERRUPTING_ITEM_RE.test(line) && !EMPTY_LIST_ITEM_RE.test(line);
+      if (!paraOpen || canInterrupt) {
+        const contentCol = listContentColumn(line);
+        const nested = nestedContainerContext(
+          line.slice(stringIndexAtVisualColumn(line, contentCol)),
+          null,
+          false,
+          0,
+          false,
+          true
+        );
+        out[i] = { type: 'list', heading: null };
+        if (nested.rawHtml) out[i].rawHtml = true;
+        // ⚠ `listContentColumn` cannot return null here, and the reason is worth
+        // stating because the consequence if it ever did is severe:
+        // `indentWidth(line) >= null` is `>= 0`, true for EVERY line, so the
+        // whole rest of the document would be swallowed as list content —
+        // silent pass. It cannot happen because `LIST_ITEM_PREFIX_RE` is built
+        // from the same two marker fragments as `LIST_ITEM_RE` and is strictly
+        // more permissive (its trailing `[ \t]*` matches empty where
+        // `LIST_ITEM_RE` requires `[ \t]` or end of line), so anything this
+        // branch accepts, it matches. Sharing the fragments is what makes that
+        // an invariant rather than a hope — this module has broken exactly this
+        // kind of unwritten relationship between two expressions five times.
+        open = {
+          kind: 'list',
+          start: open && open.kind === 'list' ? open.start : i,
+          // Each item sets the column its own content continues at.
+          contentCol,
+          blankSeen: false,
+          nestedHtml: nested.nextHtml,
+          nestedParagraph: nested.nextParagraph,
+          nestedQuoteDepth: nested.nextQuoteDepth,
+          nestedHtmlInList: nested.nextHtmlInList
+        };
+        continue;
+      }
+      // else: falls through to the paragraph continuation below.
+    }
+
+    // (5) Continuation of an open container. Inside a list item or a blockquote
+    //     the document-level block is the container, not a paragraph, so no
+    //     setext underline can close anything here — which is precisely what
+    //     `blockStartIndex` used to walk backwards to work out.
+    if (open && (open.kind === 'list' || open.kind === 'blockquote')) {
+      out[i] = { type: open.kind, heading: null };
+      // Raw HTML owned by a list item CAN cross a lazy continuation even when
+      // its list indent — and an outer quote marker — is omitted. Marked keeps
+      // the block open, so comment syntax on this line is still raw HTML. A bare
+      // blockquote cannot cross that boundary; clearing it is the quote-exit
+      // control that prevents visible escaped examples from being rejected.
+      if (open.nestedHtml && open.nestedHtmlInList) {
+        const lazy = nestedRawHtmlContext(line, open.nestedHtml);
+        if (lazy.rawHtml) out[i].rawHtml = true;
+        open.nestedHtml = lazy.next;
+        if (!lazy.next) open.nestedHtmlInList = false;
+      } else if (open.kind === 'blockquote') {
+        open.nestedHtml = null;
+        open.nestedHtmlInList = false;
+        open.nestedParagraph = false;
+        open.nestedQuoteDepth = 0;
+      }
+      continue;
+    }
+
+    // (6) A table runs until a line that is not a row.
+    // ⚠ NAMED GAP, DELIBERATELY NOT "FIXED": this branch has no indent test,
+    // while (8) — which OPENS the table — now requires the header row to sit at
+    // `indentWidth < 4`. So `| a | b |` / `|---|---|` / `<4SP>| c | d |` keeps
+    // the third line in the table for us, where GFM ends the table and starts an
+    // indented code block. The symmetric-looking change (adding an indent test
+    // here) is NOT made, because **no reference available to this repo can say
+    // which answer is right**, and shipping a change on an unarbitrated hunch is
+    // how this module's boundary logic got into trouble in the first place:
+    //   - `commonmark@0.31.2` has no tables, so it never enters this state at
+    //     all and reads the whole run as one paragraph. It agrees with us here
+    //     for a reason that has nothing to do with the question.
+    //   - `marked`'s GFM lexer does answer, but it is measurably non-conformant
+    //     on exactly this boundary — for `prose` / `<4SP>prose` / `===` the spec
+    //     and `commonmark` both say setext H1 (an indented line cannot interrupt
+    //     a paragraph, so it is a lazy continuation) while `marked` says
+    //     paragraph. A reference that is wrong on the control cannot settle the
+    //     case.
+    // Direction if GFM turns out to be right: content loss, the loud one.
+    // Closing this needs a third reference (cmark-gfm), not more reasoning.
+    if (open && open.kind === 'table') {
+      if (line.includes('|')) { out[i] = { type: 'table', heading: null }; continue; }
+      out[i] = { type: 'paragraph', heading: null };
+      open = { kind: 'paragraph', start: i };
+      continue;
+    }
+
+    // (7) Indented code — which cannot interrupt a paragraph. After one, an
+    //     indented line is a lazy continuation and the paragraph stays open.
+    // ⚠ `indentWidth(...) >= 4`, NOT a raw-line regex. This branch used
+    // `INDENTED_CODE_RE = /^(\t| {4,})/`, which decides the SAME question as
+    // `indentWidth` with different code — and they disagreed: a space followed
+    // by a tab is column 4 (a tab advances to the next multiple of four), so
+    // `indentWidth(' \tx') === 4` while the regex said false. Both directions
+    // measured: `<SP><TAB>prose` became a paragraph, so a following `---` was a
+    // setext underline and the pop deleted the body (content loss); and
+    // `<SP><SP><SP><TAB>| a | b |` became a table header, so the section ran on
+    // (silent pass). This module's own rule names it — a regex against a raw
+    // line, anywhere else, to decide what kind of line it is.
+    //
+    // ⚠⚠ WHY WIDENING THIS BRANCH STOLE NOTHING FROM THE BRANCHES ABOVE IT, and
+    // this is the part that was missing rather than wrong. `indentWidth >= 4` is
+    // strictly wider than the regex it replaced, so it can only take lines that
+    // used to reach branches further down — unless it also overlaps branch (4).
+    // It cannot, and the reason is a property of every opener in this module,
+    // not of this line: **every raw-prefix opener is `^ {0,3}` followed by a
+    // character that is neither a space nor a tab**, which bounds any line one
+    // of them matches at `indentWidth <= 3`; while `indentWidth >= 4` requires
+    // four spaces, or a tab, inside the first four columns, which no `^ {0,3}X`
+    // can match. So (4) and (7) partition cleanly.
+    // ⚠ That is a property of the OTHER expressions, so it can be broken from a
+    // distance: admit a tab into any `^ {0,3}` prefix — write `^[ \t]{0,3}`,
+    // which looks like a tolerance improvement — and this branch starts eating
+    // lines that opener was meant to claim, silently. `assertOpenerIndentPartition`
+    // in `test/upgrade-drift.mjs` sweeps every opener against every indent form
+    // so the break is a test failure and not a review round.
+    if (!paraOpen && indentWidth(line) >= 4) {
+      out[i] = { type: 'code', heading: null };
+      open = { kind: 'code', start: open && open.kind === 'code' ? open.start : i };
+      continue;
+    }
+
+    // (8) A GFM table opens when a delimiter row sits directly under a
+    //     pipe-bearing paragraph line. Requiring the header is what keeps
+    //     ordinary prose containing a pipe — "the Command | Query split" — from
+    //     being read as a table, which an earlier `line.includes('|')` test got
+    //     wrong in the silent-success direction.
+    // ⚠ The header row is the line DIRECTLY ABOVE the delimiter row, wherever
+    // that line sits in the paragraph. Requiring it to be the paragraph's first
+    // line (`open.start === i - 1`) was a regression against the predicate this
+    // pass replaced, whose backward scan had no such restriction: one intro
+    // sentence above a table — `Our rows:` / `| a | b |` / `|---|---|` — made the
+    // whole run one paragraph, so a following `---` became a setext underline
+    // and the pop deleted the ENTIRE section body. Total content loss for that
+    // section, on input a hand-edited `_conventions.md` produces immediately.
+    // Any earlier lines of the paragraph stay a paragraph; only the header row
+    // and the delimiter row become the table.
+    // ⚠⚠ THE HEADER ROW'S OWN INDENT IS CHECKED, and leaving it out was a
+    // silent-pass defect this very branch introduced. `TABLE_DELIMITER_ROW_RE`
+    // constrains the DELIMITER row to `^ {0,3}`, but the header test is only
+    // `.includes('|')`. While the header had to be the paragraph's first line
+    // that gap was unreachable — an indented line can only be a paragraph
+    // CONTINUATION, since indented code cannot interrupt a paragraph — so
+    // widening the rule opened it. A 4-column-indented header is indented code
+    // to CommonMark and no table at all to GFM (`marked` emits no table token),
+    // yet we read one, the `---` below stopped ending the section, and a stale
+    // file reported `current`. Measured: five rows where both references
+    // disagreed with us and neither with each other.
+    // `i > 0` is deliberately gone: `paraOpen` cannot be true at i === 0 (`open`
+    // starts null and is only assigned in the loop), so it never guarded
+    // anything while reading like the bounds check that made this branch safe.
+    // ⚠⚠ RELABELLING `out[i - 1]` RESTS ON AN INVARIANT NOTHING ELSE STATES:
+    // when `paraOpen` is true at `i`, `out[i - 1]` is necessarily `'paragraph'`.
+    // It holds because the only branches that leave `open.kind === 'paragraph'`
+    // are (9) and (6)'s else-path, and both write `'paragraph'` to their own
+    // line. So the overwrite below always replaces a label this loop just wrote
+    // for the header row — never a `code`, `list` or `heading` line.
+    // ⚠ A future branch that labels its line something else while leaving a
+    // paragraph open would have that label silently overwritten as `table`, and
+    // nothing here would notice. If you add such a branch, this line is the one
+    // that breaks — and it breaks quietly, which is why the invariant is written
+    // down instead of being left to be re-derived.
+    if (paraOpen && indentWidth(lines[i - 1]) < 4 && lines[i - 1].includes('|') && TABLE_DELIMITER_ROW_RE.test(line)) {
+      out[i - 1] = { type: 'table', heading: null };
+      out[i] = { type: 'table', heading: null };
+      open = { kind: 'table', start: i - 1 };
+      continue;
+    }
+
+    // (9) Paragraph: a continuation of the open one, or a new one.
+    out[i] = { type: 'paragraph', heading: null };
+    if (!paraOpen) open = { kind: 'paragraph', start: i };
+  }
+
+  // ⚠⚠ AN HTML BLOCK STILL OPEN AT EOF IS MARKED, and this is not a parsing
+  // nicety — it was a HIGH silent pass reachable on a file nobody had to
+  // construct. HTML block types 1-5 close only on their end condition, so an
+  // adopter who leaves one `<!--` unclosed mid-edit puts the ENTIRE REST OF THE
+  // FILE inside that block. The parse is right; what was wrong was that
+  // `conventionsSectionBodies` kept pushing those lines into the open section's
+  // body, so the section swallowed every later section, reached a quoted copy
+  // of the rule in an appendix, and a genuinely stale file reported `current`.
+  // Measured through the real `doctor`: closing the comment produced two
+  // warnings, leaving it open produced none.
+  //
+  // ⚠ Only HTML. A paragraph, list or code block open at EOF is ordinary — the
+  // document simply ended. Fenced blocks never reach here because
+  // `blankFencedBlocks` has already emptied them, and that immunity is
+  // accidental rather than designed, which is exactly why this needed marking
+  // rather than another special case.
+  //
+  // The flag is additive: every existing consumer reads `.type` and `.heading`.
+  // ⚠⚠ `open.endRe` IS THE WHOLE POINT, and leaving it out was a regression this
+  // very block introduced. Only types 1-5 close on an end condition; **type 6
+  // closes on a blank line**, and `endRe` is null for it. A document ending in a
+  // type-6 block therefore looked "never closed" — but a file that ends with a
+  // newline supplies a trailing blank through the splitter, so the block closes
+  // normally, while a file WITHOUT a trailing newline did not. Two files one
+  // byte apart, and the shorter one got a spurious "unclosed HTML block"
+  // warning plus a false `stale` on a section that plainly carries the rule.
+  // Content loss, on `<div>…</div>` — ordinary hand-written HTML.
+  // The comment above already said types 1-5; the code did not agree with it.
+  if (open && open.kind === 'html' && open.endRe) {
+    for (let i = open.start; i < out.length; i += 1) out[i].unclosed = true;
+  }
+
+  return out;
+}
+
+// ⚠ `toUpperCase`, not `toLowerCase`, and the difference is not cosmetic:
+// `headingResolves` PREFIX-matches on this key, and lowercasing is not
+// prefix-preserving. Greek capital sigma lowercases to a FINAL sigma at a word
+// end and a medial one elsewhere, so `ΑΣ` becomes `ας` while `ΑΣΒΓ` becomes
+// `ασβγ` — and `"ασβγ".startsWith("ας")` is false although the raw strings do
+// prefix-match. A `<file>.md § ΑΣ` reference to a heading `ΑΣΒΓ` was reported as
+// dangling. Uppercasing has no context-sensitive mapping in the default
+// case-conversion tables, so it preserves prefixes; `ß` → `SS` changes length
+// but preserves them too.
+// ⚠ Any fold works for the exact and Set comparisons; only the prefix consumer
+// constrains the choice. Keep ONE fold for all three rather than a
+// prefix-preserving one here and a convenient one there — that split is how the
+// three consumers of this normaliser drifted apart before.
+function headingKey(text) {
+  return normalizeHeading(text).toUpperCase();
+}
+
+// ALL bodies whose heading matches — `_conventions.md` is hand-edited and a
+// duplicated heading is ordinary. Taking only the first made a file that
+// carried the rule in its second copy report `stale`.
+function conventionsSectionBodies(content, heading) {
+  // Blanked by the same expression `visibleTextLines` returns — see
+  // `classifiedVisible`. Text a reader never sees is not this section's content.
+  const { info, lines } = classifiedVisible(content);
+  const target = headingKey(heading);
+  const bodies = [];
+  let level = 0;
+  let body = null;
+  for (let i = 0; i < lines.length; i += 1) {
+    const h = info[i].heading;
+    if (h) {
+      // A setext heading's TEXT lines were already pushed into the open body —
+      // take them back out. `h.start` is where the underlined paragraph began,
+      // so this pops all of them.
+      //
+      // ⚠ The old version popped exactly ONE line and guarded it with
+      // `body[body.length - 1].trim() === h.text`, because it assumed a setext
+      // heading's text was a single line. A soft-wrapped one therefore left its
+      // earlier lines sitting in the body as though they were content, and
+      // reported the heading under only its last line — so a section titled
+      // `Ceremony Scaling` / `(Project Application)` / `===` did not match the
+      // fingerprint that names it. The classification knows the paragraph's
+      // extent, so both halves are now right for free.
+      if (body && h.setext) {
+        for (let k = h.start; k < i && body.length > 0; k += 1) body.pop();
+      }
+      if (body && h.level <= level) {
+        bodies.push(body.join('\n'));
+        body = null;
+        level = 0;
+      }
+      if (!body && headingKey(h.text) === target) {
+        level = h.level;
+        body = [];
+      }
+      continue;
+    }
+    // ⚠ A line inside an HTML block that never closed is NOT this section's
+    // content — it is the interior of a block that swallowed the rest of the
+    // file. Pushing it let a section reach text from a later section and report
+    // `current` on a file that had genuinely lost the rule: silent pass, the
+    // worst direction, and reachable from one unclosed `<!--`.
+    // Stopping here is the conservative half of the fix — we only trust content
+    // we can attribute to the section. The other half is telling the user why,
+    // which `findConventionsDrift` does, because otherwise the resulting `stale`
+    // is correct and inexplicable.
+    if (info[i].unclosed) break;
+    if (body) body.push(lines[i]);
+  }
+  if (body) bodies.push(body.join('\n'));
+  return bodies;
+}
+
+// The file's lines with everything a reader cannot see blanked out: fenced code
+// (already blanked on the way in) and the interior of an HTML block that renders
+// no text — a comment, a processing instruction, a declaration, CDATA, a
+// `<script>` or a `<style>`.
+//
+// ⚠⚠ WHY THIS EXISTS AS A FUNCTION RATHER THAN A TEST AT EACH CONSUMER. The
+// rewrite made `classifyLines` the single authority on *what kind of line this
+// is* — and then every CONTENT extractor went on reading the raw text without
+// asking. So three consumers each decided independently, by not deciding:
+// `findConventionsDrift` matched a fingerprint marker inside `<!-- … -->` and
+// certified a stale file as `current`; `parseContextLine` read a commented-out
+// machine-readable policy value as though it were live; `extractSectionRefs`
+// reported a reference inside a comment as a dangling link, with the `-->`
+// captured into the heading text (`p082-b3-k1`, all three reproduced).
+//
+// ⚠ The module was already INCONSISTENT about this, which is the tell that it
+// was never decided: a retired string below an *unclosed* comment was correctly
+// ignored (the section body stops there), while the same string inside a *closed*
+// comment counted. Same question, two answers, depending on whether the user
+// typed `-->`.
+//
+// BLANK, do not delete: `extractSectionRefs` reports 1-based line numbers and
+// `conventionsSectionBodies` pops setext text by index. This is the same
+// convention `blankFencedBlocks` established, for the same reason.
+//
+// ⚠ This is a real semantic decision, not a bug fix with an obvious answer:
+// it says a commented-out rule is ABSENT. `commonmark` agrees a reader never
+// sees it, and the section differential's whole question is "does a reader see
+// the marker in this section" — so the arbiter this module already trusts was
+// answering one question while the implementation answered another.
+// ⚠⚠ ONE APPLICATION OF THE RULE, not two. The first draft of this fix had
+// `visibleTextLines` blank the lines and `conventionsSectionBodies` repeat the
+// test inline (`info[i].invisible ? '' : line`) because it needed `info` anyway.
+// Both read the same flag, so the DECISION was single-sourced — but the two
+// expressions could still drift, and "one rule, two expressions" is the defect
+// class this module exists to hold shut. It was caught by measurement, not by
+// review: breaking the projection left the `conventionsSectionBodies` pins
+// green, which is precisely the "my pin cannot fail against the thing it names"
+// shape the mutation harness was built for.
+// ⚠ SPACES, not deletion, and the span rather than the line. Two reasons, both
+// paid for: `extractSectionRefs` compares a match's index against the line's
+// length, so shortening a line moves every column it reads; and an end condition
+// can leave rendered text after it on the same line (`visibleFrom`), which
+// whole-line blanking silently dropped.
+function classifiedVisible(content) {
+  const lines = blankFencedBlocks(String(content));
+  const info = classifyLines(lines);
+  return {
+    info,
+    lines: lines.map((line, i) => {
+      if (!info[i] || !info[i].invisible) return line;
+      const from = info[i].visibleFrom;
+      const hidden = from === undefined ? line.length : Math.min(from, line.length);
+      return ' '.repeat(hidden) + line.slice(hidden);
+    })
+  };
+}
+
+function visibleTextLines(content) {
+  return classifiedVisible(content).lines;
+}
+
+// The same content with every CODE line masked to spaces — same length, same
+// line count, so an index into the result is an index into the original.
+//
+// ⚠⚠ WHY A MASK AND NOT THE LINE ARRAY. `configure-agents` finds its managed
+// region with `indexOf` over the raw file and then SLICES the original by that
+// index, so anything that shortens a line moves the cut and corrupts the write.
+// A mask keeps every offset while removing the text that must not match.
+//
+// It exists because the write path — the only path in this tool that modifies a
+// user's file — decided a structural question by not asking: a user documenting
+// Dflow in their own `AGENTS.md`, with the marker comments shown inside a fenced
+// example, had that example treated as the managed region and OVERWRITTEN.
+// `runConfigureAgents` exited 0 and `doctor` then reported all clean
+// (`p082-b3-k3` finding 1). USER CONTENT LOSS, which is the worst thing this
+// codebase can do.
+//
+// ⚠ Fenced and indented code only. A marker inside a `<pre>` block is still
+// taken as a region boundary — `pre` renders its text, so it is not code to this
+// module, and closing that case needs a decision about what `<pre>` MEANS here
+// rather than another line in this function. Stated so the gap is known rather
+// than discovered.
+function maskCodeBlocks(content) {
+  const s = String(content);
+  const raw = s.split('\n');
+  const blanked = blankFencedBlocks(s);
+  const info = classifyLines(blanked);
+  return raw.map((line, i) => {
+    const isCode = blanked[i] !== line || (info[i] && info[i].type === 'code');
+    return isCode ? ' '.repeat(line.length) : line;
+  }).join('\n');
+}
+
+// Where an HTML block that never closes begins, or -1. Reads the SAME
+// classification every other consumer reads rather than re-deciding it — the
+// module's one rule about not spelling a question twice.
+function unclosedHtmlBlockLine(content) {
+  const lines = blankFencedBlocks(String(content));
+  const info = classifyLines(lines);
+  const at = info.findIndex((c) => c && c.unclosed);
+  return at === -1 ? -1 : at + 1; // 1-based, for a message a human reads
+}
+
+// ---------------------------------------------------------------------------
+// PROPOSAL-084 — UNCERTAINTY DETECTORS.
+//
+// These answer a different KIND of question from everything above, and that
+// difference is the whole reason the feature is safe to ship on top of a parser
+// with known gaps. The checks above ask "where does this block END" — the
+// question whose edge cases the `DELIBERATELY DOES NOT IMPLEMENT` list is about.
+// These ask "is this SHAPE present anywhere in the file", which needs no block
+// extent, no container interior, and no arbiter. So a detector cannot inherit the
+// defect it warns about. Three of the four review rounds that evaluated this
+// proposal wrote prototypes and measured the false-positive rate on real corpora
+// (0/140, 0/151, 0/645) rather than reasoning about it.
+//
+// ⚠ THE ONE PLACE THAT CLAIM NEEDS QUALIFYING, stated here rather than left for
+// a reviewer to find: `unterminatedCommentLine` is combined with
+// `unclosedHtmlBlockLine` by its caller, which DOES read the classification. That
+// is deliberate and it is a differential, not a dependency — "there is an
+// unterminated comment, yet the document-level scan did not flag one" is exactly
+// what it means for the opener to be inside a container. If the classification is
+// wrong the detector goes quiet or gets noisy; it cannot manufacture a new silent
+// pass, because the silent pass is the state that exists TODAY.
+//
+// ⚠ Every detector runs on `blankFencedBlocks` output. That masker is a
+// self-contained fence scanner — it never calls `classifyLines` — so masking
+// cannot import the boundary bugs either. Fenced examples of these shapes (this
+// repo's own docs are full of them) therefore do not fire.
+// ⚠⚠ THAT SENTENCE IS TRUE ONLY FOR A FENCE THE MASKER CAN SEE, and it was stated
+// without the qualifier for eight rounds (`p084-xv8` finding 5). The masker works
+// on RAW document lines: `FENCE_OPEN_RE` carries `^ {0,3}`, and nothing strips a
+// container prefix first. So it misses exactly two things — a fence opened inside a
+// block quote (`> ` before the backticks), and a fence whose RAW indent is four
+// spaces or more. A comment inside either still reports `comment-inside-container`.
+// ⚠ "Four or more spaces of raw indent" is the whole rule, and an earlier version
+// of this note said "a deep list item's content column", which is wrong twice
+// (`p084-xv9` finding 3): it happens under an ordinary `- item` as soon as the
+// fence is indented four, and it does NOT happen at two or three however deep the
+// list is. Describing an accepted defect inaccurately is worse than not describing
+// it — the next maintainer acts on the description.
+// ⚠⚠ THE DIRECTION RECORDED HERE WAS WRONG, AND THE DECISION WAS TAKEN ON IT
+// (`p084-y2` finding 1). This said the gap costs only NOISE. Measured: an unmasked
+// fence's content is counted as section body, so quoting an upstream rule as an
+// example inside a block quote — or at raw indent four — makes the rule look PRESENT
+// while the live copy of it has been changed. Reproduced end to end: `All checks
+// passed` over a `_conventions.md` whose rule was switched off. **It costs silence
+// too.** The maintainer accepted this gap on 2026-08-09 believing it was noise-only;
+// that premise is retired.
+//
+// ⚠⚠ THE DECISION WAS RETAKEN ON THE CORRECTED PREMISE (maintainer, 2026-08-10) AND
+// THE GAP IS STILL ACCEPTED — as a temporary accepted RISK, owner maintainer, to be
+// paid before the `doctor-reader-gaps` proposal closes. Not as a resolved defect.
+// What settled it is that the obvious repair is WORSE, and measurably so
+// (`p084-sol1`): excluding the quoted lines from the section body **fabricates
+// markers that were never in the file**. Removal is not monotonic for substring
+// matching — drop a line and its neighbours become adjacent, and the marker
+// comparison collapses whitespace, so
+//     `The cascade result is` / <dropped line> / `a floor: rows may only escalate.`
+// reassembles into the very rule the file no longer states. Reproduced LF and CRLF:
+// a section that correctly reports `stale` today reports `current` after the repair.
+// Blanking the line instead of dropping it does not help, for the same reason.
+// ⚠ AND THE CLASS IS WIDER THAN FENCES, which is the part that makes a local patch
+// futile: substring matching cannot tell a RULE from PROSE ABOUT THAT RULE. An
+// indented example, a bare `> ` quotation and an ordinary sentence quoting the rule
+// all read as the live rule. The unmasked fence is one instance, not the class — so
+// closing it would move the next maintainer from a disclosed defect to an
+// undisclosed one, which is this proposal's own most expensive lesson.
+// The real repair is one walker emitting ordered evidence segments with HARD
+// boundaries that matching cannot cross, plus a declarative required/forbidden
+// direction policy — a redesign, out of this proposal's scope, tracked in
+// `planning/opt-in-backlog.md` under `doctor-reader-gaps`.
+// Pinned as-is so it cannot change without someone meeting the decision again.
+//
+// ⚠ DIRECTION RULE FOR ADDING ONE: a detector may be noisy, never silent. Where
+// the shape is ambiguous, do not fire. A false warning is visible and the user
+// can dismiss it; a missed shape restores exactly the silence this exists to
+// break. Gap D from the proposal is the worked example of the limit — its
+// prototype false-fired 5 times in 151 files, and it is deliberately NOT built,
+// because for that shape the warning really is worse than the gap.
+// ---------------------------------------------------------------------------
+
+// Which positions on one line sit inside a CommonMark code span. Needed because
+// `` `<!-- x -->` `` IS rendered — a reader sees it — so flagging it would be a
+// plain false positive. Measured: the probe's I3 control.
+//
+// ⚠ Line-level, and that is a stated limit rather than an oversight: a code span
+// may legally straddle lines. There the mask under-covers, so a straddling span
+// could produce a NOISY hit, which is the acceptable direction.
+//
+// ⚠⚠ A BACKSLASH SUPPRESSES A BACKTICK ONLY WHILE NO SPAN IS OPEN, and getting
+// this wrong has produced a silent pass TWICE, from opposite sides
+// (`p084-xv2`, then `p084-xv3` on the repair). CommonMark §6.1: backslash escapes
+// do not work inside a code span — so whether a backtick "is escaped" depends on
+// whether a span is already open, which is the very thing this function computes.
+// The first repair asked the question as a PRE-PASS, filtering escaped backticks
+// out before pairing, and that is circular. It cost a new blocker: in
+// `` `foo\` <!-- rule --> `` the real closing delimiter was discarded as escaped,
+// the opener paired with a later run instead, and the mask swallowed a comment a
+// reader never sees while doctor went on reading it.
+//
+// So this is a single left-to-right scan, which is what an inline parser actually
+// does: an escape consumes the next character while looking for an OPENER, and the
+// search for the CLOSER is raw. `` `foo\` `` is a code span whose content is
+// `foo\`, exactly as the reference renderer has it.
+function codeSpanMask(line) {
+  const mask = new Array(line.length).fill(false);
+  let i = 0;
+  while (i < line.length) {
+    // No span is open here, so a backslash consumes the character after it and an
+    // escaped backtick is plain text that opens nothing.
+    if (line[i] === '\\') { i += 2; continue; }
+    if (line[i] !== '`') { i += 1; continue; }
+    let openEnd = i;
+    while (openEnd < line.length && line[openEnd] === '`') openEnd += 1;
+    const len = openEnd - i;
+    // CommonMark pairs a backtick run with the next run of EQUAL length. No
+    // backslash handling in here — see the note above; that is the whole fix.
+    let closeStart = -1;
+    for (let j = openEnd; j < line.length;) {
+      if (line[j] !== '`') { j += 1; continue; }
+      let k = j;
+      while (k < line.length && line[k] === '`') k += 1;
+      if (k - j === len) { closeStart = j; break; }
+      j = k;
+    }
+    // An unpaired run is literal text. Resume just past it rather than past the
+    // whole line, so a later run on the same line can still open a span.
+    if (closeStart === -1) { i = openEnd; continue; }
+    for (let p = i; p < closeStart + len; p += 1) mask[p] = true;
+    i = closeStart + len;
+  }
+  return mask;
+}
+
+// Every live `<!--` on a line, as column offsets. CommonMark parses code spans
+// and backslash escapes only in inline content. Inside a raw-HTML block the line
+// is passed through as HTML, so neither syntax can make an apparent opener
+// visible to the reader.
+function commentOpenersOutsideCode(line, inlineSyntaxApplies = true) {
+  const mask = inlineSyntaxApplies ? codeSpanMask(line) : [];
+  const out = [];
+  for (let at = line.indexOf('<!--'); at !== -1; at = line.indexOf('<!--', at + 4)) {
+    if (mask[at]) continue;
+    // CommonMark backslash escaping is parity-based: an odd run escapes `<`, so
+    // `\<!--` is visible text; an even run leaves `<` live, so `\\<!--` still
+    // opens a comment after rendering one literal backslash. Count at the opener
+    // rather than stripping escapes globally — codeSpanMask owns backticks, and
+    // changing its input would move the offsets the two decisions share.
+    let backslashes = 0;
+    for (let p = at - 1; p >= 0 && line[p] === '\\'; p -= 1) backslashes += 1;
+    if (!inlineSyntaxApplies || backslashes % 2 === 0) out.push(at);
+  }
+  return out;
+}
+
+// GAP I and the container half of gap A. Both answer ONE question — **is there a
+// comment whose text this module still counts as live?** — and they are split only
+// because the two causes need different repair advice.
+//
+// ⚠⚠ THE ARBITER IS `classifyLines`, NOT A REGEX, AND THAT IS THE WHOLE FIX
+// (`p084-y1` findings 1, 2 and 5). The first version asked
+// `HTML_COMMENT_OPEN_RE.test(line)` — a DOCUMENT-LEVEL opener rule — to decide
+// whether a line's leading `<!--` opened a block. Inside a list item it does not:
+// `- x` / `  <!-- rule -->` is typed `list`, its text stays live, and a reader
+// sees nothing. That shape fired NOTHING, and it is exactly where the shipped
+// repair advice ("put the comment on a line of its own") sent the user — out of a
+// disclosed silent pass and into an undisclosed one. Restating a rule the
+// classifier already owns is this module's oldest defect; the module's own rule
+// says callers READ LABELS. So these read labels.
+//
+// ⚠ It also retires a detector. The previous `unclosed-html-in-container` fired on
+// "an unterminated comment that the document-level scan did not flag", which is
+// not the shape that hurts: measured, ANY later `-->` anywhere in the file —
+// including the one `unclosed-html-block`'s own action tells the user to add —
+// silenced it while the rule stayed hidden from readers. A check that keeps being
+// defeated a new way is mis-scoped, not under-specified. What actually matters is
+// "is the text hidden from a reader but not from us", and termination has nothing
+// to do with it.
+//
+// ⚠ Lines the classifier calls `code` are skipped in both: a reader sees indented
+// code verbatim, so there is no divergence to report and a warning there is the
+// pure noise gap D was rejected for.
+
+function commentContext(content) {
+  const lines = blankFencedBlocks(String(content));
+  return { lines, info: classifyLines(lines) };
+}
+
+// Everything that can legitimately sit between the start of a line and the start of
+// that line's CONTENT: indentation, block-quote markers, list markers. Built from
+// the same marker fragments the list predicates use, so widening a marker cannot
+// leave this behind — the reason `BULLET_MARKER` exists as a fragment at all.
+//
+// ⚠ It exists so `> <!-- rule -->` is judged as a comment that STARTS its content
+// (the container case) rather than as a mid-line one. Getting that wrong picks the
+// wrong id and prints repair advice for the wrong shape; both ids disclose, so the
+// cost is a confusing message rather than a silent pass.
+const CONTAINER_PREFIX_ONLY_RE = new RegExp(`^(?:[ \\t>]|${BULLET_MARKER}|${ORDERED_MARKER})*$`);
+function startsContent(line, at) {
+  return CONTAINER_PREFIX_ONLY_RE.test(line.slice(0, at));
+}
+
+// ⚠⚠ ONE ANSWER TO "IS THIS LINE INSIDE A CONTAINER WHOSE INTERIOR THIS MODULE
+// DOES NOT PARSE", read by every detector that needs it (`p084-xv3` finding 3).
+// The comment detectors spelled `list | blockquote | html` and the two boundary
+// detectors spelled `list | blockquote`, so a `<custom-element>` inside
+// `<details>` was container content to one and a document-level divergence to the
+// other — and only the second one warned about it. That is the same
+// two-rival-predicates shape `commentDisposition` exists to retire, one level up:
+// retiring it for the comment ids and leaving the neighbours to restate it is how
+// the class survived. Adding a container type now reaches every reader at once.
+//
+// ⚠ Deliberately NOT a block decision. Nothing here decides where a block starts
+// or ends — `classifyLines` has already done that, and this only reads the label
+// it produced. Being wrong here makes a warning noisy or absent; it cannot move a
+// boundary.
+const UNPARSED_CONTAINER_TYPES = ['list', 'blockquote', 'html'];
+function inUnparsedContainer(c) {
+  return !!c && UNPARSED_CONTAINER_TYPES.includes(c.type);
+}
+
+// GAP I — a comment that begins part-way through a line. It is an inline span, not
+// a block, so every consumer counts its contents as live document text while a
+// reader sees nothing. Two shapes: `prose <!-- rule -->`, and a SECOND comment on a
+// line that opens with one (`<!-- a --> <!-- rule -->`), because only the first
+// span is ever masked.
+// ⚠⚠ ONE FUNCTION DECIDES WHICH ID OWNS A LINE, and the two exported detectors are
+// views over it. Two independent predicates is how the first version left a hole:
+// `p084-xv1` found a comment at column 0 inside a `<details>` block that fell into
+// NEITHER id — the container detector skipped it because the line is typed `html`,
+// the inline detector skipped it because the comment starts the line's content, and
+// `parseContextLine` happily returned a policy value the reader cannot see. A
+// partition has to be written as a partition or its gaps are invisible.
+//
+// ⚠ `blockStart` is the field that makes this decidable, and it exists because the
+// previous batch stopped rebuilding what the classifier knows and had it carry the
+// answer instead. A comment line inside a type-6 block reports the ENCLOSING
+// block's start, not its own index — which is exactly the difference between "this
+// comment opened a block, so its text really is hidden" and "this comment is
+// sitting inside someone else's block, where its text is still read".
+//
+// Returns 'inline', 'container', or null (nothing to report on this line).
+function commentDisposition(lines, info, i) {
+  const c = info[i];
+  if (!c || c.type === 'code') return null; // indented code renders verbatim
+  const line = lines[i];
+  // ⚠⚠ ASK WHAT THE CHECKS ACTUALLY READ, rather than guessing from the line's
+  // type. `invisible` is NOT a whole-line boolean — it pairs with `visibleFrom`,
+  // and `classifiedVisible` blanks only up to that column. So `<!-- a --> <!-- b -->`
+  // is `invisible: true, visibleFrom: 10`: the first span is masked and the tail is
+  // live, which is the documented "only the FIRST span is masked" gap. Treating
+  // `invisible` as "this line is hidden" silently dropped that whole shape — caught
+  // by re-running the earlier round's own fixtures after this function was
+  // rewritten, which is the only reason it did not ship.
+  const hiddenUpTo = c.invisible ? (c.visibleFrom === undefined ? line.length : c.visibleFrom) : 0;
+  // The openers whose text survives into what every check reads. One inside the
+  // masked region cannot mislead anyone and is not a finding.
+  // ⚠ A comment inside a `<textarea>` IS reported here, deliberately — see the
+  // block headed `THERE IS NO TEXTAREA EXEMPTION HERE` for why that exemption was
+  // removed rather than fixed a fourth time. (Grep that phrase — an earlier version of
+  // this pointer named a FUNCTION and was ~700 lines off, `p084-y2` finding 5.)
+  const live = commentOpenersOutsideCode(line, c.type !== 'html' && !c.rawHtml).filter((at) => at >= hiddenUpTo);
+  if (live.length === 0) return null;
+  // A prefix only counts as container prefix when the classifier agrees the line is
+  // in a container. `2. <!-- x -->` continuing a paragraph LOOKS like an ordered
+  // item and is prose (`p084-xv1`), so shape alone picks the wrong id and prints
+  // repair advice about leaving a container the user is not in.
+  return (inUnparsedContainer(c) && startsContent(line, live[0])) ? 'container' : 'inline';
+}
+
+function inlineHtmlCommentLine(content) {
+  const { lines, info } = commentContext(content);
+  for (let i = 0; i < lines.length; i += 1) {
+    if (commentDisposition(lines, info, i) === 'inline') return i + 1;
+  }
+  return -1;
+}
+
+// The container half of GAP A — the comment DOES begin its line, but the line sits
+// inside a list item or block quote, whose interior this module does not parse as
+// its own block sequence. So no HTML block opens, the text stays live, and the
+// reader loses it. The repair differs from the inline case, which is why it has its
+// own id: moving such a comment "onto its own line" changes nothing.
+function containerHtmlCommentLine(content) {
+  const { lines, info } = commentContext(content);
+  for (let i = 0; i < lines.length; i += 1) {
+    if (commentDisposition(lines, info, i) === 'container') return i + 1;
+  }
+  return -1;
+}
+
+// GAP B — HTML block type 7 (a complete tag whose name is NOT in the type-6 list,
+// alone on a line). Deliberately not implemented: it is the only type that cannot
+// interrupt a paragraph and recognizing it needs a real tag parser.
+//
+// The trigger is narrow and comes from the measured differential rather than from
+// imagination: a bare `<custom-element>` line at a block start, directly followed
+// by a setext underline (`---` / `===`). Ours ends the section EARLY where the
+// reference continues it, so the usual user-visible failure is a false `stale`.
+// It is worth disclosing, because a `stale` a user cannot reproduce is what
+// teaches them to stop believing the tool.
+// ⚠⚠ BUT IT IS NOT ONLY LOUD, AND THIS COMMENT SAID IT WAS FOR MANY ROUNDS
+// (`p084-y2` finding 3; still stale here after that finding was fixed in the
+// shipped `detail` and both pages — `p084-sol2` finding 3 caught the leftover).
+// Ending the section early also DROPS ITS TAIL, and the `CONVENTIONS_RETIRED`
+// fingerprints report on what is PRESENT in a body — so a retired row below the
+// shape stops being seen and its finding disappears. Measured: control reports
+// `ceremony-ef-tweak-t3:retired`, the same row under a `<my-widget>` / `---`
+// pair reports nothing. Say "unknown in BOTH directions", never "loud".
+// ⚠ The malformed-table shape has the mirror-image of this defect for the same
+// reason — they are one mechanism (a moved section boundary) that used to wear
+// two ids. It no longer has a detector; see GAP C below for why.
+// ⚠⚠ KEEP THE TWO HALVES OF THIS ID'S `detail` APART, because they say opposite
+// things and an earlier version of this very comment ran them together. For
+// type 7 the BOUNDARY moves ONE way — the section ends EARLIER than the reader's
+// does — while the RESULTS are unknown in BOTH directions, because ending early
+// drops the tail and a retired row down there stops being seen. "Both directions"
+// is true of the results and false of the boundary. Do not "fix" the shipped
+// `detail` into saying the boundary moves both ways; that is a different id's
+// shape, and this distinction has now been got wrong twice in opposite
+// directions (`doctor-table-boundary-account` in `planning/opt-in-backlog.md`).
+// ⚠⚠ A CLOSING TAG OPENS TYPE 7 TOO, and leaving it out made the id's own docs
+// describe a shape wider than the detector found (`p084-xv5` finding 2).
+// CommonMark's start condition is "a complete open tag … **or a complete closing
+// tag**, followed by only whitespace or the end of the line". Measured:
+// `</my-widget>` above `---` is one raw HTML block to the reference renderer and a
+// setext heading to this module — the divergence the id exists to disclose — and
+// the detector returned -1 on it. Undisclosed, which is the direction that matters.
+// ⚠⚠ THE TWO FORMS NEED DIFFERENT TAILS, and sharing them was a false positive
+// (`p084-xv6` finding 2). A closing tag may carry NEITHER attributes nor a `/`:
+// CommonMark's "complete closing tag" is `</`, a name, optional whitespace, `>`.
+// So `</my-widget attr>` and `</my-widget/>` are ordinary paragraph text, `---`
+// below them really is a setext heading, and this module ALREADY agrees with the
+// spec there — nothing diverges, and firing was noise on a shape that is not a tag.
+// ⚠ The tag-name shape is still spelled ONCE, as a fragment, which is what the
+// "no second nearly-identical regex" rule actually asks for — the previous version
+// obeyed the letter of that rule by sharing a tail that does not belong to both.
+// ⚠ `m[1] || m[2]`: the two branches capture into different groups. A reader
+// changing this must keep the detector's `name` lookup in step.
+//
+// ⚠⚠ THE OPEN-TAG TAIL IS THE SPEC'S GRAMMAR, NOT AN APPROXIMATION OF IT, and the
+// approximation it replaces produced the exact failure this whole proposal exists
+// to prevent (`p084-xv7`, blocker). The tail used to be `(?:[ \t][^<>]*)?` — "any
+// run without angle brackets" — which forbids `>`. CommonMark's raw-HTML grammar
+// ALLOWS `>` inside a quoted attribute value, so `<my-widget title="a > b">` is a
+// complete open tag, starts HTML block type 7, and swallows the `---` below it.
+// This module reads that `---` as a setext heading instead. Measured end to end in
+// a real project: the divergence was there, no detector fired, and doctor printed
+// `All checks passed` over a section that was genuinely stale underneath.
+// The same approximation was loose in the other direction — `<my-widget =x>` and
+// `<my-widget "x">` are not tags at all, this module agrees with the spec about
+// them, and the detector was firing anyway.
+//
+// So the productions are transcribed rather than guessed, each named after the
+// spec's own name for it. `[ \t]` and never `\s`, for the reason given at
+// `ATX_HEADING_RE`; a line-level detector cannot see the spec's multi-line
+// whitespace and does not need to.
+const BARE_TAG_NAME = '[A-Za-z][A-Za-z0-9-]*';
+const HTML_ATTR_NAME = '[A-Za-z_:][A-Za-z0-9_.:-]*';
+// unquoted | single-quoted | double-quoted. The quoted forms are why `>` cannot be
+// excluded wholesale.
+const HTML_ATTR_VALUE = '(?:[^ \\t"\'=<>`]+|\'[^\']*\'|"[^"]*")';
+const HTML_ATTR = `(?:[ \\t]+${HTML_ATTR_NAME}(?:[ \\t]*=[ \\t]*${HTML_ATTR_VALUE})?)`;
+const BARE_TAG_LINE_RE = new RegExp(
+  `^ {0,3}<(?:(${BARE_TAG_NAME})${HTML_ATTR}*[ \\t]*\\/?|\\/(${BARE_TAG_NAME})[ \\t]*)>[ \\t]*$`
+);
+function htmlBlockType7Line(content) {
+  const lines = blankFencedBlocks(String(content));
+  const info = classifyLines(lines);
+  const type6 = new RegExp(`^(?:${HTML_BLOCK_TAGS})$`, 'i');
+  for (let i = 0; i < lines.length - 1; i += 1) {
+    const m = lines[i].match(BARE_TAG_LINE_RE);
+    const openName = m && m[1];   // complete open tag
+    const closeName = m && m[2];  // complete closing tag
+    const name = openName || closeName;
+    if (!name || type6.test(name)) continue;
+    // ⚠⚠ CommonMark §4.6 attaches the name exclusion to the OPEN-TAG form only:
+    // "a complete open tag (with any tag name other than pre, script, style, or
+    // textarea) **or a complete closing tag**". So `<pre/>` is not type 7 and
+    // `</pre>` is. Relying on the classifier for this was not enough
+    // (`p084-xv8` finding 4): `htmlBlockStart` recognises `<pre>` — the name
+    // followed by space, `>` or end of line — but NOT `<pre/>`, where a `/`
+    // follows the name, so that line stayed `paragraph`, escaped the container
+    // skip, and got reported as a divergence that does not exist.
+    if (openName && HTML_TYPE1_NAME_RE.test(openName)) continue;
+    if (!SETEXT_UNDERLINE_RE.test(lines[i + 1])) continue;
+    // ⚠ Inside a container nothing at DOCUMENT level moves, so the divergence this
+    // id describes does not occur there (`p084-xv2`, widened to HTML blocks by
+    // `p084-xv3`). The shape is about a section boundary shifting; a
+    // `<custom-element>` sitting in a list — or inside `<details>` — is container
+    // content to both readings. Firing there is noise on legitimate content.
+    // ⚠ At document level this shape's line is typed `paragraph`, never `html`
+    // (the module does not implement type 7 — that is the whole gap), so reading
+    // the shared container predicate here cannot silence the detector's real case.
+    if (inUnparsedContainer(info[i])) continue;
+    // ⚠ THE BLOCK-START TEST IS NOT OPTIONAL, and leaving it out was a false
+    // positive both doc pages already excluded in words ("standing alone at the
+    // START of a block") — `p084-y1` finding 7. Type 7 is defined by being the one
+    // HTML block that CANNOT interrupt a paragraph, so a bare tag continuing a
+    // paragraph is not type 7 at all: `some prose` / `<my-widget>` / `---` is a
+    // setext heading to CommonMark and this module already agrees with that. Firing
+    // there reports a divergence that does not exist.
+    if (i > 0 && info[i - 1] && info[i - 1].type === 'paragraph') continue;
+    return i + 1;
+  }
+  return -1;
+}
+
+// GAP C — a table whose delimiter row carries a different number of cells from
+// its header. GFM treats that pair as ordinary prose (it is not a table at all)
+// while `classifyLines` opens a table, so the two can disagree about where a
+// section ends, and `conventionsSectionBodies` then reads a different span than
+// the reader sees.
+//
+// ⚠⚠ THERE IS DELIBERATELY NO DETECTOR FOR THIS (user decision, 2026-08-12), and
+// the reason is worth the space because the obvious next move is to write one.
+// P-084 shipped one and then spent SIX review rounds on it. Every round found a
+// document it stayed silent on, and silence is the direction that prints
+// `All checks passed` over a file that has drifted:
+//   `p084gate-x7`   the bare mismatched pair
+//   `p084gate-y3`   a multi-line prose run before a dash underline
+//   `p084gate-y4`   the whole equals-underline family
+//   `x13`/`y5`      a prose run whose FIRST line is underline-shaped
+//   `x14`/`y6`      a prose run whose first line is INDENTED
+//   `p084gate-y7`   a delimiter row written with single hyphens, which GFM
+//                   accepts and `TABLE_DELIMITER_ROW_RE` does not
+// The first five were an enumeration inside the detector, and removing that
+// enumeration did not help: the sixth was the same failure living in the
+// delimiter-row recogniser instead. **An enumeration cannot be finished from the
+// inside**, and each unfinished edge fails silently.
+// ⚠ What settled it was a measurement rather than fatigue. `p084gate-y6`
+// reproduced the identical silent false clean with a delimiter row whose cell
+// count was CORRECT. So the harm is section-boundary disagreement, the detector's
+// scope was cell-count mismatch, and the second is a strict subset of the first —
+// no version of this detector, narrow or broad, could close the harm it was
+// written for.
+// ⚠⚠ The durable fix is a different instrument: `marked` is already a runtime
+// dependency of this package (`dflow render` uses it), so the section boundary
+// can be taken FROM the renderer rather than guessed alongside it and compared
+// shape by shape. That is a design change with its own review. It is recorded,
+// with owner and gate, as `doctor-section-boundary-arbiter` in
+// `planning/opt-in-backlog.md`, and both explainer pages name this gap under
+// "shapes that are known and deliberately not reported".
+// ⚠ `TABLE_DELIMITER_ROW_RE` stays — `classifyLines` and
+// `hasTableWithoutConventionComment` both use it. Its `-{2,}` is narrower than
+// GFM's `-{1,}` (`p084gate-y7`); that is now a classifier property with no
+// detector resting on it, and widening it would change what counts as a table
+// across this module.
+// Kept for callers that only need the first match.
+function conventionsSectionBody(content, heading) {
+  const bodies = conventionsSectionBodies(content, heading);
+  return bodies.length === 0 ? null : bodies[0];
+}
+
+// Each `marker` is verified present in BOTH packaged templates (or, where the
+// section is edition-specific, in the edition that has it).
+// `test/upgrade-drift.mjs` re-derives that from the packaged templates rather
+// than trusting this comment.
+//
+// ⚠ BE PRECISE ABOUT WHICH HALF IS MECHANICAL. This sentence used to also claim
+// each marker is "absent from the pre-P082 shape", with the same
+// "re-derives that" clause covering both halves. Only the presence half is
+// re-derived; nothing in the tree checks the absence half (`p082-b3-g1`
+// finding 4). The risk it leaves is real and worth naming: a marker phrase that
+// ALREADY existed in the old text would make an un-migrated file report
+// `current` — silence about a stale file, the false-negative direction.
+// It is not mechanized because the only source for the old shape is git
+// history, and a test that shells out to git cannot run from the published
+// tarball, where there is no `.git`. So it stays a review obligation: when you
+// add a marker, check it against the pre-P082 text yourself.
+// `missingLevel` is per-fingerprint on purpose. `### SPEC-ID Format` was
+// re-parented by 59e0eb2 and no released version ever projected it, so EVERY
+// existing project is legitimately `missing` there — info. The other two
+// sections HAVE always shipped, so their absence means the file was edited or
+// predates them, which is worth a warn. A blanket info also mis-reported a
+// merely RENAMED heading as "projects created before this section shipped do
+// not have it at all", which is a false statement about a file that has it.
+const CONVENTIONS_FINGERPRINTS = [
+  {
+    id: 'ceremony-escalate-only',
+    heading: 'Ceremony Scaling (Project Application)',
+    marker: 'cascade result is a floor',
+    editions: null,
+    missingLevel: 'warn',
+    rule: 'the escalate-only rule (project rows may raise a tier, never lower it)',
+    consequence: 'Without it the table reads as a free re-classification surface, so a project row can lower a tier the cascade raised — the drift PROPOSAL-082 closed.'
+  },
+  {
+    id: 'spec-files-no-br-families',
+    heading: 'Filling the Templates',
+    marker: 'no-BR family variants',
+    editions: null,
+    missingLevel: 'warn',
+    rule: 'the no-BR family variants of `lightweight-spec.md`',
+    consequence: 'Without them the table implies a T2 always carries a BR delta, so a presentation / contract / operational / performance change gets a fabricated BR-ID to satisfy a rule that no longer exists.'
+  },
+  {
+    id: 'spec-id-minimal-host',
+    heading: 'SPEC-ID Format',
+    marker: 'Minimal (zero-phase) host exception',
+    editions: null,
+    missingLevel: 'info',
+    neverProjected: true,
+    rule: 'the minimal (zero-phase) host exception',
+    consequence: 'Without it the section still says the SPEC-ID appears in the first phase-spec filename and the branch name, which a zero-phase host has no way to satisfy — and a functional-bug host carries a BUG-NUMBER branch instead.'
+  }
+];
+
+// The second fingerprint kind: strings PROPOSAL-082 retired, which must not
+// still be sitting in an adopter's file. These need no new upstream contract —
+// the evidence is that batch 1 deleted them from both packaged templates — so
+// unlike the gf DDD-Modeling-Depth fingerprint (which has no marker to pin and
+// is recorded as debt 10), there is nothing blocking them.
+//
+// Every string below is verified zero-match in both packaged templates AND both
+// tutorial fixtures; `test/upgrade-drift.mjs` re-derives that rather than
+// trusting this comment. A retired string that still matched the current
+// template would fire on every project forever.
+const CONVENTIONS_RETIRED = [
+  {
+    id: 'ceremony-ef-tweak-t3',
+    heading: 'Ceremony Scaling (Project Application)',
+    retired: 'T3 if no Domain change',
+    editions: null,
+    rule: 'the retired "EF configuration tweak → T3 if no Domain change" example row',
+    consequence: 'Under the ordered cascade an Infrastructure mapping tweak is not automatically T3 — the packaged template now uses that row to show a project ESCALATING it, and the old row teaches the opposite.'
+  },
+  {
+    id: 'ceremony-query-only-t2',
+    heading: 'Ceremony Scaling (Project Application)',
+    // Anchored through the TIER cell, not just the situation. The situation
+    // alone flagged `| Adding a Query only (no write) | T1 (project convention) |
+    // We escalate all new reads |` — a row an adopter migrated CORRECTLY into
+    // the form the current template teaches — and then told them to overwrite it.
+    // The claim is about a row that restates a bare tier, so the anchor has to
+    // include the bare tier. Sibling `ceremony-ef-tweak-t3` never had this
+    // problem because its anchor was already the tier cell.
+    retired: 'Adding a Query only (no write)} | T2',
+    editions: null,
+    rule: 'the retired "Adding a Query only (no write) → T2" example row',
+    consequence: 'The cascade decides this now; the row restated a tier instead of recording a project decision, which is the drift the escalate-only rule was added to stop.'
+  },
+  {
+    id: 'ceremony-criteria-table',
+    heading: 'Ceremony Scaling (Project Application)',
+    // Anchored on enough of the retired sentence to be implausible as adopter
+    // prose. Two shorter anchors were tried and both trip on legitimate text:
+    // `criteria table` matches "Our own criteria table below records the
+    // escalations we apply", and `for the full criteria table` still matches
+    // "see that document for the full criteria table" — a generic five-word
+    // English construction. The retired text was "See `AI-AGENT-GUIDE.md`
+    // § Ceremony Scaling for the full criteria table.", soft-wrapped between
+    // "full" and "criteria"; `normalizeForMarker` collapses that, so including
+    // the § name costs nothing and no longer matches ordinary sentences.
+    retired: 'Ceremony Scaling for the full criteria table',
+    editions: null,
+    rule: 'the retired pointer to a "criteria table" in AI-AGENT-GUIDE.md',
+    consequence: 'That table was replaced by the ordered cascade. A file still pointing at it sends the reader to a section that no longer exists under that name.'
+  },
+  {
+    id: 'spec-files-br-delta-equation',
+    heading: 'Filling the Templates',
+    retired: 'bug fix / small tweak with BR Delta',
+    editions: null,
+    rule: 'the retired "T2 Light — bug fix / small tweak with BR Delta" row',
+    consequence: 'It equates T2 with carrying a BR Delta, which the no-BR families retired — the same equation that made people fabricate BR-IDs.'
+  }
+];
+
+// Markers are matched against whitespace-normalized text. `_conventions.md` is
+// user-owned and reflowing a paragraph is an ordinary edit; matching raw made a
+// soft-wrap inside the marker report a false `stale`.
+function normalizeForMarker(text) {
+  return String(text).replace(/\s+/g, ' ');
+}
+
+// ⚠ INHERENT LIMIT, stated rather than papered over: these are heuristic
+// substring checks (PROPOSAL-082 specifies them as such — 字串偵測, following
+// the P058 starter-drift precedent). A substring cannot tell a rule from a
+// sentence ABOUT the rule, so text like "we removed the old rule that the
+// cascade result is a floor" satisfies the fingerprint and reports `current`.
+// That is a false negative on a deliberately-worded file, not on drift, and no
+// amount of matching harder fixes it — deciding it needs to read meaning.
+// Do not describe this check as proving a project's conventions are correct;
+// it detects the shapes that arise from a file predating a contract change.
+//
+// ⚠ The `retired` kind fails in the OPPOSITE direction, and the two must not be
+// conflated. A `marker` that is too short yields a false NEGATIVE (silence); a
+// `retired` string that is too short yields a false POSITIVE — doctor telling a
+// developer their own sentence is retired Dflow text. So a retired entry must
+// be anchored on enough of the original sentence to be implausible as adopter
+// prose, and `test/upgrade-drift.mjs` asserts each is zero-match against both
+// packaged templates and both tutorial fixtures.
+//
+// Returns one entry per fingerprint that is not `current`. `edition` selects
+// edition-specific fingerprints; pass null to evaluate only the shared ones.
+// Whether an entry applies to the edition being checked. `editions: null` means
+// "shared, applies everywhere"; a list means the entry is only meaningful for
+// those editions and a caller that did not resolve an edition must not see it.
+//
+// Extracted from the two identical inline conditions below because every shipped
+// entry currently has `editions: null`, which makes the non-null path dead and
+// therefore unproven (`p082-b3-g1` finding 5). It is NOT speculative — debt 10
+// (the greenfield DDD-Modeling-Depth fingerprint) is a known future
+// edition-specific entry, blocked only on an upstream marker to pin. So the
+// branch is kept and tested here instead of being deleted and rewritten
+// untested at the moment someone is busy thinking about something else.
+function fingerprintAppliesTo(fp, edition) {
+  if (!fp.editions) return true;
+  return Boolean(edition) && fp.editions.includes(edition);
+}
+
+function findConventionsDrift(content, edition = null) {
+  // No early return for empty input. It used to short-circuit to `[]`, which
+  // made a whitespace-only file report NOTHING while a one-character file
+  // reported all three sections missing — the emptier file getting the cleaner
+  // verdict, and the gate silently accepting absence, which is the exact thing
+  // this module says it exists to prevent. Empty content genuinely has every
+  // section missing, so it says so; the caller collapses that into one finding.
+  const text = String(content || '');
+  const drift = [];
+  for (const fp of CONVENTIONS_FINGERPRINTS) {
+    if (!fingerprintAppliesTo(fp, edition)) continue;
+    const bodies = conventionsSectionBodies(text, fp.heading);
+    const base = {
+      id: fp.id,
+      heading: fp.heading,
+      rule: fp.rule,
+      consequence: fp.consequence,
+      neverProjected: Boolean(fp.neverProjected)
+    };
+    if (bodies.length === 0) {
+      drift.push({ ...base, state: 'missing', level: fp.missingLevel || 'warn' });
+      continue;
+    }
+    const marker = normalizeForMarker(fp.marker);
+    // Any copy of the section carrying the rule is enough.
+    if (!bodies.some((body) => normalizeForMarker(body).includes(marker))) {
+      drift.push({ ...base, state: 'stale', level: 'warn' });
+    }
+  }
+  for (const fp of CONVENTIONS_RETIRED) {
+    if (!fingerprintAppliesTo(fp, edition)) continue;
+    const bodies = conventionsSectionBodies(text, fp.heading);
+    // A section that is absent cannot carry a retired string. Its absence is
+    // already reported by the `requires` fingerprint on the same heading, so
+    // saying nothing here is not silence about an unchecked state.
+    if (bodies.length === 0) continue;
+    const retired = normalizeForMarker(fp.retired);
+    if (bodies.some((body) => normalizeForMarker(body).includes(retired))) {
+      drift.push({
+        id: fp.id,
+        state: 'retired',
+        level: 'warn',
+        heading: fp.heading,
+        rule: fp.rule,
+        consequence: fp.consequence,
+        neverProjected: false
+      });
+    }
+  }
+  return drift;
+}
+
+// --- PROPOSAL-092: shape markers and template skeletons ------------------------
+//
+// Every template an adopter's document is created from carries one line naming
+// its track, its template and the number of the shape it has:
+//
+//   <!-- dflow-shape: greenfield/rules.md 1 — keep this line: dflow doctor reads it -->
+//
+// The document inherits the line when it is created from the template, so
+// doctor can compare the number with the template's current one. Same number:
+// every difference between the document and the template is the adopter's own
+// decision, and nothing is reported — which is the distinction a comparison
+// alone cannot make (six OBTS `rules.md` files written one consistent way, not
+// the template's). Older number: the registry (`lib/doc-shapes.json`) says what
+// changed between the two numbers.
+//
+// ⚠ Only the three fields are read. Whatever follows the number up to `-->` is
+// the note for the reader and is not validated: an AI that re-words the note has
+// not changed what the line records.
+const crypto = require('node:crypto');
+
+const SHAPE_MARKER_MENTION = 'dflow-shape:';
+// The note after the number stops at a line break of either kind: in a file
+// with lone-CR line breaks it would otherwise swallow the next line — another
+// marker included — and pass the doc as read.
+const SHAPE_MARKER_RE = /^<!-- dflow-shape: ([a-z]+)\/([A-Za-z0-9_.-]+\.md) ([1-9][0-9]*)(?: [^\r\n]*)? -->[ \t]*$/;
+
+// Stage one of two: every line that mentions `dflow-shape:`, wherever it sits —
+// in a fence, a comment, a list, a quote, an HTML block.
+// ⚠ Doctor does not decide which of those lines is live (PROPOSAL-092 D2).
+// Deciding means reading every container exactly the way `dflow render`
+// (`marked`) reads it, and the two readings are hard to keep aligned. A mention
+// anywhere but the standard position makes the doc unreadable instead: saying
+// "cannot tell" never reports a doc doctor did not read as passing.
+// ⚠ Finding and validating stay separate: validating while finding would let one
+// valid line plus one broken line count as "exactly one marker", and would let a
+// doc whose only marker is broken count as unmarked.
+function findShapeMarkerLines(content) {
+  const found = [];
+  String(content).split('\n').forEach((line, i) => {
+    if (line.includes(SHAPE_MARKER_MENTION)) found.push({ line: i + 1, text: line.replace(/\r$/, '') });
+  });
+  return found;
+}
+
+// The one line a marker is read from: line 1, or the line after the
+// frontmatter's closing `---` — the frontmatter rule `dflow render` uses, which
+// is also where every template puts its marker. 1-based.
+// ⚠ Found in the text as it is, a byte-order mark included: render does not
+// skip one, so a BOM in front of `---` leaves the file with no frontmatter — for
+// render, and so for doctor. Skipping it here alone would read a marker that
+// render shows as body text.
+function shapeMarkerStandardLine(content) {
+  return frontmatterLineCount(String(content).split('\n')) + 1;
+}
+
+// Stage two. `absent`: no line mentions it. `ok`: exactly one line mentions it,
+// that line is the standard one, and it parses. Anything else is `unreadable`,
+// with the reason — `multiple`, `misplaced` (`standard` is the line it belongs
+// on; `bomHidesFrontmatter` when a BOM is what hides the frontmatter above it)
+// or `malformed`. Whether the track and template name exist is the caller's
+// question: it needs the registry, and this module does no I/O.
+function readShapeMarker(content) {
+  const raw = String(content);
+  // A BOM is not a line: line numbers and the marker's own text are read without it.
+  const text = raw.replace(/^\uFEFF/, '');
+  const found = findShapeMarkerLines(text);
+  if (found.length === 0) return { state: 'absent' };
+  if (found.length > 1) {
+    return { state: 'unreadable', reason: 'multiple', lines: found.map((f) => f.line) };
+  }
+  const standard = shapeMarkerStandardLine(raw);
+  if (found[0].line !== standard) {
+    const misplaced = { state: 'unreadable', reason: 'misplaced', lines: [found[0].line], standard };
+    if (text !== raw && frontmatterLineCount(text.split('\n')) > 0) misplaced.bomHidesFrontmatter = true;
+    return misplaced;
+  }
+  const m = found[0].text.match(SHAPE_MARKER_RE);
+  const number = m ? Number(m[3]) : NaN;
+  if (!m || !Number.isSafeInteger(number)) {
+    return { state: 'unreadable', reason: 'malformed', lines: [found[0].line] };
+  }
+  return { state: 'ok', track: m[1], template: m[2], number, line: found[0].line };
+}
+
+// The number of lines the frontmatter occupies, fences included; 0 when there
+// is none. The SAME rule as `splitFrontmatter` in `lib/render.js`, which the
+// marker placement was measured against: the document's first line starts with
+// `---`, and the frontmatter ends at the next line that is `---` once trimmed;
+// with no such line there is no frontmatter. `test/doc-shapes.mjs` pins the two
+// against each other on every packaged template and on the line-ending cases.
+// ⚠ Callers pass the text split on `\n` ONLY — render's split, not
+// `LINE_SPLIT_RE`. With the module's own splitter a lone-CR file had
+// frontmatter here and none in render, so "the same rule" was two rules.
+// ⚠ Nothing else in this module knows about frontmatter, and `classifyLines`
+// reads it as ordinary blocks: a commented field like `# follow-up-of:` is an
+// H1 to it and the closing `---` underlines an H2. So the skeleton cuts it off
+// before classifying anything.
+function frontmatterLineCount(lines) {
+  if (lines.length === 0 || !lines[0].startsWith('---')) return 0;
+  for (let i = 1; i < lines.length; i += 1) {
+    if (lines[i].trim() === '---') return i + 1;
+  }
+  return 0;
+}
+
+// A field the template carries commented out: `# name: …`, indented or not,
+// with the name spelled as a key would be (quoted, dotted), as long as it is
+// one token — `# a note: …` in prose is not a field.
+const FRONTMATTER_COMMENTED_FIELD_RE = /^[ \t]*#[ \t]*("[^"\n]*"|'[^'\n]*'|[A-Za-z][A-Za-z0-9_.-]*)[ \t]*:/;
+// A `{…}` placeholder anywhere in a heading makes it an example, not a section
+// the template requires (`## {Feature Area 1}`, `### FL-01: {流程名稱}`).
+const SHAPE_PLACEHOLDER_RE = /\{[^}\n]*\}/;
+
+function shapeHeadingText(text) {
+  return String(text)
+    .replace(/<!--[\s\S]*?-->/g, '')
+    .replace(/<!--.*$/, '')
+    .replace(/[ \t]+/g, ' ')
+    .trim();
+}
+
+// The frontmatter's field lines and the body after it, cut the way `dflow
+// render` cuts them (see `frontmatterLineCount`).
+function splitShapeFrontmatter(content) {
+  const text = String(content);
+  const lines = text.split('\n');
+  const count = frontmatterLineCount(lines);
+  return {
+    fields: count === 0 ? [] : lines.slice(1, count - 1).map((l) => l.replace(/\r$/, '')),
+    body: count === 0 ? text : lines.slice(count).join('\n')
+  };
+}
+
+// A frontmatter field is whatever `splitFrontmatter` in `lib/render.js` reads
+// as a key — the text before the line's first `:`, trimmed, on a line that has
+// one and does not start with `#` — so a field render shows on the meta card
+// (`"review-owner":`, `review.owner:`) is never missing from the skeleton.
+// `test/doc-shapes.mjs` pins the two against each other. Null for any other line.
+function frontmatterFieldName(line) {
+  if (line.trimStart().startsWith('#')) return null;
+  const colon = line.indexOf(':');
+  return colon === -1 ? null : line.slice(0, colon).trim();
+}
+
+function tableHeaderCells(line) {
+  // Comments go before the split: a `|` inside one is not a column boundary.
+  let row = line.replace(/<!--[\s\S]*?-->/g, '').trim();
+  if (row.startsWith('|')) row = row.slice(1);
+  if (row.endsWith('|') && !row.endsWith('\\|')) row = row.slice(0, -1);
+  return row.split(/(?<!\\)\|/).map((cell) => shapeHeadingText(cell));
+}
+
+// The shape of a template: what a shape number stands for (PROPOSAL-092 D6).
+// Items are small arrays so they compare, sort and print without a parser:
+//
+//   ['field', name]                     frontmatter field
+//   ['field', name, 'optional']         field the template carries commented out
+//   ['h2', heading]
+//   ['h3', h2, heading]                 h2 is '' when the H3 sits above any H2
+//   ['column', h2, h3, table, position, heading]
+//                                       a table's header cell; `table` counts
+//                                       from 1 within that (h2, h3) section, and
+//                                       `position` from 1 within the row
+//   ['note', h2, h3, digest]            the `>` notes of that section
+//   ['comment', h2, h3, digest]         its HTML comments: every one that starts
+//                                       a line's content — at the top level or in
+//                                       a list item, multi-line ones included —
+//                                       and the ones in its heading line
+//
+// The first four are the skeleton; notes, comments and the heading order are
+// the shape's notes-and-order half — a change there does not change the doc's
+// structure, and doctor reports it as such. A note or comment digest is taken
+// over its text with `>` and line breaks folded to single spaces, so re-wrapping
+// is not a change. A comment counts as its `<!-- … -->` span only: prose after
+// `-->` on the same line is prose. A comment in a `>` block is part of that
+// note. The marker line is not a comment of the shape.
+//
+// ⚠ The column POSITION is part of the item: a table's columns are read by
+// position, so swapping `Upstream` and `Downstream` reverses what every row
+// means while leaving the set of header names the same. Items compare
+// order-free; the heading order is compared on its own (`shapeOrderChanges`).
+//
+// Left out: H1 and H4 and below, prose outside notes and comments, fixed label
+// text, table rows, and every `##` / `###` heading with a placeholder —
+// together with everything under it, down to the next heading at its level or
+// above. A table or comment under an H4 is recorded under the nearest H2 / H3,
+// placeholder H4 or not: an H4 is not part of the skeleton, so it cannot take
+// what follows it out of the shape either.
+// `variable` lists the sections a template lets the author replace (`[h2]` or
+// `[h2, h3]`); those and everything under them are left out as well.
+// ⚠ `test/doc-shapes.mjs` holds this reading against `dflow render`'s parser on
+// every registered template: the headings, tables, notes and comments render
+// sees must be the ones recorded here. A `>` block inside a list item is one
+// render sees and this does not read, so a template may not carry one.
+function extractShapeSkeleton(content, options) {
+  const { items, sections } = extractShapeSections(content, options);
+  for (const t of sections) {
+    if (t.note.length > 0) items.push(['note', t.h2, t.h3, shapeTextDigest(t.note)]);
+    if (t.comment.length > 0) items.push(['comment', t.h2, t.h3, shapeTextDigest(t.comment)]);
+  }
+  return items;
+}
+
+// The `<!-- … -->` spans in `text` that a shape records — never the prose around
+// them. An unterminated one runs to the end of the text. The marker is not one.
+function shapeCommentSpans(text) {
+  return (String(text).match(/<!--[\s\S]*?(?:-->|$)/g) || [])
+    .filter((span) => !span.includes(SHAPE_MARKER_MENTION));
+}
+
+// The skeleton items, and per section the raw note and comment texts its
+// digests are taken over (`extractShapeSkeleton` adds the digests).
+function extractShapeSections(content, { variable = [] } = {}) {
+  const { fields, body: bodyText } = splitShapeFrontmatter(content);
+  const items = [];
+  for (const line of fields) {
+    const name = frontmatterFieldName(line);
+    if (name !== null) { items.push(['field', name]); continue; }
+    const m = line.match(FRONTMATTER_COMMENTED_FIELD_RE);
+    if (m) items.push(['field', m[1], 'optional']);
+  }
+  const variableKeys = new Set(variable.map((v) => JSON.stringify(v)));
+  const body = blankFencedBlocks(bodyText);
+  const classes = classifyLines(body);
+  let h2 = '';
+  let h3 = '';
+  let placeholderLevel = 0;
+  let skipped = false;
+  const tables = new Map();
+  // Per section, in the order sections first appear: its notes and comments.
+  const texts = new Map();
+  const textsHere = () => {
+    const key = JSON.stringify([h2, h3]);
+    if (!texts.has(key)) texts.set(key, { h2, h3, note: [], comment: [] });
+    return texts.get(key);
+  };
+  const commentStillOpen = (t) => t.lastIndexOf('<!--') > t.lastIndexOf('-->');
+  for (let i = 0; i < body.length; i += 1) {
+    const c = classes[i];
+    if (c.heading) {
+      const { level } = c.heading;
+      const text = shapeHeadingText(c.heading.text);
+      if (placeholderLevel && level <= placeholderLevel) placeholderLevel = 0;
+      if (placeholderLevel) continue;
+      if ((level === 2 || level === 3) && SHAPE_PLACEHOLDER_RE.test(text)) {
+        placeholderLevel = level;
+        continue;
+      }
+      if (level === 1) {
+        h2 = '';
+        h3 = '';
+        skipped = false;
+      } else if (level === 2) {
+        h2 = text;
+        h3 = '';
+        skipped = variableKeys.has(JSON.stringify([h2]));
+        if (!skipped) items.push(['h2', h2]);
+      } else if (level === 3) {
+        h3 = text;
+        skipped = variableKeys.has(JSON.stringify([h2])) || variableKeys.has(JSON.stringify([h2, h3]));
+        if (!skipped) items.push(['h3', h2, h3]);
+      }
+      if (!skipped) textsHere().comment.push(...shapeCommentSpans(c.heading.text));
+      continue;
+    }
+    if (placeholderLevel || skipped) continue;
+    if (c.type === 'blockquote') {
+      // The line is a blockquote by `classifyLines`; its `>` markers go — all of
+      // them, so re-wrapping a nested `> >` note is not a change either.
+      const part = body[i].trimStart().replace(/^(?:>[ \t]?)+/, '');
+      const notes = textsHere().note;
+      if (i > 0 && classes[i - 1].type === 'blockquote' && notes.length > 0) notes[notes.length - 1] += `\n${part}`;
+      else notes.push(part);
+      continue;
+    }
+    // An HTML block: the comments in it, whatever else it holds.
+    if (c.type === 'html' && c.blockStart === i) {
+      let end = i;
+      while (end + 1 < body.length && classes[end + 1].type === 'html' && classes[end + 1].blockStart === i) end += 1;
+      textsHere().comment.push(...shapeCommentSpans(body.slice(i, end + 1).join('\n')));
+      i = end;
+      continue;
+    }
+    // A comment that starts a list line's content (`  <!-- … -->` under an item,
+    // or `- <!-- … -->`): a block of its own inside the item, as render reads it.
+    // It runs on until it closes, across blank lines, as a comment does.
+    if (c.type === 'list') {
+      const at = body[i].indexOf('<!--');
+      if (at >= 0 && startsContent(body[i], at) && !body[i].slice(0, at).includes('>')) {
+        let end = i;
+        let chunk = body[i].slice(at);
+        while (commentStillOpen(chunk) && end + 1 < body.length && (classes[end + 1].type === 'list' || classes[end + 1].type === 'blank')) {
+          end += 1;
+          chunk += `\n${body[end]}`;
+        }
+        textsHere().comment.push(...shapeCommentSpans(chunk));
+        i = end;
+        continue;
+      }
+    }
+    const startsTable = c.type === 'table' && (i === 0 || classes[i - 1].type !== 'table');
+    if (!startsTable) continue;
+    const section = JSON.stringify([h2, h3]);
+    const table = (tables.get(section) || 0) + 1;
+    tables.set(section, table);
+    tableHeaderCells(body[i]).forEach((cell, k) => items.push(['column', h2, h3, table, k + 1, cell]));
+  }
+  return { items, sections: [...texts.values()] };
+}
+
+// A section's notes or comments, folded so that re-wrapping changes nothing:
+// every run of whitespace is one space. The order of the parts is kept.
+function shapeTextDigest(parts) {
+  const folded = parts.map((p) => String(p).replace(/\s+/g, ' ').trim()).join('\n');
+  return crypto.createHash('sha256').update(folded, 'utf8').digest('hex').slice(0, 16);
+}
+
+// The heading order a shape records: the H2s, and the H3s under each H2 ('' for
+// H3s above the first H2). The `null` key holds the H2 list itself.
+function shapeHeadingOrder(skeleton) {
+  const order = new Map([[null, []]]);
+  for (const item of skeleton) {
+    if (item[0] === 'h2') order.get(null).push(item[1]);
+    else if (item[0] === 'h3') {
+      if (!order.has(item[1])) order.set(item[1], []);
+      order.get(item[1]).push(item[2]);
+    }
+  }
+  return order;
+}
+
+// Where the headings both shapes have stand in a different order: `null` for
+// the H2s, an H2's name for the H3s under it. A heading only one shape has is
+// left out — adding or removing a section is a change of its own, not a
+// reordering.
+function shapeOrderChanges(from, to) {
+  const before = shapeHeadingOrder(from);
+  const after = shapeHeadingOrder(to);
+  const shared = (list, other) => [...new Set(list.filter((h) => other.includes(h)))];
+  const changed = [];
+  for (const [parent, list] of before) {
+    const other = after.get(parent);
+    if (!other) continue;
+    if (JSON.stringify(shared(list, other)) !== JSON.stringify(shared(other, list))) changed.push(parent);
+  }
+  return changed;
+}
+
+function describeShapeOrder(parent) {
+  if (parent === null) return 'the order of the `##` sections';
+  return parent ? `the order of the \`###\` sections under \`## ${parent}\`` : 'the order of the `###` sections above the first `##`';
+}
+
+// Multiset difference: what `to` has that `from` does not, and the reverse.
+function skeletonDifference(from, to) {
+  const left = new Map();
+  for (const item of from) {
+    const key = JSON.stringify(item);
+    left.set(key, (left.get(key) || 0) + 1);
+  }
+  const added = [];
+  for (const item of to) {
+    const key = JSON.stringify(item);
+    const n = left.get(key) || 0;
+    if (n > 0) left.set(key, n - 1);
+    else added.push(item);
+  }
+  const removed = [];
+  for (const [key, n] of left) {
+    for (let k = 0; k < n; k += 1) removed.push(JSON.parse(key));
+  }
+  return { added, removed };
+}
+
+// The items order-free, plus the heading order: a section moved without being
+// renamed is a new shape too (its notes-and-order half). `test/doc-shapes.mjs`
+// recomputes this for every registered number, which is what makes a rewrite of
+// a published number visible.
+function shapeDigest(skeleton) {
+  const canonical = skeleton.map((item) => JSON.stringify(item)).sort().join('\n');
+  const order = JSON.stringify([...shapeHeadingOrder(skeleton)]);
+  return crypto.createHash('sha256').update(`${canonical}\n${order}`, 'utf8').digest('hex');
+}
+
+// Notes, comments and heading order: the part of a shape that does not change
+// a doc's structure (PROPOSAL-092 D4's third class).
+function isShapeTextItem(item) {
+  return Array.isArray(item) && (item[0] === 'note' || item[0] === 'comment');
+}
+
+function describeShapeItem(item) {
+  const [kind] = item;
+  if (kind === 'field') return `frontmatter field \`${item[1]}:\`${item[2] === 'optional' ? ' (optional)' : ''}`;
+  if (kind === 'h2') return `\`## ${item[1]}\``;
+  if (kind === 'h3') return item[1] ? `\`### ${item[2]}\` under \`## ${item[1]}\`` : `\`### ${item[2]}\``;
+  if (kind === 'column') {
+    const where = [item[1] && `\`## ${item[1]}\``, item[2] && `\`### ${item[2]}\``].filter(Boolean).join(' › ') || 'the top of the document';
+    return `column \`${item[5]}\` (position ${item[4]}) in table ${item[3]} under ${where}`;
+  }
+  if (isShapeTextItem(item)) {
+    const where = [item[1] && `\`## ${item[1]}\``, item[2] && `\`### ${item[2]}\``].filter(Boolean).join(' › ');
+    const what = kind === 'note' ? 'the `>` notes' : 'the HTML comments';
+    return where ? `${what} under ${where}` : `${what} at the top of the document`;
+  }
+  return JSON.stringify(item);
+}
+
+// `pattern` is relative to `dflow/specs/`; `*` matches within one path segment.
+function shapePathMatches(pattern, relPath) {
+  const re = new RegExp(`^${pattern.split('*').map(escapeRegExp).join('[^/]*')}$`);
+  return re.test(relPath);
+}
+
+// The data rows of the first table under the H2 named `heading`, or null when
+// there is no such section or it holds no table. Used to recognise a zero-phase
+// host from its `_index.md`: an empty `## Phase Specs` table is what the flows
+// themselves test (`finish-feature-flow.md` Step 1 certifies a host that carries
+// a phase as phase-bearing).
+function sectionTableRowCount(content, heading) {
+  const body = blankFencedBlocks(splitShapeFrontmatter(content).body);
+  const classes = classifyLines(body);
+  const want = headingKey(heading);
+  let inside = false;
+  for (let i = 0; i < body.length; i += 1) {
+    const c = classes[i];
+    if (c.heading && c.heading.level <= 2) {
+      if (inside) return null;
+      inside = c.heading.level === 2 && headingKey(c.heading.text) === want;
+      continue;
+    }
+    if (!inside || c.type !== 'table') continue;
+    let end = i;
+    while (end + 1 < body.length && classes[end + 1].type === 'table') end += 1;
+    return Math.max(0, end - i - 1);
+  }
+  return null;
+}
+
+module.exports = {
+  GIT_POLICY_LINE_RE,
+  AI_COMMIT_MARKER_LINE_RE,
+  PROSE_LANGUAGE_LINE_RE,
+  TECH_STACK_ROW_RE,
+  MIGRATION_CONTEXT_ROW_RE,
+  GIT_POLICY_VALUES,
+  AI_COMMIT_MARKER_VALUES,
+  parseContextLine,
+  blankFencedBlocks,
+  extractHeadings,
+  extractH2Headings,
+  extractSectionRefs,
+  headingResolves,
+  missingTemplateSections,
+  matchesTemplateWithPlaceholders,
+  SPEC_FORMATTING_CONVENTION_SNIPPET,
+  hasTableWithoutConventionComment,
+  conventionsSectionBody,
+  conventionsSectionBodies,
+  CONVENTIONS_FINGERPRINTS,
+  CONVENTIONS_RETIRED,
+  // Exported so the edition filter can be tested directly. Every shipped entry
+  // has `editions: null`, so `findConventionsDrift` alone can never exercise the
+  // non-null path — a test written through it would prove nothing.
+  fingerprintAppliesTo,
+  isThematicBreak,
+  // The single block-structure decision point (debt 12). Exported so
+  // `lib/init.js` can locate headings through it instead of hand-rolling a
+  // fourth ATX expression, and so `test/upgrade-drift.mjs` can assert labels
+  // directly rather than only through what a section body happens to contain.
+  parseAtxHeading,
+  classifyLines,
+  visibleTextLines,
+  maskCodeBlocks,
+  unclosedHtmlBlockLine,
+  // Exported so `lib/init.js` reads the rule instead of writing a third copy of
+  // `/^[ \t]*$/` inline. The commit that introduced this constant claimed it and
+  // `stripSpaceTab` were "the only two spellings now"; they were not, because
+  // neither was reachable from the other file.
+  BLANK_LINE_RE,
+  stripSpaceTab,
+  findConventionsDrift,
+  // PROPOSAL-084 uncertainty detectors. Each returns a 1-based line number or -1
+  // and asks only whether a SHAPE is present, never where a block ends — see the
+  // section header above them for why that is what makes them safe to run on top
+  // of a parser with named gaps. Exported individually (rather than behind one
+  // aggregate) so `test/upgrade-drift.mjs` can pin each shape and each
+  // false-positive control against the detector that owns it: an aggregate that
+  // returns "something fired" cannot fail for the right reason.
+  inlineHtmlCommentLine,
+  containerHtmlCommentLine,
+  htmlBlockType7Line,
+  // Exported for the false-positive controls specifically: the code-span rule is
+  // the boundary that keeps `` `<!-- x -->` `` — which a reader DOES see — out of
+  // the inline-comment detector, and it deserves a direct pin rather than being
+  // tested only through its two consumers.
+  codeSpanMask,
+  // PROPOSAL-092.
+  findShapeMarkerLines,
+  readShapeMarker,
+  shapeMarkerStandardLine,
+  frontmatterLineCount,
+  extractShapeSkeleton,
+  extractShapeSections,
+  shapeCommentSpans,
+  shapeHeadingText,
+  skeletonDifference,
+  shapeHeadingOrder,
+  shapeOrderChanges,
+  shapeDigest,
+  isShapeTextItem,
+  describeShapeItem,
+  describeShapeOrder,
+  shapePathMatches,
+  sectionTableRowCount
+};