@dev-loops/core 1.0.1 → 1.0.2-slim.0

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

@@ -1,17 +1,22 @@
 /**
  * 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 — the full matrix of an Acceptance criteria
- * checklist plus a Definition of done checklist plus an explicit Non-goals
- * section, or a linked refinement doc that is a complete artifact on its own —
- * that the pre-approval gate can verify against. An issue missing any matrix
- * part fails closed with the matching finding (`missing_dod_checklist`,
- * `missing_ac_checklist`, `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.
+ * The authoritative refined-issue artifact is the semantic 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 a
+ * linked refinement doc that is a complete artifact on its own (the doc carries
+ * the matrix). Interactive issue-side AC/DoD checklists are NOT a substitute
+ * for the matrix; the PR carries the derived self-contained list-form
+ * checklists (`derivePrChecklistsFromIssueMatrix`; the PR body is validated by
+ * `validateTrackerBackedPrBodySpec`, never this predicate).
+ *
+ * Detection validates the structural PRESENCE and SHAPE of the mapping table,
+ * not its semantic truthfulness (a reviewer responsibility). A matrix that is
+ * absent, empty, malformed, or identifier-only fails closed with the matching
+ * finding (`missing_ac_dod_matrix`, `malformed_ac_dod_matrix`,
+ * `missing_explicit_non_goals`, or `missing_refinement_artifact`). A body
+ * carrying only checklists and no matrix fails closed and is re-grilled; no
+ * compatibility alias is retained.
  */
 import { existsSync } from "node:fs";
 import path from "node:path";
@@ -29,6 +34,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",
@@ -37,42 +43,37 @@ export const REFINEMENT_SOURCE = Object.freeze({
 
 const REFINEMENT_ARTIFACT_FINDING = "missing_refinement_artifact";
 
-// REFINEMENT_ARTIFACT_SOURCES: the full-matrix floor vocabulary (#1877). The
-// refinement floor is the FULL AC/DoD/Non-goals matrix (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.
+// REFINEMENT_ARTIFACT_SOURCES: the shape of a COMPLETE refinement artifact,
+// not a menu where any one entry suffices. A linked refinement doc
+// remains a complete artifact on its own.
 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",
 ]);
 
 /**
- * #1866: finding reported when the issue body carries a refinement artifact
- * (AC/DoD checklist or a resolvable linked doc) but no explicit Non-goals
- * section. Mirrors the PR-path narrative-invariant code
- * (`PR_BODY_SPEC_NARRATIVE_SECTIONS.non_goals.code`) so both spec surfaces
- * name the missing invariant identically.
+ * Finding: refinement artifact present but no explicit Non-goals section.
+ * Mirrors the PR-path code (`PR_BODY_SPEC_NARRATIVE_SECTIONS.non_goals.code`)
+ * so both spec surfaces name the missing invariant identically.
  */
 export const MISSING_EXPLICIT_NON_GOALS_FINDING = "missing_explicit_non_goals";
 
 /**
- * #1877: finding reported when the issue body carries an AC checklist (and
- * the Non-goals floor is met) but NO DoD checklist — the tracker-backed
- * refinement floor is the full AC/DoD/Non-goals matrix (each AC mapped to its
- * DoD item(s), plus explicit Non-goals), not AC-or-DoD. This lifts the
- * epic-only matrix requirement (epic-tree-refinement-procedure.md) into the
- * general refinement predicate, reconciled with #1866's Non-goals parity.
+ * Finding: refinement content present but NO authoritative AC→DoD mapping
+ * matrix table. The mapping table is the authoritative issue artifact;
+ * issue-side checklists are not a substitute. Fails closed so the issue is
+ * re-grilled to add the matrix.
  */
-export const MISSING_DOD_CHECKLIST_FINDING = "missing_dod_checklist";
+export const MISSING_AC_DOD_MATRIX_FINDING = "missing_ac_dod_matrix";
 
 /**
- * #1877: the symmetric matrix miss — a DoD checklist with no Acceptance
- * criteria checklist. The matrix is authored at refinement on the issue; the
- * PR then carries the derived checklist whose boxes the pre-approval gate
- * requires all ticked.
+ * Finding: an AC→DoD mapping table is present but empty (header/separator only)
+ * or identifier-only/tautological (cells such as `AC1 → D1` with no concrete
+ * criterion or evidence prose). Structural shape validation only — semantic
+ * truthfulness stays a reviewer responsibility.
  */
-export const MISSING_AC_CHECKLIST_FINDING = "missing_ac_checklist";
+export const MALFORMED_AC_DOD_MATRIX_FINDING = "malformed_ac_dod_matrix";
 
 /**
  * Canonical list of section headings that satisfy the refinement check.
@@ -82,47 +83,35 @@ export const MISSING_AC_CHECKLIST_FINDING = "missing_ac_checklist";
  *   - one DoD-style section (DoD or Definition of Done)
  */
 const ACCEPTANCE_SECTION_PATTERNS = Object.freeze([
-  // #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.
+  // Index 0 is the exact-canonical ANCHOR (`^acceptance criteria\b`); the rest
+  // are aliases. A decorated-variant canonical heading (`## Acceptance criteria
+  // (v2)`) still lands in the exact bucket rather than matching no pattern. The
+  // anchor stays distinct from the `/^ac\b/` alias, so 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([
-  // 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).
+  // Same anchor-family widening as the AC family. A decorated-variant alias
+  // heading (`## DoD (v2)`) 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).
+ * Normalize a heading name before section-pattern matching. Strip
+ * harmless decoration once, at the parse boundary, so decorated canonical
+ * headings (`## **Acceptance criteria**`, `## Acceptance criteria:`) still
+ * match their pattern family instead of silently disarming the AC/DoD reads.
+ * 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/backtick runs (bold and single-char
+ * italic), trailing `:`, closing ATX `#`, and surrounding whitespace.
+ * NOT touched: interior text, and leading `#` (never reaches `match[2]`).
  */
 function normalizeHeadingName(name) {
   if (typeof name !== "string") return name;
@@ -130,30 +119,23 @@ function normalizeHeadingName(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)
+    // surrounding emphasis/backtick runs (any length, must pair; a run may be
+    // single-char italic `*`/`_` as well as bold `**`/`__`)
     .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.
+// Exact canonical headings (pattern index 0 in each family) must outrank loose
+// aliases (`/^ac\b/`, `/^dod\b/`) so a matrix-shaped heading (`## AC/DoD
+// matrix`) can never hijack the canonical section read. 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.
+ * Resolve the section matching a heading-pattern family with exact-first
+ * precedence: the first EXACT canonical match (index 0) wins over any
+ * earlier alias-only match. Falls back to the first alias match, else null.
  */
 function findSectionByPatterns(sections, patterns) {
   const exact = patterns[EXACT_PATTERN_INDEX];
@@ -173,10 +155,9 @@ function findSectionByPatterns(sections, patterns) {
 }
 
 /**
- * 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.
+ * Collect ALL sections matching a heading-pattern family, exact-first ordered.
+ * Shares `findSectionByPatterns`'s precedence semantics so single-section and
+ * union consumers (PR-body unchecked-box extraction) cannot drift.
  */
 function findAllSectionsByPatterns(sections, patterns) {
   const exact = patterns[EXACT_PATTERN_INDEX];
@@ -198,28 +179,19 @@ function findAllSectionsByPatterns(sections, patterns) {
 }
 
 /**
- * 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.
+ * Flatten a section into a body string that extends past `###` sub-headings
+ * by joining the section and every following DEEPER-level section up to the
+ * next same-or-shallower heading, so nested checklist items stay visible to
+ * 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.)
+  // Anti-spoof: the raw sub-heading NAME is NEVER re-injected into the text the
+  // checklist parser re-parses. A fence-opening name (`### ``` `) would corrupt
+  // fence state and eat real boxes (fail-open); a checkbox-shaped name
+  // (`### - [ ] fake`) would count as a phantom unchecked item (fail-closed).
+  // Only already-classified bodyLines are joined; real boxes under sub-headings
+  // stay visible because their bodyLines still join normally.
   const parts = [start.bodyLines.join("\n")];
   for (let i = startIndex + 1; i < sections.length; i += 1) {
     if (sections[i].level <= start.level) break;
@@ -238,7 +210,7 @@ function flattenSectionDeep(sections, startIndex) {
  * CommonMark: an N-marker fence (``` or ~~~) closes only on a line of >= N
  * markers of the SAME char with no info string. This is the single source of
  * truth shared by parseMarkdownSections (headings) and extractChecklistItems
- * (checkboxes) so the two anti-spoof layers cannot drift (issue #1025).
+ * (checkboxes) so the two anti-spoof layers cannot drift.
  */
 function stepFence(fence, line) {
   const openMatch = /^\s*(`{3,}|~{3,})/u.exec(line);
@@ -265,7 +237,7 @@ function stepFence(fence, line) {
  *
  * Headings inside a fenced code span (``` or ~~~) are NOT treated as headings —
  * otherwise a body could spoof the refinement/spec gate with real-looking
- * headings that carry no real spec (gate integrity, issue #1025).
+ * headings that carry no real spec (gate integrity).
  */
 export function parseMarkdownSections(body) {
   if (typeof body !== "string" || body.length === 0) {
@@ -291,11 +263,9 @@ export function parseMarkdownSections(body) {
       }
       current = {
         level: match[1].length,
-        // #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).
+        // Normalize the captured name so decorated canonical headings
+        // (`## **Acceptance criteria**`) match the section patterns. The raw
+        // form is never re-parsed as body text, so it is not retained.
         name: normalizeHeadingName(match[2]),
         bodyLines: [],
       };
@@ -315,27 +285,21 @@ export function parseMarkdownSections(body) {
 
 
 /**
- * Parse bullet/checkbox items from a section body into item states. Each
- * 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.
- * Code-fenced lines are skipped (same fence logic as parseMarkdownSections,
- * issue #1025) so a body cannot spoof the AC/DoD gate with code-fenced
- * checkboxes.
+ * Parse bullet/checkbox items from a section body into item states. A checkbox
+ * item — any GFM/CommonMark task-list marker (`-`/`*`/`+` bullets, ordered
+ * `N.`/`N)`, blockquote-nested `> - [ ]`; parity with
+ * tick-verified-checkboxes.mjs) — becomes `{ text, checked }`, where `checked`
+ * is 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) becomes `{ text, checked: null }` — it has no checkbox. Empty
+ * placeholders (`- [ ]` with no text) are skipped. Code-fenced lines are
+ * skipped (same fence logic as parseMarkdownSections) so a body cannot spoof
+ * the AC/DoD gate with code-fenced checkboxes.
  *
- * Shared by `extractChecklistItems` (text-only) and the unticked-AC check
- * (`extractUncheckedChecklistItems`) so the two never drift on what counts as
- * a checklist item or on the checkbox-state read (#1621). Only ever called on
- * the body of an already-recognized AC/DoD section (see
- * `detectIssueRefinementArtifact`), so counting plain bullets is scoped to
- * those sections and never affects prose sections.
+ * Shared by `extractChecklistItems` and `extractUncheckedChecklistItems` so the
+ * two never drift on what counts as an item or on the checkbox-state read.
+ * Only called on an already-recognized AC/DoD section, so counting
+ * plain bullets never affects prose sections.
  */
 function parseChecklistItems(sectionBody) {
   if (typeof sectionBody !== "string" || sectionBody.length === 0) {
@@ -352,20 +316,15 @@ function parseChecklistItems(sectionBody) {
     if (step.insideFence) {
       continue;
     }
-    // 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.
+    // Checklist item: GFM/CommonMark task-list markers (`-`/`*`/`+` bullets,
+    // ordered `N.`/`N)`, blockquote-nested `> - [ ]`) — grammar parity with
+    // tick-verified-checkboxes.mjs so every form surfaced as unchecked is
+    // flippable by the tick tool. Push only when the line carries text, so
+    // empty placeholders are skipped. The tick state comes from the CAPTURED
+    // marker group, never a second whole-line re-test: an unanchored
+    // `/\[[xX]\]/.test(line)` would read an unchecked box whose label merely
+    // mentions `[x]` (`- [ ] verify [x] flags`) as checked, a fail-open the
+    // marker-anchored read cannot produce.
     const checkboxMatch =
       /^\s*(?:>|\s)*(?:[-*+]|\d+[.)])\s+\[([ xX])\](?:\s+(.+?))?\s*$/u.exec(line);
     if (checkboxMatch) {
@@ -399,7 +358,7 @@ function parseChecklistItems(sectionBody) {
  * are skipped. Returns the trimmed item text for each matching line; the
  * checkbox state is not preserved (use `extractUncheckedChecklistItems` for
  * that). Thin wrapper over `parseChecklistItems` so the text-only contract
- * stays byte-identical to its pre-#1621 shape.
+ * stays byte-identical to its original shape.
  */
 export function extractChecklistItems(sectionBody) {
   return parseChecklistItems(sectionBody).map((item) => item.text);
@@ -409,7 +368,7 @@ export function extractChecklistItems(sectionBody) {
  * Extract the text of UNCHECKED checkbox items (`- [ ]`) from a section body.
  * A ticked box (`- [x]`/`- [X]`) and a plain bullet (no checkbox) are both
  * excluded — only an actual unticked checkbox is an "unticked AC item"
- * (#1621, ACCEPT-CRITERIA-VERIFY-AND-REFLECT). Empty placeholders are skipped.
+ * (ACCEPT-CRITERIA-VERIFY-AND-REFLECT). Empty placeholders are skipped.
  * Thin wrapper over `parseChecklistItems` so the unticked read never drifts
  * from `extractChecklistItems` on what counts as a checklist item.
  */
@@ -419,6 +378,210 @@ export function extractUncheckedChecklistItems(sectionBody) {
     .map((item) => item.text);
 }
 
+// ---------------------------------------------------------------------------
+// AC→DoD mapping matrix detection
+// ---------------------------------------------------------------------------
+// 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. Recognizes an unheaded but clearly criterion→evidence table anywhere in
+// the body. Kept STRONG on purpose: a generic status table like
+// `| Outcome | Done |` must NOT be mistaken for the refinement matrix — only
+// headers naming 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).
+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. This rejects identifier-only/tautological rows (`AC1 | D1`,
+// `AC1 → D1`, `DoD`, empty cells) WITHOUT false-rejecting a terse-but-real
+// mapping (`Feature works | Regression test added`). The threshold is
+// deliberately >=1, not >=2: reject bare identifiers, do not mandate a minimum
+// verbosity.
+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: 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
@@ -467,33 +630,21 @@ export function detectLinkedRefinementDoc(body) {
 /**
  * Detect the refinement artifact on a parsed issue body.
  *
- * #1866: the tracker-backed refinement floor is the artifact (AC checklist,
- * DoD checklist, or a resolvable linked refinement doc) AND an explicit,
- * non-empty Non-goals section — the loop-grill / artifact-authority contract
- * requires Non-goals on a refined issue body, so the deterministic check
- * enforces it (fail-closed) with the distinct finding
- * `MISSING_EXPLICIT_NON_GOALS_FINDING`. The non-goals matcher is shared with
- * `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.
- *
- * `resolveLinkedDoc` (optional, #1866): a `(path) => boolean` callback used to
- * verify that a linked `tmp/refinement/*.md` doc actually resolves (e.g.
- * `existsSync`). Enforcement-point callers (enqueue gate, draft-gate
- * linked-issue path) supply it; a linked doc found in the body then satisfies
- * the artifact check only when the callback returns true. When the callback is
- * not supplied the predicate stays pure/no-I/O and behavior is unchanged, and
- * the `linkedDoc` result carries no `resolves` field. When supplied and the
- * doc does not resolve, `linkedDoc.resolves === false` and the linked doc does
- * not satisfy the artifact check (other artifact sources still count).
+ * The floor is a valid AC→DoD mapping matrix (or a resolvable linked refinement
+ * doc) AND an explicit, non-empty Non-goals section. A missing Non-goals
+ * section fails closed with the distinct finding
+ * `MISSING_EXPLICIT_NON_GOALS_FINDING`; its matcher is shared with
+ * `validatePrBodySpec` so the two spec surfaces cannot drift. `hasACs` is true
+ * only when the FULL check passes, so every `.hasACs` consumer 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.
  *
- * Result-shape note: on a `missing_explicit_non_goals` result, `source` keeps
- * the detected artifact origin (e.g. `issue-body-ac`) so callers/reporting can
- * still see what artifact exists; `hasACs` is false because the full
- * refinement check did not pass.
+ * `resolveLinkedDoc` (optional): a `(path) => boolean` callback verifying that a
+ * linked `tmp/refinement/*.md` doc actually resolves (e.g. `existsSync`). When
+ * not supplied the predicate stays pure/no-I/O and `linkedDoc` carries no
+ * `resolves` field; when supplied and the doc does not resolve, the linked doc
+ * does not satisfy the check (other artifact sources still count).
  *
  * @param {object} input
  * @param {string} [input.body]  Raw issue body Markdown.
@@ -508,6 +659,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,
  * }}
@@ -523,7 +675,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,
     };
   }
@@ -534,7 +687,7 @@ 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
+  // CONSUMER-CONTRACT BOUNDARY (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
@@ -549,7 +702,7 @@ export function detectIssueRefinementArtifact({ body = "", issueNumber = null, r
   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
-  // must refuse on (#1621). Only actual unticked checkboxes count; a ticked
+  // must refuse on. Only actual unticked checkboxes count; a ticked
   // box and a plain bullet (no checkbox) are both excluded.
   const uncheckedAcItems = acceptanceSection ? extractUncheckedChecklistItems(acceptanceSection.bodyLines.join("\n")) : [];
   const dodItems = dodSection ? extractChecklistItems(dodSection.bodyLines.join("\n")) : [];
@@ -561,7 +714,7 @@ export function detectIssueRefinementArtifact({ body = "", issueNumber = null, r
     linkedDoc = { ...linkedDoc, resolves: linkedDocResolves };
   }
 
-  // #1866: explicit Non-goals section required on a refined tracker-backed
+  // explicit Non-goals section required on a refined tracker-backed
   // issue body — same matcher the PR-body spec path uses, so the two cannot
   // drift. A heading-only or fenced-only section does not count
   // (sectionHasBody anti-spoof).
@@ -569,13 +722,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;
+  // 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,
@@ -584,76 +739,97 @@ 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) {
-      // #1877 matrix floor: an AC checklist alone is no longer a complete
-      // refinement artifact on a tracker-backed issue — the matrix is each AC
-      // mapped to its DoD item(s) plus explicit Non-goals, so a missing DoD
-      // checklist fails closed with its own finding. A linked refinement doc
-      // stays a complete artifact on its own (the doc itself carries the
-      // matrix).
-      if (dodItems.length === 0) {
-        return {
-          ...base,
-          hasACs: false,
-          source: artifactSource,
-          reason:
-            "Issue body carries an Acceptance criteria checklist but no Definition of done checklist; " +
-            "the tracker-backed refinement contract requires the full AC/DoD/Non-goals matrix " +
-            "(#1877, rule ARTIFACT-TRACKER-ISSUE-REFINEMENT-FLOOR). Refusing: the refinement check fails closed " +
-            "without a DoD checklist mapped to the acceptance criteria.",
-          finding: MISSING_DOD_CHECKLIST_FINDING,
-        };
-      }
-      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) {
-      // #1877 matrix floor, symmetric arm: a DoD checklist with no Acceptance
-      // criteria checklist is an incomplete matrix, not a refined issue.
+    return {
+      ...base,
+      hasACs: true,
+      source: REFINEMENT_SOURCE.LINKED_DOC,
+      acItems: [],
+      uncheckedAcItems: [],
+      dodItems: [],
+      reason: `Issue body links a refinement doc at ${linkedDoc.path}; treating that as the refinement artifact source.`,
+      finding: null,
+    };
+  }
+
+  // Matrix present but empty/malformed/identifier-only: fail closed.
+  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_DOD,
+        source: REFINEMENT_SOURCE.ISSUE_BODY_MATRIX,
         reason:
-          "Issue body carries a Definition of done checklist but no Acceptance criteria checklist; " +
-          "the tracker-backed refinement contract requires the full AC/DoD/Non-goals matrix " +
-          "(#1877, rule ARTIFACT-TRACKER-ISSUE-REFINEMENT-FLOOR). Refusing: the refinement check fails closed " +
-          "without acceptance criteria for the DoD items to map to.",
-        finding: MISSING_AC_CHECKLIST_FINDING,
+          "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.LINKED_DOC,
-      acItems: [],
-      uncheckedAcItems: [],
-      dodItems: [],
-      reason: `Issue body links a refinement doc at ${linkedDoc.path}; treating that as the refinement artifact source.`,
+      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 during
+  // 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,
@@ -661,13 +837,13 @@ 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,
   };
 }
 
 /**
- * PR-body-as-spec invariant sections (issue #1025, lightweight path).
+ * PR-body-as-spec invariant sections (lightweight path).
  *
  * When a lightweight session uses the PR description itself as the
  * spec-of-record (no committed phase/plan doc), the PR body must still carry
@@ -702,9 +878,8 @@ export const PR_BODY_SPEC_NARRATIVE_SECTIONS = Object.freeze({
 /**
  * GitHub's accepted closing-keyword issue references (close/closes/closed,
  * fix/fixes/fixed, resolve/resolves/resolved), case-insensitive, followed by
- * `#N` or the cross-repo `owner/repo#N` form. Mirrors the linkage the
- * lightweight path (#1025) requires the PR body to carry (issue #1181: five
- * lightweight PRs merged without this and none auto-closed their issue).
+ * `#N` or the cross-repo `owner/repo#N` form. Required linkage on the PR body:
+ * five lightweight PRs merged without this and none auto-closed their issue.
  */
 const CLOSING_ISSUE_REFERENCE_PATTERN =
   /\b(?:close[sd]?|fix(?:e[sd])?|resolve[sd]?)\s+(?:[\w.-]+\/[\w.-]+)?#(\d+)/giu;
@@ -742,7 +917,7 @@ function extractClosingIssueNumbers(body) {
 function sectionHasBody(section) {
   // A real body needs >=1 non-whitespace line OUTSIDE any fenced code span —
   // a section whose only content is a ```fenced``` block is treated as empty so
-  // it cannot spoof the narrative-invariant gate (issue #1025, same stepFence as
+  // it cannot spoof the narrative-invariant gate (same stepFence as
   // parseMarkdownSections + extractChecklistItems).
   if (!section) return false;
   let fence = null;
@@ -759,40 +934,29 @@ function sectionHasBody(section) {
  * Validate that a PR body carries every invariant required to serve as the
  * lightweight spec-of-record: Objective/why, in-scope, explicit non-goals,
  * testable Acceptance criteria (>=1 checklist item), Definition of done
- * (>=1 checklist item), Open questions/risks, and — unless explicit
- * issue-less mode is requested — a GitHub closing-keyword issue reference
- * (`Closes #N` and GitHub's other accepted forms — the lightweight path's
- * `Closes #N` linkage, issue #1181). Reuses the generic markdown logic
- * (parseMarkdownSections / AC + DoD patterns / extractChecklistItems) so
- * there is no parallel validator. Fails closed: every missing invariant is
- * reported under its distinct `missing_*` code. Pure; no side effects.
+ * (>=1 checklist item), Open questions/risks, and — unless issue-less mode is
+ * requested — a GitHub closing-keyword issue reference. Reuses the generic
+ * markdown logic so there is no parallel validator. Fails closed: every missing
+ * invariant is reported under its distinct `missing_*` code. Pure; no I/O.
  *
- * Issue-less mode (`issueLess: true`, issue #1210): the narrative invariants
- * stay unconditional, but the closing-issue linkage flips from REQUIRED to
- * FORBIDDEN — the PR is the sole artifact, so it MUST NOT carry a closing
- * reference to an issue that doesn't back it. A present reference in this
- * mode fails closed under `unexpected_closing_issue_reference`, distinct
- * from `missing_closing_issue_reference` (tracker-backed mode, the default)
- * so callers can tell "no issue expected" apart from "issue expected but
- * absent". `expectedIssue` and `issueLess` are mutually exclusive; callers
- * pick exactly one mode (tracker-backed, with or without a specific
- * expected issue) or issue-less — never both.
+ * Issue-less mode (`issueLess: true`): the closing-issue linkage flips from
+ * REQUIRED to FORBIDDEN (the PR is the sole artifact), failing closed under
+ * `unexpected_closing_issue_reference` — distinct from
+ * `missing_closing_issue_reference` (tracker-backed, the default).
+ * `expectedIssue` and `issueLess` are mutually exclusive; callers pick exactly
+ * one mode.
  *
- * `requireOpenQuestions` (default `true`, issue #1863): the lightweight
- * PR-body-as-spec contract (this function's original scope) requires an Open
- * questions/risks section; the ordinary tracker-backed PR-description
- * contract (skills/docs/copilot-loop-operations.md "PR description
- * contract") does not name one. Pass `false` (see
- * `validateTrackerBackedPrBodySpec` below) to skip the `missing_open_questions`
- * check without touching any other invariant — the lightweight caller's
- * default stays byte-identical.
+ * `requireOpenQuestions` (default `true`): the tracker-backed PR-description
+ * contract does not name an Open questions/risks section; pass `false` (see
+ * `validateTrackerBackedPrBodySpec`) to skip that check without touching any
+ * other invariant.
  *
  * @param {{ body?: string, expectedIssue?: number, issueLess?: boolean, requireOpenQuestions?: boolean }} input
  * @returns {{ checker: "validate-pr-body-spec", ok: boolean, errors: { code: string, message: string }[], sections: string[], acItems: string[], dodItems: string[], closesIssues: number[] }}
  */
 
 // ---------------------------------------------------------------------------
-// Grill sub-loop body predicates (GRILL-SUBLOOP-*, #1628)
+// Grill sub-loop body predicates (GRILL-SUBLOOP-*)
 // ---------------------------------------------------------------------------
 // The loop-grill skill writes its raw Q&A transcript and synthesis to an
 // ephemeral tmp artifact and keeps only the canonical synthesized sections
@@ -912,8 +1076,8 @@ export function validatePrBodySpec({ body = "", expectedIssue = null, issueLess
 
 /**
  * Validate a TRACKER-BACKED PR's own body against the PR-description contract
- * (skills/docs/copilot-loop-operations.md "PR description contract", issue
- * #1863): Acceptance criteria + Definition of done checklists, an explicit
+ * (skills/docs/copilot-loop-operations.md "PR description contract"):
+ * Acceptance criteria + Definition of done checklists, an explicit
  * Non-goals section, and a `Closes #N`/`Fixes #N` reference — regardless of
  * whether the linked issue itself already carries a refinement artifact. A
  * linked issue with real ACs is necessary but not sufficient: the PR body is
@@ -936,7 +1100,7 @@ export function validateTrackerBackedPrBodySpec({ body = "", closingIssues = []
 }
 
 /**
- * #1877: extract the UNCHECKED AC/DoD checkbox items from a PR body's own
+ * 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
@@ -954,7 +1118,7 @@ export function validateTrackerBackedPrBodySpec({ body = "", closingIssues = []
  * (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
+ * draft-exit `validateTrackerBackedPrBodySpec` check already owns
  * requiring the sections to EXIST.
  *
  * @param {{ body?: string }} input
@@ -967,7 +1131,7 @@ export function extractPrBodyUncheckedChecklistItems({ body = "" } = {}) {
   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
+  // sub-headings: 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).
@@ -1004,13 +1168,13 @@ export function extractPrBodyUncheckedChecklistItems({ body = "" } = {}) {
  */
 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 AND — since #1877 — the full AC/DoD checklist matrix), 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" };
   }
-  // #1866: artifact present but the contract-mandated Non-goals section is
+  // artifact present but the contract-mandated Non-goals section is
   // absent/empty — a distinct failure with its own guidance.
   if (artifact.finding === MISSING_EXPLICIT_NON_GOALS_FINDING) {
     const reason =
@@ -1019,27 +1183,28 @@ 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"] };
   }
-  // #1877 matrix arms: name the actual missing matrix arm — an AC-only or
-  // DoD-only issue is NOT artifact-less, so the generic reason below would be
-  // factually wrong and would misdirect the fix.
-  if (artifact.finding === MISSING_DOD_CHECKLIST_FINDING) {
+  // 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 Acceptance criteria checklist but no Definition of done checklist — the refinement floor is the full AC/DoD/Non-goals matrix (#1877). " +
-      "Add a Definition of done checklist to the issue body (mapped to the acceptance criteria) " +
-      "(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 full matrix.";
-    return { action: auto ? "divert" : "block", reason, missing: ["Definition of done checklist"] };
+      "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"] };
   }
-  if (artifact.finding === MISSING_AC_CHECKLIST_FINDING) {
+  // 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 a Definition of done checklist but no Acceptance criteria checklist — the refinement floor is the full AC/DoD/Non-goals matrix (#1877). " +
-      "Add an Acceptance criteria checklist to the issue body (for the DoD items to map to) " +
-      "(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 full matrix.";
-    return { action: auto ? "divert" : "block", reason, missing: ["Acceptance criteria checklist"] };
+      "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(", ")}). ` +
-    "Refine the issue to the full AC/DoD/Non-goals matrix — an Acceptance criteria checklist, a Definition of done checklist, and an explicit Non-goals section — " +
+    "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 };
@@ -1074,7 +1239,7 @@ export async function runPickupRefinementGate({ issueNumber, repo, env, runChild
     throw new Error("Invalid JSON input");
   }
   const body = typeof bodyPayload?.body === "string" ? bodyPayload.body : "";
-  // #1866: a linked refinement doc satisfies the gate only when it actually
+  // a linked refinement doc satisfies the gate only when it actually
   // resolves. Paths follow the `tmp/refinement/*.md` convention and are
   // anchored to the caller's repo root (`repoRoot` option, falling back to
   // process.cwd()) — never the ambient cwd of whichever subdirectory the