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

package/src/loop/pr-gate-coordination.mjs

@@ -3,6 +3,11 @@ import { findBlockingTitleMarkers } from "./pr-title-markers.mjs";
 import { evaluateUiE2eScoping } from "./ui-e2e-scoping.mjs";
 import { evaluateUiDesignerReviewScoping } from "./ui-designer-review-scoping.mjs";
 import { trimmedOrNull } from "./normalize.mjs";
+import {
+  MISSING_AC_CHECKLIST_FINDING,
+  MISSING_DOD_CHECKLIST_FINDING,
+  MISSING_EXPLICIT_NON_GOALS_FINDING,
+} from "./issue-refinement-artifact.mjs";
 
 export const PR_CHECKPOINT = Object.freeze({
   DRAFT_REVIEW: "draft_review",
@@ -241,15 +246,35 @@ function normalizeRefinementArtifactStatus(value) {
 // their own validation-failure reason from the detector; that reason must
 // replace the "linked issue" wording, which does not apply when the PR is the
 // spec-of-record and no linked issue was ever expected.
+// #1877 full-matrix vocabulary for the draft-gate blocked reason: which
+// matrix arm is missing per finding — the SAME finding taxonomy the enqueue
+// gate's guidance (decideEnqueueRefinementGate) and the detector
+// (detectIssueRefinementArtifact) use, so the draft gate (the unconditional
+// backstop for that floor) cannot drift from it. An AC-only or DoD-only
+// linked issue is a matrix miss, not "no artifact" — the guidance must name
+// the actually-missing arm so the fix is not misdirected.
+const REFINEMENT_MISSING_ARM_BY_FINDING = Object.freeze({
+  [MISSING_DOD_CHECKLIST_FINDING]: "a Definition of done checklist (mapped to the acceptance criteria)",
+  [MISSING_AC_CHECKLIST_FINDING]: "an Acceptance criteria checklist (for the DoD items to map to)",
+  [MISSING_EXPLICIT_NON_GOALS_FINDING]: "an explicit Non-goals section",
+});
+
 function formatRefinementBlockedReason(linkedIssue, status, refinementArtifact) {
   const specSource = refinementArtifact?.specSource;
   if (specSource != null && specSource !== REFINEMENT_ARTIFACT_SPEC_SOURCE.LINKED_ISSUE && typeof refinementArtifact?.reason === "string" && refinementArtifact.reason.length > 0) {
     return `The draft gate cannot complete: ${refinementArtifact.reason} finding=${REFINEMENT_ARTIFACT_FINDING}`;
   }
+  const finding = typeof refinementArtifact?.finding === "string" && refinementArtifact.finding.length > 0
+    ? refinementArtifact.finding
+    : REFINEMENT_ARTIFACT_FINDING;
+  const missingArm = REFINEMENT_MISSING_ARM_BY_FINDING[finding];
+  if (missingArm !== undefined) {
+    return `Linked issue #${linkedIssue} has an incomplete refinement matrix — it is missing ${missingArm}. Add it to the issue body to complete the full AC/DoD/Non-goals matrix, then re-open the draft PR. finding=${finding}`;
+  }
   if (linkedIssue !== null && Number.isInteger(linkedIssue)) {
-    return `Linked issue #${linkedIssue} has no refinement artifact (Acceptance criteria / DoD / linked refinement doc). Run refinement first, add ACs/DoD to the issue, then re-open the draft PR. finding=${REFINEMENT_ARTIFACT_FINDING}`;
+    return `Linked issue #${linkedIssue} has no refinement artifact (no Acceptance criteria checklist, DoD checklist, or resolvable linked refinement doc). Refine the issue to the full AC/DoD/Non-goals matrix — or link a refinement doc (tmp/refinement/*.md), a complete artifact on its own — then re-open the draft PR. finding=${REFINEMENT_ARTIFACT_FINDING}`;
   }
-  return `The draft gate cannot complete: the linked issue has no detectable refinement artifact (Acceptance criteria / DoD / linked refinement doc). finding=${REFINEMENT_ARTIFACT_FINDING}`;
+  return `The draft gate cannot complete: the linked issue has no detectable refinement artifact (no Acceptance criteria checklist, DoD checklist, or resolvable linked refinement doc). finding=${REFINEMENT_ARTIFACT_FINDING}`;
 }
 
 // #1472: describes the CI state a round-cap-reached fallback branch actually

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/queue-board-sync.mjs

@@ -172,9 +172,8 @@ function readDevloopsSettings(repoRoot) {
     try {
       const raw = readFileSync(base + ext, "utf8");
       const settings = ext === ".json" ? JSON.parse(raw) : parseYaml(raw);
-      // `tracker` (issue #1408, the tracker-agnostic seam) is surfaced
-      // alongside `queue` so loadBoardConfig can prefer tracker.board over
-      // the deprecated queue.board without a second file read.
+      // `tracker` (issue #1408, the tracker-agnostic seam) is surfaced so
+      // loadBoardConfig can read tracker.board directly.
       return { settings: settings?.queue ?? null, tracker: settings?.tracker ?? null };
     } catch (err) {
       if (err?.code === "ENOENT") {
@@ -204,18 +203,15 @@ function boardSelector(board) {
 }
 
 export function loadBoardConfig(repoRoot) {
-  const { settings: queue, tracker, error } = readDevloopsSettings(repoRoot);
+  const { tracker, error } = readDevloopsSettings(repoRoot);
   if (error) {
     return { enabled: false, reason: `config read/parse error: ${error}` };
   }
-  // tracker.board (canonical) takes priority over the deprecated queue.board
-  // (issue #1408) — see resolveTrackerBoard in ../config/config.mjs for the
-  // equivalent resolution against the validated, loaded config.
+  // tracker.board (canonical board key, issue #1408) — see resolveTrackerBoard
+  // in ../config/config.mjs for the equivalent resolution against the
+  // validated, loaded config.
   const trackerBoard = boardSelector(tracker?.board);
   if (trackerBoard) return trackerBoard;
-  if (!queue) return { enabled: false };
-  const queueBoard = boardSelector(queue.board);
-  if (queueBoard) return queueBoard;
   return { enabled: false };
 }
 

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" };
     }
   }

package/src/projects/resolve-project.mjs

@@ -6,9 +6,9 @@ import { parse as parseYaml } from "yaml";
 // resolution used by ensure-queue-board.mjs. Returns { project }, { title },
 // and/or { olderThanDays } when configured; never throws on a missing/bad file.
 //
-// `tracker.board` (issue #1408, the tracker-agnostic seam) takes priority over
-// the deprecated `queue.board` — same precedence as loadBoardConfig in
-// ../loop/queue-board-sync.mjs and resolveTrackerBoard in ../config/config.mjs.
+// The board resolves from `tracker.board` (issue #1408, the tracker-agnostic
+// seam) — same source as loadBoardConfig in ../loop/queue-board-sync.mjs and
+// resolveTrackerBoard in ../config/config.mjs.
 function resolveSettings(cwd) {
   const basePath = path.join(cwd, ".devloops");
   const extensions = ["", ".yaml", ".yml", ".json"];
@@ -18,7 +18,7 @@ function resolveSettings(cwd) {
       const settings = ext === ".json" ? JSON.parse(raw) : parseYaml(raw);
       const queue = settings?.queue;
       const out = {};
-      const board = settings?.tracker?.board ?? queue?.board;
+      const board = settings?.tracker?.board;
       if (board && typeof board === "object") {
         if (typeof board.number === "number" && Number.isInteger(board.number) && board.number > 0) {
           out.project = board.number;
@@ -139,7 +139,7 @@ function resolveProjectSelector(args) {
     : null;
   if (!projectRef && !projectTitle) {
     throw Object.assign(
-      new Error("--project is required (or set tracker.board — or the deprecated queue.board — number / title in .devloops)"),
+      new Error("--project is required (or set tracker.board number / title in .devloops)"),
       { code: "INVALID_PROJECT" },
     );
   }
@@ -178,7 +178,7 @@ function findProject(projects, { projectRef, projectTitle }, owner) {
 }
 
 // Apply .devloops board settings when --project was not passed. Precedence:
-// explicit --project flag > queue.board.number/queue.board.title. Mutates args.
+// explicit --project flag > tracker.board.number/tracker.board.title. Mutates args.
 function applyDevloopsBoard(args, cwd) {
   if (args.project === undefined) {
     const settings = resolveSettings(cwd);