@dev-loops/core 0.6.0 → 0.7.1

package/src/loop/handoff-envelope.mjs

@@ -269,6 +269,55 @@ function deriveRequiredReads(bundle, resolverOutput) {
   return Array.isArray(reads) ? [...reads] : [];
 }
 
+// ---------------------------------------------------------------------------
+// specSource derivation (issue #1025 — lightweight PR-body-as-spec)
+// ---------------------------------------------------------------------------
+
+/**
+ * The LOCAL-FIRST spec-source subset the envelope distinguishes: phase_doc vs
+ * pr_body. This is NOT the full `canonicalSpecSource` value space — the same
+ * field name also carries "tracker_issue" in the tracker-backed mode
+ * (scripts/github/resolve-tracker-local-spec.mjs), which the envelope does not
+ * model (deriveSpecSource coerces it to null).
+ */
+export const CANONICAL_SPEC_SOURCE = Object.freeze({
+  PHASE_DOC: "phase_doc",
+  PR_BODY: "pr_body",
+});
+
+/**
+ * Derive the canonical spec source. Prefer the resolver-output-level field,
+ * fall back to bundle-level (mirrors deriveRequiredReads). Returns null when
+ * absent so the default (phase-doc) path carries no specSource field and stays
+ * byte-identical. Any value outside the local-first subset {phase_doc, pr_body}
+ * — e.g. the tracker-backed "tracker_issue" carried by the same field name — is
+ * coerced to null so the envelope can never set a specSource that
+ * validateHandoffEnvelope would then reject.
+ */
+function deriveSpecSource(bundle, resolverOutput) {
+  const raw = normalizeStringOrNull(resolverOutput?.canonicalSpecSource)
+    ?? normalizeStringOrNull(bundle?.canonicalSpecSource);
+  return raw === CANONICAL_SPEC_SOURCE.PHASE_DOC || raw === CANONICAL_SPEC_SOURCE.PR_BODY ? raw : null;
+}
+
+/**
+ * Apply the spec-source variant to acceptance criteria. Under the lightweight
+ * PR-body-as-spec path the phase-doc criterion text is retargeted to the PR
+ * description; the default (null/phase_doc) path returns the criteria verbatim
+ * so the phase-doc template text stays identical.
+ */
+function applySpecSourceVariant(criteria, specSource) {
+  // ponytail: free-text substring retarget is a no-op for any strategy whose
+  // criteria lack the phase-doc phrase — fine while lightweight only composes
+  // with local_implementation; make it a structured criterion-id lookup if
+  // lightweight is ever extended to another strategy.
+  if (specSource !== CANONICAL_SPEC_SOURCE.PR_BODY) return [...criteria];
+  return criteria.map((c) => ({
+    ...c,
+    must: c.must.replace("from the active phase doc", "from the PR description"),
+  }));
+}
+
 // ---------------------------------------------------------------------------
 // Gate config derivation
 // ---------------------------------------------------------------------------
@@ -412,6 +461,37 @@ function normalizeGateState(gateState) {
   };
 }
 
+
+/**
+ * Normalize the structured retrospective findings (issue #1077, Reading B).
+ *
+ * The retrospective is advisory: it never blocks merge or any lifecycle
+ * transition. Its findings travel in the handoff envelope (the conductor's
+ * decision input) and in an advisory PR comment — never on disk as a gate.
+ *
+ * The source is the `check-retro-tooling.mjs` JSON output shape:
+ *   { ok, internalToolingOnly, rawCallViolations, allowedWriteOps }
+ *
+ * Returns a normalized object carrying the substantive fields, or null when no
+ * findings were supplied (the field is optional — present only when the loop
+ * subagent ran the retrospective tooling).
+ */
+function normalizeRetrospectiveFindings(findings) {
+  if (findings === null || findings === undefined) return null;
+  if (typeof findings !== "object" || Array.isArray(findings)) return null;
+
+  const toStrArray = (v) => Array.isArray(v)
+    ? v.map((x) => (typeof x === "string" ? x : String(x)).trim()).filter((x) => x.length > 0)
+    : [];
+
+  const internalToolingOnly = findings.internalToolingOnly === true;
+  return {
+    internalToolingOnly,
+    rawCallViolations: toStrArray(findings.rawCallViolations),
+    allowedWriteOps: toStrArray(findings.allowedWriteOps),
+  };
+}
+
 // ---------------------------------------------------------------------------
 // Sub-gate resolution
 // ---------------------------------------------------------------------------
@@ -461,6 +541,11 @@ export function buildDevLoopHandoffEnvelope(resolverOutput, settings, gateState
 
   const gs = normalizeGateState(gateState);
   const subGate = resolveSubGate(strategy, gs);
+  // Normalize each source independently, then fall back on the normalized result
+  // (not the raw value): a present-but-invalid gateState value must NOT shadow a
+  // valid options.retrospectiveFindings fallback (issue #1077 review finding).
+  const retrospectiveFindings = normalizeRetrospectiveFindings(gateState?.retrospectiveFindings)
+    ?? normalizeRetrospectiveFindings(options.retrospectiveFindings);
 
   const target = deriveTarget(bundle, repo);
   const requiredReads = deriveRequiredReads(bundle, resolverOutput);
@@ -468,11 +553,25 @@ export function buildDevLoopHandoffEnvelope(resolverOutput, settings, gateState
   const gateConfig = deriveGateConfig(settings, subGate);
   const derivedCwd = deriveCwd(bundle, { repoRoot: options.repoRoot, worktreeCwd: options.worktreeCwd });
   const template = lookupAcceptanceTemplate(strategy, subGate);
+  // Lightweight PR-body-as-spec (issue #1025): retarget the phase-doc criterion
+  // text to the PR description. Null/phase_doc leaves the criteria untouched, so
+  // the non-lightweight path stays byte-identical.
+  const specSource = deriveSpecSource(bundle, resolverOutput);
+  const acceptanceCriteria = applySpecSourceVariant(template.criteria, specSource);
 
   const overrides = options.overrides && typeof options.overrides === "object" && Object.keys(options.overrides).length > 0
     ? { ...options.overrides }
     : undefined;
 
+  // Sanctioned operation → wrapper command map (issue #1081). Core is
+  // consumer-agnostic: it carries whatever map the consumer supplies (the
+  // `loop build-envelope` CLI injects this repo's scripts/... paths) so every
+  // spawned subagent receives it by DEFAULT. Core defines the SHAPE only —
+  // it never hardcodes repo-specific paths. A non-object is ignored.
+  const sanctionedCommands = options.sanctionedCommands && typeof options.sanctionedCommands === "object" && !Array.isArray(options.sanctionedCommands)
+    ? options.sanctionedCommands
+    : undefined;
+
   // Surface the *effective* async-start posture alongside the *configured* one (#834). The
   // configured `asyncStartMode` is echoed verbatim from settings (back-compat), but the contract
   // is relaxed at validation time under the Claude harness (resolveEffectiveAsyncStartMode →
@@ -509,7 +608,7 @@ export function buildDevLoopHandoffEnvelope(resolverOutput, settings, gateState
     worktreeRequired: true,
 
     acceptance: {
-      criteria: [...template.criteria],
+      criteria: acceptanceCriteria,
       evidence: [...template.evidence],
       maxFinalizationTurns: template.maxFinalizationTurns,
     },
@@ -528,11 +627,22 @@ export function buildDevLoopHandoffEnvelope(resolverOutput, settings, gateState
     envelope.overrides = overrides;
   }
 
-  // Optional refinement contract (AC/DoD matrix) from the refiner.
-  // Set via options.refinementContract, bundle.refinementContract, or resolverOutput.refinementContract.
-  const refinementContract = options.refinementContract ?? bundle.refinementContract ?? resolverOutput.refinementContract ?? null;
-  if (refinementContract != null) {
-    envelope.refinementContract = refinementContract;
+  if (sanctionedCommands) {
+    envelope.sanctionedCommands = sanctionedCommands;
+  }
+
+  // Advisory retrospective findings (issue #1077, Reading B). Optional structured
+  // field carrying the check-retro-tooling.mjs JSON output to the conductor. Never a
+  // gate — the conductor surfaces these as an advisory PR comment, not a block.
+  if (retrospectiveFindings) {
+    envelope.retrospectiveFindings = retrospectiveFindings;
+  }
+
+  // Canonical spec source (issue #1025). Optional: only set when the resolver
+  // marks a lightweight PR-body-as-spec session, so the default (phase-doc) path
+  // carries no specSource field and its envelope stays byte-identical.
+  if (specSource) {
+    envelope.specSource = specSource;
   }
 
   return deepFreeze(envelope);
@@ -767,79 +877,40 @@ export function validateHandoffEnvelope(envelope) {
     });
   }
 
-  // ----- refinementContract (optional) -----
-  if (envelope.refinementContract !== undefined && envelope.refinementContract !== null) {
-    if (typeof envelope.refinementContract !== "object" || Array.isArray(envelope.refinementContract)) {
+  // ----- retrospectiveFindings (optional, advisory — issue #1077) -----
+  if (envelope.retrospectiveFindings !== undefined && envelope.retrospectiveFindings !== null) {
+    const rf = envelope.retrospectiveFindings;
+    if (typeof rf !== "object" || Array.isArray(rf)) {
       errors.push({
-        field: "refinementContract",
-        reason: "if present, must be a non-array object with schema, items, generatedAt, and isComplete",
-        got: envelope.refinementContract,
+        field: "retrospectiveFindings",
+        reason: "if present, must be a non-array object { internalToolingOnly, rawCallViolations, allowedWriteOps }",
+        got: rf,
       });
     } else {
-      if (envelope.refinementContract.schema !== "ac-dod-matrix/v1") {
-        warnings.push({
-          field: "refinementContract.schema",
-          reason: "expected 'ac-dod-matrix/v1'",
-          got: envelope.refinementContract.schema,
-        });
-      }
-      if (!Array.isArray(envelope.refinementContract.items) || envelope.refinementContract.items.length === 0) {
-        errors.push({
-          field: "refinementContract.items",
-          reason: "must be a non-empty array of AC/DoD matrix items",
-          got: envelope.refinementContract.items,
-        });
-      } else {
-        const bad = [];
-        for (let i = 0; i < envelope.refinementContract.items.length; i++) {
-          const item = envelope.refinementContract.items[i];
-          if (
-            !item || typeof item !== "object" ||
-            typeof item.item !== "string" || !item.item.trim() ||
-            !["AC", "DoD", "Non-goal"].includes(item.type) ||
-            !["Met", "Partial", "Unmet", "Unverified"].includes(item.status) ||
-            typeof item.evidence !== "string" ||
-            typeof item.notes !== "string"
-          ) {
-            bad.push(i);
-          }
-        }
-        if (bad.length > 0) {
-          errors.push({
-            field: "refinementContract.items",
-            reason: `entries at indices [${bad.join(",")}] must have valid item, type, status, evidence, and notes fields`,
-            got: envelope.refinementContract.items,
-          });
-        }
+      if (typeof rf.internalToolingOnly !== "boolean") {
+        errors.push({ field: "retrospectiveFindings.internalToolingOnly", reason: "must be a boolean", got: rf.internalToolingOnly });
       }
-      if (typeof envelope.refinementContract.generatedAt !== "string" || isNaN(Date.parse(envelope.refinementContract.generatedAt))) {
-        errors.push({
-          field: "refinementContract.generatedAt",
-          reason: "must be a valid ISO 8601 timestamp",
-          got: envelope.refinementContract.generatedAt,
-        });
+      if (!Array.isArray(rf.rawCallViolations) || rf.rawCallViolations.some((v) => typeof v !== "string")) {
+        errors.push({ field: "retrospectiveFindings.rawCallViolations", reason: "must be an array of strings", got: rf.rawCallViolations });
       }
-      if (typeof envelope.refinementContract.isComplete !== "boolean") {
-        errors.push({
-          field: "refinementContract.isComplete",
-          reason: "must be a boolean",
-          got: envelope.refinementContract.isComplete,
-        });
-      } else if (envelope.refinementContract.items && Array.isArray(envelope.refinementContract.items)) {
-        const allMet = envelope.refinementContract.items.every(
-          (item) => item && typeof item === "object" && item.status === "Met"
-        );
-        if (envelope.refinementContract.isComplete !== allMet) {
-          errors.push({
-            field: "refinementContract.isComplete",
-            reason: "must match items status (true iff every item has status 'Met')",
-            got: { isComplete: envelope.refinementContract.isComplete, allItemsMet: allMet },
-          });
-        }
+      if (!Array.isArray(rf.allowedWriteOps) || rf.allowedWriteOps.some((v) => typeof v !== "string")) {
+        errors.push({ field: "retrospectiveFindings.allowedWriteOps", reason: "must be an array of strings", got: rf.allowedWriteOps });
       }
     }
   }
 
+  // ----- specSource (optional — issue #1025, lightweight PR-body-as-spec) -----
+  if (envelope.specSource !== undefined && envelope.specSource !== null) {
+    const validSources = [CANONICAL_SPEC_SOURCE.PHASE_DOC, CANONICAL_SPEC_SOURCE.PR_BODY];
+    if (typeof envelope.specSource !== "string" || !validSources.includes(envelope.specSource)) {
+      errors.push({
+        field: "specSource",
+        reason: `if present, must be one of ${validSources.join(", ")}`,
+        got: envelope.specSource,
+      });
+    }
+  }
+
   // ----- derivedAt (informational, warn on missing) -----
   if (typeof envelope.derivedAt !== "string" || !envelope.derivedAt.trim()) {
     warnings.push({ field: "derivedAt", reason: "should be an ISO 8601 timestamp" });
@@ -863,6 +934,7 @@ export {
   deriveCwd,
   deriveRequiredReads,
   normalizeGateState,
+  normalizeRetrospectiveFindings,
   resolveSubGate,
   lookupAcceptanceTemplate,
   buildWorktreeSlug,

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,162 @@ 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 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.
+ *
+ * @param {{ body?: string, expectedIssue?: number }} 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 } = {}) {
+  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 (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.",
 });
 
 // ---------------------------------------------------------------------------