@opengsd/gsd-core 1.10.0 → 1.12.0

package/gsd-core/bin/lib/uat.cjs

@@ -19,16 +19,13 @@ const io = require("./io.cjs");
 const { output, error } = io;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const markdownSectionizer = require("./markdown-sectionizer.cjs");
-const { collectSection, tokenizeHeadings } = markdownSectionizer;
+const { collectSection, tokenizeHeadings, stripFencedCode, scanFencedBlocks } = markdownSectionizer;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const markdownTable = require("./markdown-table.cjs");
 const { splitTableRow, isDelimiterRow } = markdownTable;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
-const roadmapParser = require("./roadmap-parser.cjs");
-const { getMilestonePhaseFilter } = roadmapParser;
-// eslint-disable-next-line @typescript-eslint/no-require-imports
 const coreUtils = require("./core-utils.cjs");
-const { toPosixPath } = coreUtils;
+const { toPosixPath, normalizeLineEndings } = coreUtils;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const planningWorkspace = require("./planning-workspace.cjs");
 const { planningDir } = planningWorkspace;
@@ -37,15 +34,48 @@ const frontmatter = require("./frontmatter.cjs");
 const { extractFrontmatter } = frontmatter;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const phaseIdMod = require("./phase-id.cjs");
-const { PHASE_NUMBER_TOKEN_SOURCE } = phaseIdMod;
+const { PHASE_NUMBER_TOKEN_SOURCE, scopeToPhase } = phaseIdMod;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const phaseLocator = require("./phase-locator.cjs");
-const { getArchivedPhaseDirs } = phaseLocator;
+const { listMilestonePhaseDirs, getAllArchivedPhaseDirs } = phaseLocator;
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const auditMod = require("./audit.cjs");
+const { isAuditItemAcknowledged, deriveUatGapSnapshotValue } = auditMod;
 const security_cjs_1 = require("./security.cjs");
 // eslint-disable-next-line @typescript-eslint/no-require-imports -- config-loader.cjs is an export= CommonJS module
 const configLoader = require("./config-loader.cjs");
 const { loadConfig } = configLoader;
 // ─── cmdAuditUat ─────────────────────────────────────────────────────────────
+/**
+ * Select the UAT documents belonging to ONE phase directory.
+ *
+ * Extracted (#2790) so `cmdAuditUat` and the read-only `planning.inspect` query
+ * cannot drift on which files count as this phase's UAT. `scopeToPhase` has no
+ * unfiltered fallback on purpose: a phase whose own UAT file is genuinely absent
+ * scopes to empty and contributes nothing, rather than picking up a stray
+ * cross-phase file (#3511).
+ */
+function selectPhaseUatFiles(files, phaseDirName) {
+    return scopeToPhase(files.filter((f) => f.includes('-UAT') && f.endsWith('.md')), phaseDirName);
+}
+/**
+ * The ONE read boundary for every document `cmdAuditUat` scans off disk
+ * (#3707-CR follow-up MAJOR). Wraps `fs.readFileSync` +
+ * `normalizeLineEndings` in a single seam so a lone-CR-separated
+ * `*-UAT.md`, `*-VERIFICATION.md`, or `deferred-items.md` is normalized BY
+ * CONSTRUCTION before it reaches ANY downstream parser — current
+ * (`parseUatItemsWithStats`, `parseVerificationItems`, `parseDeferredItems`)
+ * or future. Fixing this per-parser was the original (#3707-CR) MEDIUM fix's
+ * mistake: two of the four ingresses in this function were normalized by
+ * editing their own parsers directly, and the other two (VERIFICATION,
+ * deferred-items.md) were missed precisely because nothing forced a new call
+ * site to remember the step. Routing every read through this function
+ * removes that failure mode: a parser added later needs no line-ending logic
+ * of its own, because the text it receives is already normalized.
+ */
+function readNormalizedDocument(filePath) {
+    return normalizeLineEndings(node_fs_1.default.readFileSync(filePath, 'utf-8'));
+}
 function cmdAuditUat(cwd, raw) {
     const phasesDir = node_path_1.default.join(planningDir(cwd), 'phases');
     const hasActivePhases = node_fs_1.default.existsSync(phasesDir);
@@ -58,26 +88,29 @@ function cmdAuditUat(cwd, raw) {
     // mattering when a milestone closes: a deferred human-UAT scenario or a
     // `skipped` live-stack test is exactly what gets archived still-open.
     //
-    // Reuses the canonical `getArchivedPhaseDirs` seam (phase-locator.cts), which
+    // Reuses the canonical `getAllArchivedPhaseDirs` seam (phase-locator.cts), which
     // `findPhaseInternal` already uses for this same fallback, so the archive
     // layout convention stays owned by one module.
-    const archivedDirs = getArchivedPhaseDirs(cwd);
+    // #3804: the guard AND the scan use the cross-workstream enumeration —
+    // a project whose only phases live in workstream milestone trees is a
+    // fully-populated audit, not a broken install.
+    const archivedDirs = getAllArchivedPhaseDirs(cwd);
     if (!hasActivePhases && archivedDirs.length === 0) {
         error('No phases directory found in planning directory');
     }
-    const isDirInMilestone = getMilestonePhaseFilter(cwd);
     const results = [];
+    let acknowledgedFiles = 0;
     // Active dirs are milestone-filtered; archived dirs deliberately are NOT.
-    // getMilestonePhaseFilter derives the CURRENT milestone's phase numbers from
-    // ROADMAP.md, and archived phases belong to past milestones by definition — so
-    // applying it to them discards every one and silently reinstates the bug.
+    // listMilestonePhaseDirs derives the CURRENT milestone's phase directories
+    // (window + sentinel filtered) from ROADMAP.md, and archived phases belong
+    // to past milestones by definition — so applying it to them discards every
+    // one and silently reinstates the bug.
     const scanTargets = [];
     if (hasActivePhases) {
-        const dirs = node_fs_1.default.readdirSync(phasesDir, { withFileTypes: true })
-            .filter(e => e.isDirectory())
-            .map(e => e.name)
-            .filter(isDirInMilestone)
-            .sort();
+        // #3185 (ADR-3180 Decision 1): routed through the canonical owner
+        // instead of a hand-rolled readdirSync + isDirInMilestone filter, which
+        // also never excluded sentinels, unlike the owner.
+        const dirs = listMilestonePhaseDirs(phasesDir, { cwd }).value;
         for (const dir of dirs) {
             scanTargets.push({ dir, phaseDir: node_path_1.default.join(phasesDir, dir) });
         }
@@ -93,30 +126,94 @@ function cmdAuditUat(cwd, raw) {
         const phaseMatch = dir.match(new RegExp(`^(${PHASE_NUMBER_TOKEN_SOURCE})`, 'i'));
         const phaseNum = phaseMatch ? phaseMatch[1] : dir;
         const files = node_fs_1.default.readdirSync(phaseDir);
-        // Process UAT files
-        for (const file of files.filter(f => f.includes('-UAT') && f.endsWith('.md'))) {
+        // Process UAT files — scoped to THIS phase's own token (#3511) via
+        // scopeToPhase, so a stray, cross-phase, or ad-hoc file cannot be reported
+        // under this phase's audit-uat entry. A phase whose own UAT file is
+        // genuinely absent scopes to empty and contributes nothing — correct, and
+        // the reason scopeToPhase has no unfiltered fallback.
+        for (const file of selectPhaseUatFiles(files, dir)) {
             const uatFilePath = node_path_1.default.join(phaseDir, file);
-            const content = node_fs_1.default.readFileSync(uatFilePath, 'utf-8');
-            const items = parseUatItems(content);
-            if (items.length > 0) {
-                results.push({
+            const content = readNormalizedDocument(uatFilePath);
+            const { items, headingsSeen } = parseUatItemsWithStats(content);
+            const uatFm = extractFrontmatter(content, uatFilePath);
+            const status = (uatFm.status || 'unknown').toLowerCase();
+            // #3805: honour the audit_acknowledged marker with the SAME snapshot
+            // key audit.cts's scanUatGaps uses ('gap_snapshot', derived value
+            // composed by the shared derivation) — one acknowledgement means the
+            // same thing to both commands.
+            if (isAuditItemAcknowledged(uatFm, { snapshotKey: 'gap_snapshot', currentValue: deriveUatGapSnapshotValue(status, content) })) {
+                acknowledgedFiles++;
+                continue;
+            }
+            // `parse_gap` means the file contained `### N.` test blocks that
+            // yielded no items — NOT merely "zero items and not complete" (#3707
+            // MAJOR: that broader signal false-positived on an all-pass file and on
+            // a Gaps-only file with everything resolved). A file whose blocks all
+            // passed, or that has no test blocks at all, never sets `headingsSeen`,
+            // so it never sets the flag regardless of status.
+            //
+            // `status` deliberately does NOT gate this (#3078 security review). A
+            // terminal `status: complete` is an ASSERTION BY THE AUTHOR that the
+            // work is finished — and an assertion is exactly the thing that must
+            // not be allowed to switch off the detector that would contradict it.
+            // The earlier `status !== 'complete'` guard did precisely that: a file
+            // could declare itself complete and thereby suppress the report of the
+            // rows this tool could not read, which is a self-declared kill switch
+            // over the very detector this issue built. The distinction that
+            // actually matters is not "is it complete" but "is there anything the
+            // tool failed to parse":
+            //   - complete + `headingsSeen === 0` — nothing unread, so nothing to
+            //     contradict the claim. Still omitted entirely, exactly as before;
+            //     that is the whole point of a terminal status and must not
+            //     regress. (Same for a file whose blocks all parsed and passed.)
+            //   - complete + `headingsSeen > 0` — the author's claim of
+            //     completeness CANNOT BE VERIFIED against rows the parser could not
+            //     read, so the file is surfaced with `parse_gap` and the
+            //     `unparsed_blocks` count. The audit reports what it could not see
+            //     rather than trusting the frontmatter over the file body.
+            //
+            // This check is deliberately UNCONDITIONAL on `items.length` (#3707
+            // follow-up BLOCKER): a MIXED file — some parseable rows plus some
+            // unparseable blocks — must report BOTH the real items AND the parse
+            // gap, quantified via `unparsed_blocks`. The previous `else if` only
+            // ever flagged a file with ZERO items, silently discarding
+            // `headingsSeen` (and every unparseable row it counted) the instant any
+            // single item existed anywhere in the file, including via the Gaps
+            // union.
+            if (items.length > 0 || headingsSeen > 0) {
+                const entry = {
                     phase: phaseNum,
                     phase_dir: dir,
                     file,
                     file_path: toPosixPath(node_path_1.default.relative(cwd, node_path_1.default.join(phaseDir, file))),
                     type: 'uat',
-                    status: (extractFrontmatter(content, uatFilePath).status || 'unknown'),
+                    status,
                     archived_milestone: milestone,
                     items,
-                });
+                };
+                if (headingsSeen > 0) {
+                    entry.parse_gap = true;
+                    entry.unparsed_blocks = headingsSeen;
+                }
+                results.push(entry);
             }
         }
-        // Process VERIFICATION files
-        for (const file of files.filter(f => f.includes('-VERIFICATION') && f.endsWith('.md'))) {
+        // Process VERIFICATION files — scoped to THIS phase's own token (#3511)
+        // for the same reason as the UAT loop above.
+        for (const file of scopeToPhase(files.filter(f => f.includes('-VERIFICATION') && f.endsWith('.md')), dir)) {
             const verificationFilePath = node_path_1.default.join(phaseDir, file);
-            const content = node_fs_1.default.readFileSync(verificationFilePath, 'utf-8');
-            const status = extractFrontmatter(content, verificationFilePath).status || 'unknown';
+            const content = readNormalizedDocument(verificationFilePath);
+            const verFm = extractFrontmatter(content, verificationFilePath);
+            const status = (verFm.status || 'unknown').toLowerCase();
+            // #3805: same marker, same 'status' snapshot key as scanVerificationGaps,
+            // and the same ORDERING — the open-status gate runs FIRST (a marker on
+            // a file that would never surface is not a suppressed item), then the
+            // acknowledgement suppresses what the gate surfaced.
             if (status === 'human_needed' || status === 'gaps_found') {
+                if (isAuditItemAcknowledged(verFm, { snapshotKey: 'status', currentValue: status })) {
+                    acknowledgedFiles++;
+                    continue;
+                }
                 const items = parseVerificationItems(content, status, verificationFilePath);
                 if (items.length > 0) {
                     results.push({
@@ -141,7 +238,7 @@ function cmdAuditUat(cwd, raw) {
         // required.
         const deferredFile = 'deferred-items.md';
         if (files.includes(deferredFile)) {
-            const content = node_fs_1.default.readFileSync(node_path_1.default.join(phaseDir, deferredFile), 'utf-8');
+            const content = readNormalizedDocument(node_path_1.default.join(phaseDir, deferredFile));
             const items = parseDeferredItems(content);
             if (items.length > 0) {
                 results.push({
@@ -161,10 +258,34 @@ function cmdAuditUat(cwd, raw) {
     const summary = {
         total_files: results.length,
         total_items: results.reduce((sum, r) => sum + r.items.length, 0),
+        // #3707 blocker 2: a distinct counter so a file whose test blocks
+        // yielded no items (structurally unparseable, not "all clear") stays
+        // visible even though it contributes zero to total_items. Consumers
+        // (audit-uat.md, progress.md) must gate their all-clear / debt checks on
+        // BOTH total_items === 0 AND parse_gap_files === 0.
+        //
+        // Counts EVERY entry with `parse_gap: true`, archived or not — same as
+        // `total_items`, which has no archived split. An outstanding item does
+        // not stop mattering because its phase was archived on milestone close
+        // (#2766): a deferred human-UAT scenario or a `skipped` live-stack test
+        // is exactly what gets archived still-open, so a parse gap on that same
+        // file is still an unread outstanding row, not closed history. Splitting
+        // this counter by `archived_milestone` (tried in this branch, reverted)
+        // demoted an in-progress phase filed under an archived dir out of the
+        // gate, and buried an archived outstanding row's parse failure relative
+        // to the identical row when it happened to parse — the exact bug class
+        // this issue exists to fix.
+        parse_gap_files: results.filter((r) => r.parse_gap).length,
         by_category: {},
         by_phase: {},
     };
     for (const r of results) {
+        // Deliberate (#3707 follow-up MINOR): this seeds a `by_phase` key at 0
+        // even for a parse-gap-only phase whose `items` is empty — do NOT "tidy"
+        // this away as dead code. The 0-valued key is itself the cue that this
+        // phase was scanned and produced no COUNTABLE items, distinguishing it
+        // from a phase absent from `by_phase` entirely (never scanned / no UAT
+        // file at all). A phase with a real outstanding item overwrites it below.
         if (!summary.by_phase[r.phase])
             summary.by_phase[r.phase] = 0;
         for (const item of r.items) {
@@ -173,7 +294,9 @@ function cmdAuditUat(cwd, raw) {
             summary.by_category[cat] = (summary.by_category[cat] || 0) + 1;
         }
     }
-    output({ results, summary }, raw, undefined);
+    // #3805: acknowledged files surface as a COUNT (audit-open's honesty
+    // model: the marker fired, the items are suppressed, both facts visible).
+    output({ results, summary, acknowledged_files: acknowledgedFiles }, raw, undefined);
 }
 // ─── cmdRenderCheckpoint ──────────────────────────────────────────────────────
 function cmdRenderCheckpoint(cwd, options = {}, raw) {
@@ -202,6 +325,12 @@ function cmdRenderCheckpoint(cwd, options = {}, raw) {
 }
 // ─── parseCurrentTest ─────────────────────────────────────────────────────────
 function parseCurrentTest(content) {
+    // #3707-CR: this is the render-checkpoint path's own independent ingress
+    // into `tokenizeHeadings` (via the `parseFirstPendingTest` fallback below),
+    // separate from `parseUatItemsWithStats`'s. Normalize here too, ONCE, so a
+    // lone-CR document cannot hide its first pending row from this path either
+    // — see `normalizeLineEndings` for why.
+    content = normalizeLineEndings(content);
     // Use the seam to locate the ## Current Test section (ADR-1372 T5).
     // HTML-comment stripping within the section body is UAT-specific, so we keep
     // the comment removal caller-side after extracting the body.
@@ -262,24 +391,51 @@ function parseFirstPendingTest(content) {
     // tokenizeHeadings operates on the section body as a standalone document,
     // filtering to level-3 headings matching the UAT-specific "N. Name" pattern.
     // The UAT-specific item parsing (number extraction, result parsing) stays caller-side.
-    const subHeadings = tokenizeHeadings(sectionBody).filter((h) => h.level === 3 && /^\d+\.\s+/.test(h.text));
+    //
+    // #3078 blocker (same exposure as `parseUatItemsWithStats`): only a COLUMN-0
+    // heading is a test row — see `isColumnZeroHeading`. A `### N.` line indented
+    // <= 3 spaces INSIDE an `expected: |` value is value text, and must not
+    // register as a phantom heading and steal the real row's `result:` token.
+    //
+    // #3078 follow-up: tokenize a copy with the DELIMITER LINES of every
+    // wholly-INDENTED fenced block blanked out first (bodies untouched — column
+    // 0 is structure, indentation is content) — see
+    // `blankIndentedFenceDelimiters`. Without this, an
+    // indented ` ``` ` opener inside an `expected: |` value still reads as a
+    // real fence to `tokenizeHeadings` (CommonMark tolerates 1-3 leading
+    // spaces), which then hides every heading up to the next matching closer —
+    // including a later, genuinely column-0 `### N.` row.
+    //
+    // #3078 round-5 MAJOR: the row predicate is `isTestRowHeadingText`, the ONE
+    // shared helper `parseUatItemsWithStats` uses. It previously read
+    // `/^\d+\.\s+/` here while the audit path read `/^\d+\.(?!\d)/`, so
+    // `### 3.Foo` WAS a row on one path and was NOT on the other — two parse
+    // paths in one module disagreeing about the same grammar.
+    const subHeadings = tokenizeHeadings(blankIndentedFenceDelimiters(sectionBody)).filter((h) => h.level === 3 && isTestRowHeadingText(h.text) && isColumnZeroHeading(sectionBody, h));
     for (let i = 0; i < subHeadings.length; i += 1) {
         const current = subHeadings[i];
         const next = subHeadings[i + 1];
-        // Slice the block for this sub-test from the section body text
+        // Slice the block for this sub-test from the RAW section body text
         const block = next
             ? sectionBody.slice(current.offset, next.offset)
             : sectionBody.slice(current.offset);
         if (!/^result:\s*\[?pending\]?\s*$/im.test(block)) {
             continue;
         }
-        // Extract the UAT-specific number and name from the heading text
-        const headingParts = current.text.match(/^(\d+)\.\s+(.+)$/);
+        // Extract the UAT-specific number and name from the heading text via the
+        // SAME `parseTestRowHeadingText` seam the audit path uses (#3078 round-5
+        // MAJOR) — a name-mandatory `/^(\d+)\.\s+(.+)$/` here would have `continue`d
+        // past exactly the `### 3.` / `### 3.Foo` shapes the shared predicate just
+        // admitted, reintroducing the divergence one line below the fix.
+        const headingParts = parseTestRowHeadingText(current.text);
         if (!headingParts)
             continue;
-        const testNumber = parseInt(headingParts[1], 10);
-        const testName = headingParts[2].trim();
-        const expected = parseExpectedFromTestBlock(block);
+        const testNumber = headingParts.number;
+        const testName = headingParts.name;
+        // #3078 blocker: clip the block at its first fence opener before handing
+        // it to `parseExpectedFromTestBlock`, so a raw read cannot reach into
+        // fence-hidden content — including a LATER row's own `expected:` line.
+        const expected = parseExpectedFromTestBlock(clipBlockAtFirstFence(block));
         if (!expected) {
             error(`Pending UAT test ${testNumber} is missing an expected field`);
         }
@@ -292,20 +448,122 @@ function parseFirstPendingTest(content) {
     }
     return null;
 }
-function parseExpectedFromTestBlock(block) {
-    const expectedBlockMatch = block.match(/^expected:\s*\|\n([\s\S]*?)(?=^\w[\w-]*:\s)/m)
-        || block.match(/^expected:\s*\|\n([\s\S]+)/m);
-    if (expectedBlockMatch) {
-        return expectedBlockMatch[1]
+/**
+ * CRLF (#3078, found while hardening the scalar reader): the opener pattern
+ * demanded a BARE `\n` immediately after the `|`, so on a CRLF document
+ * `expected: |\r\n` never matched the block-scalar arm at all — control fell
+ * through to the INLINE arm, which happily captured the pipe character itself
+ * and published `expected: "|"`, discarding the entire multi-line value with no
+ * trace. `\r?` on the opener plus a per-line `\r` strip on the body fixes it.
+ * `(?:[1-9][+-]?|[+-][1-9]?)?` additionally admits the `|-` / `|+` chomping
+ * indicators AND the explicit indentation indicator (`|2`, `|2-`, `|-2`, ...,
+ * in either order per the YAML header grammar), keeping this reader in step
+ * with the column-0 heading rule (an indented heading inside a scalar body is
+ * otherwise a `expected: |-` or `expected: |2` value would be structurally
+ * masked but then read as the literal string `"|-"` / `"|2"` by the same
+ * fall-through.
+ *
+ * `[|>]` (#3078 follow-up): the `>` FOLDED-scalar family (`>`, `>-`, `>+`,
+ * `>2`, `>2+`, ...) hit the exact same fall-through as the CRLF/`|-`/`|+`
+ * bugs above — the opener only ever matched `|`, so `expected: >` fell to the
+ * inline arm and published the literal `">"` as the value, discarding the
+ * whole scalar. The opener character is now captured (group 1) so the caller
+ * can apply YAML's fold semantics for `>` while leaving `|` untouched.
+ *
+ * TRAILING COMMENT (#3078 round-6 MINOR 1): YAML permits a comment after a
+ * block-scalar header — `expected: | # sample`, `reason: >- # note` are both
+ * legal and open a scalar exactly as the bare forms do. The grammar was
+ * `$`-anchored immediately after the indicator, so those headers matched
+ * NEITHER `extractScalarField`'s opener (the value silently fell through to
+ * the inline arm and published the literal `"|"`) NOR
+ * `ANY_KEY_SCALAR_HEADER_LINE_RE` (so `countUnattributedIndentedRows` treated
+ * the scalar's own indented body heading as an unattributed lost row — a FALSE
+ * parse gap). `(?:#[^\r\n]*)?` closes both at the single shared source.
+ */
+const SCALAR_HEADER_BODY = String.raw `[ \t]*([|>])(?:[1-9][+-]?|[+-][1-9]?)?[ \t]*(?:#[^\r\n]*)?`;
+/**
+ * Build the block-scalar HEADER grammar for an arbitrary `key:` — the ONE
+ * source shared by `expected:`, `reason:` and `blocked_by:` (#3078 MINOR 2:
+ * `reason:`/`blocked_by:` previously had no block-scalar grammar of their own
+ * at all, and silently published the literal `"|"` / `">"` for a `|`/`>`
+ * value, discarding it). A key is always a hardcoded literal at each call
+ * site in this module (never untrusted input), so no escaping is needed.
+ */
+function scalarHeaderFor(key) {
+    return String.raw `${key}:${SCALAR_HEADER_BODY}`;
+}
+/**
+ * ANY key's block-scalar HEADER line (#3078 MINOR 1), matched against ONE
+ * already-CR-stripped source line instead of against a multi-line block.
+ * Derived from the SAME `SCALAR_HEADER_BODY` source `scalarHeaderFor` uses
+ * so the opener grammars (`|`, `|-`, `|+`, `|2`, `|-2`, `>`, `>-`, `>+`, `>2+`,
+ * ...) cannot drift between them — the generative-divergence class this repo
+ * pins elsewhere.
+ *
+ * `countUnattributedIndentedRows` walks back from an indented `### N.`-shaped
+ * line to the nearest preceding column-0 line and asks whether THAT line
+ * opened a block scalar that still owns the indented line as its body.
+ * Testing only an `expected:`-ONLY grammar there meant an indented
+ * heading-shaped line inside ANY OTHER block scalar — `reported: |`
+ * (templates/UAT.md), `reason: |`, a verbatim user response containing
+ * `  ### 9. Section Nine` — was miscounted as a lost row even though nothing
+ * is missing. YAML's indentation rule (any column-0 line terminates a scalar)
+ * does not care WHICH key opened the scalar, only that a `[|>]`-family opener
+ * did, so the walk-back only needs to recognise the opener grammar, not the
+ * specific key.
+ */
+const ANY_KEY_SCALAR_HEADER_LINE_RE = new RegExp(String.raw `^[A-Za-z_][\w-]*:${SCALAR_HEADER_BODY}$`);
+/**
+ * Apply YAML FOLDED-scalar (`>`) line-joining to an already-dedented,
+ * CRLF-stripped block-scalar body: lines within a paragraph (no blank line
+ * between them) join with a single space; a blank line between paragraphs
+ * becomes a literal `\n` in the result. `|` (LITERAL) bodies are returned
+ * unchanged — folding is `>`-only.
+ */
+function foldScalarBody(body) {
+    const lines = body.split('\n');
+    const paragraphs = [];
+    let current = [];
+    for (const line of lines) {
+        if (line === '') {
+            paragraphs.push(current.join(' '));
+            current = [];
+        }
+        else {
+            current.push(line);
+        }
+    }
+    paragraphs.push(current.join(' '));
+    return paragraphs.join('\n');
+}
+/**
+ * Extract a YAML-lite `key:` field's value from `block` — block-scalar
+ * (`|`/`>` family, dedented and, for `>`, YAML-folded) OR plain inline.
+ * Generalized from the `expected:`-only reader (#3078 MINOR 2) so `reason:`
+ * and `blocked_by:` — which previously had NO block-scalar grammar at all and
+ * silently published the literal `"|"` / `">"` for a multi-line value,
+ * discarding it — go through the exact same opener grammar and fold
+ * semantics instead of a third, hand-rolled dialect.
+ */
+function extractScalarField(block, key) {
+    const opener = String.raw `^${scalarHeaderFor(key)}\r?\n`;
+    const blockMatch = block.match(new RegExp(`${opener}([\\s\\S]*?)(?=^\\w[\\w-]*:\\s)`, 'm'))
+        || block.match(new RegExp(`${opener}([\\s\\S]+)`, 'm'));
+    if (blockMatch) {
+        const openerChar = blockMatch[1];
+        const dedented = blockMatch[2]
             .split('\n')
-            .map((line) => line.replace(/^ {2}/, ''))
+            .map((line) => line.replace(/\r$/, '').replace(/^ {2}/, ''))
             .join('\n')
             .trim();
+        return openerChar === '>' ? foldScalarBody(dedented) : dedented;
     }
-    const expectedInlineMatch = block.match(/^expected:\s*(.+)\s*$/m);
-    return expectedInlineMatch ? expectedInlineMatch[1].trim() : null;
+    const inlineMatch = block.match(new RegExp(String.raw `^${key}:\s*(.+)\s*$`, 'm'));
+    return inlineMatch ? inlineMatch[1].trim() : null;
+}
+function parseExpectedFromTestBlock(block) {
+    return extractScalarField(block, 'expected');
 }
-const CHECKPOINT_BOX_WIDTH = 64; // total column width of the ╔══...╗ border, borders stay byte-identical
 const CHECKPOINT_FRAMES = {
     english: {
         banner: 'CHECKPOINT: Verification Required',
@@ -408,52 +666,6 @@ function resolveCheckpointFrame(responseLanguage) {
     const key = CHECKPOINT_LANGUAGE_ALIASES[responseLanguage.trim().normalize('NFC').toLowerCase()];
     return (key && CHECKPOINT_FRAMES[key]) || CHECKPOINT_FRAMES.english;
 }
-// Approximate terminal-cell width. East Asian Width W/F code points occupy two
-// cells, while Unicode combining marks occupy no additional cell beyond their
-// base character. Counting only W/F ranges is insufficient for scripts such as
-// Devanagari: Hindi vowel signs and viramas are combining marks, and treating
-// each as a full cell visibly shifts the checkpoint box's right border.
-function isWideCodePoint(codePoint) {
-    return ((codePoint >= 0x1100 && codePoint <= 0x115f) || // Hangul Jamo
-        codePoint === 0x2329 || codePoint === 0x232a ||
-        (codePoint >= 0x2e80 && codePoint <= 0x303e) || // CJK Radicals .. CJK Symbols and Punctuation
-        (codePoint >= 0x3041 && codePoint <= 0x33ff) || // Hiragana .. CJK Compatibility
-        (codePoint >= 0x3400 && codePoint <= 0x4dbf) || // CJK Unified Ideographs Extension A
-        (codePoint >= 0x4e00 && codePoint <= 0x9fff) || // CJK Unified Ideographs
-        (codePoint >= 0xa000 && codePoint <= 0xa4cf) || // Yi Syllables
-        (codePoint >= 0xac00 && codePoint <= 0xd7a3) || // Hangul Syllables
-        (codePoint >= 0xf900 && codePoint <= 0xfaff) || // CJK Compatibility Ideographs
-        (codePoint >= 0xfe30 && codePoint <= 0xfe4f) || // CJK Compatibility Forms
-        (codePoint >= 0xff00 && codePoint <= 0xff60) || // Fullwidth Forms
-        (codePoint >= 0xffe0 && codePoint <= 0xffe6) ||
-        (codePoint >= 0x20000 && codePoint <= 0x3fffd) // CJK Unified Ideographs Extension B+ / supplementary
-    );
-}
-// Non-spacing/enclosing marks and format controls occupy zero terminal cells.
-// Spacing combining marks (General_Category=Mc), such as Devanagari vowel
-// signs, still advance the cursor and must contribute one column.
-const ZERO_WIDTH_MARK_RE = /\p{gc=Mn}|\p{gc=Me}|\p{gc=Cf}/u;
-// Iterates by Unicode code point (not UTF-16 code unit) so astral characters
-// are measured once, not as two surrogate units.
-function displayWidth(text) {
-    let width = 0;
-    for (const ch of text) {
-        if (ZERO_WIDTH_MARK_RE.test(ch))
-            continue;
-        width += isWideCodePoint(ch.codePointAt(0)) ? 2 : 1;
-    }
-    return width;
-}
-// Pads `text` into a `║  text…  ║` line matching CHECKPOINT_BOX_WIDTH. Content
-// that overflows the box (a longer translated string) is left unpadded rather
-// than truncated — a slightly ragged border beats losing text.
-function checkpointBoxLine(text) {
-    const innerWidth = CHECKPOINT_BOX_WIDTH - 2;
-    const content = `  ${text}`;
-    const padLength = innerWidth - displayWidth(content);
-    const padded = padLength > 0 ? content + ' '.repeat(padLength) : content;
-    return `║${padded}║`;
-}
 const RTL_ISOLATE = '\u2067';
 const POP_DIRECTIONAL_ISOLATE = '\u2069';
 function isolateCheckpointFrameText(text, frame) {
@@ -466,51 +678,777 @@ function buildCheckpoint(currentTest, responseLanguage) {
     const banner = isolateCheckpointFrameText(frame.banner, frame);
     const instruction = isolateCheckpointFrameText(frame.instruction, frame);
     return [
-        '╔══════════════════════════════════════════════════════════════╗',
-        checkpointBoxLine(banner),
-        '╚══════════════════════════════════════════════════════════════╝',
+        `### ${banner}`,
         '',
         `**Test ${currentTest.number}: ${currentTest.name}**`,
         '',
         currentTest.expected,
         '',
-        '──────────────────────────────────────────────────────────────',
-        instruction,
-        '──────────────────────────────────────────────────────────────',
+        '---',
+        '',
+        `**${instruction}**`,
     ].join('\n');
 }
 // ─── parseUatItems ────────────────────────────────────────────────────────────
-function parseUatItems(content) {
+/**
+ * Result tokens treated as PASSING (#3707 defect 1). Deliberately MINIMAL —
+ * that minimality is the point. Every token NOT in this set surfaces as an
+ * outstanding item, mirroring the fail-safe direction `parseGapsItems`
+ * already documents for this exact false-negative class (#2286): a project
+ * that invents a novel pass-word gets a visible, correctable false positive
+ * (an extra row an agent can dismiss) rather than today's invisible drop (a
+ * genuinely outstanding row silently vanishing with no trace). This was the
+ * issue's one open design question and was decided deliberately, here, in
+ * favor of the fail-safe direction over a larger "known synonyms" allowlist.
+ */
+const UAT_PASS_RESULTS = new Set(['pass', 'passed']);
+/**
+ * A fenced-code OPENER line at COLUMN 0 (``` or ~~~).
+ *
+ * Deliberately NOT the CommonMark `{0,3}`-space form (#3078 simplification):
+ * inside this module a fence only ever means "document structure the tokenizer
+ * hid from us", and every structural fence in a UAT file starts at column 0. An
+ * INDENTED fence run is, by construction, part of an `expected: |` block-scalar
+ * value — the ordinary way a UAT row reproduces a code sample verbatim — and
+ * must stay invisible to the clipper, or the very field it exists to protect
+ * gets truncated at its own sample. Column 0 is the whole rule for every
+ * fence-aware scan THIS MODULE writes directly against raw block text (this
+ * one, `dropTopLevelFencedRegions`'s `delimRe`). It does NOT extend to
+ * `tokenizeHeadings`, which is a third-party CommonMark scanner with its own
+ * {0,3}-space fence tolerance baked in — see `blankIndentedFenceDelimiters`
+ * for how an indented delimiter is kept from reaching that scanner at all.
+ */
+const FENCE_OPENER_RE = /^(?:`{3,}|~{3,})/;
+/**
+ * The CommonMark-tolerant (0-3 leading spaces) twin of `FENCE_OPENER_RE`,
+ * used ONLY by the inner delimiter-shape sweep in
+ * `blankIndentedFenceDelimiters` (#3078 round-7 MAJOR). That sweep runs
+ * strictly BETWEEN a neutralised block's own (already-blanked) delimiters,
+ * looking for a line `tokenizeHeadings` would itself read as a fence opener
+ * once those delimiters are gone — and `tokenizeHeadings` tolerates up to
+ * three leading spaces on an opener, so a column-0-anchored test here misses
+ * an INDENTED delimiter-shaped line and lets the mutation manufacture exactly
+ * the structure `scanFencedBlocks` never saw. `FENCE_OPENER_RE` itself stays
+ * column-0-anchored: every OTHER call site depends on that anchoring.
+ */
+const INDENT_TOLERANT_DELIM_RE = /^ {0,3}(?:`{3,}|~{3,})/;
+/**
+ * A raw source line whose shape is a UAT `### N.` test heading — the line-level
+ * twin of the `h.level === 3 && /^\d+\.(?!\d)/` token filter in
+ * `parseUatItemsWithStats`, and anchored at COLUMN 0 to match that filter's
+ * `isColumnZeroHeading` guard exactly. Used ONLY to count headings that
+ * `tokenizeHeadings` suppressed (a fence-straddled row), never to parse one:
+ * the two counts must be derived by the SAME rule or the shortfall they
+ * bracket over- or under-reports.
+ */
+const TEST_HEADING_LINE_RE = /^#{3}(?!#)[ \t]+\d+\.(?!\d)/;
+/**
+ * THE test-row grammar, in ONE place (#3078 round-5 MAJOR).
+ *
+ * `parseFirstPendingTest` (the render-checkpoint path) and
+ * `parseUatItemsWithStats` (the audit path) each filtered level-3 headings with
+ * their own literal — `/^\d+\.\s+/` vs `/^\d+\.(?!\d)/` — so the two paths in
+ * this one module DISAGREED about what a test row is: `### 3.Foo` (name squished
+ * against the dot) and `### 3.` (no name at all) were rows to the audit and were
+ * silently NOT rows to the checkpoint. That is the generative-divergence class
+ * this repo requires closed with a shared definition rather than two literals
+ * kept in sync by hand.
+ *
+ * The AUDIT rule wins, deliberately: `^\d+\.(?!\d)` admits `### 3.` and
+ * `### 3.Foo` (a heading missing or squishing its name still contributes to
+ * `headingsSeen`/items instead of vanishing from BOTH — the same silent-drop
+ * symptom the parse-gap flag exists to catch) while the `(?!\d)` lookahead keeps
+ * a DOTTED-SECTION heading like `### 1.2.3 Overview` out, since that is a
+ * document outline number, not test row 1. `TEST_HEADING_LINE_RE` /
+ * `INDENTED_TEST_HEADING_LINE_RE` are the raw-source-line twins of this same
+ * rule and carry the identical `\d+\.(?!\d)` core.
+ */
+const TEST_ROW_HEADING_TEXT_RE = /^\d+\.(?!\d)/;
+/** True when a level-3 heading's TEXT is a UAT test row. See `TEST_ROW_HEADING_TEXT_RE`. */
+function isTestRowHeadingText(text) {
+    return TEST_ROW_HEADING_TEXT_RE.test(text);
+}
+/**
+ * Split a test-row heading's text into its number and display name — the
+ * extraction twin of `isTestRowHeadingText`, shared by both parse paths for the
+ * same anti-divergence reason. Returns `null` for text the predicate rejects.
+ *
+ * A bare `### 3.` (no trailing name) falls back to the heading's own trimmed
+ * text (`3.`) rather than yielding an empty name.
+ */
+function parseTestRowHeadingText(text) {
+    if (!isTestRowHeadingText(text))
+        return null;
+    const parts = text.match(/^(\d+)\.\s*(.*)$/);
+    if (!parts)
+        return null;
+    return { number: parseInt(parts[1], 10), name: parts[2].trim() || text.trim() };
+}
+/**
+ * The INDENTED (1-3 leading spaces, CommonMark-legal) twin of
+ * `TEST_HEADING_LINE_RE` — used by the SHORTFALL SCAN ONLY, never by the parse
+ * gate.
+ *
+ * #3078 round-4 MAJOR 2: `isColumnZeroHeading` refusing to PARSE an indented
+ * `### N.` row is deliberate and stays (no `*UAT*.md` in the tree indents one).
+ * But the COUNTING side inherited that anchor through
+ * `TEST_HEADING_LINE_RE`, so a heading the parse gate rejected could never
+ * reach `headingsSeen` either: `  ### 1. Indented Row` with `result: pending`
+ * — which origin/next's unanchored `###\s*(\d+)\.` did surface — yielded no
+ * item, no gap, no count and no trace at all. Refusing to parse is defensible;
+ * vanishing silently is the exact defect class this issue exists to close, so
+ * the row now surfaces as a PARSE GAP instead.
+ */
+const INDENTED_TEST_HEADING_LINE_RE = /^[ \t]+#{3}(?!#)[ \t]+\d+\.(?!\d)/;
+/**
+ * True when `heading` starts at COLUMN 0 of its source line in `content`.
+ *
+ * The UAT test-row contract (#3078): a `### N.` row heading is structure ONLY
+ * at column 0. `tokenizeHeadings` implements CommonMark, which tolerates up to
+ * 3 leading spaces on an ATX heading — and that single over-permissive rule is
+ * what let a `### 3. Fake Row` line sitting INSIDE an `expected: |` value
+ * register as a phantom heading, open a block, and STEAL the real row's
+ * `result:` line, dropping a genuinely outstanding row from `items`. A scalar
+ * body is indented BY CONSTRUCTION (that is what makes it a body), so requiring
+ * column 0 makes every such line inert without the parser needing any notion of
+ * YAML block scalars at all. The shipped `templates/UAT.md` writes every `### N.`
+ * heading at column 0, and no UAT document in the tree indents one.
+ *
+ * `HeadingToken.offset` is the offset of the heading LINE's first character, so
+ * a column-0 heading is exactly one whose first character is the `#` itself.
+ */
+function isColumnZeroHeading(content, heading) {
+    return content.charCodeAt(heading.offset) === 0x23 /* '#' */;
+}
+/**
+ * An INDENTED (1-3 leading spaces, never 0) fenced-code delimiter line.
+ * Column 0 is intentionally EXCLUDED — a column-0 fence is real document
+ * structure and `tokenizeHeadings` handling it is correct; only the
+ * CommonMark-legal 1-3-space tolerance is the problem this targets.
+ */
+const INDENTED_FENCE_DELIM_RE = /^ {1,3}(?:`{3,}|~{3,})/;
+/**
+ * Return `content` with the two DELIMITER LINES of every wholly-INDENTED
+ * fenced block overwritten by spaces, byte-length- and line-count-preserving,
+ * so every downstream offset and line index still lines up against the
+ * original document. The block's BODY is left verbatim — see "COLUMN 0 IS
+ * STRUCTURE, INDENTATION IS CONTENT" below for why that is the point, not an
+ * oversight.
+ *
+ * Why (#3078 follow-up, escalated design call, answered as option (b)):
+ * dropping `maskBlockScalarBodies` in favor of the column-0 heading filter
+ * (`isColumnZeroHeading`) fixed the phantom-heading theft, but it silently
+ * dropped a SECOND thing masking used to do — hide an INDENTED fence
+ * delimiter from `tokenizeHeadings` itself. `tokenizeHeadings` is a
+ * CommonMark scanner with its own {0,3}-space fence tolerance; a 1-3-space
+ * ` ``` ` inside an `expected: |` scalar body still opens a fence AS FAR AS
+ * THAT SCANNER IS CONCERNED, and every heading between it and its matching
+ * (or absent) closer — including a LATER, genuinely column-0 `### N.` row —
+ * is hidden from the token stream entirely, not merely mis-filtered. The
+ * column-0 heading filter cannot recover a heading the tokenizer never
+ * returned in the first place.
+ *
+ * This is deliberately the SAME "column 0 is structure, anything else is
+ * value text" rule already applied to headings (`isColumnZeroHeading`) and to
+ * this module's own raw-text fence scans (`FENCE_OPENER_RE`,
+ * `dropTopLevelFencedRegions`'s `delimRe`) — extended to the one place that
+ * rule cannot be expressed as a post-hoc filter, because the tokenizer
+ * consumes the fence delimiter before this module ever sees a token for it.
+ * It carries no YAML knowledge whatsoever (no notion of `expected:`, `|`,
+ * indentation width, or scalar bodies) — it blanks an indented delimiter LINE
+ * unconditionally, wherever it appears, the same context-free way the other
+ * column-0 rules do.
+ *
+ * PAIRED, NOT UNCONDITIONAL (#3078 round-4 MAJOR 1). Blanking every indented
+ * delimiter LINE on sight perturbs fence PAIRING in BOTH directions, because
+ * CommonMark lets a COLUMN-0 fence be closed by a delimiter indented up to
+ * three spaces:
+ *   - a column-0 opener closed by an INDENTED closer had its closer blanked,
+ *     so the fence never closed for `tokenizeHeadings` and every later row —
+ *     including a genuinely column-0 `### N.` with an outstanding `result:` —
+ *     was swallowed;
+ *   - the mirror, an INDENTED opener closed by a COLUMN-0 closer, had its
+ *     opener blanked, PROMOTING that closer into an opener and swallowing
+ *     everything after it instead.
+ * Both documents are legal CommonMark that renders correctly, so neither may
+ * lose content. The decision is therefore made per FENCED BLOCK, not per line:
+ * a block is neutralised only when it is indented at BOTH ends (or is an
+ * indented opener that never closes at all) — i.e. when nothing about it is
+ * column-0 document structure. That is exactly the intended case, an indented
+ * fence pair living wholly inside an `expected: |` block-scalar value, which
+ * is why the helper exists; any block with a column-0 delimiter at either end
+ * is left completely alone so its pairing reaches the tokenizer unchanged.
+ *
+ * COLUMN 0 IS STRUCTURE, INDENTATION IS CONTENT — and that rule is applied in
+ * ONE direction only, to the DELIMITERS. Only the two delimiter lines of a
+ * neutralised block are blanked; its body is left exactly as written. A
+ * column-0 `### N.` sitting between two indented delimiters therefore becomes
+ * a real heading, and a `result:` line after it belongs to that heading. That
+ * is CORRECT under this rule, not theft: by the very rule that selected the
+ * block for neutralisation, an indented delimiter is not a fence at all, so
+ * there is no fence for the column-0 line to be "inside" of. The document is
+ * malformed; reading it this way is the consistent reading, and it is PINNED
+ * by test (see "#3078 round 5: column 0 is structure" in tests/uat.test.cjs).
+ * Blanking the whole block open-to-close was tried and REVERTED: it destroys
+ * content legitimately living between the delimiters, and — for the
+ * unterminated-opener case, where the "body" runs to EOF — silently deletes
+ * the entire remainder of the document, dropping every later row.
+ *
+ * NO SECOND FENCE DIALECT: the blocks come from `scanFencedBlocks`
+ * (markdown-sectionizer.cts), the SAME exported CommonMark state machine
+ * `stripFencedCode` — and therefore `tokenizeHeadings` — runs. Backtick AND
+ * tilde runs, run length >= 3, the <= 3-space indent tolerance, a closer of
+ * the same char with run length >= the opener and no trailing text, info
+ * strings (including the "a backtick fence's info string may not contain a
+ * backtick" rule), and the unterminated-at-EOF case are all classified by that
+ * engine, not re-derived here. This module contributes only the column-0
+ * question — which delimiter lines are structure — via
+ * `INDENTED_FENCE_DELIM_RE`.
+ *
+ * LINE-BASED by construction (`content.split('\n')` / `.join('\n')`), never
+ * character-array splicing — the exact bug class (`Array.from(content)`
+ * code-point indexing against UTF-16 offsets) that made the original
+ * `maskBlockScalarBodies` corrupt astral-character documents. A line's own
+ * `.length` and `' '.repeat(line.length)` are measured in the same (UTF-16)
+ * units as the string itself, so this cannot misalign regardless of
+ * code-point framing, and CRLF survives untouched: `split('\n')` leaves any
+ * `\r` attached to the end of its line, and blanking that line replaces the
+ * `\r` with a space exactly like every other character on it — `join('\n')`
+ * then reproduces the original line count and total length exactly.
+ */
+function blankIndentedFenceDelimiters(content) {
+    const lines = content.split('\n');
+    const isIndentedDelimiter = (idx) => idx >= 0 && idx < lines.length && INDENTED_FENCE_DELIM_RE.test(lines[idx].replace(/\r$/, ''));
+    const blank = new Set();
+    for (const block of scanFencedBlocks(lines)) {
+        // A column-0 OPENER is real document structure: leave the whole block
+        // alone, closer included, so an indented closer still closes it.
+        if (!isIndentedDelimiter(block.openLineIdx))
+            continue;
+        // An indented opener paired with a COLUMN-0 closer is likewise real
+        // structure at its far end — blanking the opener would promote that closer
+        // into an opener and hide everything after it.
+        if (block.closeLineIdx !== -1 && !isIndentedDelimiter(block.closeLineIdx))
+            continue;
+        // DELIMITERS ONLY — never the body. THE RULE: column 0 is structure,
+        // indentation is content. An indented delimiter therefore neutralises
+        // ITSELF, but it never hides column-0 structure sitting between
+        // delimiters: a column-0 `### N.` there IS a heading, and a `result:`
+        // after it IS that heading's. Widening this to the whole block was tried
+        // (#3078 round 5) and reverted — it deletes content that legitimately
+        // lives between the delimiters, and on an UNTERMINATED indented opener it
+        // blanks to EOF, taking every later row with it. Pinned by test; do not
+        // "fix" it back.
+        blank.add(block.openLineIdx);
+        if (block.closeLineIdx !== -1)
+            blank.add(block.closeLineIdx);
+        // #3078 round-6 MAJOR: the two fence engines must not disagree about the
+        // text handed downstream. `scanFencedBlocks` classified the ORIGINAL
+        // lines, but `tokenizeHeadings` re-runs its own CommonMark state machine
+        // over this MUTATED copy. A COLUMN-0 delimiter-shaped line that was mere
+        // fence CONTENT in the original — e.g. a ```-run inside an indented
+        // ````-pair — is PROMOTED to a real opener the instant its enclosing
+        // delimiters are blanked, hiding every later heading to EOF. Blank those
+        // too, so the mutation cannot manufacture structure that the classifying
+        // engine never saw.
+        //
+        // DELIMITER-SHAPED LINES ONLY. A column-0 `### N.` heading between
+        // neutralised delimiters stays a heading (the pinned "column 0 is
+        // structure" behaviour), and the field lines of a row living between two
+        // rows' scalars survive untouched — both are pinned by test. This adds
+        // exactly one shape to the blank set: a line that would itself be read as
+        // a fence delimiter.
+        const inner = block.closeLineIdx === -1 ? lines.length : block.closeLineIdx;
+        for (let i = block.openLineIdx + 1; i < inner; i += 1) {
+            if (INDENT_TOLERANT_DELIM_RE.test(lines[i].replace(/\r$/, '')))
+                blank.add(i);
+        }
+    }
+    if (blank.size === 0)
+        return content;
+    return lines.map((line, i) => (blank.has(i) ? ' '.repeat(line.length) : line)).join('\n');
+}
+/**
+ * Truncate `block` at its first TOP-LEVEL fenced-code opener (#3078 blocker).
+ *
+ * `parseExpectedFromTestBlock` must read the RAW block (an `expected: |` scalar
+ * may legitimately reproduce fenced-looking text verbatim, so a fence-STRIPPED
+ * copy would corrupt the field). But a raw block slice can run straight into
+ * content that `tokenizeHeadings` correctly hid inside a fence — including a
+ * LATER test row's own `expected:` line, which the earlier row then published
+ * as its own. Clipping at the fence opener bounds the raw read to the part of
+ * the block the tokenizer also considered visible.
+ *
+ * Column-0 fences only (`FENCE_OPENER_RE`): a fenced sample nested inside a
+ * legitimate `expected: |` value is indented by construction, so it is invisible
+ * here and cannot clip the very field this exists to preserve.
+ */
+function clipBlockAtFirstFence(block) {
+    const rawLines = block.split('\n');
+    let firstFenceLine = -1;
+    for (let i = 0; i < rawLines.length; i += 1) {
+        if (FENCE_OPENER_RE.test(rawLines[i])) {
+            firstFenceLine = i;
+            break;
+        }
+    }
+    if (firstFenceLine === -1)
+        return block;
+    const beforeFence = rawLines.slice(0, firstFenceLine).join('\n');
+    if (parseExpectedFromTestBlock(beforeFence))
+        return beforeFence;
+    // #3078 follow-up MINOR 2: an `expected:` field appearing AFTER a fence has
+    // CLOSED is not a theft risk — only content strictly INSIDE the fence must
+    // stay hidden. The plain "clip at first opener" result above silently
+    // discards a late `expected:` even when it sits outside every fence.
+    // Reconstruct the block with every top-level FENCED REGION dropped, keeping
+    // RAW text everywhere else. This exposes a late `expected:` living after a
+    // fence closes, while an `expected:` living strictly inside the fence is
+    // dropped along with it and stays unreachable — the "inside a fence" vs.
+    // "after a closed fence" split falls straight out of whether the
+    // fence-tracking state machine below is OPEN or CLOSED at that line, not out
+    // of position relative to the FIRST fence opener alone.
+    const visible = dropTopLevelFencedRegions(rawLines);
+    if (parseExpectedFromTestBlock(visible))
+        return visible;
+    return beforeFence;
+}
+/**
+ * Reconstruct `rawLines` with every TOP-LEVEL fenced region removed. Mirrors
+ * `stripFencedCode`'s own delimiter algorithm — a fence run of the SAME
+ * character and at least the SAME length, with no trailing content, is what
+ * closes an open fence — so "inside a fence" here means the same thing it means
+ * to the rest of this module's fence handling. An UNTERMINATED fence (open at
+ * EOF) drops everything from its opener to the end, same as `stripFencedCode`.
+ *
+ * Delimiters are recognised at COLUMN 0 only, for the reason given on
+ * `FENCE_OPENER_RE`: an INDENTED fence run belongs to an `expected: |` value,
+ * not to document structure, and must not open a region here.
+ */
+function dropTopLevelFencedRegions(rawLines) {
+    const kept = [];
+    let openFence = null;
+    const delimRe = /^(`{3,}|~{3,})(.*)$/;
+    for (let i = 0; i < rawLines.length; i += 1) {
+        const line = rawLines[i].replace(/\r$/, '');
+        const m = delimRe.exec(line);
+        if (m) {
+            const char = m[1][0];
+            const len = m[1].length;
+            const trailing = m[2];
+            if (openFence === null) {
+                if (char === '`' && trailing.includes('`')) {
+                    // Not a valid fence opener (CommonMark: backtick info string must
+                    // not contain a backtick) — ordinary content.
+                    kept.push(rawLines[i]);
+                    continue;
+                }
+                openFence = { char, len };
+            }
+            else if (char === openFence.char && len >= openFence.len && /^\s*$/.test(trailing)) {
+                openFence = null;
+            }
+            continue; // all delimiter lines are dropped, opener or closer
+        }
+        if (openFence === null)
+            kept.push(rawLines[i]);
+        // Lines inside an open fence are silently dropped.
+    }
+    return kept.join('\n');
+}
+/**
+ * Count the INDENTED (1-3 space) `### N.` heading-shaped lines in `surface`
+ * that are NOT the value text of a preceding `expected:` block scalar.
+ *
+ * Why the exclusion (#3078 round-4 MAJOR 2): the parse gate refuses BOTH
+ * shapes for the same reason (column 0 is structure), but only one of them is
+ * a lost ROW. A `### 3. Fake Row` line sitting inside an `expected: |` value is
+ * the row's own published `expected:` string — already surfaced, verbatim, on
+ * the item — so counting it would flag a parse gap against a document with
+ * nothing missing (the pinned scalar-body behaviour). A `  ### 1. Indented
+ * Row` that no scalar owns is a row the parser declined to read, and must be
+ * visible as an unparsed block instead of silently clean.
+ *
+ * Attribution is structural and cheap: walk BACK from the indented heading to
+ * the first non-blank line at column 0 (a block-scalar body is indented by
+ * construction, and blank lines are legal inside one). The heading is scalar
+ * VALUE exactly when that line is ANY `key:` scalar header — not `expected:`
+ * only (#3078 MINOR 1: testing the `expected:`-only grammar false-positived
+ * on an indented heading-shaped line inside a DIFFERENT block scalar, e.g. a
+ * template-sanctioned `reported: |` holding verbatim user prose, or a
+ * `reason: |` body) — per `ANY_KEY_SCALAR_HEADER_LINE_RE`, derived from the
+ * SAME `[|>]`-family opener grammar the reader itself uses. No second opener
+ * dialect, and no attempt to model YAML indentation levels.
+ */
+function countUnattributedIndentedRows(surface) {
+    const lines = surface.split('\n');
+    // LINEAR, not quadratic (#3078 round-6 MINOR 2). The walk-back above was
+    // re-scanned per indented row, so a document of N rows and N lines cost
+    // O(N^2) — measured 4x per 2x on real input (1000 rows 20ms → 16000 rows
+    // 3.6s). The walk only ever asks ONE question of the prefix — "which is the
+    // nearest preceding non-blank COLUMN-0 line?" — and that is a running value,
+    // so a single forward pass computes it for every line at once. The
+    // ATTRIBUTION RULE IS UNCHANGED: a blank line and an indented line are both
+    // transparent (a block-scalar body is indented by construction and may
+    // contain blank lines), and the first line that is neither terminates the
+    // scalar; the heading is value text exactly when THAT line is any key's
+    // block-scalar header.
+    const stripped = lines.map((line) => line.replace(/\r$/, ''));
+    const nearestColumnZero = new Array(lines.length);
+    let last = -1;
+    for (let i = 0; i < stripped.length; i += 1) {
+        nearestColumnZero[i] = last;
+        const line = stripped[i];
+        if (line.trim() !== '' && !/^[ \t]/.test(line))
+            last = i;
+    }
+    let count = 0;
+    for (let i = 0; i < lines.length; i += 1) {
+        if (!INDENTED_TEST_HEADING_LINE_RE.test(lines[i]))
+            continue;
+        const owner = nearestColumnZero[i];
+        const ownedByScalar = owner !== -1 && ANY_KEY_SCALAR_HEADER_LINE_RE.test(stripped[owner]);
+        if (!ownedByScalar)
+            count += 1;
+    }
+    return count;
+}
+/**
+ * `headingsSeen` is the TOTAL parse-gap tally (every heading-shaped thing this
+ * parser could not turn into an item). `shortfallBlocks` is the SUBSET of it
+ * contributed by the fence-suppression shortfall scan below — the one gap class
+ * this module documents as carrying an ACCEPTED OVER-REPORT (a closed-fence
+ * documentation sample written with literal digits is indistinguishable from a
+ * genuinely fence-straddled row; see the long comment at the scan itself).
+ * Reported separately so a consumer that must decide whether to WITHHOLD a
+ * derived number — as opposed to merely REPORT the gap — can tell "a row I
+ * definitely could not read" from "a row I possibly mis-counted".
+ *
+ * #3707-CR: `src/planning-inspect.cts`'s `buildUatRows` does NOT destructure
+ * this field (verified — it and `cmdAuditUat` both consume only `items` and
+ * `headingsSeen`), correcting an earlier stated instruction that it did.
+ * `shortfallBlocks` currently has NO production consumer outside this
+ * function's own computation. It is retained on the return value anyway,
+ * deliberately, as part of this function's published stats contract — tests
+ * assert on the full `{ items, headingsSeen, shortfallBlocks }` shape, and
+ * dropping a returned field is a wider, unrelated change than a line-ending
+ * fix warrants. A future consumer that needs to distinguish an
+ * accepted-over-report shortfall from the rest of `headingsSeen` (the
+ * original design intent above) can still do so.
+ */
+function parseUatItemsWithStats(content) {
+    content = normalizeLineEndings(content);
     const items = [];
-    // Match test blocks: ### N. Name\nexpected: ...\nresult: ...\n
-    // Accept both bare (result: pending) and bracketed (result: [pending]) formats (#2273)
-    const testPattern = /###\s*(\d+)\.\s*([^\n]+)\nexpected:\s*([^\n]+)\nresult:\s*\[?(\w+)\]?(?:\n(?:reported|reason|blocked_by):\s*[^\n]*)?/g;
-    let match;
-    while ((match = testPattern.exec(content)) !== null) {
-        const [, num, name, expected, result] = match;
-        if (result === 'pending' || result === 'skipped' || result === 'blocked') {
-            // Extract optional fields — limit to current test block (up to next ### or EOF)
-            const afterMatch = content.slice(match.index);
-            const nextHeading = afterMatch.indexOf('\n###', 1);
-            const blockText = nextHeading > 0 ? afterMatch.slice(0, nextHeading) : afterMatch;
-            const reasonMatch = blockText.match(/reason:\s*(.+)/);
-            const blockedByMatch = blockText.match(/blocked_by:\s*(.+)/);
-            const item = {
-                test: parseInt(num, 10),
-                name: name.trim(),
-                expected: expected.trim(),
-                result,
-                category: categorizeItem(result, reasonMatch?.[1], blockedByMatch?.[1]),
-            };
-            if (reasonMatch)
-                item.reason = reasonMatch[1].trim();
-            if (blockedByMatch)
-                item.blocked_by = blockedByMatch[1].trim();
-            items.push(item);
+    let headingsSeen = 0;
+    let shortfallBlocks = 0;
+    // Locate every `### N. Name` test heading across the WHOLE document (not
+    // adjacency-matched against `result:`, #3707 defect 2) and slice each one's
+    // own block from its heading to the next heading OF ANY LEVEL (or EOF) —
+    // a trailing `## Gaps` section or an interleaved `### Notes` heading must
+    // not be absorbed into the preceding test's block, else its unanchored
+    // `reason:`/`blocked_by:` scans below bleed a Gaps entry's fields onto the
+    // last test row.
+    // #3078 blocker: only a COLUMN-0 heading is document structure here (see
+    // `isColumnZeroHeading`). The filter is applied to the WHOLE token stream,
+    // not just to the `### N.` rows, because an indented heading must not act as
+    // a block BOUNDARY either — a `### 3. Fake Row` line inside an `expected: |`
+    // value would otherwise truncate its own row's block just before the real
+    // `result:` line and drop a genuinely outstanding row from `items`.
+    //
+    // #3078 follow-up: tokenize a copy with every indented fence delimiter
+    // blanked out (`blankIndentedFenceDelimiters`) BEFORE the column-0 filter
+    // ever runs. Otherwise an indented ` ``` ` opener inside an `expected: |`
+    // value still opens a real fence as far as `tokenizeHeadings` (a
+    // CommonMark scanner, {0,3}-space fence tolerance) is concerned, hiding
+    // every heading up to its closer from the token stream entirely — a LATER,
+    // genuinely column-0 `### N.` row is never returned as a token at all, so
+    // no post-hoc filter over the token stream could recover it.
+    const allHeadings = tokenizeHeadings(blankIndentedFenceDelimiters(content)).filter((h) => isColumnZeroHeading(content, h));
+    // #3707 follow-up MINOR: `^\d+\.` alone — a trailing name is OPTIONAL
+    // (`### 3.` and `### 3.Foo`, without the space the old `\s+`-anchored
+    // pattern required, both count) so a heading missing or squishing its name
+    // still contributes to `headingsSeen`/items rather than being silently
+    // excluded from BOTH — the same vanishing-row symptom the parse-gap flag
+    // exists to catch, reachable here at the heading-filter layer instead.
+    // #3078 round-5 MAJOR: that rule now lives in `isTestRowHeadingText` and is
+    // shared verbatim with `parseFirstPendingTest`, which used to disagree.
+    // Carry each match's own index into `allHeadings` from the filter pass
+    // itself (security review finding 3) rather than re-deriving it via
+    // `allHeadings.indexOf(current)` inside the loop below — the latter is an
+    // O(n) scan per heading, making the whole loop O(n^2) in document size.
+    const subHeadings = [];
+    allHeadings.forEach((h, index) => {
+        if (h.level === 3 && isTestRowHeadingText(h.text))
+            subHeadings.push({ heading: h, index });
+    });
+    // #3078 blocker: `tokenizeHeadings` is fence-aware, so a BALANCED fence pair
+    // that opens after one test row and closes after a later one makes every
+    // `### N.` heading between them invisible — the rows are not merely
+    // unparseable, they are absent from the token stream, so the loop below can
+    // never count them and the file reports as CLEAN with an outstanding
+    // `result: blocked` inside it. (origin/next's old whole-file regex did
+    // surface those rows, making the silent drop a regression.) Comparing the
+    // count of heading-SHAPED source lines against the headings the tokenizer
+    // actually returned recovers the shortfall; each suppressed row counts
+    // toward `headingsSeen`, so the file is flagged as a parse gap rather than
+    // silently clean. The line scan is anchored at COLUMN 0 (`TEST_HEADING_LINE_RE`)
+    // by the same rule the token filter uses, so a `### N.`-shaped line living
+    // inside an `expected: |` value — which is value text, not a suppressed row —
+    // cannot inflate the tally.
+    //
+    // #3078 round-7 HIGH — SYMMETRY IS THE INVARIANT. BOTH SIDES OF THIS
+    // COMPARISON ARE WHOLE-DOCUMENT. DO NOT SCOPE EITHER ONE. Read this whole
+    // comment before "optimising" the `## Notes` noise back out; three separate
+    // HIGH-severity silent false-cleans have been produced by three separate
+    // attempts to be clever about scope here, and every one of them was a
+    // regression against origin/next's plain whole-file regex.
+    //
+    // History of the failures, so they are not re-derived:
+    //   - round-6 HIGH: the raw line scan was SECTION-SCOPED to the `## Tests`
+    //     body while `subHeadings` stayed whole-document, so a legal
+    //     `### 9. Old / result: pass` row in a preceding `## Prior` section
+    //     decremented the shortfall by one and SILENTLY DISABLED the
+    //     fence-straddle detector.
+    //   - round-7 HIGH: "equalising" that by ALSO scoping the token side to the
+    //     section's offset span made the two counters agree with each other but
+    //     left the PARSE side whole-document — so a `### N.` row living OUTSIDE
+    //     the first `## Tests` section was parsed and surfaced normally when
+    //     visible, yet vanished with NO item AND NO parse_gap the moment a fence
+    //     straddled it: neither side of the comparison covered it. Reproduced
+    //     three ways — a straddle inside a `## Regression Tests` section, a
+    //     straddle inside a SECOND `## Tests` section (`collectSection` takes the
+    //     FIRST match only), and, as control, the identical straddle in a file
+    //     with no `## Tests` heading at all, which alone reported correctly.
+    //
+    // THE RULE: the parse side reads rows wherever they live in the document, so
+    // the counting side must too. Scan shaped `### N.` lines over the ENTIRE
+    // document and compare against ALL tokenized row headings. Any narrowing of
+    // one side that is not matched by the other manufactures a blind spot, and a
+    // blind spot here is a SILENT FALSE CLEAN — a file with an outstanding
+    // `result: blocked` in it that never even enters `results`.
+    //
+    // ACCEPTED CONSEQUENCE, DELIBERATELY TRADED (this replaces the #3078
+    // follow-up MINOR 1 scoping): a `### N.`-shaped line inside a properly
+    // CLOSED fence in a `## Notes` section — a documentation sample of the row
+    // format. NOTE the shape needs LITERAL DIGITS — the scan requires `\d+`, so the
+    // conventional placeholder `### N. Name` does NOT trigger it; only a sample written
+    // with real numbers (`### 1. Example Row`) does. On FREQUENCY, claim only what is
+    // measurable here: the SHAPE is uncommon (it takes a literal-digit row inside a
+    // CLOSED fence), and that is a claim about the shape, NOT a measurement across real
+    // projects. The in-tree sample size for it is ZERO PHASE FILES — the only `*UAT*.md`
+    // anywhere in this repo is the shipped template (which `selectPhaseUatFiles` never
+    // scans, and which itself scores headingsSeen=11, six of them literal-digit example
+    // rows), so "no phase UAT file in-tree triggers it" is vacuously true and proves
+    // nothing about rarity in the field. Do not restate it as evidence. If you test the
+    // placeholder form, see no over-report, and conclude this pin is stale: it is not.
+    // The ordinary way to explain the syntax inside a UAT file — is
+    // counted as a suppressed row and raises a parse gap on a file with nothing
+    // actually missing. That is an OVER-report: noisy, but VISIBLE and FAIL-SAFE
+    // (an agent reads the file and dismisses it). Fence-closedness cannot
+    // distinguish it from a genuinely hidden row, because the fence-straddle
+    // case this scan exists to catch is ALSO a properly closed fence — so the
+    // only lever left is scope, and scope is exactly what produced the two
+    // silent false-cleans above. This entire issue exists to eliminate false
+    // cleans, so the trade goes this way ON PURPOSE: an extra noisy row beats an
+    // invisible missing one. The behaviour is pinned by test; do not "fix" it.
+    let shapedHeadingLines = 0;
+    for (const line of content.split('\n')) {
+        if (TEST_HEADING_LINE_RE.test(line))
+            shapedHeadingLines += 1;
+    }
+    if (shapedHeadingLines > subHeadings.length) {
+        shortfallBlocks = shapedHeadingLines - subHeadings.length;
+        headingsSeen += shortfallBlocks;
+    }
+    // #3078 round-4 MAJOR 2: an INDENTED `### N.` row is refused by the parse
+    // gate (`isColumnZeroHeading`) — correct — but must not therefore vanish
+    // without a trace. See `countUnattributedIndentedRows` for why an indented
+    // heading that is the VALUE of a preceding `expected:` block scalar is
+    // excluded from this tally (it is value text, not a row), keeping the
+    // scalar-body pins intact while a genuinely indented ROW surfaces as a gap.
+    //
+    // WHOLE-DOCUMENT, for the same reason as the shortfall scan above: this
+    // counter has no token-side twin to disagree with, but scoping it to a
+    // `## Tests` body would silently drop an indented row living anywhere else
+    // in the file — the identical vanishing-row class. Its own false-positive
+    // guard is STRUCTURAL (scalar attribution via
+    // `ANY_KEY_SCALAR_HEADER_LINE_RE`) — with ONE positional caveat: the walk stops at the
+    // nearest COLUMN-0 line, so a block scalar nested inside a `## Gaps` bullet (a
+    // `- truth:` entry carrying an indented `note: |`) is transparent to it and a
+    // heading-shaped line inside that value is counted. That is another instance of the
+    // accepted over-report above, not a separate defect, not positional, so it needs no scope.
+    headingsSeen += countUnattributedIndentedRows(content);
+    // #3078: an UNTERMINATED fence swallows the entire remainder of the
+    // document — every later test row AND a trailing `## Gaps` section — so the
+    // file yields nothing at all and never even enters `results`: a whole-file
+    // false clean. Mirrors the per-file malformed-markdown guard
+    // `evaluateUatPassed` already applies via `analyzeMarkdown`
+    // (src/uat-predicate.cts:278), which likewise gates on
+    // `stripFencedCode(raw).unterminatedFence`. Deliberately measured on the RAW
+    // document: a fence opened inside an `expected:` scalar is still an
+    // unterminated fence for every downstream markdown consumer, and the masked
+    // copy would hide it.
+    if (stripFencedCode(content).unterminatedFence) {
+        headingsSeen += 1;
+    }
+    for (let i = 0; i < subHeadings.length; i += 1) {
+        const { heading: current, index: currentIdx } = subHeadings[i];
+        const next = allHeadings[currentIdx + 1];
+        const block = next ? content.slice(current.offset, next.offset) : content.slice(current.offset);
+        // Fence-stripped copy for the `result:`/`reason:`/`blocked_by:` field
+        // scans below (#3707 follow-up MAJOR/regression): `block` is raw slice
+        // text, and a fenced code sample inside a test block (a legitimate way to
+        // document expected output) can contain a line that LOOKS like a field
+        // declaration (e.g. an example ` ```\nresult: pending\n``` `). Scanning
+        // raw text reads that sample's `result:` as the test's real outcome —
+        // origin/next returned null here, so an unstripped scan is a regression,
+        // not a pre-existing behavior to preserve. `parseExpectedFromTestBlock`
+        // below still receives the RAW `block`, not this stripped copy: an
+        // `expected: |` block-scalar value may legitimately reproduce
+        // fenced-looking text verbatim, and stripping it would corrupt that field.
+        // #3707 round-3 MINOR: an UNTERMINATED fence (EOF inside a fence, or —
+        // here, scoped per test block — the closing delimiter living in a LATER
+        // block, so from this block's own slice the fence never closes) makes
+        // `stripFencedCode` drop everything from the opener to the end of the
+        // block, including a real `result:`/`reason:`/`blocked_by:` line that
+        // follows it. Falling back to the RAW (unstripped) block in that case
+        // means a legitimate fenced-code false-positive (a `result:`-shaped line
+        // INSIDE a properly-closed sample) is still guarded against in the common
+        // case, while a malformed/unterminated fence no longer silently swallows
+        // a real field line into a false parse_gap.
+        const stripResult = stripFencedCode(block);
+        const fenceStrippedBlock = stripResult.unterminatedFence ? block : stripResult.text;
+        // A block with no `result:` line at all is not a test row (e.g. still
+        // being drafted) — no item, no false positive. It IS, however, a heading
+        // that failed to yield an item for a reason other than a PASS token, so
+        // it counts toward `headingsSeen` (used to detect a genuine parse gap).
+        // Deliberately NOT end-anchored (regression fix, #3707 blocker 1): a
+        // trailing comment/clause after the token (`result: pending (blocked on
+        // staging)`, `result: [skipped] # no device`, `result: blocked -
+        // waiting`) must still match and surface the row instead of being
+        // silently dropped. The trailing text itself is matched-and-ignored
+        // (#3707 follow-up MINOR): it is NOT synthesized into `reason` — a real
+        // `reason:` line is the only source for that field (see below) — because
+        // doing so previously changed `categorizeItem`'s classification for
+        // shapes origin/next categorized differently (an unpinned behavior
+        // change, not something the blocker required).
+        // #3078-CR defect A fix, split-then-match scan: the previous `.match()`
+        // against `/^result:.../im` ran a MULTILINE regex anchor directly over
+        // unsplit block text. ECMA-262's LineTerminator set for `^`/`$` under
+        // `/m` includes U+2028 LINE SEPARATOR and U+2029 PARAGRAPH SEPARATOR, but
+        // `content.split('\n')` and this module's own heading tokenizer do NOT
+        // treat either as a boundary. A `result:`-shaped line inside an
+        // `expected: |` scalar body, sitting immediately after one of these
+        // separators instead of an ordinary character, was therefore read as a
+        // genuine line start by the regex engine even though it is not
+        // `\n`-delimited from anything — it is exactly as much "one line" to
+        // every other consumer as the ordinary-character control case.
+        // Splitting on `\n` FIRST and testing each already-split line against a
+        // single-line (`/im`-anchor-free) pattern fixes this: a line is never
+        // split by U+2028/U+2029 (`String.prototype.split` matches only its
+        // literal separator argument, never the wider ECMA-262 LineTerminator
+        // set), so a `result:`-shaped line reachable only via one of those
+        // separators can never register as its own split line — the split view
+        // and the regex view are back in agreement, by construction, exactly the
+        // way `splitLines` module is documented to be immune to the sibling `\r`
+        // bug.
+        //
+        // FIRST MATCH WINS (byte-identical to origin/next otherwise): a block
+        // with more than one column-0 `result:` line resolves to the FIRST one
+        // encountered, same as the pre-existing `.match()` behaviour without
+        // `/g` — this is deliberately NOT an ambiguity/parse-gap case (that
+        // variant was tried and reverted: its boundary-truncation heuristic
+        // mistook an indented `### N.` living inside a legitimate block scalar
+        // for a heading boundary, corrupting every scalar/indent guard in this
+        // module — see tests/uat.test.cjs's #3078 scalar guard family).
+        // Trailing text is matched with `[^]*` rather than `.*` (final review
+        // MINOR 1): `.` never matches U+2028/U+2029, so a column-0 `result:`
+        // line whose trailing text contains one of those separators would
+        // otherwise never reach `$`, and the whole line would fail to match —
+        // an unpinned regression against origin/next, which parses it.
+        const RESULT_LINE_RE = /^result:\s*\[?(\w+)\]?[^]*$/i;
+        const resultLineMatch = fenceStrippedBlock
+            .split('\n')
+            .map((line) => line.match(RESULT_LINE_RE))
+            .find((m) => m !== null);
+        if (!resultLineMatch) {
+            headingsSeen += 1;
+            continue;
         }
+        // Security review finding 2: store the token lower-cased so the published
+        // `result` field agrees with `category` (which categorizeItem already
+        // lower-cases internally, below). No consumer needs the original casing —
+        // `uat-predicate.cts` runs its own independent parser and already
+        // lower-cases too — so the raw-cased form is kept nowhere.
+        const result = resultLineMatch[1].toLowerCase();
+        // #3707 defect 1: invert the old DROP-list filter to a PASS set — see
+        // UAT_PASS_RESULTS's doc comment for why this direction was chosen.
+        // A recognised PASS token is the ONLY reason a heading is excluded from
+        // `headingsSeen` without producing an item — every other non-yielding
+        // case (missing `result:` line, above) is a genuine parse gap.
+        // `result` is already lower-cased at its extraction above, which is the
+        // single point of normalization for this value — re-lowercasing here was
+        // dead work and implied a second, independent normalization that does not
+        // exist (#3078 round-5 MINOR).
+        if (UAT_PASS_RESULTS.has(result))
+            continue;
+        // #3707 follow-up MINOR: the heading filter above now admits `### 3.`
+        // (no name at all) and `### 3.Foo` (no space before the name), so this
+        // extraction is loosened in lockstep — a bare number with no trailing
+        // name falls back to the heading's own trimmed text (`3.`). #3078 round-5
+        // MAJOR: shared with `parseFirstPendingTest` via `parseTestRowHeadingText`.
+        const headingParts = parseTestRowHeadingText(current.text);
+        const testNumber = headingParts.number;
+        const testName = headingParts.name;
+        // Reuse the existing block-scalar/inline `expected:` grammar rather than
+        // re-deriving a second one (#3707 defect 2). #3078 blocker: the block is
+        // CLIPPED at its first top-level fence opener first — still raw text (a
+        // legitimate `expected: |` scalar must be read verbatim, fences and all),
+        // but bounded to what the tokenizer also treated as visible, so this row
+        // cannot reach past a fence into a LATER row's `expected:` line and
+        // publish it as its own. See `clipBlockAtFirstFence`.
+        const expected = parseExpectedFromTestBlock(clipBlockAtFirstFence(block));
+        // #3078 MINOR 2: `reason:`/`blocked_by:` previously had no block-scalar
+        // grammar at all (only a plain `/key:\s*(.+)/` single-line match), so a
+        // `reason: |`/`reason: >`/`blocked_by: |` value silently published as the
+        // literal string `"|"` / `">"`, discarding the real multi-line value the
+        // author wrote — and `categorizeItem` below reads exactly this field, so a
+        // discarded `reason` could silently change an item's category. Routed
+        // through the SAME `extractScalarField` machinery `expected:` already
+        // uses rather than adding a third hand-rolled opener dialect.
+        const reason = extractScalarField(fenceStrippedBlock, 'reason') ?? undefined;
+        const blockedBy = extractScalarField(fenceStrippedBlock, 'blocked_by') ?? undefined;
+        const item = {
+            test: testNumber,
+            name: testName,
+            result,
+            category: categorizeItem(result, reason, blockedBy),
+        };
+        if (expected)
+            item.expected = expected;
+        if (reason)
+            item.reason = reason;
+        if (blockedBy)
+            item.blocked_by = blockedBy;
+        items.push(item);
     }
     items.push(...parseGapsItems(content));
-    return items;
+    return { items, headingsSeen, shortfallBlocks };
+}
+/**
+ * ITEMS-ONLY convenience form over `parseUatItemsWithStats` — the same parse,
+ * with the `headingsSeen` parse-gap counter dropped, for a caller that only
+ * wants the rows.
+ *
+ * Deliberately RETAINED with no in-tree caller (#3078 round-5 MINOR): both
+ * `cmdAuditUat` and `src/planning-inspect.cts` need the stats form, so this is
+ * currently used only from outside. It is a public export of a shipped module,
+ * and removing an exported symbol is a CONTRACT change, out of scope for a bug
+ * fix — so it stays, as the documented thin wrapper it has always been, with a
+ * direct test of its own rather than as untested dead weight.
+ */
+function parseUatItems(content) {
+    return parseUatItemsWithStats(content).items;
 }
 // ─── parseGapsItems ───────────────────────────────────────────────────────────
 /**
@@ -766,31 +1704,584 @@ function parseGapsTableItems(sectionBody) {
  * `.planning/todos/pending/*.md` entry required). Every other entry —
  * including one with no `status:` field at all — is UNRESOLVED and is
  * surfaced.
+ *
+ * #3457: when the section body contains headings, entries are delimited by
+ * LEAF headings (see `splitDeferredHeadingEntries`) rather than by bullets —
+ * the executor convention writes one deferred item as a heading followed by
+ * sibling `- **Field:** …` bullets, which the bullet-only split mis-counted as
+ * one item PER BULLET. A body with no headings keeps the original
+ * one-bullet-per-item split unchanged.
  */
-function parseDeferredItems(content) {
+/**
+ * One `deferred-items.md` entry with its RAW (un-lowercased) `status:` field
+ * value (`''` when the entry carries no parseable status). #3458 follow-up:
+ * `parseDeferredItems` (below) is now DEFINED IN TERMS OF this — it filters
+ * to `status !== 'resolved'` — and `audit.cts`'s `scanDeferredItems` also
+ * consumes this directly so it can tell `resolved` (fixed for real, never
+ * counted), the newer `acknowledged` (suppressed-but-tallied, #3458
+ * follow-up), and everything else (open) apart WITHOUT a second,
+ * independent entry-boundary/field-extraction pass that could drift from
+ * this one.
+ */
+function parseDeferredItemsWithStatus(content) {
     const deferredSection = collectSection(content, (h) => /^deferred\s+items$/i.test(h.text) && h.level === 2, { levelBounded: true });
     const sectionBody = deferredSection ? deferredSection.body : content;
     const items = [];
-    for (const entryLines of splitGapsEntries(sectionBody)) {
-        const fields = extractGapEntryFields(entryLines);
-        const rawStatus = fields.status;
-        if (rawStatus && rawStatus.toLowerCase() === 'resolved')
-            continue;
+    // #3457: heading-delimited shape — an entry's fields live in sibling bullets
+    // (`- **Status:** resolved`), so the bullet marker is stripped on EVERY line
+    // before field extraction, not just line 0 (which `extractGapEntryFields`
+    // does for the headless/Gaps shape, where a later `- ` line is a nested
+    // sub-list, not a field).
+    const headingEntries = splitDeferredHeadingEntries(sectionBody);
+    const entries = headingEntries !== null
+        ? headingEntries.map((entryLines) => ({
+            lines: entryLines,
+            fields: extractGapEntryFields(entryLines.map(stripLeadingBulletMarker)),
+        }))
+        : splitGapsEntries(sectionBody).map((entryLines) => ({
+            lines: entryLines,
+            fields: extractGapEntryFields(entryLines),
+        }));
+    for (const { lines: entryLines, fields } of entries) {
         const text = rawGapEntryText(entryLines);
         if (!text)
             continue;
-        items.push({
-            name: text,
-            result: 'unresolved',
-            category: 'deferred',
-        });
+        items.push({ name: text, status: fields.status || '' });
     }
     // #2766: union with the table form — see parseDeferredTableItems. Executors
     // write this file by hand with no mandated shape, and a GFM table is a natural
     // choice for the common "test → failing seeds" case, which produced ZERO items.
-    items.push(...parseDeferredTableItems(sectionBody));
+    // Table rows carry no independently-parseable status column in general —
+    // `parseDeferredTableItems` already excludes resolved/done/pass rows at its
+    // own layer (any cell reading exactly one of those three) — so anything it
+    // returns here is inherently open; `acknowledge` (#3458 follow-up) has no
+    // representable field to write for a table row, so those are reported with
+    // status `''` (never `resolved`/`acknowledged`) and remain permanently
+    // un-acknowledgeable via the CLI writer — a known, deliberate limitation
+    // (see `acknowledgeDeferredItem`'s doc comment).
+    items.push(...parseDeferredTableItems(sectionBody).map((item) => ({ name: item.name, status: '' })));
     return items;
 }
+function parseDeferredItems(content) {
+    return parseDeferredItemsWithStatus(content)
+        .filter((entry) => !(entry.status && entry.status.toLowerCase() === 'resolved'))
+        .map((entry) => ({
+        name: entry.name,
+        result: 'unresolved',
+        category: 'deferred',
+    }));
+}
+/**
+ * CLI-writer half of the #3458 follow-up deferred_items suppression seam.
+ * Sets the ONE deferred entry whose rendered text (`rawGapEntryText`, the
+ * same value `parseDeferredItemsWithStatus`/the audit's JSON output surface
+ * as `name`/`text`) exactly equals `targetText` to `status: acknowledged` —
+ * a NEW terminal value, distinct from the existing `resolved` (which keeps
+ * meaning "actually fixed"). This is the marker for this category: unlike
+ * every other audit category (a sibling `audit_acknowledged` frontmatter map
+ * that never touches the artifact's own `status:`), a deferred-items.md
+ * entry's `status:` field carries no OTHER meaning, so the field itself
+ * doubles as the marker — self-invalidating for free: edit the entry's
+ * `status:` away from `acknowledged` (or delete the field) and it resurfaces
+ * with no separate cleanup step, exactly like every other category's marker.
+ *
+ * #3781: the heading-delimited (#3457) entry shape is SUPPORTED, via
+ * `splitDeferredHeadingEntriesWithSpans` — a span-carrying sibling of the
+ * reader's walk that records each entry's (start, end) character span in the
+ * SAME pass that groups its lines (the identical technique
+ * `splitGapsEntriesWithSpans` uses for the headless shape). Leaf entries keep
+ * their RAW heading line as `lines[0]` so `sectionBody.slice(start, end)` is
+ * byte-verbatim; pending (preamble / container-direct) regions are contiguous
+ * slices handed to `splitGapsEntriesWithSpans` with a baseOffset translation.
+ * Two write rules differ from the headless path on this shape: the status
+ * search runs over the READER-form lines (what the reader actually parses —
+ * including the leaf line-0 corner where the heading text itself parses as a
+ * status field, whose raw line is rewritten with its ATX prefix preserved),
+ * and the insert branch inserts after the entry's LAST NON-BLANK line — a
+ * heading entry's body is frequently a soft-wrapped sentence, and splicing
+ * after line 0 would split it in half (#3781's sentence-split trap).
+ * Entries whose span embeds a GFM table row are non-contiguous (table lines
+ * are excluded from entries) and still refuse (`unsupported_heading_shape`)
+ * rather than risk a wrong-entry write; the fully-headless shape below is
+ * byte-for-byte the pre-#3781 path.
+ *
+ * Also refuses `ambiguous` (2+ entries share the exact same text — status must
+ * be unique to identify one) and `not_found`, and is a no-op
+ * (`already_resolved`) on an entry already carrying `status: resolved` — the
+ * verdict-preserving direction: acknowledging a genuinely-fixed item would
+ * silently downgrade its terminal state.
+ *
+ * SPAN-CARRIED, not re-searched (F1, #3458 follow-up review — see
+ * `splitGapsEntriesWithSpans`'s doc comment): the target entry's location
+ * within `sectionBody` is the (start, end) character span recorded by
+ * `splitGapsEntriesWithSpans` in the SAME pass that produced `entryLines` /
+ * `targetText` above — never re-derived afterwards by searching. The
+ * previous implementation re-found the entry with a regex anchored on its
+ * own (escaped) exact text; that regex necessarily matches the FIRST
+ * occurrence of that text within `sectionBody`, which is not always the
+ * entry that was actually selected (a continuation/quoted line inside an
+ * EARLIER or LATER entry can carry byte-identical text) — and because the
+ * mis-targeted span is byte-identical to `targetText`, no downstream check
+ * on the WRITTEN text could ever distinguish a wrong-entry write from a
+ * correct one. Carrying the span removes the re-derivation step entirely:
+ * there is no second search to mis-target.
+ *
+ * Section-anchored (BLOCKER 1, #3458 follow-up review): the span is
+ * `sectionBody`-relative — the SAME string `matches`/the `ambiguous` guard
+ * were computed over — not `content`-relative, so an identical bullet living
+ * outside `## Deferred Items` (e.g. in an unrelated `# Notes` or a
+ * UAT/VERIFICATION body) can never steal the write. The span is translated
+ * into `content`-relative offsets via `deferredSection.bodyStart` (the
+ * section's own start offset, an invariant `collectSection` guarantees:
+ * `content.slice(bodyStart, bodyEnd) === body`). Before writing, the
+ * spanned text's own raw entry is re-derived and compared against
+ * `targetText` one more time — this is now a GENUINE invariant check (the
+ * span was computed by `splitGapsEntriesCore`'s independent offset
+ * bookkeeping, a different code path than the `entryLines`/`targetText`
+ * comparison above), not a no-op — if it does not match, the write is
+ * refused with `match_verification_failed` rather than risk touching the
+ * wrong span.
+ */
+function acknowledgeDeferredItem(content, targetText) {
+    const deferredSection = collectSection(content, (h) => /^deferred\s+items$/i.test(h.text) && h.level === 2, { levelBounded: true });
+    const sectionBody = deferredSection ? deferredSection.body : content;
+    // #3781: the heading-delimited shape carries its own span walk; the
+    // headless path below is unchanged.
+    const headingEntries = splitDeferredHeadingEntriesWithSpans(sectionBody);
+    if (headingEntries !== null) {
+        return acknowledgeHeadingShapedEntry({ content, sectionBody, deferredSection, headingEntries, targetText });
+    }
+    const entries = splitGapsEntriesWithSpans(sectionBody);
+    const matches = entries
+        .map((entry) => ({ entry, text: rawGapEntryText(entry.lines) }))
+        .filter((e) => e.text === targetText);
+    if (matches.length === 0)
+        return { content, status: 'not_found' };
+    if (matches.length > 1)
+        return { content, status: 'ambiguous' };
+    const { entry } = matches[0];
+    const { lines: entryLines, start, end } = entry;
+    const fields = extractGapEntryFields(entryLines);
+    if (fields.status && fields.status.toLowerCase() === 'resolved') {
+        return { content, status: 'already_resolved' };
+    }
+    // Anchor to the SAME section body `matches`/the `ambiguous` guard above
+    // were computed over (BLOCKER 1) — never the whole `content`, which could
+    // contain an identical bullet elsewhere. `start`/`end` are the entry's own
+    // span, carried directly from `splitGapsEntriesWithSpans` — no re-search.
+    const sectionOffset = deferredSection ? deferredSection.bodyStart : 0;
+    const matchedLines = sectionBody.slice(start, end).split('\n');
+    // Genuine invariant re-verification (see doc comment above): the span was
+    // computed by a code path independent of the `entryLines`/`targetText`
+    // comparison that selected this entry — this catches real drift between
+    // the two rather than a regex trivially guaranteed to agree with itself.
+    const strippedForVerify = matchedLines.map((l) => l.replace(/\r$/, ''));
+    if (rawGapEntryText(strippedForVerify) !== targetText) {
+        return { content, status: 'match_verification_failed' };
+    }
+    const matchIndexInContent = sectionOffset + start;
+    // #3740: the search must mirror the reader exactly. extractGapEntryFields
+    // strips a bullet marker on line 0 ALONE — a later `- ` line is a nested
+    // sub-list, never a field line — so a marker-prefixed match on any
+    // continuation line would rewrite a line no reader reads and report `ok`
+    // while the entry stays outstanding. Line 0 KEEPS the marker-optional
+    // form: the reader de-bullets it, so `- status: open` as the entry line is
+    // a real field there (and first-wins means the insert branch could not
+    // outrank it). Everything else falls through to the insert branch below,
+    // which the marker-free and no-status controls already round-trip.
+    //
+    // #3775: the CASE axis of the same rule. The reader lowercases BOLDED
+    // keys only; bare keys keep their literal case (#3457 design), so a bare
+    // `Status:`/`STATUS:` line is stored under key `Status` and never read as
+    // fields.status. The search therefore matches a bolded key in ANY case
+    // and a bare key in LOWERCASE only — never a bare Title-case/UPPER line,
+    // which must fall through to the insert branch whose lowercase output the
+    // reader consumes (leaving any human `Status: resolved` untouched).
+    const statusFieldBoldedRe = /^\s*\*+status:\*+/i;
+    const statusFieldBareRe = /^\s*status:/;
+    const statusFieldBoldedReLine0 = /^\s*(?:-\s+)?\*+status:\*+/i;
+    const statusFieldBareReLine0 = /^\s*(?:-\s+)?status:/;
+    const statusLineIdx = matchedLines.findIndex((rawLine, idx) => {
+        const line = rawLine.replace(/\r$/, '');
+        return idx === 0
+            ? (statusFieldBoldedReLine0.test(line) || statusFieldBareReLine0.test(line))
+            : (statusFieldBoldedRe.test(line) || statusFieldBareRe.test(line));
+    });
+    // No CRLF-preservation branch here (WARNING 1, #3458 follow-up review):
+    // every write goes through `platformWriteSync` → `normalizeContent`, which
+    // for a `.md` path unconditionally runs `_normalizeMd` — whole-file
+    // `\r\n` → `\n`, plus blank-line normalization around headings/lists — on
+    // EVERY write, not just this one. That is this codebase's single,
+    // deliberate OS-facing I/O seam (`shell-command-projection.cts`), applied
+    // uniformly to every `.md` writer; carving out one exception here would
+    // fight it rather than follow it, for a guarantee (byte-identical CRLF on
+    // disk) the seam already makes impossible. A marker write on a CRLF
+    // `deferred-items.md` normalizes the WHOLE file to LF, same as any other
+    // `.md` write in this codebase — expected, not a regression to guard
+    // against. Where a source line still carries a trailing `\r` (read from an
+    // on-disk CRLF document before normalization), `String.prototype.replace`
+    // consumes it as part of `.*$` and the replacement text does not
+    // reproduce it, so it is dropped here too — consistent with the eventual
+    // whole-file normalization rather than duplicating it.
+    let newMatchedLines;
+    if (statusLineIdx === -1) {
+        const bulletIndentMatch = matchedLines[0].match(/^(\s*)-\s+/);
+        const continuationIndent = ' '.repeat((bulletIndentMatch ? bulletIndentMatch[1].length : 0) + 2);
+        newMatchedLines = [
+            matchedLines[0],
+            `${continuationIndent}status: acknowledged`,
+            ...matchedLines.slice(1),
+        ];
+    }
+    else {
+        const original = matchedLines[statusLineIdx];
+        const replaced = original.replace(/^(\s*(?:-\s+)?)(\*+status:\*+|status:)(\s*).*$/i, (_m, indent, key, ws) => `${indent}${key}${ws}acknowledged`);
+        newMatchedLines = matchedLines.slice();
+        newMatchedLines[statusLineIdx] = replaced;
+    }
+    const newContent = content.slice(0, matchIndexInContent) + newMatchedLines.join('\n') + content.slice(matchIndexInContent + (end - start));
+    return { content: newContent, status: 'ok' };
+}
+/**
+ * #3781 — strip an ATX heading prefix, mirroring `tokenizeHeadings`' own ATX
+ * regex (≤3 leading spaces, 1–6 `#`, space/tab separator, optional closing
+ * `#` sequence) so the raw heading line reconciles byte-exactly with the
+ * hash-stripped `text` the reader exposes. Returns null when the line is not
+ * an ATX heading line.
+ */
+function stripAtxPrefix(line) {
+    const m = /^( {0,3})(#{1,6})([ \t]+.*|[ \t]*)?$/.exec(line.replace(/\r$/, ''));
+    if (!m)
+        return null;
+    return m[3] === undefined
+        ? ''
+        : m[3].replace(/^[ \t]+/, '').replace(/[ \t]+#+[ \t]*$/, '').replace(/^#+[ \t]*$/, '').trim();
+}
+/**
+ * #3781 — span-carrying sibling of `splitDeferredHeadingEntries`: ONE walk,
+ * identical grouping rules (leaf = childless heading whose body carries a
+ * bullet; container = next heading deeper; preamble/container-direct lines →
+ * headless entries; table lines excluded), additionally recording each
+ * entry's (start, end) character span within `sectionBody`. Returns null when
+ * the body contains no heading at all — the caller then takes the unchanged
+ * fully-headless path.
+ */
+function splitDeferredHeadingEntriesWithSpans(sectionBody) {
+    const headings = tokenizeHeadings(sectionBody);
+    if (headings.length === 0)
+        return null;
+    const lines = sectionBody.split('\n');
+    const lineStarts = [];
+    const lineEnds = [];
+    let cursor = 0;
+    for (const rawLine of lines) {
+        lineStarts.push(cursor);
+        cursor += rawLine.length;
+        lineEnds.push(cursor);
+        cursor += 1;
+    }
+    const headingByLine = new Map();
+    for (let i = 0; i < headings.length; i++) {
+        const isContainer = i + 1 < headings.length && headings[i + 1].level > headings[i].level;
+        headingByLine.set(headings[i].line, { text: headings[i].text, isContainer });
+    }
+    const isTableLine = (l) => /^\s*\|/.test(l.replace(/\r$/, ''));
+    const isBulletLine = (l) => /^\s*-\s/.test(l.replace(/\r$/, ''));
+    const entries = [];
+    let current = null;
+    let currentReaderLine0 = null;
+    let currentStartLine = -1;
+    let currentEndLine = -1;
+    let currentHasBullet = false;
+    let currentTable = false;
+    let pendingStartLine = -1;
+    let pendingEndLine = -1;
+    const flushCurrent = () => {
+        if (current !== null && currentHasBullet && currentReaderLine0 !== null) {
+            const bodyReader = current.slice(1).map(stripLeadingBulletMarker);
+            entries.push({
+                kind: 'leaf',
+                lines: current,
+                readerLines: [currentReaderLine0, ...bodyReader],
+                text: rawGapEntryText([currentReaderLine0, ...current.slice(1)]),
+                fields: extractGapEntryFields([currentReaderLine0, ...bodyReader]),
+                start: lineStarts[currentStartLine],
+                end: lineEnds[currentEndLine],
+                embeddedTable: currentTable,
+            });
+        }
+        current = null;
+        currentReaderLine0 = null;
+        currentStartLine = -1;
+        currentEndLine = -1;
+        currentHasBullet = false;
+        currentTable = false;
+    };
+    const flushPending = () => {
+        if (pendingStartLine === -1)
+            return;
+        // The pending region is contiguous (a heading flushes it), but table lines
+        // inside it were skipped by the walk: the reader's identity for this
+        // region is computed over the table-FILTERED join, which may merge
+        // entries across the gap, so spans cannot be translated faithfully —
+        // mark the region's entries as refusing instead.
+        let regionTable = false;
+        for (let i = pendingStartLine; i <= pendingEndLine; i++) {
+            if (isTableLine(lines[i]))
+                regionTable = true;
+        }
+        const base = lineStarts[pendingStartLine];
+        const regionText = sectionBody.slice(lineStarts[pendingStartLine], lineEnds[pendingEndLine]);
+        for (const e of splitGapsEntriesWithSpans(regionText)) {
+            entries.push({
+                kind: 'pending',
+                lines: e.lines,
+                readerLines: e.lines,
+                text: rawGapEntryText(e.lines),
+                fields: extractGapEntryFields(e.lines),
+                start: base + e.start,
+                end: base + e.end,
+                embeddedTable: regionTable,
+            });
+        }
+        pendingStartLine = -1;
+        pendingEndLine = -1;
+    };
+    for (let i = 0; i < lines.length; i++) {
+        const heading = headingByLine.get(i + 1);
+        if (heading !== undefined) {
+            flushCurrent();
+            flushPending();
+            if (!heading.isContainer) {
+                current = [lines[i]];
+                currentReaderLine0 = heading.text;
+                currentStartLine = i;
+                currentEndLine = i;
+                currentHasBullet = false;
+                currentTable = false;
+            }
+            continue;
+        }
+        if (isTableLine(lines[i])) {
+            if (current !== null)
+                currentTable = true;
+            continue;
+        }
+        if (current !== null) {
+            current.push(lines[i]);
+            currentEndLine = i;
+            if (isBulletLine(lines[i]))
+                currentHasBullet = true;
+        }
+        else {
+            if (pendingStartLine === -1)
+                pendingStartLine = i;
+            pendingEndLine = i;
+        }
+    }
+    flushCurrent();
+    flushPending();
+    return entries;
+}
+/**
+ * #3781 — the heading-shaped half of `acknowledgeDeferredItem`, sharing the
+ * headless path's guards (not_found / ambiguous / already_resolved /
+ * match_verification_failed) and its rewrite/insert machinery, with the two
+ * shape-specific rules documented on `acknowledgeDeferredItem` (reader-form
+ * status search incl. the leaf line-0 ATX corner; insert after the entry's
+ * last non-blank line). Extracted so the headless path stays byte-identical.
+ */
+function acknowledgeHeadingShapedEntry({ content, sectionBody, deferredSection, headingEntries, targetText }) {
+    const matches = headingEntries.filter((e) => e.text === targetText);
+    if (matches.length === 0)
+        return { content, status: 'not_found' };
+    if (matches.length > 1)
+        return { content, status: 'ambiguous' };
+    const entry = matches[0];
+    if (entry.embeddedTable)
+        return { content, status: 'unsupported_heading_shape' };
+    if (entry.fields.status && entry.fields.status.toLowerCase() === 'resolved') {
+        return { content, status: 'already_resolved' };
+    }
+    const sectionOffset = deferredSection ? deferredSection.bodyStart : 0;
+    const rawSlice = sectionBody.slice(entry.start, entry.end);
+    const rawSliceLines = rawSlice.split('\n');
+    // Genuine invariant re-verification: re-derive the entry's identity from
+    // the span's own bytes and compare against the targetText that selected it
+    // — the span was recorded by an offset bookkeeping independent of the
+    // identity comparison above.
+    const verifyText = entry.kind === 'leaf'
+        ? (() => {
+            const stripped = stripAtxPrefix(rawSliceLines[0]);
+            return stripped === null ? null : rawGapEntryText([stripped, ...rawSliceLines.slice(1)]);
+        })()
+        : rawGapEntryText(rawSliceLines.map((l) => l.replace(/\r$/, '')));
+    if (verifyText !== targetText) {
+        return { content, status: 'match_verification_failed' };
+    }
+    // Status search over the READER-form lines — the exact set the reader
+    // parses (bolded any case + bare lowercase, per #3775; line-0 forms per
+    // #3740). Reader lines are index-aligned 1:1 with the raw lines.
+    const statusFieldBoldedRe = /^\s*\*+status:\*+/i;
+    const statusFieldBareRe = /^\s*status:/;
+    const statusFieldBoldedReLine0 = /^\s*(?:-\s+)?\*+status:\*+/i;
+    const statusFieldBareReLine0 = /^\s*(?:-\s+)?status:/;
+    const readerLines = entry.kind === 'leaf'
+        ? [
+            stripAtxPrefix(rawSliceLines[0]) ?? rawSliceLines[0].replace(/\r$/, ''),
+            ...rawSliceLines.slice(1).map((l) => stripLeadingBulletMarker(l.replace(/\r$/, ''))),
+        ]
+        : rawSliceLines.map((l) => l.replace(/\r$/, ''));
+    const statusLineIdx = readerLines.findIndex((line, idx) => idx === 0
+        ? (statusFieldBoldedReLine0.test(line) || statusFieldBareReLine0.test(line))
+        : (statusFieldBoldedRe.test(line) || statusFieldBareRe.test(line)));
+    let newRawLines;
+    if (statusLineIdx === -1) {
+        // Insert branch: after the entry's LAST NON-BLANK line — a heading
+        // entry's body is frequently a soft-wrapped sentence, and splicing after
+        // line 0 would split it in half (#3781's sentence trap). The headless
+        // (no-heading-anywhere) path keeps its own splice-after-line-0 shape.
+        let lastNonBlank = rawSliceLines.length - 1;
+        while (lastNonBlank > 0 && rawSliceLines[lastNonBlank].replace(/\r$/, '').trim() === '') {
+            lastNonBlank--;
+        }
+        const indent = entry.kind === 'pending'
+            ? (() => {
+                const bulletIndentMatch = rawSliceLines[0].match(/^(\s*)-\s+/);
+                return ' '.repeat((bulletIndentMatch ? bulletIndentMatch[1].length : 0) + 2);
+            })()
+            : '  ';
+        newRawLines = [
+            ...rawSliceLines.slice(0, lastNonBlank + 1),
+            `${indent}status: acknowledged`,
+            ...rawSliceLines.slice(lastNonBlank + 1),
+        ];
+    }
+    else {
+        newRawLines = rawSliceLines.slice();
+        if (entry.kind === 'leaf' && statusLineIdx === 0) {
+            // Leaf line 0 is the RAW heading line — rewrite the heading-text portion
+            // the reader treats as a field, with the ATX prefix preserved.
+            const replacedReader = readerLines[statusLineIdx].replace(/^(\s*(?:-\s+)?)(\*+status:\*+|status:)(\s*).*$/i, (_m, indent, key, ws) => `${indent}${key}${ws}acknowledged`);
+            const atxMatch = /^(\s*#+[ \t]*)(.*)$/.exec(rawSliceLines[0].replace(/\r$/, ''));
+            newRawLines[0] = atxMatch ? atxMatch[1] + replacedReader : replacedReader;
+        }
+        else {
+            // Every other status line is rewritten on its RAW line, so the bullet
+            // marker and indent survive the write (the reader-form line has the
+            // marker stripped — writing it back would mangle the markdown shape and
+            // change the entry's identity text). Same replacement regex as the
+            // headless path.
+            newRawLines[statusLineIdx] = rawSliceLines[statusLineIdx].replace(/^(\s*(?:-\s+)?)(\*+status:\*+|status:)(\s*).*$/i, (_m, indent, key, ws) => `${indent}${key}${ws}acknowledged`);
+        }
+    }
+    const matchIndexInContent = sectionOffset + entry.start;
+    const newContent = content.slice(0, matchIndexInContent) + newRawLines.join('\n') + content.slice(matchIndexInContent + (entry.end - entry.start));
+    return { content: newContent, status: 'ok' };
+}
+/**
+ * Strip one leading `- ` bullet marker (#3457). Heading-delimited deferred
+ * entries carry their fields as sibling bullets; `extractGapEntryFields` only
+ * de-bullets line 0 (Gaps-protective — there, a later `- ` line is a nested
+ * sub-list), so the deferred heading path de-bullets every line itself before
+ * field extraction. Non-bullet lines pass through untouched.
+ */
+function stripLeadingBulletMarker(line) {
+    return line.replace(/^(\s*)-\s+/, '');
+}
+/**
+ * Split a deferred-items section body into entries delimited by LEAF headings
+ * (#3457). Returns `null` when the body contains no heading at all — the
+ * caller then falls back to `splitGapsEntries`, keeping headless
+ * one-bullet-per-item files byte-for-byte on the pre-#3457 path.
+ *
+ * A heading is a CONTAINER (group/provenance/title label, contributes no
+ * entry) iff the NEXT heading is deeper — a deeper heading lives inside its
+ * span. Otherwise it is a LEAF: an entry boundary. This handles all three
+ * corpus shapes without hardcoding a depth: flat `#` title + `##` entries
+ * (title's next heading is deeper → container; each `##` followed by a
+ * same-or-shallower heading → leaf), a `##` container with `###` entries
+ * (container's next heading is deeper), and mixed-depth files where a
+ * childless `##` entry sits alongside a `##` group with `###` children — every
+ * childless heading is a leaf at whatever depth it is written. The shallower
+ * rules the issue reports as already tried (split on every heading; shallowest
+ * level; deepest level) each mis-count one of these shapes.
+ *
+ * A leaf entry is [heading text, ...body lines up to the next heading] and is
+ * kept only when its body (minus table lines) contains at least one `- `
+ * bullet:
+ * - a prose-only or bare heading contributes nothing — "prose is not an item"
+ *   is this parser's pre-existing contract (see the `# Notes` case);
+ * - a table-only body is left entirely to `parseDeferredTableItems`, which
+ *   unions over the same section body, so the heading cannot double-count the
+ *   table's rows.
+ *
+ * Lines before the first heading, and lines directly under a container heading
+ * (before its first child), are split one-bullet-per-item by the unchanged
+ * `splitGapsEntries` — headless parity, so loose bullets before a later
+ * heading group (the mixed shape) stay one item each.
+ */
+function splitDeferredHeadingEntries(sectionBody) {
+    const headings = tokenizeHeadings(sectionBody);
+    if (headings.length === 0)
+        return null;
+    const lines = sectionBody.split('\n');
+    const headingByLine = new Map();
+    for (let i = 0; i < headings.length; i++) {
+        // Container iff the next heading is deeper (see doc comment). An empty
+        // heading text (`##` alone) does not itself mean container — the flag is
+        // carried explicitly so a bare LEAF heading still opens an entry.
+        const isContainer = i + 1 < headings.length && headings[i + 1].level > headings[i].level;
+        headingByLine.set(headings[i].line, { text: headings[i].text, isContainer });
+    }
+    const entries = [];
+    let current = null; // accumulating a leaf heading's entry
+    let pending = []; // preamble / container-heading body lines
+    let currentHasBullet = false;
+    const flushCurrent = () => {
+        // Keep the leaf entry only when its body carries a bullet; the heading
+        // text line itself (element 0) never counts as one.
+        if (current !== null && currentHasBullet)
+            entries.push(current);
+        current = null;
+        currentHasBullet = false;
+    };
+    const flushPending = () => {
+        entries.push(...splitGapsEntries(pending.join('\n')));
+        pending = [];
+    };
+    for (let i = 0; i < lines.length; i++) {
+        const lineNo = i + 1;
+        const heading = headingByLine.get(lineNo);
+        if (heading !== undefined) {
+            flushCurrent();
+            // Headless-shaped region (preamble / container-direct bullets) ends at
+            // ANY heading; flushing here keeps entries in document order even when
+            // a container's direct bullets precede its first child entry.
+            flushPending();
+            if (!heading.isContainer) {
+                // Leaf heading: open an entry with the heading text as line 0.
+                current = [heading.text];
+                currentHasBullet = false;
+            }
+            continue;
+        }
+        // Table lines belong to parseDeferredTableItems, never to a heading entry.
+        if (/^\s*\|/.test(lines[i].replace(/\r$/, '')))
+            continue;
+        if (current !== null) {
+            current.push(lines[i]);
+            if (/^\s*-\s/.test(lines[i].replace(/\r$/, '')))
+                currentHasBullet = true;
+        }
+        else {
+            pending.push(lines[i]);
+        }
+    }
+    flushCurrent();
+    flushPending();
+    return entries;
+}
 /**
  * Extract deferred entries from GFM pipe tables in a deferred-items.md body
  * (#2766) — a UNION with the bullet scan in `parseDeferredItems`.
@@ -831,49 +2322,123 @@ function parseDeferredTableItems(sectionBody) {
     return items;
 }
 /**
- * Split a `## Gaps` section body into per-entry line groups on TOP-LEVEL
- * `- ` bullet openers.
- *
- * The indentation of the FIRST bullet line encountered establishes the
- * "top-level" indent for the whole section; any subsequent `- `-opening line
- * at that same indent (or shallower) starts a NEW entry, while everything
- * more deeply indented — field continuation lines (`  status: ...`) AND
- * nested sub-lists (`    - src/foo.ts` under `  artifacts:`) — is folded into
- * the CURRENT entry. This keeps a `artifacts:`/`missing:` sub-list's `- `
- * items from being mis-split into spurious standalone entries (#2286 review
- * LOW finding).
- *
- * Lines before the first bullet (e.g. the `<!-- YAML format ... -->` comment
- * the template emits) are discarded. An empty/whitespace-only section body
- * (heading present, no bullets) returns `[]`.
+ * Shared walk behind `splitGapsEntries` and `splitGapsEntriesWithSpans` — ONE
+ * pass over `sectionBody` that both groups its lines into entries (see
+ * `splitGapsEntries`'s doc comment for the grouping rule) AND records each
+ * entry's (start, end) character offset within `sectionBody`. Extracted so
+ * the two public shapes can never drift apart on what counts as an entry
+ * boundary — a second, independently-written grouping pass is exactly how a
+ * span-carrying sibling could disagree with the plain-lines version it is
+ * supposed to be span-annotating.
  */
-function splitGapsEntries(sectionBody) {
-    const lines = sectionBody.split('\n');
+function splitGapsEntriesCore(sectionBody) {
+    const rawLines = sectionBody.split('\n');
+    const lineStarts = [];
+    const lineEnds = [];
+    let cursor = 0;
+    for (const rawLine of rawLines) {
+        lineStarts.push(cursor);
+        cursor += rawLine.length;
+        lineEnds.push(cursor);
+        cursor += 1; // the '\n' separator — absent after the final line, but nothing reads past it
+    }
     const entries = [];
     let current = null;
+    let currentStartLine = -1;
+    let currentEndLine = -1;
     let baseIndent = null;
-    for (const rawLine of lines) {
+    const flush = () => {
+        if (current !== null) {
+            entries.push({ lines: current, start: lineStarts[currentStartLine], end: lineEnds[currentEndLine] });
+        }
+    };
+    // #3898: a spaced-hyphen thematic break (`- - -`, `- -`, `-  -  -`, …) is a
+    // SEPARATOR, not an entry. The opener regex below matches it (hyphen +
+    // whitespace), which fabricated a gap named `- -` with result 'unknown' —
+    // an item that cannot be cleared by editing any entry, because there is no
+    // entry, only the separator the author wrote deliberately. A line whose
+    // content after the opening marker consists solely of hyphens and spaces
+    // (with at least one further hyphen) is skipped entirely: it neither opens
+    // an entry nor is folded into the current one. This is deliberately NOT a
+    // full thematic-break concept (option 2 in the issue): a break does not
+    // close the Gaps list — entries after it keep parsing.
+    const isSeparatorShaped = (line, bulletPrefixLen) => {
+        const remainder = line.slice(bulletPrefixLen);
+        return /^[-\s]*$/.test(remainder) && remainder.includes('-');
+    };
+    rawLines.forEach((rawLine, idx) => {
         const line = rawLine.replace(/\r$/, '');
         const bulletMatch = line.match(/^(\s*)-\s/);
+        // Narrowed skip (review disposition a): a separator-shaped line is skipped
+        // only when it sits BETWEEN entries (nothing open yet, or it would open a
+        // top-level entry — where the phantom came from). One landing strictly
+        // INSIDE a live entry (indent > baseIndent) folds back as a continuation
+        // line, so the entry's GapsEntrySpan stays byte-contiguous — the span
+        // invariant below and the ack writer's identity re-verification both hold.
+        if (bulletMatch && isSeparatorShaped(line, bulletMatch[0].length) &&
+            (current === null || bulletMatch[1].length <= (baseIndent ?? 0))) {
+            return; // separator line between entries — neither an opener nor a continuation
+        }
         if (bulletMatch) {
             const indent = bulletMatch[1].length;
             if (baseIndent === null)
                 baseIndent = indent;
             if (indent <= baseIndent) {
-                if (current)
-                    entries.push(current);
+                flush();
                 current = [line];
-                continue;
+                currentStartLine = idx;
+                currentEndLine = idx;
+                return;
             }
         }
-        if (current)
+        if (current !== null) {
             current.push(line);
+            currentEndLine = idx;
+        }
         // else: pre-first-bullet content (e.g. the template's HTML comment) — discarded.
-    }
-    if (current)
-        entries.push(current);
+    });
+    flush();
     return entries;
 }
+/**
+ * Split a `## Gaps` section body into per-entry line groups on TOP-LEVEL
+ * `- ` bullet openers.
+ *
+ * The indentation of the FIRST bullet line encountered establishes the
+ * "top-level" indent for the whole section; any subsequent `- `-opening line
+ * at that same indent (or shallower) starts a NEW entry, while everything
+ * more deeply indented — field continuation lines (`  status: ...`) AND
+ * nested sub-lists (`    - src/foo.ts` under `  artifacts:`) — is folded into
+ * the CURRENT entry. This keeps a `artifacts:`/`missing:` sub-list's `- `
+ * items from being mis-split into spurious standalone entries (#2286 review
+ * LOW finding).
+ *
+ * Lines before the first bullet (e.g. the `<!-- YAML format ... -->` comment
+ * the template emits) are discarded. An empty/whitespace-only section body
+ * (heading present, no bullets) returns `[]`.
+ */
+function splitGapsEntries(sectionBody) {
+    return splitGapsEntriesCore(sectionBody).map((entry) => entry.lines);
+}
+/**
+ * Sibling of `splitGapsEntries` (F1, #3458 follow-up review) that ADDITIVELY
+ * carries each entry's character span — every existing `splitGapsEntries`
+ * caller (`parseGapsItems`, `parseDeferredItemsWithStatus`,
+ * `splitDeferredHeadingEntries`'s `flushPending`) is unaffected and keeps
+ * using the plain `lines`-only shape. `acknowledgeDeferredItem` is the one
+ * caller that needs a span: it used to select an entry via `splitGapsEntries`
+ * and then RE-FIND that entry's location with a fresh regex search over
+ * `sectionBody` — matching the FIRST occurrence of the entry's exact text,
+ * not necessarily the entry actually selected (a continuation/quoted line
+ * inside a DIFFERENT entry can carry byte-identical text). Because the
+ * mis-targeted span is byte-identical to the target text, no check on the
+ * WRITTEN result could ever tell a wrong-entry write apart from a correct
+ * one. Carrying the span out of THIS same pass — the one that already knows
+ * exactly where the entry lives — removes the re-derivation step entirely.
+ */
+function splitGapsEntriesWithSpans(sectionBody) {
+    return splitGapsEntriesCore(sectionBody);
+}
 /**
  * Extract `key: value` fields from one Gaps entry's lines, anchored to the
  * START of each (bullet-marker-stripped, trimmed) line — never scanning the
@@ -888,10 +2453,22 @@ function splitGapsEntries(sectionBody) {
  * any nested sub-list content in the template's field ordering); later
  * `key:`-shaped nested-list content is captured, if it parses as one, but
  * never overrides an already-seen top-level field.
+ *
+ * #3457: markdown emphasis around the KEY (`**Status:** resolved` — the
+ * deferred-items convention bolds every field, and a bolded resolution marker
+ * previously failed this regex outright and surfaced as its own bogus
+ * unresolved entry) is unwrapped before the match, still anchored at the
+ * start of the line. The unwrapped key is lower-cased, because the bolded
+ * convention form is Title-cased (`**Status:**`) while the field vocabulary
+ * this module reads is lowercase (`status`) — the same normalization
+ * `mapGapsHeader` already applies to table header cells. Bare (unbolded) keys
+ * keep their literal case, and mid-line emphasis is untouched, preserving the
+ * start-anchored decoy invariant above.
  */
 function extractGapEntryFields(entryLines) {
     const fields = {};
     const fieldLineRe = /^([A-Za-z_][A-Za-z0-9_-]*):\s*(.*)$/;
+    const boldedKeyRe = /^\*+([A-Za-z_][A-Za-z0-9_-]*):\*+/;
     entryLines.forEach((rawLine, idx) => {
         const line = rawLine.replace(/\r$/, '');
         // Strip ONLY the entry-opening bullet marker (idx 0); a bullet marker on
@@ -899,7 +2476,8 @@ function extractGapEntryFields(entryLines) {
         // `splitGapsEntries` already folding it in — it is not itself a field
         // line unless it independently matches `key: value` after stripping.
         const bulletStripped = line.match(/^(\s*)-\s+(.*)$/);
-        const content = idx === 0 && bulletStripped ? bulletStripped[2] : line.trim();
+        const content = (idx === 0 && bulletStripped ? bulletStripped[2] : line.trim())
+            .replace(boldedKeyRe, (_m, key) => `${key.toLowerCase()}:`);
         const m = fieldLineRe.exec(content);
         if (!m)
             return;
@@ -1093,7 +2671,13 @@ function normalizeHumanVerificationEntry(raw) {
     return s || raw.trim();
 }
 // ─── categorizeItem ───────────────────────────────────────────────────────────
-function categorizeItem(result, reason, blockedBy) {
+function categorizeItem(rawResult, reason, blockedBy) {
+    // Normalize once so this comparison agrees with the PASS-token check
+    // (`UAT_PASS_RESULTS.has(result)`, over an already-lower-cased token):
+    // `result: PENDING` and
+    // `result: Blocked` must categorize the same as their lowercase forms,
+    // not fall through to 'unknown'.
+    const result = rawResult.toLowerCase();
     if (result === 'blocked' || blockedBy) {
         if (blockedBy) {
             if (/server/i.test(blockedBy))
@@ -1122,16 +2706,26 @@ function categorizeItem(result, reason, blockedBy) {
         return 'pending';
     if (result === 'human_needed')
         return 'human_uat';
+    // #3707: the template-sanctioned `result: issue` token (templates/UAT.md)
+    // has no UatCategory branch here, so a surfaced issue row previously fell
+    // through to 'unknown' — placed AFTER the blocked/skipped/pending checks
+    // above so it never shadows their more specific categorization.
+    if (result === 'issue')
+        return 'issue';
     return 'unknown';
 }
 module.exports = {
     cmdAuditUat,
     cmdRenderCheckpoint,
     parseCurrentTest,
+    parseUatItems,
+    parseUatItemsWithStats,
+    selectPhaseUatFiles,
     buildCheckpoint,
     CHECKPOINT_FRAMES,
     CHECKPOINT_LANGUAGE_ALIASES,
     resolveCheckpointFrame,
-    checkpointBoxLine,
     parseDeferredItems,
+    parseDeferredItemsWithStatus,
+    acknowledgeDeferredItem,
 };