dev-loops 0.7.1 → 0.8.0

package/scripts/github/upsert-checkpoint-verdict.mjs

@@ -1,10 +1,11 @@
 #!/usr/bin/env node
 import { readFile } from "node:fs/promises";
-import { buildParseError, formatCliError, isDirectCliRun, parseJsonText } from "../_core-helpers.mjs";
-import { loadDevLoopConfig, resolveGateConfig, resolveRefinementConfig } from "@dev-loops/core/config";
+import { buildParseError, formatCliError, isDirectCliRun, parseJsonText, sanitizeCopilotSummonTokens } from "../_core-helpers.mjs";
+import { loadDevLoopConfig, resolveEffectiveCopilotRoundCap, resolveGateAngleContract, resolveGateConfig, resolveRefinementConfig, resolveRejectForeignAngles } from "@dev-loops/core/config";
+import { checkFanoutAngleCoverage } from "@dev-loops/core/loop/gate-fanin";
 import { parseArgs } from "node:util";
 import { JQ_OUTPUT_PARSE_OPTIONS, JQ_OUTPUT_USAGE, emitResult, matchJqOutputToken } from "../lib/jq-output.mjs";
-import { parsePrNumber, requireTokenValue, runChild } from "../_cli-primitives.mjs";
+import { parsePrNumber, requireTokenValue, runChild as defaultRunChild } from "../_cli-primitives.mjs";
 import { truncateText } from "@dev-loops/core/bash-exit-one";
 import { parseRepoSlug } from "@dev-loops/core/github/repo-slug";
 import { loadPrGateCoordinationContext } from "../loop/detect-pr-gate-coordination-state.mjs";
@@ -72,6 +73,11 @@ Optional:
   --gate <draft_gate|pre_approval_gate>     Auto-resolved from coordination state
                                             when omitted. Explicit gate is validated
                                             against allowed coordination actions.
+  --lightweight                             This PR is light-dispatched (#1210):
+                                            resolve the Copilot round cap as
+                                            min(lightMode.maxCopilotRounds ?? 1,
+                                            refinement.maxCopilotRounds) instead of
+                                            refinement.maxCopilotRounds alone.
   --findings-severity-counts <json>         JSON object mapping severity to count
                                              (e.g. '{"must-fix":0,"worth-fixing-now":0}').
                                              Required for --verdict clean when
@@ -261,6 +267,7 @@ export function parseUpsertCheckpointVerdictCliArgs(argv) {
       "findings-severity-counts": { type: "string" },
       "execution-mode": { type: "string" },
       "inline-reason": { type: "string" },
+      lightweight: { type: "boolean" },
       ...JQ_OUTPUT_PARSE_OPTIONS,
     },
     allowPositionals: true,
@@ -281,6 +288,7 @@ export function parseUpsertCheckpointVerdictCliArgs(argv) {
     findingsSeverityCounts: undefined,
     executionMode: undefined,
     inlineReason: undefined,
+    lightweight: false,
     jq: undefined,
     silent: false,
   };
@@ -306,6 +314,10 @@ export function parseUpsertCheckpointVerdictCliArgs(argv) {
       options.pr = parsePrNumber(requireTokenValue(token, parseError), parseError);
       continue;
     }
+    if (token.name === "lightweight") {
+      options.lightweight = true;
+      continue;
+    }
     if (token.name === "gate") {
       const gate = normalizeGateName(requireTokenValue(token, parseError));
       if (!gate) {
@@ -742,7 +754,11 @@ export function renderGateReviewCommentBody({ gate, headSha, verdict, findingsSu
     "",
     `**Next action:** ${nextAction}`,
   );
-  return lines.join("\n");
+  // Neutralize any bare @copilot/`/copilot`* tokens in the rendered body (gate
+  // evidence legitimately quotes the anti-summon rule, e.g. from a findings
+  // excerpt) so posting this comment can never arm request-copilot-review.mjs's
+  // anti-summon guard on a later request.
+  return sanitizeCopilotSummonTokens(lines.join("\n"));
 }
 function resolveRequestedHeadSha(requestedHeadSha, currentHeadSha) {
   if (requestedHeadSha === currentHeadSha) {
@@ -823,7 +839,7 @@ function detectStaleGateCommentWarning({ strict, headSha, gate }) {
   }
   return `A gate comment for \`${gate}\` already exists on a different head SHA \`${strict.headSha}\` (comment ${strict.commentId}). The old comment is stale for the current head.`;
 }
-async function runGhJson(args, { env, ghCommand }) {
+async function runGhJson(args, { env, ghCommand, runChild = defaultRunChild }) {
   const result = await runChild(ghCommand, args, env);
   if (result.code !== 0) {
     const detail = result.stderr.trim() || `exit code ${result.code}`;
@@ -841,18 +857,18 @@ function parseCommentMutationResponse(payload) {
   }
   return { commentId, commentUrl };
 }
-async function createComment({ repo, pr, body }, { env, ghCommand }) {
-  const payload = await runGhJson(["api", "repos/" + repo + "/issues/" + pr + "/comments", "-f", `body=${body}`], { env, ghCommand });
+async function createComment({ repo, pr, body }, { env, ghCommand, runChild = defaultRunChild }) {
+  const payload = await runGhJson(["api", "repos/" + repo + "/issues/" + pr + "/comments", "-f", `body=${body}`], { env, ghCommand, runChild });
   return parseCommentMutationResponse(payload);
 }
-async function updateComment({ repo, commentId, body }, { env, ghCommand }) {
-  const payload = await runGhJson(["api", "-X", "PATCH", `repos/${repo}/issues/comments/${commentId}`, "-f", `body=${body}`], { env, ghCommand });
+async function updateComment({ repo, commentId, body }, { env, ghCommand, runChild = defaultRunChild }) {
+  const payload = await runGhJson(["api", "-X", "PATCH", `repos/${repo}/issues/comments/${commentId}`, "-f", `body=${body}`], { env, ghCommand, runChild });
   return parseCommentMutationResponse(payload);
 }
 
-async function verifyComment({ repo, commentId }, { env, ghCommand }) {
+async function verifyComment({ repo, commentId }, { env, ghCommand, runChild = defaultRunChild }) {
   try {
-    const payload = await runGhJson(["api", `repos/${repo}/issues/comments/${commentId}`], { env, ghCommand });
+    const payload = await runGhJson(["api", `repos/${repo}/issues/comments/${commentId}`], { env, ghCommand, runChild });
     return payload?.id != null;
   } catch {
     return false;
@@ -879,13 +895,13 @@ async function verifyComment({ repo, commentId }, { env, ghCommand }) {
 // markPrReady mutations are individually idempotent, so concurrent cooperating
 // runners cause at most a transient draft flicker (not a stuck draft) — only a hard
 // crash mid-transition can leave the PR drafted until a subsequent run.
-async function postDraftGateViaDraftTransition(options, { env, ghCommand, repoRoot }) {
+async function postDraftGateViaDraftTransition(options, { env, ghCommand, repoRoot, runChild = defaultRunChild }) {
   const { convertPrToDraft, markPrReady } = await import("./reconcile-draft-gate.mjs");
   process.stderr.write(
     `[draft_gate] ${options.repo}#${options.pr} is ready but needs clean draft_gate evidence; ` +
     `temporarily converting to draft to post the verdict, then restoring ready.\n`,
   );
-  const conversion = await convertPrToDraft({ repo: options.repo, pr: options.pr }, { env, ghCommand });
+  const conversion = await convertPrToDraft({ repo: options.repo, pr: options.pr }, { env, ghCommand, runChild });
   let result;
   try {
     // The PR is now a draft, so RUN_DRAFT_GATE is the legal action. Re-enter with
@@ -896,12 +912,12 @@ async function postDraftGateViaDraftTransition(options, { env, ghCommand, repoRo
     // with a clear error instead of recursing indefinitely (exit 13). (#1020)
     result = await upsertCheckpointVerdict(
       { ...options, _draftTransitionInProgress: true },
-      { env, ghCommand, repoRoot },
+      { env, ghCommand, repoRoot, runChild },
     );
   } catch (error) {
     if (conversion.alreadyDraft !== true) {
       try {
-        await markPrReady({ repo: options.repo, pr: options.pr }, { env, ghCommand });
+        await markPrReady({ repo: options.repo, pr: options.pr }, { env, ghCommand, runChild });
         process.stderr.write(`[draft_gate] restored ${options.repo}#${options.pr} to ready after a failed verdict post.\n`);
       } catch (restoreError) {
         // Best-effort restore; surface the original error but log the restore failure
@@ -916,7 +932,7 @@ async function postDraftGateViaDraftTransition(options, { env, ghCommand, repoRo
   }
   if (conversion.alreadyDraft !== true) {
     try {
-      await markPrReady({ repo: options.repo, pr: options.pr }, { env, ghCommand });
+      await markPrReady({ repo: options.repo, pr: options.pr }, { env, ghCommand, runChild });
     } catch (restoreError) {
       // The verdict WAS posted successfully; only the ready-restore failed. Make that
       // explicit so the caller does not re-post the gate (the comment already exists)
@@ -933,7 +949,8 @@ async function postDraftGateViaDraftTransition(options, { env, ghCommand, repoRo
   return { ...result, draftTransition: true };
 }
 
-export async function upsertCheckpointVerdict(options, { env = process.env, ghCommand = "gh", repoRoot = process.cwd() } = {}) {
+export async function upsertCheckpointVerdict(options, { env = process.env, ghCommand = "gh", repoRoot = process.cwd(), runChild = defaultRunChild } = {}) {
+  const gh = { env, ghCommand, repoRoot, runChild };
   // Root cause 1: allow resurrected sessions to claim ownership when the previous
   // run's coordination record is stale. Without this, a new run ID is rejected even
   // though the old run is dead, forcing manual file deletion.
@@ -949,19 +966,24 @@ export async function upsertCheckpointVerdict(options, { env = process.env, ghCo
       // loadPrGateCoordinationContext call will surface the real error.
     }
   }
-  const coordinationContext = await loadPrGateCoordinationContext({ repo: options.repo, pr: options.pr }, { env, ghCommand });
+  // Thread the light-dispatch signal (#1210) so the context interpreter and the
+  // maxCopilotRounds resolution below both use the composed lightweight cap —
+  // the two must never disagree at the cap boundary (#1126).
+  const coordinationContext = await loadPrGateCoordinationContext({ repo: options.repo, pr: options.pr, lightweight: options.lightweight === true }, gh);
   const evidence = coordinationContext.gateEvidence;
   const canonicalHeadSha = resolveRequestedHeadSha(options.headSha, evidence.currentHeadSha);
   const { config } = await loadDevLoopConfig({ repoRoot });
   const draftGateConfig = resolveGateConfig(config, "draft");
   const preApprovalGateConfig = resolveGateConfig(config, "preApproval");
-  const maxCopilotRounds = resolveRefinementConfig(config, "maxCopilotRounds");
+  const maxCopilotRounds = options.lightweight === true
+    ? resolveEffectiveCopilotRoundCap(config, { lightweight: true })
+    : resolveRefinementConfig(config, "maxCopilotRounds");
   // Root cause 2: detect internal-only PRs so the Copilot convergence requirement
   // is suppressed. Docs-only / tooling-only PRs should go straight to pre_approval_gate
   // without requiring an external Copilot review cycle.
   let reviewMode = null;
   try {
-    const internalResult = await detectInternalOnly({ repo: options.repo, pr: options.pr }, { env, ghCommand });
+    const internalResult = await detectInternalOnly({ repo: options.repo, pr: options.pr }, gh);
     if (internalResult?.ok && internalResult.internalOnly) {
       reviewMode = "internal_only";
     }
@@ -982,9 +1004,14 @@ export async function upsertCheckpointVerdict(options, { env = process.env, ghCo
     copilotReviewRoundCount: coordinationContext.snapshot?.copilotReviewRoundCount ?? 0,
     maxCopilotRounds,
     sameHeadCleanConverged: coordinationContext.interpretation.sameHeadCleanConverged,
+    // Independent gate-ENTRY re-check (#1190): fed alongside (not derived from)
+    // sameHeadCleanConverged, so an outstanding request on the current head refuses
+    // RUN_PRE_APPROVAL_GATE even if sameHeadCleanConverged were somehow stale/wrong.
+    copilotReviewRequestStatus: coordinationContext.snapshot?.copilotReviewRequestStatus ?? "none",
     draftGateRequireCi: draftGateConfig.requireCi,
     draftGate: coordinationContext.gateEvidence.draftGate,
     draftGateMarker: coordinationContext.gateEvidence.draftGateMarker,
+    refinementArtifact: coordinationContext.refinementArtifact,
     preApprovalGate: coordinationContext.gateEvidence.preApprovalGate,
     preApprovalGateMarker: coordinationContext.gateEvidence.preApprovalGateMarker,
     ...(reviewMode ? { reviewMode } : {}),
@@ -1064,7 +1091,7 @@ export async function upsertCheckpointVerdict(options, { env = process.env, ghCo
     && !coordination.draftGateAlreadySatisfied
     && coordination.allowedNextActions.includes(PR_CHECKPOINT_ACTION.RECONCILE_DRAFT_GATE)
   ) {
-    return await postDraftGateViaDraftTransition(options, { env, ghCommand, repoRoot });
+    return await postDraftGateViaDraftTransition(options, { env, ghCommand, repoRoot, runChild });
   }
   // Fail closed on a lagged draft-state read: we are re-entering FROM
   // postDraftGateViaDraftTransition (which just converted the PR to draft) yet the
@@ -1122,6 +1149,7 @@ export async function upsertCheckpointVerdict(options, { env = process.env, ghCo
   // multi-line per-angle breakdown and the `**Findings summary:**` line carries a
   // single-line digest (so the marker/parse contract still round-trips).
   let structuredFindings = null;
+  let rawFindingsInput = null;
   if (options.findingsJson) {
     let raw;
     try {
@@ -1140,6 +1168,7 @@ export async function upsertCheckpointVerdict(options, { env = process.env, ghCo
     const candidate = Array.isArray(parsed)
       ? parsed
       : (Array.isArray(parsed?.angles) ? parsed.angles : (Array.isArray(parsed?.findings) ? parsed.findings : null));
+    rawFindingsInput = candidate;
     try {
       structuredFindings = normalizeStructuredFindings(candidate);
     } catch (err) {
@@ -1149,6 +1178,48 @@ export async function upsertCheckpointVerdict(options, { env = process.env, ghCo
       throw new Error(`--findings-json "${options.findingsJson}" did not contain any renderable findings (expected a non-empty per-angle array of { angle, findings } entries, or a flat per-finding array of { severity, summary, angle? } entries)`);
     }
   }
+  // Fan-out angle-coverage enforcement (fail closed): a fanout_fanin verdict's
+  // structured per-angle results must cover every configured mandatory angle,
+  // and (default) must not name an angle outside the gate's configured pool.
+  // Only applies when structured per-angle results were actually supplied —
+  // a free-text --findings-summary fanout_fanin verdict carries no per-angle
+  // data to validate.
+  if (structuredFindings && (options.executionMode ?? DEFAULT_EXECUTION_MODE) === "fanout_fanin") {
+    // Angle-less entries would be bucketed under the synthetic `general` label
+    // by normalization and then surface as a CONFUSING foreign-angle error.
+    // Fail first with a dedicated message naming the real problem instead.
+    const angleless = (rawFindingsInput ?? []).filter(
+      (e) => !e || typeof e !== "object" || typeof e.angle !== "string" || e.angle.trim().length === 0,
+    ).length;
+    if (angleless > 0) {
+      throw new Error(
+        `--findings-json for ${options.gate}: ${angleless} entr${angleless === 1 ? "y" : "ies"} lack a non-empty .angle — a fanout_fanin verdict must attribute every per-angle entry/finding to its review angle (use the nested [{ angle, verdict, findings }] shape, or add .angle to each flat finding)`,
+      );
+    }
+    const gateKey = options.gate === "draft_gate" ? "draft" : "preApproval";
+    const { mandatoryAngles, pool } = resolveGateAngleContract(config, gateKey);
+    const { missingMandatory, foreignAngles } = checkFanoutAngleCoverage(structuredFindings, {
+      mandatoryAngles,
+      pool,
+    });
+    if (missingMandatory.length > 0) {
+      throw new Error(
+        `--findings-json for ${options.gate} is missing mandatory angle(s): ${missingMandatory.join(", ")} (configured in gates.${gateKey}.mandatoryAngles; add a per-angle entry for each before posting a fanout_fanin verdict)`,
+      );
+    }
+    if (foreignAngles.length > 0) {
+      const message = `--findings-json for ${options.gate} names angle(s) outside the configured pool: ${foreignAngles.join(", ")}`;
+      if (resolveRejectForeignAngles(config)) {
+        throw new Error(
+          `${message} (add them to gates.${gateKey}.angles, or set gates.rejectForeignAngles: false to warn instead of fail)`,
+        );
+      }
+      // rejectForeignAngles: false is WARNING mode, not silence — one line per call.
+      if (!options.silent) {
+        process.stderr.write(`WARNING: ${message} (gates.rejectForeignAngles is false; recorded as a warning)\n`);
+      }
+    }
+  }
   // --findings-json takes precedence; when structured findings are present, do not
   // read --findings-file at all (avoids a spurious hard failure if a caller passes
   // both and the file is missing/invalid even though it would be ignored anyway).
@@ -1227,15 +1298,15 @@ export async function upsertCheckpointVerdict(options, { env = process.env, ghCo
     };
   }
   if (existing) {
-    const updated = await updateComment({ repo: options.repo, commentId: existing.commentId, body: desiredBody }, { env, ghCommand });
+    const updated = await updateComment({ repo: options.repo, commentId: existing.commentId, body: desiredBody }, gh);
     // Post-update verification: verify the updated comment is visible via direct API fetch by comment ID.
     // A run id is set (production context) — DEVLOOPS_RUN_ID.
     let updateVerificationWarning = null;
     if (envRunId) {
-      let verified = await verifyComment({ repo: options.repo, commentId: updated.commentId }, { env, ghCommand });
+      let verified = await verifyComment({ repo: options.repo, commentId: updated.commentId }, gh);
       if (!verified) {
         await new Promise((resolve) => setTimeout(resolve, 2000));
-        verified = await verifyComment({ repo: options.repo, commentId: updated.commentId }, { env, ghCommand });
+        verified = await verifyComment({ repo: options.repo, commentId: updated.commentId }, gh);
       }
       updateVerificationWarning = !verified
         ? `Post-update verification failed: comment ${updated.commentId} not retrievable after retry.`
@@ -1258,7 +1329,7 @@ export async function upsertCheckpointVerdict(options, { env = process.env, ghCo
       ...(updateVerificationWarning ? { verificationWarning: updateVerificationWarning } : {}),
     };
   }
-  const created = await createComment({ repo: options.repo, pr: options.pr, body: desiredBody }, { env, ghCommand });
+  const created = await createComment({ repo: options.repo, pr: options.pr, body: desiredBody }, gh);
   // Post-creation verification: verify the comment is retrievable before returning.
   // GitHub API can have brief eventual-consistency windows where a just-posted
   // comment is not yet returned by paginated list endpoints. A direct fetch
@@ -1268,11 +1339,11 @@ export async function upsertCheckpointVerdict(options, { env = process.env, ghCo
   let verified = true;
   let verificationWarning = null;
   if (envRunId) {
-    verified = await verifyComment({ repo: options.repo, commentId: created.commentId }, { env, ghCommand });
+    verified = await verifyComment({ repo: options.repo, commentId: created.commentId }, gh);
     if (!verified) {
       // Brief wait then retry — eventual consistency should resolve within ~2s.
       await new Promise((resolve) => setTimeout(resolve, 2000));
-      verified = await verifyComment({ repo: options.repo, commentId: created.commentId }, { env, ghCommand });
+      verified = await verifyComment({ repo: options.repo, commentId: created.commentId }, gh);
     }
     verificationWarning = !verified
       ? `Post-creation verification failed: comment ${created.commentId} not retrievable after retry. The comment was created (API confirmed) but may not appear in list endpoints immediately.`