@dev-loops/core 1.0.0-rc.7 → 1.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dev-loops/core",
-  "version": "1.0.0-rc.7",
+  "version": "1.0.0",
   "type": "module",
   "engines": {
     "node": ">=24"
@@ -53,6 +53,7 @@
     "./loop/refinement-grill-state": "./src/loop/refinement-grill-state.mjs",
     "./loop/queue-board-ordering": "./src/loop/queue-board-ordering.mjs",
     "./loop/default-branch-guard": "./src/loop/default-branch-guard.mjs",
+    "./loop/commit-msg-guard": "./src/loop/commit-msg-guard.mjs",
     "./loop/queue-board-sync": "./src/loop/queue-board-sync.mjs",
     "./loop/queue-driver": "./src/loop/queue-driver.mjs",
     "./loop/queue-membership": "./src/loop/queue-membership.mjs",

package/src/loop/commit-msg-guard.mjs

@@ -0,0 +1,168 @@
+import fs from "node:fs";
+import path from "node:path";
+
+/**
+ * Enforces the commit-message contract AT COMMIT TIME (issue #1869): the
+ * attribution trailers, the no-bare-#N rule, and the conventional-commit
+ * subject form were previously prose-only — nothing checked them, so a
+ * non-compliant commit landed silently. Installed alongside the
+ * default-branch guard (see default-branch-guard.mjs), through the same
+ * ensure-worktree provisioning path, so it rides into every worktree too.
+ *
+ * The rendered hook is a single self-contained Node script (ESM: this repo's
+ * root package.json is `"type": "module"`, and Node resolves an
+ * extensionless direct-run script's module type by walking up for the
+ * nearest package.json — verified empirically, not merely assumed). Keeping
+ * the ENTIRE check inline in the rendered script (rather than requiring a
+ * sibling file back into the checkout) means the installed hook keeps
+ * working even if the checkout that installed it is later removed or moved
+ * — the same self-containment default-branch-guard's hooks rely on.
+ */
+export const COMMIT_MSG_GUARD_MARKER = "dev-loops:commit-msg-guard";
+export const COMMIT_MSG_WAIVER_MARKER = `${COMMIT_MSG_GUARD_MARKER}:allow`;
+
+// Ownership check mirrors default-branch-guard's: the marker must be its own
+// line (a `//` comment, since the rendered hook is JS), not merely mentioned,
+// so a foreign hook that references us in prose is still left untouched.
+const GUARD_MARKER_LINE = new RegExp(`^// ${COMMIT_MSG_GUARD_MARKER}$`, "mu");
+
+/**
+ * Renders the commit-msg hook as a standalone, runnable Node script. The
+ * validation logic below is the ONLY copy of it — there is no separate JS
+ * implementation this must stay in sync with, exactly like renderGuardHook's
+ * shell body has none either. Tests exercise it by actually running it (see
+ * commit-msg-guard.test.mjs), the same way default-branch-guard.test.mjs
+ * drives real git rather than asserting on rendered text.
+ *
+ * String.raw, not a plain template literal: the generated script is full of
+ * regex backslash escapes (\s, \d, \b, \.) that a normal template literal
+ * would silently strip (an unrecognized string escape drops its backslash),
+ * corrupting every regex in the installed hook. String.raw keeps every
+ * backslash literal while still substituting the ${...} marker constants.
+ * The generated script deliberately uses NO template literals of its own
+ * (string concatenation instead) — a literal backtick would otherwise close
+ * THIS OUTER template early.
+ */
+export function renderCommitMsgGuardHook() {
+  return String.raw`#!/usr/bin/env node
+// ${COMMIT_MSG_GUARD_MARKER}
+// Enforces the commit-message contract (issue #1869): attribution trailers,
+// no bare non-issue #<digits>, and a conventional-commit subject. A
+// per-commit waiver line (${COMMIT_MSG_WAIVER_MARKER}) skips every check
+// below for a deliberate exception.
+import { readFileSync } from "node:fs";
+
+// git invokes commit-msg with ONLY the message-file path (unlike
+// prepare-commit-msg, which also gets a source/sha) — no signal distinguishes
+// an ordinary commit from a merge/squash at this hook. A default, unedited
+// merge message ("Merge branch '...'", "Merge pull request #...", "Merge tag
+// '...'"), a default git-revert message (Revert "..."), or a
+// git commit --fixup/--squash autosquash subject (fixup! ... / squash! ...)
+// is git/tooling-generated, not operator-authored prose, so each is exempt by
+// its own recognizable shape rather than forced through a conventional-commit
+// subject and trailers it was never meant to carry.
+const [, , msgPath] = process.argv;
+const message = readFileSync(msgPath, "utf8");
+const subjectLine = message.split("\n", 1)[0] || "";
+if (
+  /^Merge (branch|tag|remote-tracking branch|pull request) /u.test(subjectLine) ||
+  /^Revert "/u.test(subjectLine) ||
+  /^(fixup|squash)! /u.test(subjectLine)
+) process.exit(0);
+
+if (/^${COMMIT_MSG_GUARD_MARKER}:allow\b/mu.test(message)) process.exit(0);
+
+const errors = [];
+
+// Trailers are required only for an AGENT-authored commit: Claude Code sets
+// CLAUDECODE=1 in every shell it spawns (the same harness-detection signal
+// packages/core/src/loop/run-context.mjs's isClaudeHarness checks) — a plain
+// human commit (CLAUDECODE unset) is never "Claude", so requiring a Claude
+// co-author trailer on it would misattribute the commit, not enforce honesty.
+if (process.env.CLAUDECODE === "1") {
+  if (!/^Co-Authored-By:\s*Claude\s+.+\s+<noreply@anthropic\.com>\s*$/imu.test(message)) {
+    errors.push("missing required trailer: Co-Authored-By: Claude <model> <noreply@anthropic.com>");
+  }
+  if (!/^Claude-Session:\s*\S+/imu.test(message)) {
+    errors.push("missing required trailer: Claude-Session: <url>");
+  }
+}
+
+// A genuine "Closes #N" / "Fixes #N" / "Refs #N" reference (optionally a
+// comma/and-joined list, and optionally the trailer colon form "Closes: #N")
+// is allowed and stripped first; any #<digits> left over is a bare non-issue
+// enumeration, which GitHub auto-links to an unrelated issue/PR when
+// rendered.
+const withoutAllowedRefs = message.replace(
+  /\b(?:close[sd]?|fix(?:e[sd])?|resolve[sd]?|refs?|references?):?\s+#\d+(?:\s*(?:,|and)\s*#\d+)*/giu,
+  "",
+);
+if (/#\d+/u.test(withoutAllowedRefs)) {
+  errors.push('bare #<digits> reference found; use "Closes #N" / "Fixes #N" / "Refs #N" for a genuine issue reference, or reword a non-issue enumeration (e.g. "defect N")');
+}
+
+if (!/^(feat|fix|chore|docs|test|refactor|revert|perf|style|ci|build)\([^()\n]+\): .+\S/u.test(subjectLine)) {
+  errors.push("subject must be conventional-commit form \"type(scope): summary\" (type one of feat/fix/chore/docs/test/refactor/revert/perf/style/ci/build)");
+}
+
+if (errors.length > 0) {
+  console.error("dev-loops: WORKTREE-COMMIT-MSG-GUARD refuses this commit — contract violation(s):");
+  for (const error of errors) console.error("  - " + error);
+  console.error("  Waiver: add a \"${COMMIT_MSG_WAIVER_MARKER}\" line to the commit message for a deliberate exception.");
+  process.exit(1);
+}
+process.exit(0);
+`;
+}
+
+/**
+ * Install the commit-msg guard into a repository's hook directory. Mirrors
+ * default-branch-guard's install-refusal checks (a caller with an unsafe
+ * `core.hooksPath`, a non-absolute/non-git `gitDir`, or a linked worktree's
+ * OWN gitdir must never report success for a hook that can never fire) and
+ * its atomic write + foreign-hook preservation — duplicated rather than
+ * shared, since it is one hook, not a family; see default-branch-guard.mjs
+ * for the family version if a third hook installer ever needs the same
+ * shape factored out.
+ *
+ * @param {{ gitDir: string, hooksPathOverride?: string|null }} target
+ */
+export function installCommitMsgGuard({ gitDir, hooksPathOverride = null }) {
+  const refuse = (reason) => ({ ok: false, installed: false, refreshed: false, skipped: true, reason });
+
+  if (typeof hooksPathOverride === "string") {
+    const configured = hooksPathOverride.trim();
+    return configured.length > 0
+      ? refuse(`core.hooksPath is set to ${JSON.stringify(configured)} — install the guard there, or unset it`)
+      : refuse("core.hooksPath is set to an empty string — git runs no hooks at all");
+  }
+  if (typeof gitDir !== "string" || !path.isAbsolute(gitDir)) {
+    return refuse(`gitDir must be an absolute path; got ${JSON.stringify(gitDir)}`);
+  }
+  if (!fs.existsSync(path.join(gitDir, "HEAD"))) {
+    return refuse(`gitDir ${JSON.stringify(gitDir)} does not look like a git directory (no HEAD file)`);
+  }
+  if (fs.existsSync(path.join(gitDir, "commondir"))) {
+    return refuse(`gitDir ${JSON.stringify(gitDir)} is a linked worktree's own git directory, not the common one — hooks installed there never run`);
+  }
+
+  const hooksDir = path.join(gitDir, "hooks");
+  fs.mkdirSync(hooksDir, { recursive: true });
+  const hookPath = path.join(hooksDir, "commit-msg");
+
+  const existing = fs.existsSync(hookPath) ? fs.readFileSync(hookPath, "utf8") : null;
+  const ours = existing === null || GUARD_MARKER_LINE.test(existing);
+  if (!ours) {
+    return { ok: true, installed: false, refreshed: false, skipped: true, reason: "a pre-existing hook is present and was left untouched" };
+  }
+
+  // Same atomic tmp-write + rename as default-branch-guard: the hooks dir is
+  // shared across worktrees, so a direct writeFileSync would be visible
+  // mid-write to a concurrent install or a real commit racing this one.
+  const tmpPath = path.join(hooksDir, `.commit-msg.tmp-${process.pid}-${Date.now()}`);
+  fs.writeFileSync(tmpPath, renderCommitMsgGuardHook(), { mode: 0o755 });
+  fs.chmodSync(tmpPath, 0o755);
+  fs.renameSync(tmpPath, hookPath);
+
+  return { ok: true, installed: existing === null, refreshed: existing !== null, skipped: false };
+}

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

@@ -9,6 +9,13 @@
  * `Acceptance criteria` or `DoD` section cause the draft gate to post
  * `verdict=blocked` with the `missing_refinement_artifact` finding.
  *
+ * Since #1866 the check ALSO requires an explicit Non-goals section on the
+ * issue body (see `MISSING_EXPLICIT_NON_GOALS_FINDING` below).
+ */
+import { existsSync } from "node:fs";
+import path from "node:path";
+
+/**
  * This module owns:
  * - canonical section-name matching for AC / DoD blocks
  * - bullet-item extraction (checklist `- [ ]`/`- [x]` and top-level `- ` bullets)
@@ -38,6 +45,15 @@ export const REFINEMENT_ARTIFACT_SOURCES = Object.freeze([
   "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.
+ */
+export const MISSING_EXPLICIT_NON_GOALS_FINDING = "missing_explicit_non_goals";
+
 /**
  * Canonical list of section headings that satisfy the refinement check.
  * Matching is case-insensitive and tolerates trailing/leading whitespace.
@@ -248,6 +264,13 @@ export function detectLinkedRefinementDoc(body) {
 
   const pathMatch = /(?:^|\s|[`(\[<])(tmp\/refinement\/[A-Za-z0-9._/\-]+\.md)\b/u.exec(body);
   if (pathMatch) {
+    // Containment guard: reject actual '..' path segments (not benign
+    // double-dot filenames) so the new fs-probe wiring can never be used as a
+    // filesystem existence oracle outside tmp/refinement
+    // (e.g. `tmp/refinement/../../docs/some-existing.md`).
+    if (pathMatch[1].split("/").some((segment) => segment === "..")) {
+      return { found: false, path: null, reason: "path-escapes-refinement-dir" };
+    }
     return { found: true, path: pathMatch[1], reason: "explicit-path" };
   }
 
@@ -261,6 +284,11 @@ export function detectLinkedRefinementDoc(body) {
   if (refinementSection) {
     const inlinePath = /(?:^|\s)(tmp\/refinement\/[^\s)`'"]+\.md)\b/u.exec(refinementSection.bodyLines.join("\n"));
     if (inlinePath) {
+      // Containment guard: same segment-based '..' rejection as the
+      // explicit-path branch.
+      if (inlinePath[1].split("/").some((segment) => segment === "..")) {
+        return { found: false, path: null, reason: "path-escapes-refinement-dir" };
+      }
       return { found: true, path: inlinePath[1], reason: "refinement-section-path" };
     }
   }
@@ -271,25 +299,56 @@ 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).
+ *
+ * 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.
+ *
  * @param {object} input
  * @param {string} [input.body]  Raw issue body Markdown.
  * @param {number} [input.issueNumber]  Issue number, used for linked-doc convention.
+ * @param {Function} [input.resolveLinkedDoc]  Optional `(path) => boolean` doc-resolution check.
  * @returns {{
  *   hasACs: boolean,
+ *   hasNonGoals: boolean,
  *   source: string,
  *   acItems: string[],
  *   uncheckedAcItems: string[],
  *   dodItems: string[],
  *   sections: string[],
- *   linkedDoc: { found: boolean, path: string|null, reason: string },
+ *   linkedDoc: { found: boolean, path: string|null, reason: string, resolves?: boolean },
  *   reason: string,
  *   finding: string|null,
  * }}
  */
-export function detectIssueRefinementArtifact({ body = "", issueNumber = null } = {}) {
+export function detectIssueRefinementArtifact({ body = "", issueNumber = null, resolveLinkedDoc = null } = {}) {
   if (typeof body !== "string" || body.length === 0) {
     return {
       hasACs: false,
+      hasNonGoals: false,
       source: REFINEMENT_SOURCE.MISSING,
       acItems: [],
       uncheckedAcItems: [],
@@ -315,58 +374,88 @@ export function detectIssueRefinementArtifact({ body = "", issueNumber = null }
   const uncheckedAcItems = acceptanceSection ? extractUncheckedChecklistItems(acceptanceSection.bodyLines.join("\n")) : [];
   const dodItems = dodSection ? extractChecklistItems(dodSection.bodyLines.join("\n")) : [];
 
-  const linkedDoc = detectLinkedRefinementDoc(body);
-
-  if (acItems.length > 0) {
-    return {
-      hasACs: true,
-      source: REFINEMENT_SOURCE.ISSUE_BODY_AC,
-      acItems,
-      uncheckedAcItems,
-      dodItems,
-      sections: sectionNames,
-      linkedDoc,
-      reason: `Found ${acItems.length} Acceptance criteria checklist item(s) in the issue body.`,
-      finding: null,
-    };
+  let linkedDoc = detectLinkedRefinementDoc(body);
+  let linkedDocResolves = linkedDoc.found;
+  if (linkedDoc.found && typeof resolveLinkedDoc === "function") {
+    linkedDocResolves = resolveLinkedDoc(linkedDoc.path) === true;
+    linkedDoc = { ...linkedDoc, resolves: linkedDocResolves };
   }
 
-  if (dodItems.length > 0) {
-    return {
-      hasACs: true,
-      source: REFINEMENT_SOURCE.ISSUE_BODY_DOD,
-      acItems,
-      uncheckedAcItems,
-      dodItems,
-      sections: sectionNames,
-      linkedDoc,
-      reason: `Found ${dodItems.length} DoD checklist item(s) in the issue body.`,
-      finding: null,
-    };
-  }
+  // #1866: 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).
+  const hasNonGoals = sectionHasBody(
+    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;
 
-  if (linkedDoc.found) {
+  const base = {
+    hasNonGoals,
+    acItems,
+    uncheckedAcItems,
+    dodItems,
+    sections: sectionNames,
+    linkedDoc,
+  };
+
+  if (artifactSource !== null) {
+    if (!hasNonGoals) {
+      return {
+        ...base,
+        hasACs: false,
+        source: artifactSource,
+        reason:
+          `Issue body carries a refinement artifact (${artifactSource}) 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,
+      };
+    }
+    if (artifactSource === REFINEMENT_SOURCE.ISSUE_BODY_AC) {
+      return {
+        ...base,
+        hasACs: true,
+        source: REFINEMENT_SOURCE.ISSUE_BODY_AC,
+        reason: `Found ${acItems.length} Acceptance criteria checklist item(s) in the issue body.`,
+        finding: null,
+      };
+    }
+    if (artifactSource === REFINEMENT_SOURCE.ISSUE_BODY_DOD) {
+      return {
+        ...base,
+        hasACs: true,
+        source: REFINEMENT_SOURCE.ISSUE_BODY_DOD,
+        reason: `Found ${dodItems.length} DoD checklist item(s) in the issue body.`,
+        finding: null,
+      };
+    }
     return {
+      ...base,
       hasACs: true,
       source: REFINEMENT_SOURCE.LINKED_DOC,
       acItems: [],
       uncheckedAcItems: [],
       dodItems: [],
-      sections: sectionNames,
-      linkedDoc,
       reason: `Issue body links a refinement doc at ${linkedDoc.path}; treating that as the refinement artifact source.`,
       finding: null,
     };
   }
 
   return {
+    ...base,
     hasACs: false,
     source: REFINEMENT_SOURCE.MISSING,
     acItems: [],
     uncheckedAcItems: [],
     dodItems: [],
-    sections: sectionNames,
-    linkedDoc,
     reason: "Issue body has no Acceptance criteria section, no DoD section, and no linked refinement doc.",
     finding: REFINEMENT_ARTIFACT_FINDING,
   };
@@ -484,7 +573,16 @@ function sectionHasBody(section) {
  * 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
+ * `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.
+ *
+ * @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[] }}
  */
 
@@ -540,7 +638,7 @@ export function detectGrillEmbedHeading(body = "") {
   return null;
 }
 
-export function validatePrBodySpec({ body = "", expectedIssue = null, issueLess = false } = {}) {
+export function validatePrBodySpec({ body = "", expectedIssue = null, issueLess = false, requireOpenQuestions = true } = {}) {
   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.
@@ -550,7 +648,8 @@ export function validatePrBodySpec({ body = "", expectedIssue = null, issueLess
   const sections = parseMarkdownSections(bodyText);
   const errors = [];
 
-  for (const { code, label, patterns } of Object.values(PR_BODY_SPEC_NARRATIVE_SECTIONS)) {
+  for (const [key, { code, label, patterns }] of Object.entries(PR_BODY_SPEC_NARRATIVE_SECTIONS)) {
+    if (key === "open_questions" && !requireOpenQuestions) continue;
     const section = findSectionByPatterns(sections, patterns);
     if (!sectionHasBody(section)) {
       errors.push({ code, message: `Missing or empty ${label} section.` });
@@ -606,6 +705,31 @@ 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
+ * 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
+ * the portable spec-of-record a tracker-agnostic consumer reads.
+ *
+ * Thin wrapper over `validatePrBodySpec`, not a second divergent checker:
+ * `requireOpenQuestions: false` because the tracker-backed contract, unlike
+ * the lightweight PR-body-as-spec path, does not require an Open
+ * questions/risks section. `expectedIssue` is only checked when the PR closes
+ * exactly ONE issue — an umbrella PR closing several is not required to name
+ * any single one of them in the `expectedIssue` slot (each linked issue's
+ * refinement is verified separately by the caller).
+ *
+ * @param {{ body?: string, closingIssues?: number[] }} input
+ * @returns {ReturnType<typeof validatePrBodySpec>}
+ */
+export function validateTrackerBackedPrBodySpec({ body = "", closingIssues = [] } = {}) {
+  const expectedIssue = Array.isArray(closingIssues) && closingIssues.length === 1 ? closingIssues[0] : null;
+  return validatePrBodySpec({ body, expectedIssue, requireOpenQuestions: false });
+}
+
 /**
  * Decide what an enqueue caller should do with a refinement-artifact result,
  * so an un-refined item never lands in the Next Up pickup column in the first
@@ -623,12 +747,22 @@ export function validatePrBodySpec({ body = "", expectedIssue = null, issueLess
  * @returns {{ action: "enqueue" } | { action: "block"|"divert", reason: string, missing: string[] }}
  */
 export function decideEnqueueRefinementGate({ artifact, targetIsPickup, auto = false }) {
-  // `artifact.finding === null` is the explicit "has ANY refinement artifact"
-  // signal (AC checklist OR DoD checklist OR linked doc) — clearer than reading
-  // `hasACs`, whose name understates that a DoD or linked doc also satisfies it.
+  // `artifact.finding === null` is the explicit "passes the full refinement
+  // check" signal (artifact AND — since #1866 — an explicit Non-goals
+  // section), clearer than reading `hasACs`, whose name understates what it
+  // covers.
   if (!targetIsPickup || artifact.finding === null) {
     return { action: "enqueue" };
   }
+  // #1866: 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 =
+      "Issue carries a refinement artifact but no explicit Non-goals section. " +
+      "Add an explicit `## Non-goals` section to the issue body " +
+      "(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"] };
+  }
   const missing = [...REFINEMENT_ARTIFACT_SOURCES];
   const reason =
     `Issue has no refinement artifact (none of: ${missing.join(", ")}). ` +
@@ -649,7 +783,7 @@ export function decideEnqueueRefinementGate({ artifact, targetIsPickup, auto = f
  * @param {{ issueNumber: number, repo: string, env: object, runChild: Function, auto?: boolean }} input
  * @returns {Promise<{ action: "enqueue" } | { action: "divert"|"block", reason: string, missing: string[] }>}
  */
-export async function runPickupRefinementGate({ issueNumber, repo, env, runChild, auto = false }) {
+export async function runPickupRefinementGate({ issueNumber, repo, env, runChild, auto = false, repoRoot = null }) {
   const bodyResult = await runChild(
     "gh",
     ["issue", "view", String(issueNumber), "--repo", repo, "--json", "body"],
@@ -666,7 +800,17 @@ export async function runPickupRefinementGate({ issueNumber, repo, env, runChild
     throw new Error("Invalid JSON input");
   }
   const body = typeof bodyPayload?.body === "string" ? bodyPayload.body : "";
-  const artifact = detectIssueRefinementArtifact({ body, issueNumber });
+  // #1866: 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
+  // gate happened to run from.
+  const docAnchor = repoRoot ?? process.cwd();
+  const artifact = detectIssueRefinementArtifact({
+    body,
+    issueNumber,
+    resolveLinkedDoc: (p) => existsSync(path.isAbsolute(p) ? p : path.resolve(docAnchor, p)),
+  });
   const decision = decideEnqueueRefinementGate({ artifact, targetIsPickup: true, auto });
   if (decision.action === "block") {
     throw Object.assign(new Error(decision.reason), {

package/src/loop/public-dev-loop-routing.mjs

@@ -2,7 +2,9 @@ import {
   evaluateRetrospectiveGate,
   normalizeRetrospectiveCheckpointState,
   normalizeCheckpointCycleIdentity,
+  normalizeRetroProvenance,
   resolveCheckpointStateFromArtifact,
+  RETROSPECTIVE_PROVENANCE,
 } from "./retrospective-checkpoint.mjs";
 import {
   EXTERNAL_HEALTHY_WAIT_TIMEOUT_POLICY,
@@ -43,7 +45,9 @@ export * from "./public-dev-loop-routing-contract.mjs";
 // package export (see skills/docs/retrospective-checkpoint-contract.md).
 export {
   normalizeCheckpointCycleIdentity,
+  normalizeRetroProvenance,
   resolveCheckpointStateFromArtifact,
+  RETROSPECTIVE_PROVENANCE,
 };
 
 const COPILOT_ISSUE_ASSIGNEE = "copilot-swe-agent";

package/src/loop/retrospective-checkpoint.mjs

@@ -55,6 +55,54 @@ export const RETROSPECTIVE_QUALIFYING_GATES = Object.freeze([
   "issue_intake",
 ]);
 
+/**
+ * Provenance context values for a recorded retrospective (issue #1870).
+ *
+ * A retrospective MUST be produced by a FRESH-CONTEXT, independent dispatch
+ * (analogous to a gate reviewer) seeded with the cycle's full agent/subagent
+ * tool-call/action/result record — never written inline by the same working
+ * context that did the work. A self-authored retro reflects the working
+ * agent's own blind spots back at it; it validates consistency, not
+ * conformance, so an inline retro fails the checkpoint.
+ */
+export const RETROSPECTIVE_PROVENANCE = Object.freeze({
+  /** Dispatched as a fresh, independent context (the only accepting value). */
+  CONTEXT_FRESH: "fresh",
+  /** Self-authored by the working context — rejected, fails closed. */
+  CONTEXT_INLINE: "inline",
+  /** The retro was seeded with the full agent/subagent tool-call record. */
+  SEEDED_FROM_RECORD: "agent_tool_call_record",
+});
+
+/**
+ * Normalizes a retrospective provenance record from a durable checkpoint
+ * artifact. Returns the normalized provenance only when it pins a valid
+ * fresh-context pass over the full tool-call record:
+ * - `context` must normalize to "fresh" (trimmed, case-insensitive; an
+ *   "inline"/self-authored retro is rejected — it fails closed, never accepted)
+ * - `seededFrom` must be exactly "agent_tool_call_record" (the retro audited
+ *   the cycle's actual behavior, not a summary)
+ * - `recordSource` must be a non-blank string (the transcript/journal path
+ *   the retro was seeded with)
+ *
+ * Returns null for anything else — absent, malformed, inline, or partial.
+ *
+ * @param {unknown} value
+ * @returns {{context: "fresh", seededFrom: "agent_tool_call_record", recordSource: string}|null}
+ */
+export function normalizeRetroProvenance(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    return null;
+  }
+  const context = typeof value.context === "string" ? value.context.trim().toLowerCase() : "";
+  const seededFrom = typeof value.seededFrom === "string" ? value.seededFrom.trim().toLowerCase() : "";
+  const recordSource = typeof value.recordSource === "string" ? value.recordSource.trim() : "";
+  if (context !== RETROSPECTIVE_PROVENANCE.CONTEXT_FRESH || seededFrom !== RETROSPECTIVE_PROVENANCE.SEEDED_FROM_RECORD || recordSource.length === 0) {
+    return null;
+  }
+  return { context: RETROSPECTIVE_PROVENANCE.CONTEXT_FRESH, seededFrom: RETROSPECTIVE_PROVENANCE.SEEDED_FROM_RECORD, recordSource };
+}
+
 /**
  * Normalizes an external retrospective checkpoint-state input to one of the
  * stable RETROSPECTIVE_CHECKPOINT_STATE values. Returns null when the value is
@@ -149,7 +197,17 @@ export function resolveCheckpointStateFromArtifact(artifact, { hasNewerMergeSinc
     return hasNewerMergeSinceCheckpoint ? RETROSPECTIVE_CHECKPOINT_STATE.MISSING : RETROSPECTIVE_CHECKPOINT_STATE.SKIPPED;
   }
   if (rawState === "complete") {
-    return hasNewerMergeSinceCheckpoint ? RETROSPECTIVE_CHECKPOINT_STATE.MISSING : RETROSPECTIVE_CHECKPOINT_STATE.COMPLETE;
+    if (hasNewerMergeSinceCheckpoint) {
+      return RETROSPECTIVE_CHECKPOINT_STATE.MISSING;
+    }
+    // Fresh-context provenance is mandatory (issue #1870): a `complete` record
+    // without provenance that pins a fresh-context pass over the full
+    // tool-call record — including legacy inline/self-authored retros — fails
+    // closed to MISSING. The old inline self-review path is disallowed.
+    if (normalizeRetroProvenance(artifact.provenance) === null) {
+      return RETROSPECTIVE_CHECKPOINT_STATE.MISSING;
+    }
+    return RETROSPECTIVE_CHECKPOINT_STATE.COMPLETE;
   }
   // Malformed/unrecognized durable state — fail closed.
   return RETROSPECTIVE_CHECKPOINT_STATE.MISSING;

package/src/projects/move-queue-item.mjs

@@ -369,7 +369,7 @@ async function main(args, { env = process.env, runChild, cwd = null } = {}) {
           { code: "CONFIG_ERROR" },
         );
       }
-      const decision = await runPickupRefinementGate({ issueNumber, repo, env, runChild: child, auto: false });
+      const decision = await runPickupRefinementGate({ issueNumber, repo, env, runChild: child, auto: false, repoRoot: cwd });
       refinement = { refined: decision.action === "enqueue" };
     }
   }