@dev-loops/core 0.6.0 → 0.7.2

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

@@ -11,7 +11,7 @@
  *
  * This module owns:
  * - canonical section-name matching for AC / DoD blocks
- * - bullet-item extraction (both `- [ ]` and `- [x]`)
+ * - bullet-item extraction (checklist `- [ ]`/`- [x]` and top-level `- ` bullets)
  * - linked-refinement-doc detection from issue body
  *
  * It deliberately does NOT:
@@ -47,9 +47,44 @@ const DOD_SECTION_PATTERNS = Object.freeze([
   /^dod\s*$/i,
 ]);
 
+/**
+ * Fenced-code-span tracker. Given the previous fence state and the current
+ * line, returns { fence, insideFence } where:
+ *   - `fence` is the next state ({ char, len } while open, else null)
+ *   - `insideFence` is true when the line's CONTENT is inside a code span
+ *     (i.e. a fence line, or a line between an open and its close)
+ *
+ * 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).
+ */
+function stepFence(fence, line) {
+  const openMatch = /^\s*(`{3,}|~{3,})/u.exec(line);
+  if (openMatch) {
+    const char = openMatch[1][0];
+    const len = openMatch[1].length;
+    // A closing fence is a bare run of >= N markers of ONLY the opening char
+    // (CommonMark: no mixed markers, no info string).
+    const isBareRun = new RegExp(`^\\s*${char}+\\s*$`, "u").test(line);
+    if (fence === null) {
+      return { fence: { char, len }, insideFence: true };
+    }
+    if (fence.char === char && len >= fence.len && isBareRun) {
+      return { fence: null, insideFence: true };
+    }
+    return { fence, insideFence: true };
+  }
+  return { fence, insideFence: fence !== null };
+}
+
 /**
  * Extract `## ...` heading boundaries from a Markdown body.
  * Returns a sorted array of { level, name, bodyLines } records.
+ *
+ * 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).
  */
 export function parseMarkdownSections(body) {
   if (typeof body !== "string" || body.length === 0) {
@@ -59,8 +94,15 @@ export function parseMarkdownSections(body) {
   const lines = body.split(/\r?\n/u);
   const sections = [];
   let current = null;
+  let fence = null;
 
   for (const line of lines) {
+    const step = stepFence(fence, line);
+    fence = step.fence;
+    if (step.insideFence) {
+      if (current) current.bodyLines.push(line);
+      continue;
+    }
     const match = /^(#{1,6})\s+(.+?)\s*$/u.exec(line);
     if (match) {
       if (current) {
@@ -97,10 +139,18 @@ function findSectionByPatterns(sections, patterns) {
 }
 
 /**
- * Extract checklist bullet items (`- [ ]` and `- [x]`) from a section body.
- * Returns the trimmed item text for each matching line. The checkbox state
- * (checked vs unchecked) is intentionally not preserved: callers only need
- * the item text to satisfy the refinement-artifact contract.
+ * Extract bullet items from a section body. Counts both `- [ ]`/`- [x]`
+ * checklist items and top-level plain `- ` bullets (dash at column 0, so
+ * nested/indented sub-bullets are not counted). Empty checkbox placeholders
+ * (`- [ ]` / `- [x]` with no trailing text) are skipped, not counted, so a
+ * section of only unfilled placeholders reports as unrefined. Returns the
+ * trimmed item text for each matching line. The checkbox state (checked vs
+ * unchecked) is intentionally not preserved: callers only need the item
+ * text to satisfy the refinement-artifact contract.
+ *
+ * This is 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.
  */
 export function extractChecklistItems(sectionBody) {
   if (typeof sectionBody !== "string" || sectionBody.length === 0) {
@@ -109,11 +159,33 @@ export function extractChecklistItems(sectionBody) {
 
   const items = [];
   const lines = sectionBody.split(/\r?\n/u);
+  let fence = null;
 
   for (const line of lines) {
-    const match = /^\s*-\s+\[(?:[ xX])\]\s+(.+?)\s*$/u.exec(line);
-    if (match) {
-      const text = match[1].trim();
+    // Checkboxes/bullets inside a fenced code span are non-interactive text, not
+    // real items — skip them so a body cannot spoof the AC/DoD gate with
+    // code-fenced checkboxes (issue #1025). Same fence logic as parseMarkdownSections.
+    const step = stepFence(fence, line);
+    fence = step.fence;
+    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);
+    if (checkboxMatch) {
+      const text = (checkboxMatch[1] ?? "").trim();
+      if (text.length > 0) {
+        items.push(text);
+      }
+      continue;
+    }
+    // Top-level plain bullet: dash at column 0, space required (so `---`
+    // horizontal rules and `-x` do not match; indented sub-bullets do not).
+    const bulletMatch = /^-\s+(.+?)\s*$/u.exec(line);
+    if (bulletMatch) {
+      const text = bulletMatch[1].trim();
       if (text.length > 0) {
         items.push(text);
       }
@@ -248,6 +320,185 @@ export function detectIssueRefinementArtifact({ body = "", issueNumber = null }
   };
 }
 
+/**
+ * PR-body-as-spec invariant sections (issue #1025, 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
+ * the same invariants a durable spec doc would. AC/DoD reuse the checklist
+ * patterns above; these are the narrative sections not covered by those.
+ * Key order = validation/report order. Each key maps to its distinct
+ * `missing_*` code (mirrors `checkBaseSections` in _refine-helpers.mjs).
+ */
+export const PR_BODY_SPEC_NARRATIVE_SECTIONS = Object.freeze({
+  objective: {
+    code: "missing_objective",
+    label: "Objective/why",
+    patterns: [/^objective\b/iu, /^why\b/iu, /^goals?\b/iu, /^summary\b/iu, /^problem\b/iu],
+  },
+  in_scope: {
+    code: "missing_in_scope",
+    label: "In scope",
+    patterns: [/^in[- ]?scope\b/iu, /^scope\b/iu],
+  },
+  non_goals: {
+    code: "missing_explicit_non_goals",
+    label: "Explicit non-goals",
+    patterns: [/^explicit non-?goals\b/iu, /^non-?goals\b/iu, /^out of scope\b/iu],
+  },
+  open_questions: {
+    code: "missing_open_questions",
+    label: "Open questions/risks",
+    patterns: [/^open questions\b/iu, /^risks?\b/iu, /^questions\b/iu],
+  },
+});
+
+/**
+ * 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).
+ */
+const CLOSING_ISSUE_REFERENCE_PATTERN =
+  /\b(?:close[sd]?|fix(?:e[sd])?|resolve[sd]?)\s+(?:[\w.-]+\/[\w.-]+)?#(\d+)/giu;
+
+function extractClosingIssueNumbers(body) {
+  // Same fence-skip as sectionHasBody: a `Closes #N` line quoted inside a
+  // ```fenced``` example (e.g. a PR-template sample) must not spoof the gate.
+  let fence = null;
+  const unfenced = [];
+  for (const line of body.split("\n")) {
+    const step = stepFence(fence, line);
+    fence = step.fence;
+    if (step.insideFence) continue;
+    unfenced.push(line);
+  }
+  // Inline `code` spans don't auto-close on GitHub either: blank out any
+  // backtick-run-delimited span (equal-length runs pair, so ``a `b` c`` works).
+  // ponytail: not full CommonMark span matching; an unbalanced stray backtick
+  // over-strips toward fail-closed, which is the safe direction for this gate.
+  const text = unfenced.join("\n").replace(/(`+)[\s\S]*?\1/gu, " ");
+  const seen = new Set();
+  const numbers = [];
+  for (const match of text.matchAll(CLOSING_ISSUE_REFERENCE_PATTERN)) {
+    const n = Number(match[1]);
+    if (Number.isInteger(n) && n > 0 && !seen.has(n)) {
+      seen.add(n);
+      numbers.push(n);
+    }
+  }
+  return numbers;
+}
+
+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
+  // parseMarkdownSections + extractChecklistItems).
+  if (!section) return false;
+  let fence = null;
+  for (const line of section.bodyLines) {
+    const step = stepFence(fence, line);
+    fence = step.fence;
+    if (step.insideFence) continue;
+    if (line.trim().length > 0) return true;
+  }
+  return false;
+}
+
+/**
+ * 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.
+ *
+ * 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.
+ *
+ * @param {{ body?: string, expectedIssue?: number, issueLess?: boolean }} input
+ * @returns {{ checker: "validate-pr-body-spec", ok: boolean, errors: { code: string, message: string }[], sections: string[], acItems: string[], dodItems: string[], closesIssues: number[] }}
+ */
+export function validatePrBodySpec({ body = "", expectedIssue = null, issueLess = false } = {}) {
+  if (issueLess && Number.isInteger(expectedIssue)) {
+    // Fail closed at the library boundary too (not just the CLI): the two modes
+    // are contradictory and silently preferring one would hide caller bugs.
+    throw new Error("validatePrBodySpec: issueLess and expectedIssue are mutually exclusive; pass exactly one issue-linkage mode");
+  }
+  const bodyText = typeof body === "string" ? body : "";
+  const sections = parseMarkdownSections(bodyText);
+  const errors = [];
+
+  for (const { code, label, patterns } of Object.values(PR_BODY_SPEC_NARRATIVE_SECTIONS)) {
+    const section = findSectionByPatterns(sections, patterns);
+    if (!sectionHasBody(section)) {
+      errors.push({ code, message: `Missing or empty ${label} section.` });
+    }
+  }
+
+  const acSection = findSectionByPatterns(sections, ACCEPTANCE_SECTION_PATTERNS);
+  const acItems = acSection ? extractChecklistItems(acSection.bodyLines.join("\n")) : [];
+  if (acItems.length === 0) {
+    errors.push({
+      code: "missing_acceptance_criteria",
+      message: "Missing testable Acceptance criteria (no checklist items found).",
+    });
+  }
+
+  const dodSection = findSectionByPatterns(sections, DOD_SECTION_PATTERNS);
+  const dodItems = dodSection ? extractChecklistItems(dodSection.bodyLines.join("\n")) : [];
+  if (dodItems.length === 0) {
+    errors.push({
+      code: "missing_definition_of_done",
+      message: "Missing Definition of done (no checklist items found).",
+    });
+  }
+
+  const closesIssues = extractClosingIssueNumbers(bodyText);
+  if (issueLess) {
+    if (closesIssues.length > 0) {
+      errors.push({
+        code: "unexpected_closing_issue_reference",
+        message: `Issue-less PR body MUST NOT carry a closing reference to an issue that doesn't back it (found ${closesIssues.map((n) => `#${n}`).join(", ")}).`,
+      });
+    }
+  } else if (closesIssues.length === 0) {
+    errors.push({
+      code: "missing_closing_issue_reference",
+      message: "Missing a GitHub closing-keyword issue reference (e.g. `Closes #123`).",
+    });
+  } else if (Number.isInteger(expectedIssue) && !closesIssues.includes(expectedIssue)) {
+    errors.push({
+      code: "closes_wrong_issue",
+      message: `PR body closes ${closesIssues.map((n) => `#${n}`).join(", ")}, not the expected #${expectedIssue}.`,
+    });
+  }
+
+  return {
+    checker: "validate-pr-body-spec",
+    ok: errors.length === 0,
+    errors,
+    sections: sections.map((s) => s.name),
+    acItems,
+    dodItems,
+    closesIssues,
+  };
+}
+
 /**
  * Map a draft-gate refinement check to the result surface consumed by
  * `evaluatePrGateCoordination`. The mapping keeps the contract

package/src/loop/lifecycle-state.mjs

@@ -133,7 +133,7 @@ export const LIFECYCLE_NEXT_ACTIONS = Object.freeze({
   [LIFECYCLE_STATE.PRE_APPROVAL_GATE]:
     "Run pre-approval gate review; verify gate evidence, CI, and unresolved threads.",
   [LIFECYCLE_STATE.MERGE]:
-    "Merge is authorized; run the final merge step and write the retrospective checkpoint.",
+    "Merge is authorized; run the final merge step. The retrospective is advisory and post-merge: it records flagged raw-calls for the conductor, never blocks a transition.",
 });
 
 // ---------------------------------------------------------------------------