dev-loops 0.7.2 → 0.8.0

package/scripts/loop/copilot-pr-handoff.mjs

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 import { buildParseError, formatCliError, isCopilotLogin, isDirectCliRun, normalizeTimestamp, parseJsonText } from "../_core-helpers.mjs";
-import { parsePrNumber, requireTokenValue, runChild } from "../_cli-primitives.mjs";
+import { parsePrNumber, requireTokenValue, runChild as defaultRunChild } from "../_cli-primitives.mjs";
 import { detectPostConvergenceSignificantChange } from "./_post-convergence-change.mjs";
 import { detectRepoSlug, parseRepoSlug } from "@dev-loops/core/github/repo-slug";
 import { resolveRunId } from "@dev-loops/core/loop/run-context";
@@ -227,7 +227,7 @@ export function parseHandoffCliArgs(argv, { cwd = process.cwd() } = {}) {
  * loop should pause for operator review.
  * Returns { paused: true, humanComments: [...] } when human comments need attention.
  */
-export async function detectRecentHumanComments({ repo, pr, claimedAtMs }, { env = process.env, ghCommand = "gh" } = {}) {
+export async function detectRecentHumanComments({ repo, pr, claimedAtMs }, { env = process.env, ghCommand = "gh", runChild = defaultRunChild } = {}) {
   try {
     const result = await runChild(
       ghCommand,
@@ -312,7 +312,7 @@ export async function detectRecentHumanComments({ repo, pr, claimedAtMs }, { env
 // (#1103, #1126): the current head, the Copilot reviews (to find the last
 // reviewed head), and the PR's changed files. Fetched only when the interpreter
 // already resolved ROUND_CAP_CLEAN_FALLBACK, so this extra call is off the hot path.
-async function fetchReopenCycleFacts({ repo, pr }, { env = process.env, ghCommand = "gh" } = {}) {
+async function fetchReopenCycleFacts({ repo, pr }, { env = process.env, ghCommand = "gh", runChild = defaultRunChild } = {}) {
   const result = await runChild(
     ghCommand,
     ["pr", "view", String(pr), "--repo", repo, "--json", "headRefOid,reviews,files"],
@@ -328,12 +328,16 @@ async function fetchReopenCycleFacts({ repo, pr }, { env = process.env, ghComman
   }
 }
 
-export async function runHandoff(options, { env = process.env, ghCommand = "gh" } = {}) {
+export async function runHandoff(options, { env = process.env, ghCommand = "gh", runChild = defaultRunChild, repoRoot } = {}) {
+  // Single resolved repo root for config + runner-coordination reads/writes.
+  // Defaults to the checkout's git toplevel (production); an injected repoRoot
+  // keeps the whole cascade hermetic when driven in-process.
+  const resolvedRepoRoot = repoRoot ?? resolveRepoRoot(process.cwd());
   const runnerOwnership = await ensureAsyncRunnerOwnership({
     repo: options.repo,
     pr: options.pr,
     env,
-    cwd: resolveRepoRoot(process.cwd()),
+    cwd: resolvedRepoRoot,
     claimIfMissing: true,
   });
   if (!runnerOwnership.ok) {
@@ -363,9 +367,9 @@ export async function runHandoff(options, { env = process.env, ghCommand = "gh"
   }
   let snapshot = await autoDetectSnapshot(
     { repo: options.repo, pr: options.pr },
-    { env, ghCommand },
+    { env, ghCommand, runChild },
   );
-  const config = await loadDevLoopConfig({ repoRoot: resolveRepoRoot(process.cwd()) });
+  const config = await loadDevLoopConfig({ repoRoot: resolvedRepoRoot });
   if (config.errors?.length > 0) {
     console.error("[copilot-pr-handoff] config warnings:", JSON.stringify(config.errors));
   }
@@ -389,7 +393,7 @@ export async function runHandoff(options, { env = process.env, ghCommand = "gh"
   if (resolveRunId(env)) {
     humanCommentCheck = await detectRecentHumanComments(
       { repo: options.repo, pr: options.pr, claimedAtMs: runnerOwnership?.activeRun?.claimedAt ? new Date(runnerOwnership.activeRun.claimedAt).getTime() : undefined },
-      { env, ghCommand },
+      { env, ghCommand, runChild },
     );
   }
   const TERMINAL_STATES = new Set([STATE.NO_PR, STATE.DONE, STATE.BLOCKED_NEEDS_USER_DECISION]);
@@ -399,7 +403,7 @@ export async function runHandoff(options, { env = process.env, ghCommand = "gh"
       repo: options.repo,
       pr: options.pr,
       env,
-      cwd: resolveRepoRoot(process.cwd()),
+      cwd: resolvedRepoRoot,
     });
     return {
       ok: true,
@@ -467,7 +471,7 @@ export async function runHandoff(options, { env = process.env, ghCommand = "gh"
       interpretation.state === STATE.READY_TO_REREQUEST_REVIEW)
   ) {
     try {
-      const internalCheck = await detectPrInternalOnly(options, { env, ghCommand });
+      const internalCheck = await detectPrInternalOnly(options, { env, ghCommand, runChild });
       if (internalCheck.ok && internalCheck.internalOnly) {
         internalOnlySkipCopilot = true;
         interpretation = {
@@ -526,7 +530,7 @@ export async function runHandoff(options, { env = process.env, ghCommand = "gh"
   if (!internalOnlySkipCopilot
       && options.watchStatus === undefined
       && interpretation.state === STATE.ROUND_CAP_CLEAN_FALLBACK) {
-    const reopenFacts = await fetchReopenCycleFacts(options, { env, ghCommand });
+    const reopenFacts = await fetchReopenCycleFacts(options, { env, ghCommand, runChild });
     const significant = await detectPostConvergenceSignificantChange(
       {
         repo: options.repo,
@@ -537,7 +541,7 @@ export async function runHandoff(options, { env = process.env, ghCommand = "gh"
         roundCapReached: true,
         regularCopilotRounds: (snapshot.copilotReviewRoundCount ?? 0) > 0,
       },
-      { env, ghCommand },
+      { env, ghCommand, runChild },
     );
     if (significant) {
       reopenedCapCycle = true;
@@ -573,7 +577,7 @@ export async function runHandoff(options, { env = process.env, ghCommand = "gh"
         // backstop must never permit rounds the interpreter already forbids.
         lightweight: options.lightweight,
       },
-      { env, ghCommand },
+      { env, ghCommand, runChild },
     );
     reviewRequestStatus = requestResult.status;
     snapshot = applyConfirmedReviewRequest(snapshot, reviewRequestStatus);
@@ -659,7 +663,7 @@ export async function runHandoff(options, { env = process.env, ghCommand = "gh"
       repo: options.repo,
       pr: options.pr,
       env,
-      cwd: resolveRepoRoot(process.cwd()),
+      cwd: resolvedRepoRoot,
     });
     if (runnerRelease.status !== "skipped_no_async_run_id") {
       result.runnerRelease = runnerRelease;

package/scripts/loop/detect-copilot-loop-state.mjs

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import { readFile } from "node:fs/promises";
 import { parseArgs } from "node:util";
-import { parsePrNumber, requireTokenValue, runChild } from "../_cli-primitives.mjs";
+import { parsePrNumber, requireTokenValue, runChild as defaultRunChild } from "../_cli-primitives.mjs";
 import {
   buildParseError,
   formatCliError,
@@ -140,7 +140,7 @@ export function parseDetectCliArgs(argv) {
   }
   return options;
 }
-async function fetchPrView({ repo, pr }, { env, ghCommand }) {
+async function fetchPrView({ repo, pr }, { env, ghCommand, runChild = defaultRunChild }) {
   const result = await runChild(
     ghCommand,
     ["pr", "view", String(pr), "--repo", repo, "--json", "headRefOid,isDraft,state,number,reviews,statusCheckRollup"],
@@ -161,7 +161,7 @@ async function fetchPrView({ repo, pr }, { env, ghCommand }) {
   }
   return payload;
 }
-async function fetchCopilotRequested({ repo, pr }, { env, ghCommand }) {
+async function fetchCopilotRequested({ repo, pr }, { env, ghCommand, runChild = defaultRunChild }) {
   const result = await runChild(
     ghCommand,
     ["api", `repos/${repo}/pulls/${pr}/requested_reviewers`],
@@ -180,7 +180,7 @@ async function fetchCopilotRequested({ repo, pr }, { env, ghCommand }) {
   const users = Array.isArray(payload?.users) ? payload.users : [];
   return users.some((user) => isCopilotLogin(user?.login));
 }
-async function fetchLatestCopilotReviewRequestAt({ repo, pr }, { env, ghCommand }) {
+async function fetchLatestCopilotReviewRequestAt({ repo, pr }, { env, ghCommand, runChild = defaultRunChild }) {
   const result = await runChild(
     ghCommand,
     ["api", `repos/${repo}/issues/${pr}/timeline`, "--paginate", "--jq",
@@ -212,7 +212,7 @@ function extractPrVisibleCheckNames(statusCheckRollup) {
     .filter((name) => typeof name === "string" && name.length > 0);
 }
 
-async function fetchCurrentHeadCiEvidence({ repo, headSha, prVisibleCheckNames }, { env, ghCommand }) {
+async function fetchCurrentHeadCiEvidence({ repo, headSha, prVisibleCheckNames }, { env, ghCommand, runChild = defaultRunChild }) {
   const [checkRunsResult, statusesResult] = await Promise.all([
     runChild(
       ghCommand,
@@ -328,8 +328,8 @@ function hasSubmittedCopilotReviewOffCurrentHead(reviewSummary, currentHeadSha)
 }
 
 
-export async function autoDetectSnapshot({ repo, pr, reviewRequestStatusOverride, localValidationHeadSha, draftGateResetAtMs }, { env = process.env, ghCommand = "gh" } = {}) {
-  const prData = await fetchPrView({ repo, pr }, { env, ghCommand });
+export async function autoDetectSnapshot({ repo, pr, reviewRequestStatusOverride, localValidationHeadSha, draftGateResetAtMs }, { env = process.env, ghCommand = "gh", runChild = defaultRunChild } = {}) {
+  const prData = await fetchPrView({ repo, pr }, { env, ghCommand, runChild });
   if (prData === null) {
     return normalizeSnapshot({ prExists: false });
   }
@@ -355,13 +355,13 @@ export async function autoDetectSnapshot({ repo, pr, reviewRequestStatusOverride
   } else if (reviewSummary.hasPendingReviewOnCurrentHead) {
     copilotReviewRequestStatus = "requested";
   } else {
-    const copilotRequested = await fetchCopilotRequested({ repo, pr }, { env, ghCommand });
+    const copilotRequested = await fetchCopilotRequested({ repo, pr }, { env, ghCommand, runChild });
     if (!copilotRequested) {
       copilotReviewRequestStatus = "none";
     } else if (!reviewSummary.hasSubmittedReviewOnCurrentHead) {
       copilotReviewRequestStatus = "requested";
     } else {
-      const latestRequestAt = await fetchLatestCopilotReviewRequestAt({ repo, pr }, { env, ghCommand });
+      const latestRequestAt = await fetchLatestCopilotReviewRequestAt({ repo, pr }, { env, ghCommand, runChild });
       const latestReviewAt = reviewSummary.latestSubmittedReviewOnCurrentHeadAt;
       if (latestRequestAt !== null && latestReviewAt !== null && latestRequestAt > latestReviewAt) {
         copilotReviewRequestStatus = "requested";
@@ -376,7 +376,7 @@ export async function autoDetectSnapshot({ repo, pr, reviewRequestStatusOverride
   let actionableThreadCount = 0;
   let lastCopilotRoundMaxSignal = null;
   try {
-    const threadsPayload = await fetchGithubReviewThreadsPayload({ repo, pr }, { env, ghCommand });
+    const threadsPayload = await fetchGithubReviewThreadsPayload({ repo, pr }, { env, ghCommand, runChild });
     const parsed = parseReviewThreads(threadsPayload);
     unresolvedThreadCount = parsed.summary.unresolvedThreads;
     actionableThreadCount = parsed.summary.actionableThreads;
@@ -400,7 +400,7 @@ export async function autoDetectSnapshot({ repo, pr, reviewRequestStatusOverride
   let failureDetails = [];
   let excludedFailureDetails = [];
   if (shouldRefreshCurrentHeadCi) {
-    const refreshed = await fetchCurrentHeadCiEvidence({ repo, headSha: prHeadSha, prVisibleCheckNames }, { env, ghCommand });
+    const refreshed = await fetchCurrentHeadCiEvidence({ repo, headSha: prHeadSha, prVisibleCheckNames }, { env, ghCommand, runChild });
     currentHeadCiStatus = refreshed?.status ?? "none";
     failureDetails = refreshed?.failureDetails ?? [];
     excludedFailureDetails = refreshed?.excludedFailureDetails ?? [];

package/scripts/loop/detect-internal-only-pr.mjs

@@ -3,7 +3,7 @@ import { statSync, readFileSync } from "node:fs";
 import path from "node:path";
 import { parse as parseYaml } from "yaml";
 import { buildParseError, formatCliError, isDirectCliRun } from "../_core-helpers.mjs";
-import { parsePrNumber, requireTokenValue, runChild } from "../_cli-primitives.mjs";
+import { parsePrNumber, requireTokenValue, runChild as defaultRunChild } from "../_cli-primitives.mjs";
 import { parseRepoSlug } from "@dev-loops/core/github/repo-slug";
 import { parseArgs } from "node:util";
 import { JQ_OUTPUT_PARSE_OPTIONS, JQ_OUTPUT_USAGE, emitResult, matchJqOutputToken } from "../lib/jq-output.mjs";
@@ -184,7 +184,7 @@ export function parseCliArgs(argv) {
   return options;
 }
 
-async function fetchPrFiles({ repo, pr }, { env = process.env, ghCommand = "gh" } = {}) {
+async function fetchPrFiles({ repo, pr }, { env = process.env, ghCommand = "gh", runChild = defaultRunChild } = {}) {
   const result = await runChild(
     ghCommand,
     ["pr", "view", String(pr), "--repo", repo, "--json", "files", "--jq", ".files[].path"],
@@ -198,7 +198,7 @@ async function fetchPrFiles({ repo, pr }, { env = process.env, ghCommand = "gh"
   return paths;
 }
 
-async function fetchPrLabels({ repo, pr }, { env = process.env, ghCommand = "gh" } = {}) {
+async function fetchPrLabels({ repo, pr }, { env = process.env, ghCommand = "gh", runChild = defaultRunChild } = {}) {
   const result = await runChild(
     ghCommand,
     ["pr", "view", String(pr), "--repo", repo, "--json", "labels", "--jq", ".labels[].name"],
@@ -219,10 +219,10 @@ async function fetchPrLabels({ repo, pr }, { env = process.env, ghCommand = "gh"
  * - If ANY changed file doesn't match any pattern → internalOnly=false
  * - No blacklist needed — a non-matching file is consumer-facing by definition.
  */
-export async function detectInternalOnly(options, { env = process.env, ghCommand = "gh" } = {}) {
+export async function detectInternalOnly(options, { env = process.env, ghCommand = "gh", runChild = defaultRunChild } = {}) {
   const patterns = loadInternalPathPatterns(options.config);
   const matchers = buildPatternMatchers(patterns);
-  const files = await fetchPrFiles(options, { env, ghCommand });
+  const files = await fetchPrFiles(options, { env, ghCommand, runChild });
 
   if (files.length === 0) {
     return {
@@ -250,7 +250,7 @@ export async function detectInternalOnly(options, { env = process.env, ghCommand
 
   // Check for explicit internal_only label if requested (confirmation only)
   if (options.labelCheck) {
-    const labels = await fetchPrLabels(options, { env, ghCommand });
+    const labels = await fetchPrLabels(options, { env, ghCommand, runChild });
     if (labels.includes("internal_only")) {
       // Label confirms — path check already passed
     }

package/scripts/loop/detect-pr-gate-coordination-state.mjs

@@ -10,12 +10,13 @@ import {
   resolveDraftGateRoundResetMs,
   summarizeCopilotReviews,
 } from "../_core-helpers.mjs";
-import { parsePrNumber, requireTokenValue, runChild } from "../_cli-primitives.mjs";
+import { parsePrNumber, requireTokenValue, runChild as defaultRunChild } from "../_cli-primitives.mjs";
 import { loadDevLoopConfig, resolveEffectiveCopilotRoundCap, resolveGateConfig, resolveRefinement, resolveRefinementConfig, resolveWorkflowConfig } from "@dev-loops/core/config";
 import { parseRepoSlug } from "@dev-loops/core/github/repo-slug";
 import { buildSnapshotFromPrFacts, interpretLoopState, isCopilotRoundCapReached, summarizeLoopInterpretation } from "@dev-loops/core/loop/copilot-loop-state";
-import { evaluatePrGateCoordination, PR_CHECKPOINT, PR_CHECKPOINT_ACTION } from "@dev-loops/core/loop/pr-gate-coordination";
+import { evaluatePrGateCoordination, PR_CHECKPOINT, PR_CHECKPOINT_ACTION, REFINEMENT_ARTIFACT_SPEC_SOURCE } from "@dev-loops/core/loop/pr-gate-coordination";
 import { shouldGuardCopilotReviewRequest } from "@dev-loops/core/loop/pr-gate-coordination";
+import { PLAN_FILE_PROMOTION_DOC_PATH_PATTERN } from "@dev-loops/core/loop/plan-file-promote-contract";
 import { UI_E2E_CHECK_NAMES } from "@dev-loops/core/loop/ui-e2e-scoping";
 import { fetchGithubReviewThreadsPayload } from "../github/capture-review-threads.mjs";
 import { detectPostConvergenceSignificantChange } from "./_post-convergence-change.mjs";
@@ -67,11 +68,19 @@ Output (stdout, JSON):
       "headSha": null,
       "verdict": null
     },
+    "refinementArtifact": {
+      "status": "present",
+      "specSource": "linked_issue",
+      "reason": "...",
+      "finding": null
+    },
     "allowedNextActions": ["resolve_merge_conflicts"],
     "forbiddenActions": ["run_pre_approval_gate", "declare_merge_ready"],
     "nextAction": "resolve_merge_conflicts",
     "reason": "..."
   }
+  (refinementArtifact.planDocPath is present only when specSource is
+  "plan_file"; the key is omitted entirely for "linked_issue" and "pr_body")
 Error output (stderr, JSON):
   { "ok": false, "error": "...", "usage": "..." }
   { "ok": false, "error": "..." }
@@ -167,7 +176,7 @@ export function parseGitStatusConflictFiles(text) {
   }
   return conflictFiles;
 }
-async function fetchRequestedReviewers({ repo, pr }, { env = process.env, ghCommand = "gh" } = {}) {
+async function fetchRequestedReviewers({ repo, pr }, { env = process.env, ghCommand = "gh", runChild = defaultRunChild } = {}) {
   const result = await runChild(
     ghCommand,
     ["api", `repos/${repo}/pulls/${pr}/requested_reviewers`],
@@ -179,7 +188,7 @@ async function fetchRequestedReviewers({ repo, pr }, { env = process.env, ghComm
   }
   return parseRequestedReviewersPayload(result.stdout);
 }
-async function fetchPrFacts({ repo, pr }, { env = process.env, ghCommand = "gh" } = {}) {
+async function fetchPrFacts({ repo, pr }, { env = process.env, ghCommand = "gh", runChild = defaultRunChild } = {}) {
   const result = await runChild(
     ghCommand,
     ["pr", "view", String(pr), "--repo", repo, "--json", "number,state,isDraft,headRefOid,mergeable,mergeStateStatus,body,title,closingIssuesReferences,reviews,statusCheckRollup,files"],
@@ -202,18 +211,19 @@ export async function fetchPrFactsWithSettledMergeable(
   {
     env = process.env,
     ghCommand = "gh",
+    runChild = defaultRunChild,
     maxPolls = 3,
     pollDelayMs = 1500,
     sleep = (ms) => new Promise((r) => setTimeout(r, ms)),
     fetch = fetchPrFacts,
   } = {},
 ) {
-  let prData = await fetch(options, { env, ghCommand });
+  let prData = await fetch(options, { env, ghCommand, runChild });
   let polls = 0;
   while (String(prData?.mergeable || "").toUpperCase() === "UNKNOWN" && polls < maxPolls) {
     polls += 1;
     await sleep(pollDelayMs);
-    prData = await fetch(options, { env, ghCommand });
+    prData = await fetch(options, { env, ghCommand, runChild });
   }
   return prData;
 }
@@ -271,7 +281,7 @@ export function resolveLinkedIssuesFromPr(prData) {
   return dedupe(matches.map((m) => Number((/(\d+)/.exec(m) || [])[1])));
 }
 
-async function fetchIssueBody({ repo, issue }, { env = process.env, ghCommand = "gh" } = {}) {
+async function fetchIssueBody({ repo, issue }, { env = process.env, ghCommand = "gh", runChild = defaultRunChild } = {}) {
   const result = await runChild(
     ghCommand,
     ["issue", "view", String(issue), "--repo", repo, "--json", "body"],
@@ -287,18 +297,107 @@ async function fetchIssueBody({ repo, issue }, { env = process.env, ghCommand =
     return null;
   }
 }
-export async function loadRefinementArtifact({ repo, prData, prDraft, prClosed, prMerged }, { env = process.env, ghCommand = "gh" } = {}) {
-  const linkedIssues = resolveLinkedIssuesFromPr(prData);
-  if (linkedIssues.length === 0) {
-    if (prDraft) {
+// Plan-file promotion PRs (P4, `buildPromotionPrBody`) carry no linked issue by
+// design; the PR body instead names the committed plan doc as the spec-of-record
+// verbatim (marker owned by plan-file-promote-contract.mjs). Matching that
+// literal marker is how the refinement check tells a promoted plan-file PR
+// apart from an ordinary issue-less body.
+
+// Resolve the refinement artifact for a draft PR with zero linked issues,
+// directly from its own body. The sanctioned three-origin model
+// (artifact-authority-contract.md) backs a draft PR with a linked issue, a
+// promoted plan file, or the PR body itself as the spec-of-record; only the
+// first fetches an issue body, so this never needs a network call.
+// `specSource` here (linked_issue|pr_body|plan_file) is a distinct enum from
+// handoff-envelope.mjs's CANONICAL_SPEC_SOURCE (phase_doc|pr_body): same field
+// name, different object, different value space — never conflate the two.
+async function resolveNoIssueRefinementArtifact(body) {
+  const { detectIssueRefinementArtifact, validatePrBodySpec } = await import("@dev-loops/core/loop/issue-refinement-artifact");
+  const planDocMatch = PLAN_FILE_PROMOTION_DOC_PATH_PATTERN.exec(body);
+  if (planDocMatch) {
+    const planDocPath = planDocMatch[1].trim();
+    // The marker sentence alone is spoofable (any body can paste it): require the
+    // body to still carry real AC/DoD checklist content, the same invariant
+    // `buildPromotionPrBody` actually embeds, before trusting the plan-file claim.
+    // Deliberately narrower than `artifact.hasACs`: that flag also turns true on a
+    // bare linked-refinement-doc mention (no checklist items at all), which is the
+    // right OR for a linked ISSUE body but not for a plan-file promotion PR body —
+    // a plan-file claim must be backed by actual AC/DoD checklist items, not just
+    // another doc mention next to the marker.
+    // Plan-file promotion is issue-less by design (`buildPromotionPrBody`
+    // neutralizes closing keywords): any closing reference the body carries —
+    // including the cross-repo `owner/repo#N` form validatePrBodySpec also
+    // accepts — means the body would auto-close an issue it doesn't actually
+    // back. Reuse validatePrBodySpec's closing-reference extraction
+    // (issueLess mode's `closesIssues`) instead of a second regex.
+    const closesIssues = validatePrBodySpec({ body, issueLess: true }).closesIssues;
+    if (closesIssues.length > 0) {
       return {
         status: "missing",
         linkedIssue: null,
         linkedIssues: [],
-        reason: "Draft PR has no deterministically resolvable linked issue (no closingIssuesReferences and no Closes/Fixes/Resolves #n reference in body); draft gate cannot verify a refinement artifact.",
+        specSource: REFINEMENT_ARTIFACT_SPEC_SOURCE.PLAN_FILE,
+        planDocPath,
+        reason: `PR body names the promoted plan doc \`${planDocPath}\` as the spec-of-record but also carries a GitHub closing reference (${closesIssues.map((n) => `#${n}`).join(", ")}); plan-file promotion is issue-less by design and must not carry a reference that would auto-close an issue it doesn't back.`,
         finding: "missing_refinement_artifact",
       };
     }
+    const artifact = detectIssueRefinementArtifact({ body });
+    if (artifact.acItems.length > 0 || artifact.dodItems.length > 0) {
+      return {
+        status: "present",
+        linkedIssue: null,
+        linkedIssues: [],
+        specSource: REFINEMENT_ARTIFACT_SPEC_SOURCE.PLAN_FILE,
+        planDocPath,
+        acItems: artifact.acItems,
+        dodItems: artifact.dodItems,
+        sections: artifact.sections,
+        reason: `Refinement artifact present via the promoted plan doc \`${planDocPath}\` the PR body carries as the spec-of-record (plan-file promotion; no linked issue required).`,
+        finding: null,
+      };
+    }
+    return {
+      status: "missing",
+      linkedIssue: null,
+      linkedIssues: [],
+      specSource: REFINEMENT_ARTIFACT_SPEC_SOURCE.PLAN_FILE,
+      planDocPath,
+      reason: `PR body names the promoted plan doc \`${planDocPath}\` as the spec-of-record but carries no Acceptance criteria / DoD checklist content (${artifact.reason}); a bare marker sentence cannot satisfy the refinement check.`,
+      finding: "missing_refinement_artifact",
+    };
+  }
+  const specResult = validatePrBodySpec({ body, issueLess: true });
+  if (specResult.ok) {
+    return {
+      status: "present",
+      linkedIssue: null,
+      linkedIssues: [],
+      specSource: REFINEMENT_ARTIFACT_SPEC_SOURCE.PR_BODY,
+      acItems: specResult.acItems,
+      dodItems: specResult.dodItems,
+      sections: specResult.sections,
+      reason: "Refinement artifact present via the PR body itself (issue-less lightweight PR-body-as-spec; validate-pr-body-spec --no-issue clean).",
+      finding: null,
+    };
+  }
+  return {
+    status: "missing",
+    linkedIssue: null,
+    linkedIssues: [],
+    specSource: REFINEMENT_ARTIFACT_SPEC_SOURCE.PR_BODY,
+    reason: `PR body fails the issue-less lightweight spec-of-record validation (validate-pr-body-spec --no-issue: ${specResult.errors.map((e) => e.code).join(", ")}).`,
+    finding: "missing_refinement_artifact",
+  };
+}
+
+export async function loadRefinementArtifact({ repo, prData, prDraft, prClosed, prMerged }, { env = process.env, ghCommand = "gh", runChild = defaultRunChild } = {}) {
+  const linkedIssues = resolveLinkedIssuesFromPr(prData);
+  if (linkedIssues.length === 0) {
+    if (prDraft) {
+      const body = typeof prData?.body === "string" ? prData.body : "";
+      return resolveNoIssueRefinementArtifact(body);
+    }
     return {
       status: "unknown",
       linkedIssue: null,
@@ -320,7 +419,7 @@ export async function loadRefinementArtifact({ repo, prData, prDraft, prClosed,
   // is refined if AT LEAST ONE linked issue carries a refinement artifact.
   const evaluated = [];
   for (const issue of linkedIssues) {
-    const body = await fetchIssueBody({ repo, issue }, { env, ghCommand });
+    const body = await fetchIssueBody({ repo, issue }, { env, ghCommand, runChild });
     if (body === null) {
       evaluated.push({ issue, artifact: null });
       continue;
@@ -339,6 +438,7 @@ export async function loadRefinementArtifact({ repo, prData, prDraft, prClosed,
       status: "present",
       linkedIssue: firstPresent.issue,
       linkedIssues,
+      specSource: REFINEMENT_ARTIFACT_SPEC_SOURCE.LINKED_ISSUE,
       refinedIssues,
       source: a.source,
       acItems: a.acItems,
@@ -366,6 +466,7 @@ export async function loadRefinementArtifact({ repo, prData, prDraft, prClosed,
         status: "missing",
         linkedIssue: firstEvaluated.issue,
         linkedIssues,
+        specSource: REFINEMENT_ARTIFACT_SPEC_SOURCE.LINKED_ISSUE,
         refinedIssues,
         reason: `Failed to fetch body for linked issue(s) ${scopeLabel}; draft gate cannot verify a refinement artifact, treating as missing.`,
         finding: "missing_refinement_artifact",
@@ -389,6 +490,7 @@ export async function loadRefinementArtifact({ repo, prData, prDraft, prClosed,
     status: "missing",
     linkedIssue: firstFetched.issue,
     linkedIssues,
+    specSource: REFINEMENT_ARTIFACT_SPEC_SOURCE.LINKED_ISSUE,
     refinedIssues,
     source: first.source,
     acItems: first.acItems,
@@ -402,7 +504,7 @@ export async function loadRefinementArtifact({ repo, prData, prDraft, prClosed,
     _onlyEnforcedWhenDraft: prDraft === true,
   };
 }
-async function fetchLocalConflictFiles({ env = process.env, gitCommand = "git" } = {}) {
+async function fetchLocalConflictFiles({ env = process.env, gitCommand = "git", runChild = defaultRunChild } = {}) {
   let result;
   try {
     result = await runChild(
@@ -516,7 +618,7 @@ export async function loadPrGateCoordinationContext(options, runtime = {}) {
   };
 }
 
-async function fetchCopilotEverFormallyRequested({ repo, pr }, { env = process.env, ghCommand = "gh" } = {}) {
+async function fetchCopilotEverFormallyRequested({ repo, pr }, { env = process.env, ghCommand = "gh", runChild = defaultRunChild } = {}) {
   const result = await runChild(
     ghCommand,
     ["api", `repos/${repo}/issues/${pr}/timeline`, "--paginate", "--jq",

package/scripts/loop/detect-refinement-grill-state.mjs

@@ -0,0 +1,136 @@
+#!/usr/bin/env node
+import { readFile } from "node:fs/promises";
+import { parseArgs } from "node:util";
+import { requireTokenValue } from "../_cli-primitives.mjs";
+import { formatCliError, isDirectCliRun, parseJsonText } from "../_core-helpers.mjs";
+import {
+  interpretRefinementGrillState,
+  normalizeGrillSnapshot,
+} from "@dev-loops/core/loop/refinement-grill-state";
+import { detectIssueRefinementArtifact } from "@dev-loops/core/loop/issue-refinement-artifact";
+import { JQ_OUTPUT_PARSE_OPTIONS, JQ_OUTPUT_USAGE, emitResult, matchJqOutputToken } from "../lib/jq-output.mjs";
+
+const HELP = `Usage: detect-refinement-grill-state.mjs [--input <path> | --body-file <path> [--surface issue|pr|plan]]
+Detect refinement/grill sub-loop state.
+Modes (choose exactly one):
+  --input <path>                  Interpret a JSON grill snapshot from file
+  --body-file <path>              Seed the deterministic already-refined / zero-iteration
+                                  snapshot from a markdown body on disk
+Options (body-file mode only):
+  --surface issue|pr|plan         Surface the body belongs to (default: issue)
+
+${JQ_OUTPUT_USAGE}
+
+Exit codes:
+  0   Success
+  1   Error
+  2   Invalid --jq filter
+`;
+
+const VALID_SURFACES = new Set(["issue", "pr", "plan"]);
+
+export function parseDetectGrillCliArgs(argv) {
+  const { tokens } = parseArgs({
+    args: [...argv],
+    options: {
+      help: { type: "boolean", short: "h" },
+      input: { type: "string" },
+      "body-file": { type: "string" },
+      surface: { type: "string" },
+      ...JQ_OUTPUT_PARSE_OPTIONS,
+    },
+    allowPositionals: true,
+    strict: false,
+    tokens: true,
+  });
+  const options = {
+    inputPath: undefined,
+    bodyFilePath: undefined,
+    surface: undefined,
+    help: false,
+  };
+  for (const token of tokens) {
+    if (token.kind === "positional") {
+      throw new Error(`Unknown argument: ${token.value}`);
+    }
+    if (token.kind !== "option") {
+      continue;
+    }
+    if (token.name === "help") {
+      options.help = true;
+      return options;
+    }
+    if (token.name === "input") {
+      options.inputPath = requireTokenValue(token);
+      continue;
+    }
+    if (token.name === "body-file") {
+      options.bodyFilePath = requireTokenValue(token);
+      continue;
+    }
+    if (token.name === "surface") {
+      const surface = requireTokenValue(token).trim();
+      if (!VALID_SURFACES.has(surface)) {
+        throw new Error("--surface must be one of: issue, pr, plan");
+      }
+      options.surface = surface;
+      continue;
+    }
+    if (matchJqOutputToken(token, options, (t) => requireTokenValue(t))) continue;
+    throw new Error(`Unknown argument: ${token.rawName}`);
+  }
+  const hasInput = options.inputPath !== undefined;
+  const hasBodyFile = options.bodyFilePath !== undefined;
+  if (hasInput === hasBodyFile) {
+    throw new Error("Provide exactly one input source: --input <path> or --body-file <path>");
+  }
+  if (hasInput && options.surface !== undefined) {
+    throw new Error("--surface applies only to --body-file mode");
+  }
+  return options;
+}
+
+export async function runCli(
+  argv = process.argv.slice(2),
+  { stdout = process.stdout, stderr = process.stderr } = {},
+) {
+  const options = parseDetectGrillCliArgs(argv);
+  if (options.help) { stdout.write(HELP); return; }
+
+  let snapshot;
+  if (options.inputPath) {
+    const text = await readFile(options.inputPath, "utf8");
+    snapshot = normalizeGrillSnapshot(parseJsonText(text));
+  } else {
+    const body = await readFile(options.bodyFilePath, "utf8");
+    const surface = options.surface ?? "issue";
+    // Deterministic seed for the already-refined / zero-iteration path only: the full
+    // semantic gap detection (scope/actor/decision) is the agent-layer bounded input consumed
+    // at await_answers. This body-file mode computes ONLY the deterministic AC-presence signal
+    // via the single is-it-refined source of truth, detectIssueRefinementArtifact.
+    const artifact = detectIssueRefinementArtifact({ body });
+    snapshot = normalizeGrillSnapshot({
+      loaded: true,
+      detectRan: true,
+      surface,
+      openGapCount: artifact.finding ? 1 : 0,
+      unresolvedGapCount: 0,
+    });
+  }
+
+  const interpretation = interpretRefinementGrillState(snapshot);
+  process.exitCode = emitResult(
+    {
+      ok: true,
+      snapshot,
+      state: interpretation.state,
+      allowedTransitions: interpretation.allowedTransitions,
+      nextAction: interpretation.nextAction,
+    },
+    { jq: options.jq, silent: options.silent, stdout, stderr },
+  );
+}
+
+if (isDirectCliRun(import.meta.url)) {
+  runCli().catch((error) => { process.stderr.write(`${formatCliError(error)}\n`); process.exitCode = 1; });
+}