dev-loops 0.2.6 → 0.3.0

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

@@ -2,7 +2,8 @@
 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 { parsePrNumber, requireOptionValue, runChild } from "../_cli-primitives.mjs";
+import { parseArgs } from "node:util";
+import { parsePrNumber, requireTokenValue, runChild } 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";
@@ -14,13 +15,16 @@ import { detectStaleRunner } from "../loop/_stale-runner-detection.mjs";
 import { detectInternalOnly } from "../loop/detect-internal-only-pr.mjs";
 const GATE_NAMES = new Set(["draft_gate", "pre_approval_gate"]);
 const GATE_VERDICTS = new Set(["clean", "findings_present", "blocked"]);
+const GATE_EXECUTION_MODES = new Set(["fanout_fanin", "inline_single_agent"]);
+const DEFAULT_EXECUTION_MODE = "inline_single_agent";
 const MAX_GATE_COMMENT_TEXT_LENGTH = 2000;
 const MAX_GATE_COMMENT_EXCERPT_LENGTH = 120;
 const REMOVED_FLAGS = new Set([
   "--force",
   "--force-reason",
 ]);
-const USAGE = `Usage: upsert-checkpoint-verdict.mjs --repo <owner/name> --pr <number> --head-sha <sha> --verdict <clean|findings_present|blocked> (--findings-summary <text> | --findings-file <path>) --next-action <text> [--gate <draft_gate|pre_approval_gate>]
+const USAGE = `Usage: upsert-checkpoint-verdict.mjs --repo <owner/name> --pr <number> --head-sha <sha> --verdict <clean|findings_present|blocked> (--findings-summary <text> | --findings-file <path> | --findings-json <path>) --next-action <text> [--gate <draft_gate|pre_approval_gate>]
+The --findings-json structured per-angle path is preferred for --execution-mode fanout_fanin.
 Create or update the visible checkpoint verdict comment for a gate/head pair.
 Same-head reruns are idempotent: if a visible marker already exists for the same
 \`gate + headSha\`, this helper updates it in place when correction is needed and
@@ -39,6 +43,29 @@ Required:
                                             alternative to --findings-summary
                                             (preserves newlines; takes precedence
                                             when both are present)
+  --findings-json <path>                    Read STRUCTURED fan-out review
+                                            findings from a JSON file. PRIMARY
+                                            shape is the per-angle review-results
+                                            array (array of { angle, verdict?,
+                                            findings:[{severity, summary, file?,
+                                            line?, disposition?}] } — the same
+                                            per-angle objects that feed
+                                            consolidateFanin). A FLAT per-finding
+                                            array (array of { severity, summary,
+                                            angle?, file?|files?, line?,
+                                            disposition? } — consolidateFanin's
+                                            OUTPUT / toFindingsLogShape) is also
+                                            accepted and is GROUPED by each
+                                            finding's .angle. A non-empty input
+                                            matching NEITHER shape is rejected
+                                            (no silent all-clean). Renders a
+                                            readable per-angle breakdown (newlines
+                                            preserved); the findings summary line
+                                            carries a single-line digest. Takes
+                                            precedence over
+                                            --findings-summary/--findings-file for
+                                            the rendered body. Intended for
+                                            --execution-mode fanout_fanin.
   --next-action <text>
 Optional:
   --gate <draft_gate|pre_approval_gate>     Auto-resolved from coordination state
@@ -48,6 +75,19 @@ Optional:
                                              (e.g. '{"must-fix":0,"worth-fixing-now":0}').
                                              Required for --verdict clean when
                                              blockCleanOnFindingSeverities is configured.
+  --execution-mode <fanout_fanin|inline_single_agent>
+                                            How the gate review was executed.
+                                            Defaults to inline_single_agent. Inline
+                                            runs (default or explicit) emit a stderr
+                                            warning that the fan-out/fan-in sub-loop
+                                            was not run and REQUIRE --inline-reason.
+  --inline-reason <text>                    REQUIRED when executionMode resolves to
+                                            inline_single_agent (the default mode):
+                                            short reason recorded for why the gate
+                                            ran inline. A bare call with neither
+                                            --execution-mode nor --inline-reason
+                                            errors. Optional and ignored (dropped)
+                                            for --execution-mode fanout_fanin.
 Output (stdout, JSON):
   {
     "ok": true,
@@ -86,6 +126,10 @@ function normalizeHeadSha(value) {
   const normalized = typeof value === "string" ? value.trim().toLowerCase() : "";
   return /^[0-9a-f]{7,64}$/i.test(normalized) ? normalized : null;
 }
+function normalizeExecutionMode(value) {
+  const normalized = typeof value === "string" ? value.trim().toLowerCase() : "";
+  return GATE_EXECUTION_MODES.has(normalized) ? normalized : null;
+}
 function normalizeRequiredText(value, flag) {
   const normalized = typeof value === "string" ? value.trim() : "";
   if (normalized.length === 0) {
@@ -198,7 +242,27 @@ export function summarizeCheckpointVerdictText(value, limit = MAX_GATE_COMMENT_T
   return smartTruncate(verboseSummary ?? flat, limit);
 }
 export function parseUpsertCheckpointVerdictCliArgs(argv) {
-  const args = [...argv];
+  const { tokens } = parseArgs({
+    args: [...argv],
+    options: {
+      help: { type: "boolean", short: "h" },
+      repo: { type: "string" },
+      pr: { type: "string" },
+      gate: { type: "string" },
+      "head-sha": { type: "string" },
+      verdict: { type: "string" },
+      "findings-summary": { type: "string" },
+      "findings-file": { type: "string" },
+      "findings-json": { type: "string" },
+      "next-action": { type: "string" },
+      "findings-severity-counts": { type: "string" },
+      "execution-mode": { type: "string" },
+      "inline-reason": { type: "string" },
+    },
+    allowPositionals: true,
+    strict: false,
+    tokens: true,
+  });
   const options = {
     help: false,
     repo: undefined,
@@ -208,68 +272,84 @@ export function parseUpsertCheckpointVerdictCliArgs(argv) {
     verdict: undefined,
     findingsSummary: undefined,
     findingsFile: undefined,
+    findingsJson: undefined,
     nextAction: undefined,
     findingsSeverityCounts: undefined,
+    executionMode: undefined,
+    inlineReason: undefined,
   };
-  while (args.length > 0) {
-    const token = args.shift();
-    if (token === "--help" || token === "-h") {
+  for (const token of tokens) {
+    if (token.kind === "positional") {
+      throw parseError(`Unknown argument: ${token.value}`);
+    }
+    if (token.kind !== "option") {
+      continue;
+    }
+    if (token.name === "help") {
       options.help = true;
       return options;
     }
-    if (REMOVED_FLAGS.has(token)) {
-      rejectRemovedFlag(token);
+    if (REMOVED_FLAGS.has(token.rawName)) {
+      rejectRemovedFlag(token.rawName);
     }
-    if (token === "--repo") {
-      options.repo = requireOptionValue(args, "--repo", parseError).trim();
+    if (token.name === "repo") {
+      options.repo = requireTokenValue(token, parseError).trim();
       continue;
     }
-    if (token === "--pr") {
-      options.pr = parsePrNumber(requireOptionValue(args, "--pr", parseError), parseError);
+    if (token.name === "pr") {
+      options.pr = parsePrNumber(requireTokenValue(token, parseError), parseError);
       continue;
     }
-    if (token === "--gate") {
-      const gate = normalizeGateName(requireOptionValue(args, "--gate", parseError));
+    if (token.name === "gate") {
+      const gate = normalizeGateName(requireTokenValue(token, parseError));
       if (!gate) {
         throw parseError("--gate must be one of: draft_gate, pre_approval_gate");
       }
       options.gate = gate;
       continue;
     }
-    if (token === "--head-sha") {
-      const headSha = normalizeHeadSha(requireOptionValue(args, "--head-sha", parseError));
+    if (token.name === "head-sha") {
+      const headSha = normalizeHeadSha(requireTokenValue(token, parseError));
       if (!headSha) {
         throw parseError("--head-sha must be a 7-64 character hexadecimal SHA");
       }
       options.headSha = headSha;
       continue;
     }
-    if (token === "--verdict") {
-      const verdict = normalizeVerdict(requireOptionValue(args, "--verdict", parseError));
+    if (token.name === "verdict") {
+      const verdict = normalizeVerdict(requireTokenValue(token, parseError));
       if (!verdict) {
         throw parseError("--verdict must be one of: clean, findings_present, blocked");
       }
       options.verdict = verdict;
       continue;
     }
-    if (token === "--findings-summary") {
-      options.findingsSummary = normalizeRequiredText(requireOptionValue(args, "--findings-summary", parseError), "--findings-summary");
+    if (token.name === "findings-summary") {
+      options.findingsSummary = normalizeRequiredText(requireTokenValue(token, parseError), "--findings-summary");
       continue;
     }
-    if (token === "--findings-file") {
-      const rawPath = requireOptionValue(args, "--findings-file", parseError).trim();
+    if (token.name === "findings-file") {
+      const rawPath = requireTokenValue(token, parseError).trim();
       if (rawPath.length === 0) {
         throw parseError("--findings-file must be a non-empty path");
       }
       options.findingsFile = rawPath;
       continue;
     }
-    if (token === "--next-action") {
-      options.nextAction = normalizeRequiredText(requireOptionValue(args, "--next-action", parseError), "--next-action");
+    if (token.name === "findings-json") {
+      const rawPath = requireTokenValue(token, parseError).trim();
+      if (rawPath.length === 0) {
+        throw parseError("--findings-json must be a non-empty path");
+      }
+      options.findingsJson = rawPath;
       continue;
     }
-    if (token === "--findings-severity-counts") {
-      const raw = requireOptionValue(args, "--findings-severity-counts", parseError);
+    if (token.name === "next-action") {
+      options.nextAction = normalizeRequiredText(requireTokenValue(token, parseError), "--next-action");
+      continue;
+    }
+    if (token.name === "findings-severity-counts") {
+      const raw = requireTokenValue(token, parseError);
       let parsed;
       try {
         parsed = JSON.parse(raw);
@@ -289,16 +369,51 @@ export function parseUpsertCheckpointVerdictCliArgs(argv) {
       options.findingsSeverityCounts = counts;
       continue;
     }
-    throw parseError(`Unknown argument: ${token}`);
+    if (token.name === "execution-mode") {
+      const mode = normalizeExecutionMode(requireTokenValue(token, parseError));
+      if (!mode) {
+        throw parseError("--execution-mode must be one of: fanout_fanin, inline_single_agent");
+      }
+      options.executionMode = mode;
+      continue;
+    }
+    if (token.name === "inline-reason") {
+      const reason = collapseWhitespace(requireTokenValue(token, parseError));
+      if (reason.length === 0) {
+        throw parseError("--inline-reason must be a non-empty string");
+      }
+      options.inlineReason = smartTruncate(reason, MAX_GATE_COMMENT_EXCERPT_LENGTH);
+      continue;
+    }
+    throw parseError(`Unknown argument: ${token.rawName}`);
+  }
+  // Default execution mode to inline_single_agent when omitted. inlineReason is
+  // only meaningful for inline mode; drop it for fanout_fanin to avoid recording
+  // a misleading reason.
+  options.executionMode = options.executionMode ?? DEFAULT_EXECUTION_MODE;
+  if (options.executionMode !== "inline_single_agent") {
+    options.inlineReason = undefined;
   }
   const missing = ["repo", "pr", "headSha", "verdict", "findingsSummary", "nextAction"]
     .filter((key) => options[key] === undefined);
-  if (options.findingsFile) {
+  // --findings-file and --findings-json each provide the findings body, so either
+  // satisfies the findingsSummary requirement.
+  if (options.findingsFile || options.findingsJson) {
     const fsIdx = missing.indexOf("findingsSummary");
     if (fsIdx !== -1) missing.splice(fsIdx, 1);
   }
   if (missing.length > 0) {
-    throw parseError("upsert-checkpoint-verdict requires --repo, --pr, --head-sha, --verdict, --findings-summary (or --findings-file), and --next-action");
+    throw parseError("upsert-checkpoint-verdict requires --repo, --pr, --head-sha, --verdict, --findings-summary (or --findings-file or --findings-json), and --next-action");
+  }
+  // Contract (skills/copilot-pr-followup/SKILL.md): inline runs MUST pass
+  // --inline-reason. Inline is the default mode, so a complete call that resolves
+  // to inline without a reason errors here. fanout_fanin does not require a
+  // reason. Checked after required-field validation so an incomplete call still
+  // reports the missing-field error first.
+  if (options.executionMode === "inline_single_agent" && options.inlineReason === undefined) {
+    throw parseError(
+      "--inline-reason is required for executionMode inline_single_agent (the default). Pass --execution-mode fanout_fanin for fan-out/fan-in runs, or --inline-reason \"<why>\" to record why the gate ran inline.",
+    );
   }
   try {
     parseRepoSlug(options.repo);
@@ -321,20 +436,302 @@ function appendGateEvidenceNote(summary, note) {
   }
   return smartTruncate(`${normalizedSummary}; ${normalizedNote}`, MAX_GATE_COMMENT_TEXT_LENGTH);
 }
-export function renderGateReviewCommentBody({ gate, headSha, verdict, findingsSummary, nextAction, blockCleanOnFindingSeverities }) {
+const STRUCTURED_FINDINGS_SEVERITY_ORDER = ["must-fix", "worth-fixing-now", "defer"];
+// Sanitize free text for a single-line markdown bullet. Collapse whitespace
+// (LLM text often carries embedded newlines, which would split a bullet across
+// lines) and neutralize HTML-comment delimiters so a finding field cannot smuggle
+// a hidden marker into the rendered body. Mirrors post-gate-findings.mjs.
+function sanitizeStructuredInline(value) {
+  return String(value)
+    .replace(/\s+/gu, " ")
+    .replace(/<!--/gu, "&lt;!--")
+    .replace(/-->/gu, "--&gt;")
+    .trim();
+}
+// Sanitize text rendered inside an inline backtick code span (angle labels,
+// file refs): additionally strip backticks so an embedded backtick cannot close
+// the span and break out into raw markdown.
+function sanitizeStructuredCodeSpan(value) {
+  return sanitizeStructuredInline(String(value).replace(/`/gu, ""));
+}
+// Normalize a single finding object into a deterministic render entry, or null
+// when it carries no usable summary.
+function normalizeStructuredFinding(f) {
+  if (!f || typeof f !== "object" || Array.isArray(f)) {
+    return null;
+  }
+  const summary = typeof f.summary === "string" ? f.summary.trim() : "";
+  if (summary.length === 0) {
+    return null;
+  }
+  const entry = {
+    severity: typeof f.severity === "string" ? f.severity.trim() : "",
+    summary,
+  };
+  if (typeof f.file === "string" && f.file.trim().length > 0) {
+    entry.file = f.file.trim();
+  } else if (Array.isArray(f.files)) {
+    // Flat consolidated findings (toFindingsLogShape) carry a `files` array
+    // rather than a single `file`; surface the first entry as the location ref.
+    const file = f.files.find((x) => typeof x === "string" && x.trim().length > 0);
+    if (file) {
+      entry.file = file.trim();
+    }
+  }
+  if (typeof f.line === "number" && Number.isFinite(f.line)) {
+    entry.line = f.line;
+  }
+  if (typeof f.disposition === "string" && f.disposition.trim().length > 0) {
+    entry.disposition = f.disposition.trim();
+  }
+  return entry;
+}
+// Map a severity to its sort rank. Known severities follow
+// STRUCTURED_FINDINGS_SEVERITY_ORDER (must-fix → worth-fixing-now → defer);
+// unknown/missing severities map to a LARGE rank so they sort LAST, never
+// before must-fix. (indexOf alone would give an unknown severity rank -1,
+// floating it ABOVE must-fix and hiding the highest-priority items below it.)
+function severitySortRank(severity) {
+  const idx = STRUCTURED_FINDINGS_SEVERITY_ORDER.indexOf(severity);
+  return idx === -1 ? STRUCTURED_FINDINGS_SEVERITY_ORDER.length : idx;
+}
+// Sort findings by severity (must-fix first, unknown/missing last) for
+// deterministic output, preserving input order within a severity.
+function sortStructuredFindings(findings) {
+  findings.sort(
+    (a, b) => severitySortRank(a.severity) - severitySortRank(b.severity),
+  );
+  return findings;
+}
+// Does this item look like a NESTED per-angle entry (consolidateFanin's INPUT
+// shape: { angle, verdict?, findings: [...] })? It must carry a `findings`
+// ARRAY — that, not the presence of an `angle` string, is what distinguishes a
+// per-angle section from a single flat finding.
+function looksLikePerAngleEntry(item) {
+  return Boolean(item) && typeof item === "object" && !Array.isArray(item) && Array.isArray(item.findings);
+}
+// Does this item look like a FLAT per-finding entry (consolidateFanin's OUTPUT /
+// toFindingsLogShape shape: { severity, summary, angle?, file?/files?, ... })? It
+// carries a summary (and typically a severity) but NO nested `findings` array.
+function looksLikeFlatFinding(item) {
+  if (!item || typeof item !== "object" || Array.isArray(item)) {
+    return false;
+  }
+  if (Array.isArray(item.findings)) {
+    return false;
+  }
+  return typeof item.summary === "string" && item.summary.trim().length > 0;
+}
+// Build a render-ready per-angle section from a nested entry. A missing/blank
+// angle is NOT dropped — its findings still matter for the verdict — so it is
+// rendered under a `general` fallback label (consistent with the flat-grouping
+// angleless→`general` bucket). Dropping it would let a non-empty structured
+// payload silently degrade to the free-text path and hide findings.
+function buildAngleSectionFromNested(raw) {
+  const trimmedAngle = typeof raw.angle === "string" ? raw.angle.trim() : "";
+  const angle = trimmedAngle.length > 0 ? trimmedAngle : "general";
+  const findings = [];
+  for (const f of raw.findings) {
+    const entry = normalizeStructuredFinding(f);
+    if (entry) {
+      findings.push(entry);
+    }
+  }
+  sortStructuredFindings(findings);
+  const verdict = typeof raw.verdict === "string" && raw.verdict.trim().length > 0
+    ? raw.verdict.trim()
+    : (findings.length > 0 ? "findings_present" : "clean");
+  return { angle, verdict, findings };
+}
+// Group a FLAT per-finding array into per-angle sections, keyed by each
+// finding's `.angle` field (findings without an angle are grouped under a
+// shared "general" bucket so they are NOT dropped). The verdict for each
+// section is derived from whether it carries findings.
+function groupFlatFindingsByAngle(input) {
+  const order = [];
+  const byAngle = new Map();
+  for (const f of input) {
+    const entry = normalizeStructuredFinding(f);
+    if (!entry) {
+      continue;
+    }
+    const angle = typeof f.angle === "string" && f.angle.trim().length > 0
+      ? f.angle.trim()
+      : "general";
+    if (!byAngle.has(angle)) {
+      byAngle.set(angle, []);
+      order.push(angle);
+    }
+    byAngle.get(angle).push(entry);
+  }
+  const angles = [];
+  for (const angle of order) {
+    const findings = sortStructuredFindings(byAngle.get(angle));
+    angles.push({
+      angle,
+      verdict: findings.length > 0 ? "findings_present" : "clean",
+      findings,
+    });
+  }
+  return angles;
+}
+// Normalize the structured findings input into a deterministic, render-ready
+// per-angle shape. Accepts BOTH recognizable shapes without silently zeroing
+// findings:
+//   1. NESTED per-angle (consolidateFanin INPUT):
+//        [{ angle, verdict?, findings: [{ severity, summary, file?, line?, disposition? }] }]
+//      → rendered one section per angle.
+//   2. FLAT per-finding (consolidateFanin OUTPUT / toFindingsLogShape):
+//        [{ severity, summary, angle?, file?|files?, line?, disposition? }]
+//      → GROUPED by each finding's `.angle` into per-angle sections.
+// Returns null when the input is empty/non-array (caller falls back to the
+// free-text summary). THROWS when the input is non-empty but matches NEITHER
+// shape, so a wrong input shape can never silently render an all-clean verdict.
+function normalizeStructuredFindings(input) {
+  if (!Array.isArray(input) || input.length === 0) {
+    return null;
+  }
+  // A gate verdict comment must NEVER silently hide/drop findings. If ANY item
+  // in a non-empty payload is neither a recognizable per-angle entry nor a
+  // recognizable flat finding, THROW rather than filter-and-proceed — an
+  // unrecognized item (producer drift, malformed entry) could otherwise carry a
+  // dropped finding the reviewer never sees.
+  const unrecognized = input.filter(
+    (item) => !looksLikePerAngleEntry(item) && !looksLikeFlatFinding(item),
+  );
+  if (unrecognized.length === input.length) {
+    throw new Error(
+      "--findings-json input is non-empty but matches neither recognized shape: "
+      + "a per-angle array ([{ angle, verdict?, findings: [...] }]) or a flat "
+      + "per-finding array ([{ severity, summary, angle?, ... }]). Refusing to "
+      + "render an all-clean verdict from unrecognized findings.",
+    );
+  }
+  if (unrecognized.length > 0) {
+    throw new Error(
+      "--findings-json input contains "
+      + `${unrecognized.length} of ${input.length} item(s) that match neither a `
+      + "per-angle entry (with a nested `findings` array) nor a flat per-finding "
+      + "entry (with a non-empty `summary`). Refusing to silently drop them from a "
+      + "gate verdict; fix the producer or remove the malformed entries.",
+    );
+  }
+  const nestedCount = input.filter(looksLikePerAngleEntry).length;
+  let angles;
+  if (nestedCount > 0) {
+    // Treat as per-angle. Any flat items mixed in are ambiguous; reject rather
+    // than guess (mixing the two shapes is not a supported producer output).
+    if (nestedCount !== input.length) {
+      throw new Error(
+        "--findings-json input mixes per-angle entries (with a nested `findings` "
+        + "array) and flat per-finding entries; supply one shape or the other.",
+      );
+    }
+    angles = [];
+    for (const raw of input) {
+      angles.push(buildAngleSectionFromNested(raw));
+    }
+  } else {
+    angles = groupFlatFindingsByAngle(input);
+  }
+  return angles.length > 0 ? angles : null;
+}
+// Render the consolidated per-angle fan-in findings as a readable, multi-line
+// markdown block: one section per angle (angle label + per-angle verdict),
+// nested findings carrying severity and an optional file:line reference. Newlines
+// are intentionally PRESERVED — this block is NOT run through collapseWhitespace /
+// summarizeCheckpointVerdictText. The whole block is bounded by
+// MAX_GATE_COMMENT_TEXT_LENGTH. The leading single-line digest is what the marker
+// parser captures for the `**Findings summary:**` field; the structured body is
+// nested below it and is deliberately written so no nested line matches a gate
+// field regex (no `verdict:` / `next action:` / `execution mode:` line starts).
+function renderStructuredFindings(angles) {
+  const lines = [];
+  for (const { angle, verdict, findings } of angles) {
+    const angleLabel = sanitizeStructuredCodeSpan(angle);
+    lines.push(`- \`${angleLabel}\` → ${sanitizeStructuredInline(verdict)}`);
+    for (const finding of findings) {
+      const severity = sanitizeStructuredInline(finding.severity) || "finding";
+      const summary = sanitizeStructuredInline(finding.summary);
+      let location = "";
+      if (finding.file) {
+        const fileRef = sanitizeStructuredCodeSpan(finding.file);
+        const lineRef = Number.isFinite(finding.line) ? `:${finding.line}` : "";
+        if (fileRef.length > 0) {
+          location = ` (\`${fileRef}${lineRef}\`)`;
+        }
+      }
+      const dispositionSuffix = finding.disposition
+        ? ` — _${sanitizeStructuredInline(finding.disposition)}_`
+        : "";
+      lines.push(`  - [${severity}] ${summary}${location}${dispositionSuffix}`);
+    }
+  }
+  return smartTruncate(lines.join("\n"), MAX_GATE_COMMENT_TEXT_LENGTH);
+}
+// Build the single-line digest shown on the `**Findings summary:**` line when a
+// structured per-angle block is rendered. The marker/parse contract requires this
+// line to carry non-empty, single-line content (parseGateReviewCommentFields
+// captures only the remainder of this one line), so the structured block below it
+// is purely presentational.
+function buildStructuredFindingsDigest(angles) {
+  const totalFindings = angles.reduce((sum, a) => sum + a.findings.length, 0);
+  const angleWord = angles.length === 1 ? "angle" : "angles";
+  if (totalFindings === 0) {
+    return `${angles.length} ${angleWord} reviewed; no findings (see per-angle breakdown below).`;
+  }
+  const findingWord = totalFindings === 1 ? "finding" : "findings";
+  return `${angles.length} ${angleWord} reviewed; ${totalFindings} ${findingWord} (see per-angle breakdown below).`;
+}
+function renderExecutionModeLine(executionMode, inlineReason) {
+  const mode = executionMode ?? DEFAULT_EXECUTION_MODE;
+  if (mode === "inline_single_agent") {
+    const reason = typeof inlineReason === "string" ? collapseWhitespace(inlineReason) : "";
+    return reason.length > 0
+      ? `**Execution mode:** inline_single_agent — ${reason}`
+      : "**Execution mode:** inline_single_agent";
+  }
+  return `**Execution mode:** ${mode}`;
+}
+export function renderGateReviewCommentBody({ gate, headSha, verdict, findingsSummary, nextAction, blockCleanOnFindingSeverities, executionMode, inlineReason, structuredFindings, gateEvidenceNote }) {
   const lines = [
     `### Gate review: \`${gate}\``,
     "",
     `**Reviewed head SHA:** \`${headSha}\``,
     `**Verdict:** ${verdict}`,
+    renderExecutionModeLine(executionMode, inlineReason),
   ];
   if ((verdict === "findings_present" || verdict === "blocked") && blockCleanOnFindingSeverities && blockCleanOnFindingSeverities.length > 0) {
     const sevs = blockCleanOnFindingSeverities.join(", ");
     lines.push(`**Blocking severities:** ${sevs} (clean requires no findings matching these severities)`);
   }
+  // When structured per-angle fan-in data is supplied, render it as a readable
+  // multi-line block. The `**Findings summary:**` line still carries a non-empty
+  // single-line digest so the marker/parse contract (which captures only that
+  // one line) keeps round-tripping; the structured breakdown is nested below it
+  // with newlines preserved (NOT collapsed to a run-on line).
+  const angles = normalizeStructuredFindings(structuredFindings);
+  if (angles) {
+    // Build the single-line digest and append the gate-evidence note (parity with
+    // the free-text appendGateEvidenceNote path), so a structured verdict carries
+    // the gate-evidence note (e.g. the round-cap / round-exhaustion fallback note)
+    // on the `**Findings summary:**` line just like a free-text verdict does.
+    // appendGateEvidenceNote keeps this a single, length-bounded line, preserving
+    // the marker/parse contract. The per-angle bullets below are unaffected.
+    const structuredSummary = appendGateEvidenceNote(buildStructuredFindingsDigest(angles), gateEvidenceNote ?? null);
+    lines.push(
+      "",
+      `**Findings summary:** ${structuredSummary}`,
+      "",
+      renderStructuredFindings(angles),
+    );
+  } else {
+    lines.push(
+      "",
+      `**Findings summary:** ${findingsSummary}`,
+    );
+  }
   lines.push(
-    "",
-    `**Findings summary:** ${findingsSummary}`,
     "",
     `**Next action:** ${nextAction}`,
   );
@@ -380,6 +777,8 @@ function summarizeExistingComment({ strict, marker, headSha }) {
       verdict: markerSameHead.verdict,
       findingsSummary: markerSameHead.findingsSummary ?? null,
       nextAction: markerSameHead.nextAction ?? null,
+      executionMode: markerSameHead.executionMode ?? null,
+      inlineReason: markerSameHead.inlineReason ?? null,
       contractComplete: markerSameHead.contractComplete === true,
     };
   }
@@ -391,6 +790,8 @@ function summarizeExistingComment({ strict, marker, headSha }) {
       verdict: strictSameHead.verdict,
       findingsSummary: strictSameHead.findingsSummary,
       nextAction: strictSameHead.nextAction,
+      executionMode: strictSameHead.executionMode ?? markerSameHead?.executionMode ?? null,
+      inlineReason: strictSameHead.inlineReason ?? markerSameHead?.inlineReason ?? null,
       contractComplete: true,
     };
   }
@@ -402,6 +803,8 @@ function summarizeExistingComment({ strict, marker, headSha }) {
       verdict: markerSameHead.verdict,
       findingsSummary: markerSameHead.findingsSummary ?? null,
       nextAction: markerSameHead.nextAction ?? null,
+      executionMode: markerSameHead.executionMode ?? null,
+      inlineReason: markerSameHead.inlineReason ?? null,
       contractComplete: markerSameHead.contractComplete === true,
     };
   }
@@ -449,6 +852,73 @@ async function verifyComment({ repo, commentId }, { env, ghCommand }) {
   }
 }
 
+// Post a draft_gate verdict on a PR that is currently READY (non-draft) by
+// briefly transitioning it back to draft, posting the verdict (which is only
+// legal while the PR is a draft), then restoring the ready state. The caller's
+// options — verdict, execution mode (e.g. fanout_fanin), findings, ledger — are
+// preserved verbatim by re-entering upsertCheckpointVerdict once the PR is a
+// draft. Unlike `reconcile-draft-gate` (which posts an inline verdict and so
+// cannot satisfy requireFanoutEvidence on draft_gate), this preserves fanout
+// evidence. On any failure mid-transition the PR is best-effort restored to
+// ready before rethrowing. (#891)
+//
+// Durability note: there is a bounded window between convertPrToDraft and
+// markPrReady (the recursive verdict post does network I/O) in which a process
+// crash would leave the PR in draft INDEFINITELY — until a later dev-loop run (or a
+// manual `gh pr ready`) restores it. Recovery is automatic but NOT instantaneous:
+// the next run re-enters as a draft, posts normally, and restores ready. The
+// transition is logged (below) so a stuck-draft PR leaves a breadcrumb. There is no
+// mutual exclusion around the GitHub draft toggle itself; the convert and
+// 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 }) {
+  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 });
+  let result;
+  try {
+    // The PR is now a draft, so RUN_DRAFT_GATE is the legal action. Re-enter with
+    // the caller's full options; prIsDraft is now true so this branch is skipped.
+    result = await upsertCheckpointVerdict(options, { env, ghCommand, repoRoot });
+  } catch (error) {
+    if (conversion.alreadyDraft !== true) {
+      try {
+        await markPrReady({ repo: options.repo, pr: options.pr }, { env, ghCommand });
+        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
+        // so the transient draft state is not silent.
+        process.stderr.write(
+          `[draft_gate] WARNING: failed to restore ${options.repo}#${options.pr} to ready after a failed verdict post; ` +
+          `it may be left in draft: ${restoreError instanceof Error ? restoreError.message : String(restoreError)}\n`,
+        );
+      }
+    }
+    throw error;
+  }
+  if (conversion.alreadyDraft !== true) {
+    try {
+      await markPrReady({ repo: options.repo, pr: options.pr }, { env, ghCommand });
+    } 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)
+      // and knows the PR may be left in draft until restored. (#891, Copilot review)
+      throw new Error(
+        `draft_gate verdict was posted to ${options.repo}#${options.pr} (comment ${result.commentId ?? "?"}), ` +
+        `but restoring the PR to ready failed; it may be left in draft. Do not re-post the gate — re-run ` +
+        `\`gh pr ready ${options.pr}\` (or the dev-loop) to restore ready. Cause: ` +
+        `${restoreError instanceof Error ? restoreError.message : String(restoreError)}`,
+      );
+    }
+    process.stderr.write(`[draft_gate] restored ${options.repo}#${options.pr} to ready after posting draft_gate evidence.\n`);
+  }
+  return { ...result, draftTransition: true };
+}
+
 export async function upsertCheckpointVerdict(options, { env = process.env, ghCommand = "gh", repoRoot = process.cwd() } = {}) {
   // 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
@@ -517,14 +987,70 @@ export async function upsertCheckpointVerdict(options, { env = process.env, ghCo
     }
   }
   const requestedGateAction = resolveGateAction(options.gate);
+  const prIsDraft = Boolean(coordinationContext.prData?.isDraft);
   if (options.gate === "draft_gate" && coordination.draftGateAlreadySatisfied) {
-    throw new Error(
-      `Cannot enter draft_gate on ${options.repo}#${options.pr}: draft gate was already satisfied ` +
-      `(clean evidence exists, PR is no longer draft). ` +
-      `Do not re-post draft_gate. The draft→ready transition was already recorded.`,
-    );
+    // The draft gate is a one-time boundary: a non-draft PR with clean draft_gate
+    // evidence (on any head) has already passed it, and the pre-merge gate check
+    // accepts that evidence. Re-posting is therefore a no-op, not an error —
+    // return idempotent success so scripted/automated callers are not dead-ended
+    // by a hard throw. (#891)
+    const satisfied = coordinationContext.gateEvidence?.draftGate ?? {};
+    // executionMode lives on the gate MARKER summary, not the COMMENT (strict)
+    // summary: the strict `draftGate` summary is parsed from the visible comment
+    // body via normalizeGateSummary, which carries no executionMode field, so it
+    // would always collapse to inline_single_agent — misleading when the satisfied
+    // gate actually ran fanout_fanin. Prefer the marker's executionMode; if the
+    // marker is unavailable, OMIT the field rather than report a misleading default.
+    const satisfiedExecutionMode =
+      coordinationContext.gateEvidence?.draftGateMarker?.executionMode
+      ?? satisfied.executionMode
+      ?? null;
+    return {
+      ok: true,
+      action: "noop",
+      reason: "draft_gate already satisfied (clean evidence exists; draft→ready boundary recorded)",
+      repo: options.repo,
+      pr: options.pr,
+      gate: "draft_gate",
+      // Report the head the existing clean evidence was recorded on (which may be a
+      // stale head — the draft gate is a one-time boundary accepted on any head),
+      // not the request's canonical head, so the field is not misleading.
+      headSha: satisfied.headSha ?? canonicalHeadSha,
+      currentHeadSha: evidence.currentHeadSha,
+      draftGateAlreadySatisfied: true,
+      // Mirror the field shape of the other success paths for consistent consumers.
+      blockCleanOnFindingSeverities: draftGateConfig.blockCleanOnFindingSeverities,
+      ...(satisfiedExecutionMode != null ? { executionMode: satisfiedExecutionMode } : {}),
+      ...(satisfied.commentId != null ? { commentId: satisfied.commentId } : {}),
+      ...(satisfied.commentUrl ? { commentUrl: satisfied.commentUrl } : {}),
+    };
   }
   const gateActionForbidden = coordination.forbiddenActions.includes(requestedGateAction);
+  // Draft gate can only be posted while the PR is a draft (RUN_DRAFT_GATE is
+  // forbidden once the PR is ready). A PR opened directly as ready — or any ready
+  // PR that still needs clean draft_gate evidence for the pre-merge check — would
+  // otherwise dead-end: the poster refuses, yet the pre-merge gate check fails
+  // closed on "missing visible clean draft_gate comment". Rather than force the
+  // operator to manually toggle the PR back to draft, perform the
+  // draft→post→ready transition here, preserving the caller's verdict, execution
+  // mode (e.g. fanout_fanin), findings, and ledger. This is the fanout-aware
+  // analogue of `reconcile-draft-gate` (which only posts inline and so cannot
+  // satisfy requireFanoutEvidence on draft_gate). (#891)
+  //
+  // Trigger ONLY when coordination explicitly allows RECONCILE_DRAFT_GATE — i.e. the
+  // state machine determined this ready PR genuinely needs draft-gate evidence
+  // reconciled (a converged/merge-progression state with no clean draft evidence).
+  // RUN_DRAFT_GATE is forbidden on a ready PR in many OTHER states too (merge
+  // conflicts, waiting-for-CI, unresolved feedback, blocked); converting those to
+  // draft would be wrong, so we must NOT key off `gateActionForbidden` alone. (#891)
+  if (
+    options.gate === "draft_gate"
+    && !prIsDraft
+    && !coordination.draftGateAlreadySatisfied
+    && coordination.allowedNextActions.includes(PR_CHECKPOINT_ACTION.RECONCILE_DRAFT_GATE)
+  ) {
+    return await postDraftGateViaDraftTransition(options, { env, ghCommand, repoRoot });
+  }
   if (gateActionForbidden) {
     throw new Error(buildGateEntryRefusalError({ options, coordination }));
   }
@@ -556,7 +1082,42 @@ export async function upsertCheckpointVerdict(options, { env = process.env, ghCo
       );
     }
   }
-  if (options.findingsFile) {
+  // Structured per-angle findings (consolidated fan-in shape) take precedence
+  // over the free-text summary: when present, the verdict comment renders a
+  // 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;
+  if (options.findingsJson) {
+    let raw;
+    try {
+      raw = await readFile(options.findingsJson, "utf8");
+    } catch (err) {
+      throw new Error(`Cannot read --findings-json "${options.findingsJson}": ${err instanceof Error ? err.message : String(err)}`);
+    }
+    let parsed;
+    try {
+      parsed = JSON.parse(raw);
+    } catch {
+      throw new Error(`--findings-json "${options.findingsJson}" is not valid JSON`);
+    }
+    // Accept either a bare array of per-angle entries or an object wrapping it
+    // under `angles` / `findings` (defensive against caller shape drift).
+    const candidate = Array.isArray(parsed)
+      ? parsed
+      : (Array.isArray(parsed?.angles) ? parsed.angles : (Array.isArray(parsed?.findings) ? parsed.findings : null));
+    try {
+      structuredFindings = normalizeStructuredFindings(candidate);
+    } catch (err) {
+      throw new Error(`--findings-json "${options.findingsJson}": ${err instanceof Error ? err.message : String(err)}`);
+    }
+    if (!structuredFindings) {
+      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)`);
+    }
+  }
+  // --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).
+  if (!structuredFindings && options.findingsFile) {
     try {
       const fileContent = await readFile(options.findingsFile, "utf8");
       const trimmedEnd = fileContent.replace(/\n+$/, "");
@@ -571,24 +1132,48 @@ export async function upsertCheckpointVerdict(options, { env = process.env, ghCo
       throw new Error(`Cannot read --findings-file "${options.findingsFile}": ${err instanceof Error ? err.message : String(err)}`);
     }
   }
-  const effectiveFindingsSummary = options.findingsFile
-    ? options.findingsSummary
-    : appendGateEvidenceNote(options.findingsSummary, coordination.gateEvidenceNote ?? null);
+  // The findings-summary the comment is compared/round-tripped against. With a
+  // structured render this is the single-line digest (what the marker parser
+  // recovers from the `**Findings summary:**` line); otherwise the free-text path.
+  const effectiveFindingsSummary = structuredFindings
+    ? appendGateEvidenceNote(buildStructuredFindingsDigest(structuredFindings), coordination.gateEvidenceNote ?? null)
+    : (options.findingsFile
+      ? options.findingsSummary
+      : appendGateEvidenceNote(options.findingsSummary, coordination.gateEvidenceNote ?? null));
   const desiredBody = renderGateReviewCommentBody({
     ...options,
     headSha: canonicalHeadSha,
     findingsSummary: effectiveFindingsSummary,
+    structuredFindings,
+    // In structured mode the renderer rebuilds the digest internally and appends
+    // this note, so the rendered `**Findings summary:**` line matches
+    // effectiveFindingsSummary (the value used for the noop/round-trip compare).
+    gateEvidenceNote: coordination.gateEvidenceNote ?? null,
     blockCleanOnFindingSeverities: activeGateConfig.blockCleanOnFindingSeverities,
   });
   const gateEvidence = selectGateEvidence(evidence, options.gate);
   const existing = summarizeExistingComment({ ...gateEvidence, headSha: canonicalHeadSha });
   const warning = detectStaleGateCommentWarning({ strict: gateEvidence.strict, headSha: canonicalHeadSha, gate: options.gate });
+  const desiredExecutionMode = options.executionMode ?? DEFAULT_EXECUTION_MODE;
+  // inlineReason is only meaningful for inline mode and is dropped for
+  // fanout_fanin at parse time, so normalize both sides to null when the
+  // resolved mode is not inline. This makes the noop short-circuit fire only
+  // when verdict/summary/nextAction/executionMode AND the inline reason all
+  // match, so a changed/added --inline-reason forces a comment update.
+  const desiredInlineReason = desiredExecutionMode === "inline_single_agent"
+    ? (options.inlineReason ?? null)
+    : null;
+  const existingInlineReason = (existing?.executionMode ?? DEFAULT_EXECUTION_MODE) === "inline_single_agent"
+    ? (existing?.inlineReason ?? null)
+    : null;
   if (
     existing
     && existing.contractComplete
     && existing.verdict === options.verdict
     && existing.findingsSummary === effectiveFindingsSummary
     && existing.nextAction === options.nextAction
+    && (existing.executionMode ?? DEFAULT_EXECUTION_MODE) === desiredExecutionMode
+    && existingInlineReason === desiredInlineReason
   ) {
     return {
       ok: true,
@@ -601,6 +1186,8 @@ export async function upsertCheckpointVerdict(options, { env = process.env, ghCo
       commentId: existing.commentId,
       commentUrl: existing.commentUrl,
       blockCleanOnFindingSeverities: activeGateConfig.blockCleanOnFindingSeverities,
+      executionMode: options.executionMode ?? DEFAULT_EXECUTION_MODE,
+      ...(existingInlineReason ? { inlineReason: existingInlineReason } : {}),
       ...(warning ? { warning } : {}),
     };
   }
@@ -630,6 +1217,8 @@ export async function upsertCheckpointVerdict(options, { env = process.env, ghCo
       commentId: updated.commentId,
       commentUrl: updated.commentUrl,
       blockCleanOnFindingSeverities: activeGateConfig.blockCleanOnFindingSeverities,
+      executionMode: options.executionMode ?? DEFAULT_EXECUTION_MODE,
+      ...(options.inlineReason ? { inlineReason: options.inlineReason } : {}),
       ...(warning ? { warning } : {}),
       ...(updateVerificationWarning ? { verificationWarning: updateVerificationWarning } : {}),
     };
@@ -665,10 +1254,20 @@ export async function upsertCheckpointVerdict(options, { env = process.env, ghCo
     commentId: created.commentId,
     commentUrl: created.commentUrl,
     blockCleanOnFindingSeverities: activeGateConfig.blockCleanOnFindingSeverities,
+    executionMode: options.executionMode ?? DEFAULT_EXECUTION_MODE,
+    ...(options.inlineReason ? { inlineReason: options.inlineReason } : {}),
     ...(warning ? { warning } : {}),
     ...(verificationWarning ? { verificationWarning } : {}),
   };
 }
+export function buildInlineExecutionWarning(executionMode, inlineReason) {
+  if ((executionMode ?? DEFAULT_EXECUTION_MODE) !== "inline_single_agent") {
+    return null;
+  }
+  const reason = typeof inlineReason === "string" ? inlineReason.trim() : "";
+  const base = "WARNING: gate ran inline_single_agent (not via the fan-out/fan-in review sub-loop).";
+  return reason.length > 0 ? `${base} Reason: ${reason}` : base;
+}
 async function main() {
   let options;
   try {
@@ -682,8 +1281,14 @@ async function main() {
     process.stdout.write(`${USAGE}\n`);
     return;
   }
+  const inlineWarning = buildInlineExecutionWarning(options.executionMode, options.inlineReason);
   try {
     const result = await upsertCheckpointVerdict(options);
+    // Emit the inline-execution warning only on success so the JSON error
+    // envelope on stderr stays clean and machine-parseable on failures.
+    if (inlineWarning) {
+      process.stderr.write(`${inlineWarning}\n`);
+    }
     process.stdout.write(`${JSON.stringify(result)}\n`);
   } catch (error) {
     process.stderr.write(`${JSON.stringify({ ok: false, error: error instanceof Error ? error.message : String(error) })}\n`);