@dev-loops/core 1.0.0 → 1.0.2-pre.0

package/src/loop/issue-refinement-artifact.mjs

@@ -2,15 +2,35 @@
  * Deterministic issue refinement-artifact detection.
  *
  * Implements the bounded refinement check required by the draft gate per
- * issue #532: a draft PR cannot leave draft unless the linked issue has an
- * explicit refinement artifact (Acceptance criteria section, DoD section,
- * or a linked refinement doc) that the pre-approval gate can verify
- * against. Prose-only issues (Problem / Root Cause / Fix) without an
- * `Acceptance criteria` or `DoD` section cause the draft gate to post
- * `verdict=blocked` with the `missing_refinement_artifact` finding.
+ * issue #532, reshaped by #1951 to honor "matrix on the issue, checklist on
+ * the PR" WITHOUT duplicate issue-side checklists: a draft PR cannot leave
+ * draft unless the linked issue carries the authoritative semantic AC→DoD
+ * mapping MATRIX (a real two-column table mapping each acceptance-criterion
+ * outcome to its required completion evidence) plus an explicit Non-goals
+ * section — or a linked refinement doc that is a complete artifact on its own
+ * (the doc carries the matrix). Interactive issue-side Acceptance criteria /
+ * Definition of done CHECKLISTS are NO LONGER required merely to satisfy
+ * detection (#1951 AC1): the matrix is the authoritative issue artifact, and
+ * the PR carries the derived self-contained list-form AC/DoD checklists
+ * (`derivePrChecklistsFromIssueMatrix`; the PR body is validated by
+ * `validateTrackerBackedPrBodySpec`, never this predicate).
  *
- * Since #1866 the check ALSO requires an explicit Non-goals section on the
- * issue body (see `MISSING_EXPLICIT_NON_GOALS_FINDING` below).
+ * Detection validates the structural PRESENCE and SHAPE of the mapping table,
+ * not its semantic truthfulness (that stays a reviewer responsibility). An
+ * issue whose AC content, DoD content, and Non-goals are present but whose
+ * mapping table is absent, empty, malformed, or identifier-only fails closed
+ * (#1951 AC2) with the matching finding (`missing_ac_dod_matrix`,
+ * `malformed_ac_dod_matrix`, `missing_explicit_non_goals`, or
+ * `missing_refinement_artifact`); prose-only issues (Problem / Root Cause /
+ * Fix) cause the draft gate to post `verdict=blocked` with the
+ * `missing_refinement_artifact` finding.
+ *
+ * Migration (#1951 AC7/D7): existing checklist-bearing issues stay readable —
+ * the parser still extracts their AC/DoD checklist content — but a body that
+ * carries only checklists and no mapping matrix now fails closed with
+ * `missing_ac_dod_matrix` and is re-grilled (loop-grill synthesizes the
+ * matrix) rather than being silently grandfathered. No compatibility alias is
+ * retained.
  */
 import { existsSync } from "node:fs";
 import path from "node:path";
@@ -28,6 +48,7 @@ import path from "node:path";
  */
 
 export const REFINEMENT_SOURCE = Object.freeze({
+  ISSUE_BODY_MATRIX: "issue-body-matrix",
   ISSUE_BODY_AC: "issue-body-ac",
   ISSUE_BODY_DOD: "issue-body-dod",
   LINKED_DOC: "linked-doc",
@@ -36,12 +57,14 @@ export const REFINEMENT_SOURCE = Object.freeze({
 
 const REFINEMENT_ARTIFACT_FINDING = "missing_refinement_artifact";
 
-// The three artifact sources, any ONE of which satisfies the refinement gate.
-// Single source of truth for the "missing" vocabulary reported when none is
-// present — consumed by the enqueue gate and the parked-unrefined discovery.
+// REFINEMENT_ARTIFACT_SOURCES: the refinement floor vocabulary (#1951). The
+// floor is the authoritative AC→DoD mapping MATRIX plus an explicit Non-goals
+// section (a linked refinement doc remains a complete artifact on its own) —
+// this list is the shape of a COMPLETE artifact, not a menu where any one
+// entry suffices.
 export const REFINEMENT_ARTIFACT_SOURCES = Object.freeze([
-  "Acceptance criteria section",
-  "Definition of done section",
+  "AC→DoD mapping matrix (a two-column table)",
+  "explicit Non-goals section",
   "linked refinement doc",
 ]);
 
@@ -54,6 +77,25 @@ export const REFINEMENT_ARTIFACT_SOURCES = Object.freeze([
  */
 export const MISSING_EXPLICIT_NON_GOALS_FINDING = "missing_explicit_non_goals";
 
+/**
+ * #1951: finding reported when the issue body carries refinement content (AC
+ * content, DoD content, and/or a Non-goals section) but NO authoritative
+ * AC→DoD mapping matrix table. Under "matrix on the issue, checklist on the
+ * PR" the mapping table is the authoritative issue artifact; interactive
+ * issue-side AC/DoD checklists are not a substitute for it. Fails closed so
+ * the issue is re-grilled to add the matrix.
+ */
+export const MISSING_AC_DOD_MATRIX_FINDING = "missing_ac_dod_matrix";
+
+/**
+ * #1951: finding reported when the issue body carries an AC→DoD mapping table
+ * but it is empty (header/separator only, no data rows) or identifier-only /
+ * tautological (cells such as `AC1 → D1` with no concrete criterion or
+ * completion-evidence prose). Structural shape validation only — semantic
+ * truthfulness of the mapping stays a reviewer responsibility.
+ */
+export const MALFORMED_AC_DOD_MATRIX_FINDING = "malformed_ac_dod_matrix";
+
 /**
  * Canonical list of section headings that satisfy the refinement check.
  * Matching is case-insensitive and tolerates trailing/leading whitespace.
@@ -62,16 +104,152 @@ export const MISSING_EXPLICIT_NON_GOALS_FINDING = "missing_explicit_non_goals";
  *   - one DoD-style section (DoD or Definition of Done)
  */
 const ACCEPTANCE_SECTION_PATTERNS = Object.freeze([
-  /^acceptance criteria\s*$/i,
+  // #1877 round-6: index 0 is the exact-canonical ANCHOR family —
+  // `^acceptance criteria\b` — so a decorated-variant canonical heading
+  // (`## Acceptance criteria (v2)`, `## Definition of done — core`) still lands
+  // in the exact bucket rather than matching NO pattern at all (the alias
+  // families anchor on the `AC`/`DoD` abbreviations and never fire for the
+  // spelled-out phrase). The anchor stays distinct from the alias family below
+  // (`/^ac\b/`), so the precedence contract is unchanged: a spelled-out
+  // canonical heading always outranks an abbreviation-shaped alias heading.
+  /^acceptance criteria\b.*$/i,
   /^ac\b.*$/i,
 ]);
 
 const DOD_SECTION_PATTERNS = Object.freeze([
-  /^definition of done\s*$/i,
-  /^done\s*$/i,
-  /^dod\s*$/i,
+  // Same anchor-family widening as the AC family (see above). #1877 round-7:
+  // the ALIAS arms are widened symmetrically with the AC family too — a
+  // decorated-variant alias heading (`## DoD (v2)`, `## Done — core`) must land
+  // in the alias bucket, not in NO bucket (a `$`-anchored alias silently
+  // disarms the PR-side DoD read and false-blocks the issue side).
+  /^definition of done\b.*$/i,
+  /^done\b.*$/i,
+  /^dod\b.*$/i,
 ]);
 
+/**
+ * Normalize a heading name before section-pattern matching (#1877 round-6
+ * parser hardening): GitHub authors legitimately write decorated canonical
+ * headings — `## **Acceptance criteria**`, `## Acceptance criteria:`,
+ * `## Acceptance criteria ##` — and the raw ATX capture (`match[2]`)
+ * fails every pattern family on them, silently disarming the deterministic
+ * AC/DoD reads (PR-side extractor fail-open; issue-side false
+ * missing_refinement_artifact). Strip the harmless decoration once, at the
+ * parse boundary, so exact-vs-alias precedence stays intact: a normalized
+ * `Acceptance criteria` still matches the exact pattern, a decorated alias
+ * still matches its alias family. Strips: surrounding emphasis runs of any
+ * of `*`/`_` (bold `**`/`__` and single-char italic `*`/`_` alike, #1877
+ * round-7), surrounding backtick runs, trailing `:` and surrounding
+ * whitespace.
+ * Deliberately NOT touched: interior text (a real `AC (v2) - final` name keeps
+ * its interior), leading `#` (ATX markers never reach `match[2]`), and any
+ * decoration a section pattern itself could rely on (none does — every family
+ * anchors at the name's start).
+ */
+function normalizeHeadingName(name) {
+  if (typeof name !== "string") return name;
+  return name
+    // trailing decoration first: closing `##` ATX-style, colons, whitespace
+    .replace(/\s*:*\s*$/u, "")
+    .replace(/\s*#+\s*$/u, "")
+    // surrounding emphasis/backtick runs (any length, must pair; #1877
+    // round-7: a run may be single-char italic `*`/`_` as well as bold
+    // `**`/`__`, so `## *Acceptance criteria*` and `## _Definition of done_`
+    // normalize exactly like their bold forms)
+    .replace(/^[*_`]+/u, "")
+    .replace(/[*_`]+$/u, "")
+    .trim();
+}
+
+// #1877 alias-precedence: exact canonical headings (the first pattern in each
+// family) must outrank loose aliases (`/^ac\b/`, `/^dod\b/`) so a matrix-shaped
+// heading the refined-issue contract itself produces (`## AC/DoD matrix`,
+// `## AC → DoD mapping`) can never hijack the canonical section read. Split
+// each pattern family into [exact, aliases] by convention: pattern index 0
+// is the exact canonical match, the rest are aliases.
+const EXACT_PATTERN_INDEX = 0;
+
+/**
+ * Resolve the sections matching a heading-pattern family with exact-first
+ * precedence (#1877): the first section matching the EXACT canonical pattern
+ * (index 0) wins over any earlier section that only matched a loose alias
+ * (e.g. `## AC/DoD matrix` before `## Acceptance criteria`). When no exact
+ * match exists, the first alias match is returned (alias-only bodies keep
+ * working). Returns null when no section matches at all.
+ */
+function findSectionByPatterns(sections, patterns) {
+  const exact = patterns[EXACT_PATTERN_INDEX];
+  for (const section of sections) {
+    if (exact.test(section.name)) {
+      return section;
+    }
+  }
+  for (const section of sections) {
+    for (let i = 1; i < patterns.length; i += 1) {
+      if (patterns[i].test(section.name)) {
+        return section;
+      }
+    }
+  }
+  return null;
+}
+
+/**
+ * Collect ALL sections matching a heading-pattern family, exact-first ordered
+ * (exact canonical matches before alias-only matches). Shared with
+ * `findSectionByPatterns`'s precedence semantics so single-section consumers
+ * and union consumers (#1877 PR-body unchecked-box extraction) cannot drift.
+ */
+function findAllSectionsByPatterns(sections, patterns) {
+  const exact = patterns[EXACT_PATTERN_INDEX];
+  const exactMatches = [];
+  const aliasMatches = [];
+  for (const section of sections) {
+    if (exact.test(section.name)) {
+      exactMatches.push(section);
+    } else {
+      for (let i = 1; i < patterns.length; i += 1) {
+        if (patterns[i].test(section.name)) {
+          aliasMatches.push(section);
+          break;
+        }
+      }
+    }
+  }
+  return [...exactMatches, ...aliasMatches];
+}
+
+/**
+ * Flatten a section (heading record) into a body string that extends past
+ * `###` sub-headings (#1877): a section's checklist may nest items under
+ * deeper sub-headings (`### edge cases` inside `## Acceptance criteria`), so
+ * join the section and every following section of a DEEPER heading level up
+ * to the next same-or-shallower heading. `parseMarkdownSections` terminates a
+ * section's `bodyLines` at ANY heading, which is correct for heading
+ * matching but hides unchecked boxes from consumers that must see ALL of a
+ * canonical section's boxes.
+ */
+function flattenSectionDeep(sections, startIndex) {
+  const start = sections[startIndex];
+  // #1877 round-6 heading-name re-injection fix: the raw sub-heading NAME is
+  // NEVER re-injected into the text the checklist parser re-parses. A name is
+  // a different input class from checklist body text: a fence-opening name
+  // (`### ``` `) used to corrupt the parser's fence state and eat every real
+  // box after it (fail-open), and a checkbox-shaped name (`### - [ ] fake`)
+  // used to be counted as a phantom unchecked item (spurious fail-closed).
+  // Only already-classified bodyLines are joined — a heading can never match
+  // any line-level grammar, and real boxes under sub-headings stay visible
+  // because their bodyLines still join normally. (Keeping a marker line is
+  // unnecessary: parseChecklistItems never needed the heading boundary to
+  // track fence state — body lines carry their own fences.)
+  const parts = [start.bodyLines.join("\n")];
+  for (let i = startIndex + 1; i < sections.length; i += 1) {
+    if (sections[i].level <= start.level) break;
+    parts.push(sections[i].bodyLines.join("\n"));
+  }
+  return parts.join("\n");
+}
+
 /**
  * Fenced-code-span tracker. Given the previous fence state and the current
  * line, returns { fence, insideFence } where:
@@ -135,7 +313,12 @@ export function parseMarkdownSections(body) {
       }
       current = {
         level: match[1].length,
-        name: match[2],
+        // #1877 round-6: normalize the captured name so decorated canonical
+        // headings (`## **Acceptance criteria**`) match the section patterns.
+        // The RAW name is never re-parsed as body text (flattenSectionDeep no
+        // longer re-injects it), so normalization is the only consumer of the
+        // capture — the raw form is not retained (no consumer reads it).
+        name: normalizeHeadingName(match[2]),
         bodyLines: [],
       };
       continue;
@@ -152,22 +335,16 @@ export function parseMarkdownSections(body) {
   return sections;
 }
 
-function findSectionByPatterns(sections, patterns) {
-  for (const section of sections) {
-    for (const pattern of patterns) {
-      if (pattern.test(section.name)) {
-        return section;
-      }
-    }
-  }
-  return null;
-}
 
 /**
  * Parse bullet/checkbox items from a section body into item states. Each
- * checkbox item (`- [ ]`/`- [x]`/`- [X]`) becomes `{ text, checked }`
- * (`checked` true only for a ticked `[x]`/`[X]`); a top-level plain bullet
- * (`- text`, dash at column 0 so nested/indented sub-bullets are not counted)
+ * checkbox item — any GFM/CommonMark task-list marker: `-`/`*`/`+` bullets,
+ * ordered `N.`/`N)`, and blockquote-nested `> - [ ]` (#1877 round-6 grammar
+ * widening; parity with tick-verified-checkboxes.mjs's `[-*+]`) — becomes
+ * `{ text, checked }` (`checked` true only for a ticked `[x]`/`[X]` marker,
+ * read from the captured marker group, never a whole-line re-test); a
+ * top-level plain bullet (`- text`, dash at column 0 so nested/indented
+ * sub-bullets are not counted)
  * becomes `{ text, checked: null }` — it has no checkbox to tick. Empty
  * checkbox placeholders (`- [ ]` / `- [x]` with no trailing text) are skipped,
  * not counted, so a section of only unfilled placeholders reports as unrefined.
@@ -197,17 +374,30 @@ function parseChecklistItems(sectionBody) {
     if (step.insideFence) {
       continue;
     }
-    // Checklist item: `- [ ]` / `- [x]` (leading indentation tolerated).
-    // Consume ANY checkbox-marker line here; push only when it carries text,
-    // so empty placeholders (`- [ ]`) are skipped rather than counted.
-    const checkboxMatch = /^\s*-\s+\[(?:[ xX])\](?:\s+(.+?))?\s*$/u.exec(line);
+    // Checklist item: GFM/CommonMark task-list markers (#1877 round-6 parser
+    // hardening): `-`/`*`/`+` bullets, ordered `N.`/`N)`, and blockquote-nested
+    // `> - [ ]` — the forms GitHub itself renders as interactive checkboxes.
+    // Grammar parity with tick-verified-checkboxes.mjs's CHECKBOX_RE (same
+    // #1877 round-1 widening): both accept bullets, ordered markers, and
+    // blockquote-nested forms, so every form this extractor surfaces as
+    // unchecked is flippable by the tick tool. Consume ANY checkbox-marker line
+    // here; push only when it carries text, so empty placeholders (`- [ ]`) are
+    // skipped rather than counted. #1877 round-7: the tick state comes from the
+    // CAPTURED marker group of this single match — never a second whole-line
+    // re-test. An unanchored `/\[(?:[xX])\]/u.test(line)` reads an UNCHECKED box
+    // whose label text merely mentions `[x]` (e.g. `- [ ] verify [x] flags`) as
+    // checked, silently disarming the deterministic block — the exact
+    // fail-open class the marker-anchored pre-#1877 read could not produce.
+    const checkboxMatch =
+      /^\s*(?:>|\s)*(?:[-*+]|\d+[.)])\s+\[([ xX])\](?:\s+(.+?))?\s*$/u.exec(line);
     if (checkboxMatch) {
-      const text = (checkboxMatch[1] ?? "").trim();
+      const text = (checkboxMatch[2] ?? "").trim();
       if (text.length > 0) {
-        // `checked` is true only for a ticked box; `[ ]` (space) is false.
+        // `checked` is true only for a ticked marker (`[x]`/`[X]`); a space
+        // marker (`[ ]`) is false — regardless of what the label text says.
         // A plain bullet has no checkbox, so it stays `null` below — it is
         // neither ticked nor unticked and does not count as an unticked AC.
-        items.push({ text, checked: /^\s*-\s+\[[xX]\]/u.test(line) });
+        items.push({ text, checked: checkboxMatch[1] !== " " });
       }
       continue;
     }
@@ -251,6 +441,214 @@ export function extractUncheckedChecklistItems(sectionBody) {
     .map((item) => item.text);
 }
 
+// ---------------------------------------------------------------------------
+// AC→DoD mapping matrix detection (#1951)
+// ---------------------------------------------------------------------------
+// The authoritative refined-issue artifact is a semantic AC→DoD mapping table:
+// a GFM pipe table whose rows map each acceptance-criterion outcome to its
+// required completion evidence. This is the "matrix on the issue" half of
+// "matrix on the issue, checklist on the PR". Detection validates the table's
+// PRESENCE and SHAPE only — its semantic truthfulness stays a reviewer duty.
+
+// Heading families that name the mapping-matrix section. A qualifying table
+// under one of these headings is treated as the matrix even when its column
+// headers do not name criterion/evidence explicitly.
+const MATRIX_SECTION_PATTERNS = Object.freeze([
+  /\bac\b.*\bdod\b.*\b(matrix|mapping|map)\b/i,
+  /\b(acceptance|criteri\w*)\b.*\b(matrix|mapping|map)\b/i,
+  /\bmapping (matrix|table)\b/i,
+  /\bac\s*(?:\/|→|->|to)\s*dod\b/i,
+]);
+
+// Header column families: col0 names the criterion side, col1 the evidence
+// side. Used to recognize an unheaded (not under a matrix heading) but clearly
+// criterion→evidence table anywhere in the body. Kept STRONG on purpose (#1951
+// draft_gate correctness review): a generic status table like `| Outcome |
+// Done |` must NOT be mistaken for the refinement matrix — only headers that
+// explicitly name acceptance criteria AND completion evidence / DoD qualify
+// without a matrix heading. A matrix under a weaker header still qualifies via
+// its `## AC / DoD matrix` heading (MATRIX_SECTION_PATTERNS), which is what the
+// loop-grill synthesis and the epic procedure both write.
+const MATRIX_CRITERION_HEADER = /\b(criteri\w*|acceptance|ac)\b/i;
+const MATRIX_EVIDENCE_HEADER = /\b(evidence|dod|definition of done)\b/i;
+
+const TABLE_DELIMITER_RE = /^\s*\|?\s*:?-{1,}:?\s*(\|\s*:?-{1,}:?\s*)+\|?\s*$/u;
+
+/** Split one GFM table row into trimmed cell strings (drops leading/trailing pipes). */
+function splitTableRow(line) {
+  let s = line.trim();
+  if (s.startsWith("|")) s = s.slice(1);
+  if (s.endsWith("|")) s = s.slice(0, -1);
+  // ponytail: no escaped-pipe (`\|`) handling — refined-issue matrix cells are
+  // short prose, not pipe-bearing code. Add a split-on-unescaped-pipe pass only
+  // if a real matrix cell ever needs a literal `|`.
+  return s.split("|").map((c) => c.trim());
+}
+
+/**
+ * Count real prose words in a matrix cell: runs of >=3 letters that are not the
+ * `dod` identifier token. Bare identifiers (`AC1`, `D1`, `DoD`), arrows, and
+ * digits contribute nothing, so a tautological/identifier-only cell scores 0.
+ */
+function cellProseWordCount(cell) {
+  if (typeof cell !== "string") return 0;
+  const stripped = cell.replace(/[*_`]+/gu, " ");
+  const runs = stripped.match(/[A-Za-z]{3,}/gu) ?? [];
+  return runs.filter((w) => w.toLowerCase() !== "dod").length;
+}
+
+// A matrix data row is semantic when BOTH mapped cells carry at least one real
+// prose word (a letter-run of >=3 chars, excluding the `dod` token). This
+// rejects the identifier-only/tautological rows the contract names — `AC1 | D1`,
+// `AC1 → D1`, `DoD`, and empty cells (all 0 prose words) — WITHOUT false-
+// rejecting a legitimately terse-but-real mapping (e.g. `Feature works |
+// Regression test added`). The threshold is deliberately >=1, not >=2: the goal
+// is to reject bare identifiers, not to mandate a minimum verbosity (#1951
+// draft_gate/Copilot review).
+function rowIsSemantic(criterion, evidence) {
+  return cellProseWordCount(criterion) >= 1 && cellProseWordCount(evidence) >= 1;
+}
+
+/**
+ * Parse every GFM pipe table in a Markdown body (skipping fenced code spans via
+ * the shared `stepFence`). Returns an array of
+ * `{ heading, headerCells, rows }` where `rows` is the list of data rows (each
+ * an array of trimmed cell strings). A table is a header line containing `|`,
+ * a delimiter row (`|---|---|`), and >=0 data rows.
+ */
+function parseMarkdownTables(body) {
+  if (typeof body !== "string" || body.length === 0) return [];
+  const lines = body.split(/\r?\n/u);
+  const tables = [];
+  let fence = null;
+  let heading = null;
+  let i = 0;
+  while (i < lines.length) {
+    const step = stepFence(fence, lines[i]);
+    fence = step.fence;
+    if (step.insideFence) {
+      i += 1;
+      continue;
+    }
+    const headingMatch = /^(#{1,6})\s+(.+?)\s*$/u.exec(lines[i]);
+    if (headingMatch) {
+      heading = normalizeHeadingName(headingMatch[2]);
+      i += 1;
+      continue;
+    }
+    const header = lines[i];
+    const delim = lines[i + 1];
+    if (header.includes("|") && typeof delim === "string" && TABLE_DELIMITER_RE.test(delim)) {
+      const headerCells = splitTableRow(header);
+      const rows = [];
+      let j = i + 2;
+      while (j < lines.length) {
+        const rowStep = stepFence(fence, lines[j]);
+        // A table ends at the first non-fence line without a pipe, or a heading.
+        if (rowStep.insideFence) break;
+        if (!lines[j].includes("|") || /^#{1,6}\s+/u.test(lines[j])) break;
+        rows.push(splitTableRow(lines[j]));
+        j += 1;
+      }
+      tables.push({ heading, headerCells, rows });
+      i = j;
+      continue;
+    }
+    i += 1;
+  }
+  return tables;
+}
+
+/**
+ * Detect the authoritative AC→DoD mapping matrix in an issue body.
+ *
+ * A qualifying table has >=2 columns and EITHER sits under a matrix-named
+ * heading ({@link MATRIX_SECTION_PATTERNS}) OR names criterion/evidence-like
+ * columns in its header. The matrix is VALID when it carries at least one
+ * SEMANTIC data row (both mapped cells carry real prose — see
+ * {@link rowIsSemantic}); a header/separator-only table (no data rows) or a
+ * table whose rows are all identifier-only/tautological (`AC1 → D1`) is
+ * malformed.
+ *
+ * @param {string} [body]
+ * @returns {{ found: boolean, valid: boolean, rowCount: number, rows: { criterion: string, evidence: string }[], reason: string }}
+ */
+export function detectAcDodMatrix(body = "") {
+  const tables = parseMarkdownTables(body);
+  const candidates = tables.filter((t) => {
+    if (!Array.isArray(t.headerCells) || t.headerCells.length < 2) return false;
+    const underHeading = typeof t.heading === "string" &&
+      MATRIX_SECTION_PATTERNS.some((p) => p.test(t.heading));
+    const headerNamesMap =
+      MATRIX_CRITERION_HEADER.test(t.headerCells[0] ?? "") &&
+      MATRIX_EVIDENCE_HEADER.test(t.headerCells[1] ?? "");
+    return underHeading || headerNamesMap;
+  });
+  if (candidates.length === 0) {
+    return { found: false, valid: false, rowCount: 0, rows: [], reason: "No AC→DoD mapping matrix table found." };
+  }
+  // Prefer the first candidate that has >=1 semantic row; otherwise report the
+  // first candidate as malformed.
+  for (const table of candidates) {
+    const semanticRows = [];
+    for (const cells of table.rows) {
+      if (cells.length < 2) continue;
+      const criterion = cells[0] ?? "";
+      const evidence = cells[1] ?? "";
+      if (rowIsSemantic(criterion, evidence)) {
+        semanticRows.push({ criterion, evidence });
+      }
+    }
+    if (semanticRows.length > 0) {
+      return {
+        found: true,
+        valid: true,
+        rowCount: semanticRows.length,
+        rows: semanticRows,
+        reason: `Found an AC→DoD mapping matrix with ${semanticRows.length} semantic row(s).`,
+      };
+    }
+  }
+  const dataRowCount = candidates[0].rows.length;
+  return {
+    found: true,
+    valid: false,
+    rowCount: 0,
+    rows: [],
+    reason: dataRowCount === 0
+      ? "AC→DoD mapping matrix table is empty (header/separator only, no data rows)."
+      : "AC→DoD mapping matrix table is identifier-only/tautological (no row maps a concrete criterion to concrete completion evidence).",
+  };
+}
+
+/**
+ * Project an issue's AC→DoD mapping matrix into self-contained list-form PR
+ * checklists (#1951 AC4): the PR carries list-form Acceptance criteria and
+ * Definition of done checkboxes derived from the matrix — never a matrix/table,
+ * never checkboxes inside table cells. Accepts a pre-parsed `matrix` (from
+ * {@link detectAcDodMatrix}) or a raw `body` to parse. Fails closed on a
+ * missing/malformed matrix rather than emitting empty checklists.
+ *
+ * @param {{ matrix?: ReturnType<typeof detectAcDodMatrix>, body?: string }} input
+ * @returns {{ acChecklist: string[], dodChecklist: string[], markdown: string }}
+ */
+export function derivePrChecklistsFromIssueMatrix({ matrix = null, body = "" } = {}) {
+  const m = matrix ?? detectAcDodMatrix(body);
+  if (!m || !m.found || !m.valid || !Array.isArray(m.rows) || m.rows.length === 0) {
+    throw Object.assign(
+      new Error(`derivePrChecklistsFromIssueMatrix: ${m?.reason ?? "no valid AC→DoD mapping matrix to project"}`),
+      { code: "MALFORMED_MATRIX_SOURCE" },
+    );
+  }
+  const dedupe = (items) => [...new Set(items.map((s) => s.trim()).filter((s) => s.length > 0))];
+  const acChecklist = dedupe(m.rows.map((r) => r.criterion));
+  const dodChecklist = dedupe(m.rows.map((r) => r.evidence));
+  const render = (heading, items) =>
+    `## ${heading}\n\n${items.map((t) => `- [ ] ${t}`).join("\n")}\n`;
+  const markdown = `${render("Acceptance criteria", acChecklist)}\n${render("Definition of done", dodChecklist)}`;
+  return { acChecklist, dodChecklist, markdown };
+}
+
 /**
  * Detect a linked refinement doc path from the issue body.
  * Looks for explicit `tmp/refinement/<n>-plan.md` style paths and the
@@ -308,9 +706,12 @@ export function detectLinkedRefinementDoc(body) {
  * `validatePrBodySpec` (`PR_BODY_SPEC_NARRATIVE_SECTIONS.non_goals.patterns`),
  * so the two spec surfaces cannot drift on what counts as an explicit
  * Non-goals section. `hasACs` keeps its caller-facing meaning: true only when
- * the FULL check passes, so every `.hasACs` consumer (enqueue gate, draft
- * gate, parked-items discovery, gate context) fails closed with no call-site
- * change.
+ * the FULL check passes (#1951: a valid AC→DoD mapping matrix plus an explicit
+ * Non-goals section, or a resolvable linked refinement doc plus Non-goals), so
+ * every `.hasACs` consumer (enqueue gate, draft gate, parked-items discovery,
+ * gate context) fails closed with no call-site change. `acItems`/`dodItems`
+ * stay populated for downstream consumers: from the issue's own checklist
+ * sections when present, otherwise projected from the matrix rows.
  *
  * `resolveLinkedDoc` (optional, #1866): a `(path) => boolean` callback used to
  * verify that a linked `tmp/refinement/*.md` doc actually resolves (e.g.
@@ -340,6 +741,7 @@ export function detectLinkedRefinementDoc(body) {
  *   dodItems: string[],
  *   sections: string[],
  *   linkedDoc: { found: boolean, path: string|null, reason: string, resolves?: boolean },
+ *   matrix: { found: boolean, valid: boolean, rowCount: number, rows: { criterion: string, evidence: string }[], reason: string },
  *   reason: string,
  *   finding: string|null,
  * }}
@@ -355,7 +757,8 @@ export function detectIssueRefinementArtifact({ body = "", issueNumber = null, r
       dodItems: [],
       sections: [],
       linkedDoc: { found: false, path: null, reason: "empty-body" },
-      reason: "Issue body is empty; no ACs/DoD/linked-doc can be detected.",
+      matrix: { found: false, valid: false, rowCount: 0, rows: [], reason: "empty-body" },
+      reason: "Issue body is empty; no matrix/ACs/DoD/linked-doc can be detected.",
       finding: REFINEMENT_ARTIFACT_FINDING,
     };
   }
@@ -366,6 +769,18 @@ export function detectIssueRefinementArtifact({ body = "", issueNumber = null, r
   const acceptanceSection = findSectionByPatterns(sections, ACCEPTANCE_SECTION_PATTERNS);
   const dodSection = findSectionByPatterns(sections, DOD_SECTION_PATTERNS);
 
+  // CONSUMER-CONTRACT BOUNDARY (#1877, intentional asymmetry): the issue-side
+  // reads above are strict — ONE exact-first section, NO deep flattening —
+  // while extractPrBodyUncheckedChecklistItems (PR side) unions ALL matching
+  // sections and deep-flattens past ### sub-headings. The issue side is a
+  // presence check of the refinement matrix: a checklist hidden entirely
+  // under a ### sub-heading fails CLOSED (reported missing, the issue stays
+  // parked for human refinement). The PR side enforces a hard gate over the
+  // derived checklist: it must NEVER miss an unchecked box, so it fails open
+  // on nothing — it unions and deep-flattens. Do not "unify" these reads: the
+  // two failure directions are both deliberate (issue side = safe direction,
+  // PR side = fail-closed gate).
+
   const acItems = acceptanceSection ? extractChecklistItems(acceptanceSection.bodyLines.join("\n")) : [];
   // Unticked AC checkboxes (`- [ ]`) of the spec-of-record — the
   // ACCEPT-CRITERIA-VERIFY-AND-REFLECT precondition a clean pre_approval_gate
@@ -389,13 +804,15 @@ export function detectIssueRefinementArtifact({ body = "", issueNumber = null, r
     findSectionByPatterns(sections, PR_BODY_SPEC_NARRATIVE_SECTIONS.non_goals.patterns),
   );
 
-  const artifactSource = acItems.length > 0
-    ? REFINEMENT_SOURCE.ISSUE_BODY_AC
-    : dodItems.length > 0
-      ? REFINEMENT_SOURCE.ISSUE_BODY_DOD
-      : linkedDocResolves
-        ? REFINEMENT_SOURCE.LINKED_DOC
-        : null;
+  // #1951: the authoritative issue artifact is the AC→DoD mapping MATRIX, not
+  // duplicate interactive issue-side checklists. Detect its presence + shape.
+  const matrix = detectAcDodMatrix(body);
+
+  // Keep acItems/dodItems populated for downstream consumers (gate context,
+  // coordination state) even when the issue carries only the matrix and no
+  // interactive checklists: project the matrix rows into AC/DoD items.
+  const effectiveAcItems = acItems.length > 0 ? acItems : matrix.rows.map((r) => r.criterion.trim()).filter(Boolean);
+  const effectiveDodItems = dodItems.length > 0 ? dodItems : matrix.rows.map((r) => r.evidence.trim()).filter(Boolean);
 
   const base = {
     hasNonGoals,
@@ -404,39 +821,24 @@ export function detectIssueRefinementArtifact({ body = "", issueNumber = null, r
     dodItems,
     sections: sectionNames,
     linkedDoc,
+    matrix,
   };
 
-  if (artifactSource !== null) {
+  // A linked refinement doc remains a complete artifact on its own (the doc
+  // carries the matrix). It still requires an explicit Non-goals section.
+  if (linkedDocResolves) {
     if (!hasNonGoals) {
       return {
         ...base,
         hasACs: false,
-        source: artifactSource,
+        source: REFINEMENT_SOURCE.LINKED_DOC,
         reason:
-          `Issue body carries a refinement artifact (${artifactSource}) but no explicit Non-goals section; ` +
+          "Issue body links a refinement doc but has no explicit Non-goals section; " +
           "the tracker-backed refinement contract requires one (rule ARTIFACT-TRACKER-ISSUE-REFINEMENT-FLOOR; " +
           "e.g. run the loop-grill synthesis). Refusing: the refinement check fails closed without an explicit Non-goals section.",
         finding: MISSING_EXPLICIT_NON_GOALS_FINDING,
       };
     }
-    if (artifactSource === REFINEMENT_SOURCE.ISSUE_BODY_AC) {
-      return {
-        ...base,
-        hasACs: true,
-        source: REFINEMENT_SOURCE.ISSUE_BODY_AC,
-        reason: `Found ${acItems.length} Acceptance criteria checklist item(s) in the issue body.`,
-        finding: null,
-      };
-    }
-    if (artifactSource === REFINEMENT_SOURCE.ISSUE_BODY_DOD) {
-      return {
-        ...base,
-        hasACs: true,
-        source: REFINEMENT_SOURCE.ISSUE_BODY_DOD,
-        reason: `Found ${dodItems.length} DoD checklist item(s) in the issue body.`,
-        finding: null,
-      };
-    }
     return {
       ...base,
       hasACs: true,
@@ -449,6 +851,67 @@ export function detectIssueRefinementArtifact({ body = "", issueNumber = null, r
     };
   }
 
+  // Matrix present but empty/malformed/identifier-only: fail closed (#1951 AC2).
+  if (matrix.found && !matrix.valid) {
+    return {
+      ...base,
+      hasACs: false,
+      source: REFINEMENT_SOURCE.ISSUE_BODY_MATRIX,
+      reason:
+        `Issue body carries an AC→DoD mapping matrix but it is not a valid semantic mapping (${matrix.reason}); ` +
+        "the refinement contract requires a real criterion→completion-evidence mapping " +
+        "(rule ARTIFACT-TRACKER-ISSUE-REFINEMENT-FLOOR; e.g. run the loop-grill synthesis). " +
+        "Refusing: the refinement check fails closed on a malformed/identifier-only matrix.",
+      finding: MALFORMED_AC_DOD_MATRIX_FINDING,
+    };
+  }
+
+  // Matrix present and valid: the refinement floor is the matrix + explicit
+  // Non-goals. Interactive issue-side AC/DoD checklists are NOT required.
+  if (matrix.found && matrix.valid) {
+    if (!hasNonGoals) {
+      return {
+        ...base,
+        hasACs: false,
+        source: REFINEMENT_SOURCE.ISSUE_BODY_MATRIX,
+        reason:
+          "Issue body carries a valid AC→DoD mapping matrix but no explicit Non-goals section; " +
+          "the tracker-backed refinement contract requires one (rule ARTIFACT-TRACKER-ISSUE-REFINEMENT-FLOOR; " +
+          "e.g. run the loop-grill synthesis). Refusing: the refinement check fails closed without an explicit Non-goals section.",
+        finding: MISSING_EXPLICIT_NON_GOALS_FINDING,
+      };
+    }
+    return {
+      ...base,
+      hasACs: true,
+      source: REFINEMENT_SOURCE.ISSUE_BODY_MATRIX,
+      acItems: effectiveAcItems,
+      dodItems: effectiveDodItems,
+      reason: `Found a valid AC→DoD mapping matrix with ${matrix.rowCount} semantic row(s) and an explicit Non-goals section.`,
+      finding: null,
+    };
+  }
+
+  // Matrix absent. If the body carries AC/DoD checklist content it is a
+  // checklist-bearing issue missing the authoritative matrix (#1951 AC2 /
+  // migration): fail closed on the missing matrix so it is re-grilled. A body
+  // with no matrix and no AC/DoD content (prose-only, or only a Non-goals
+  // section / an unresolved linked-doc mention) stays the pre-existing
+  // missing_refinement_artifact.
+  if (acItems.length > 0 || dodItems.length > 0) {
+    return {
+      ...base,
+      hasACs: false,
+      source: REFINEMENT_SOURCE.MISSING,
+      reason:
+        "Issue body carries Acceptance criteria / Definition of done content but no authoritative AC→DoD mapping matrix table; " +
+        "under matrix-on-issue/checklist-on-PR the mapping table is the authoritative issue artifact " +
+        "(rule ARTIFACT-TRACKER-ISSUE-REFINEMENT-FLOOR; e.g. run the loop-grill synthesis). " +
+        "Refusing: the refinement check fails closed without the mapping matrix.",
+      finding: MISSING_AC_DOD_MATRIX_FINDING,
+    };
+  }
+
   return {
     ...base,
     hasACs: false,
@@ -456,7 +919,7 @@ export function detectIssueRefinementArtifact({ body = "", issueNumber = null, r
     acItems: [],
     uncheckedAcItems: [],
     dodItems: [],
-    reason: "Issue body has no Acceptance criteria section, no DoD section, and no linked refinement doc.",
+    reason: "Issue body has no AC→DoD mapping matrix, no Acceptance criteria/DoD content, and no linked refinement doc.",
     finding: REFINEMENT_ARTIFACT_FINDING,
   };
 }
@@ -730,6 +1193,57 @@ export function validateTrackerBackedPrBodySpec({ body = "", closingIssues = []
   return validatePrBodySpec({ body, expectedIssue, requireOpenQuestions: false });
 }
 
+/**
+ * #1877: extract the UNCHECKED AC/DoD checkbox items from a PR body's own
+ * Acceptance criteria / Definition of done checklists — the derived,
+ * self-contained checklist that mirrors the linked issue's AC/DoD/Non-goals
+ * matrix. Any unchecked `- [ ]` in those sections means an acceptance
+ * criterion or definition-of-done item is still open, and the deterministic
+ * pre-approval block (`upsert-checkpoint-verdict.mjs`) fails the gate closed:
+ * the round is `blocked` and the PR cannot reach approval with an open
+ * acceptance criterion. This enforces COMPLETENESS (nothing left
+ * unchecked/forgotten), not truthfulness — a dishonestly-ticked `[x]` passes
+ * this mechanical check and remains the reviewer/judge's responsibility
+ * (ACCEPT-CRITERIA-VERIFY-AND-REFLECT). Composes with
+ * `tick-verified-checkboxes.mjs`: a box the gate could not verify stays
+ * unchecked and therefore blocks.
+ *
+ * Pure; no I/O. Reuses the shared section patterns and checklist parser
+ * (same `parseMarkdownSections` + `extractUncheckedChecklistItems` seams as
+ * `detectIssueRefinementArtifact` / `validatePrBodySpec`) so no parallel
+ * parser can drift. Sections absent from the body contribute no items — the
+ * draft-exit `validateTrackerBackedPrBodySpec` check (#1863) already owns
+ * requiring the sections to EXIST.
+ *
+ * @param {{ body?: string }} input
+ * @returns {{ uncheckedAcItems: string[], uncheckedDodItems: string[] }}
+ */
+export function extractPrBodyUncheckedChecklistItems({ body = "" } = {}) {
+  if (typeof body !== "string" || body.length === 0) {
+    return { uncheckedAcItems: [], uncheckedDodItems: [] };
+  }
+  const sections = parseMarkdownSections(body);
+  // Union the unchecked boxes across ALL sections matching each pattern
+  // family (exact-first ordered), flattening each section past its deeper
+  // sub-headings (#1877): a body nesting ACs under `###` subsections, or
+  // repeating an AC/DoD heading, must not hide unchecked boxes from the
+  // deterministic completeness block. Deduped by text (same box re-read in a
+  // duplicate section is the same box).
+  const collect = (patterns) => {
+    const matched = findAllSectionsByPatterns(sections, patterns);
+    const items = [];
+    for (let i = 0; i < sections.length; i += 1) {
+      if (!matched.includes(sections[i])) continue;
+      items.push(...extractUncheckedChecklistItems(flattenSectionDeep(sections, i)));
+    }
+    return [...new Set(items)];
+  };
+  return {
+    uncheckedAcItems: collect(ACCEPTANCE_SECTION_PATTERNS),
+    uncheckedDodItems: collect(DOD_SECTION_PATTERNS),
+  };
+}
+
 /**
  * Decide what an enqueue caller should do with a refinement-artifact result,
  * so an un-refined item never lands in the Next Up pickup column in the first
@@ -748,9 +1262,9 @@ export function validateTrackerBackedPrBodySpec({ body = "", closingIssues = []
  */
 export function decideEnqueueRefinementGate({ artifact, targetIsPickup, auto = false }) {
   // `artifact.finding === null` is the explicit "passes the full refinement
-  // check" signal (artifact AND — since #1866 — an explicit Non-goals
-  // section), clearer than reading `hasACs`, whose name understates what it
-  // covers.
+  // check" signal (a valid AC→DoD mapping matrix + an explicit Non-goals
+  // section, or a resolvable linked refinement doc + Non-goals), clearer than
+  // reading `hasACs`, whose name understates what it covers.
   if (!targetIsPickup || artifact.finding === null) {
     return { action: "enqueue" };
   }
@@ -763,10 +1277,29 @@ export function decideEnqueueRefinementGate({ artifact, targetIsPickup, auto = f
       "(rule ARTIFACT-TRACKER-ISSUE-REFINEMENT-FLOOR; e.g. run `/dev-loops:loop-grill <issue> --auto` (or `/loop-grill <issue> --auto` in the dev-loops repo itself)) — refusing to enqueue without an explicit Non-goals section.";
     return { action: auto ? "divert" : "block", reason, missing: ["explicit Non-goals section"] };
   }
+  // #1951: matrix present but empty/malformed/identifier-only — name the shape
+  // defect so the fix targets the mapping table, not a missing section.
+  if (artifact.finding === MALFORMED_AC_DOD_MATRIX_FINDING) {
+    const reason =
+      "Issue carries an AC→DoD mapping matrix but it is empty, malformed, or identifier-only/tautological (e.g. `AC1 → D1`). " +
+      "Rewrite the mapping table so each row maps a concrete acceptance-criterion outcome to concrete completion evidence " +
+      "(rule ARTIFACT-TRACKER-ISSUE-REFINEMENT-FLOOR; e.g. run `/dev-loops:loop-grill <issue> --auto` (or `/loop-grill <issue> --auto` in the dev-loops repo itself)) — refusing to enqueue on a malformed matrix.";
+    return { action: auto ? "divert" : "block", reason, missing: ["valid AC→DoD mapping matrix"] };
+  }
+  // #1951: matrix absent (whether or not the body carries duplicate issue-side
+  // checklists) — the mapping table is the authoritative issue artifact.
+  if (artifact.finding === MISSING_AC_DOD_MATRIX_FINDING) {
+    const reason =
+      "Issue carries Acceptance criteria / Definition of done content but no authoritative AC→DoD mapping matrix — under matrix-on-issue/checklist-on-PR the mapping table is the authoritative issue artifact (#1951). " +
+      "Add a semantic AC→DoD mapping table to the issue body (each acceptance-criterion outcome mapped to its required completion evidence), and an explicit Non-goals section if one is not already present " +
+      "(rule ARTIFACT-TRACKER-ISSUE-REFINEMENT-FLOOR; e.g. run `/dev-loops:loop-grill <issue> --auto` (or `/loop-grill <issue> --auto` in the dev-loops repo itself)) — refusing to enqueue without the mapping matrix.";
+    return { action: auto ? "divert" : "block", reason, missing: ["AC→DoD mapping matrix"] };
+  }
   const missing = [...REFINEMENT_ARTIFACT_SOURCES];
   const reason =
     `Issue has no refinement artifact (none of: ${missing.join(", ")}). ` +
-    "Add at least ONE of them — an Acceptance criteria section, a Definition of done section, or a linked refinement doc " +
+    "Refine the issue to the authoritative AC→DoD mapping matrix (a two-column table mapping each acceptance-criterion outcome to its required completion evidence) plus an explicit Non-goals section — " +
+    "or link a refinement doc (tmp/refinement/*.md), which is a complete artifact on its own " +
     "(e.g. run `/dev-loops:loop-grill <issue> --auto` (or `/loop-grill <issue> --auto` in the dev-loops repo itself), or the refiner) — before it enters the pickup queue.";
   return { action: auto ? "divert" : "block", reason, missing };
 }