dev-loops 0.2.7 → 0.3.0

package/scripts/github/{create-draft-pr.mjs → create-pr.mjs}

@@ -2,17 +2,20 @@
 import { readFile } from "node:fs/promises";
 import { spawn } from "node:child_process";
 import { buildParseError, formatCliError, isDirectCliRun } from "../_core-helpers.mjs";
-const USAGE = `Usage: create-draft-pr.mjs [gh pr create args...]
-Thin wrapper around \`gh pr create\` that enforces draft-first PR creation.
+const USAGE = `Usage: create-pr.mjs [gh pr create args...]
+Canonical PR-creation wrapper around \`gh pr create\`. Every PR opened through this
+tool is ALWAYS a draft and is self-assigned by default. Never call raw \`gh pr create\`.
 Behavior:
-  - injects exactly one \`--draft\` when absent
+  - injects exactly one \`--draft\` when absent (draft is the only mode)
+  - defaults \`--assignee @me\` when no assignee is given (self-assigned by default)
+  - honors an explicit \`--assignee <login>\` / \`-a <login>\` when supplied (no default injected)
   - rejects \`--ready\` before invoking \`gh\`
   - detects missing \`Closes #N\` / \`Fixes #N\` in \`--body\` or \`--body-file\` content (non-fatal stderr warning)
   - forwards every other argument to \`gh pr create\` unchanged
   - preserves the underlying \`gh pr create\` stdout, stderr, and exit code
 Examples:
-  node scripts/github/create-draft-pr.mjs --repo owner/repo --assignee @me --base main --head feature --title "..." --body-file pr.md
-  node <resolved-skill-scripts>/github/create-draft-pr.mjs --repo owner/repo --assignee @me --base main --head feature --title "..." --body-file pr.md
+  node scripts/github/create-pr.mjs --repo owner/repo --base main --head feature --title "..." --body-file pr.md
+  node <resolved-skill-scripts>/github/create-pr.mjs --repo owner/repo --base main --head feature --title "..." --body-file pr.md
 Notes:
   - Use \`gh pr ready\` later to leave draft state; this wrapper never opens a ready PR.
   - Wrapper-owned validation is limited to \`--ready\`; all other argument validation is left to \`gh pr create\`.
@@ -25,6 +28,12 @@ const parseError = buildParseError(USAGE);
 const READY_FLAG_PATTERN = /^--ready(?:$|=)/u;
 const DRAFT_FLAG_PATTERN = /^--draft(?:=(.*))?$/iu;
 const DRAFT_TRUE_VALUE_PATTERN = /^(?:true|1)$/iu;
+// Detect both the long `--assignee`/`--assignee=<login>` forms and the `-a`
+// short flag that `gh pr create` documents, so an explicit assignee in either
+// form suppresses the `--assignee @me` default (otherwise a caller passing
+// `-a <login>` would get a conflicting `--assignee @me` injected). (#894)
+const ASSIGNEE_FLAG_PATTERN = /^(?:--assignee(?:$|=)|-a$)/u;
+const DEFAULT_ASSIGNEE = "@me";
 const CLOSING_KEYWORD_PATTERN = /Closes\s+#\d+|Fixes\s+#\d+/i;
 const MAX_BODY_SCAN_BYTES = 16 * 1024;
 export function detectClosingKeyword(body) {
@@ -52,12 +61,12 @@ async function warnMissingClosingKeyword(args) {
   if (body === null) return; // no --body or --body-file, skip
   if (!detectClosingKeyword(body)) {
     process.stderr.write(
-      "[create-draft-pr] Warning: PR body missing `Closes #N` or `Fixes #N`. " +
+      "[create-pr] Warning: PR body missing `Closes #N` or `Fixes #N`. " +
         "GitHub will not auto-close the linked issue on merge.\n",
     );
   }
 }
-export function buildCreateDraftPrArgs(argv) {
+export function buildCreatePrArgs(argv) {
   const args = [...argv];
   if (args.includes("--help") || args.includes("-h")) {
     return {
@@ -66,17 +75,24 @@ export function buildCreateDraftPrArgs(argv) {
     };
   }
   if (args.some((token) => READY_FLAG_PATTERN.test(token))) {
-    throw parseError("create-draft-pr rejects --ready; open the PR as draft first, then run `gh pr ready` after the draft gate is satisfied");
+    throw parseError("create-pr rejects --ready; open the PR as draft first, then run `gh pr ready` after the draft gate is satisfied");
   }
   const draftTokens = args.filter((token) => DRAFT_FLAG_PATTERN.test(token));
   const lastDraftToken = draftTokens.length > 0 ? draftTokens.at(-1) : null;
   const lastDraftSuppliesDraft = lastDraftToken === "--draft" || (typeof lastDraftToken === "string" && DRAFT_TRUE_VALUE_PATTERN.test(lastDraftToken.slice("--draft=".length)));
+  const hasAssignee = args.some((token) => ASSIGNEE_FLAG_PATTERN.test(token));
   return {
     help: false,
-    ghArgs: ["pr", "create", ...args, ...(lastDraftSuppliesDraft ? [] : ["--draft"])],
+    ghArgs: [
+      "pr",
+      "create",
+      ...args,
+      ...(hasAssignee ? [] : ["--assignee", DEFAULT_ASSIGNEE]),
+      ...(lastDraftSuppliesDraft ? [] : ["--draft"]),
+    ],
   };
 }
-export function spawnCreateDraftPr(ghArgs, { ghCommand = "gh", env = process.env } = {}) {
+export function spawnCreatePr(ghArgs, { ghCommand = "gh", env = process.env } = {}) {
   return new Promise((resolve, reject) => {
     const child = spawn(ghCommand, ghArgs, {
       env,
@@ -89,13 +105,13 @@ export function spawnCreateDraftPr(ghArgs, { ghCommand = "gh", env = process.env
   });
 }
 export async function main(argv = process.argv.slice(2), runtime = {}) {
-  const { help, ghArgs } = buildCreateDraftPrArgs(argv);
+  const { help, ghArgs } = buildCreatePrArgs(argv);
   if (help) {
     process.stdout.write(`${USAGE}\n`);
     return 0;
   }
   await warnMissingClosingKeyword(argv);
-  return spawnCreateDraftPr(ghArgs, runtime);
+  return spawnCreatePr(ghArgs, runtime);
 }
 if (isDirectCliRun(import.meta.url)) {
   try {

package/scripts/github/detect-checkpoint-evidence.mjs

@@ -9,9 +9,13 @@ import {
   summarizeGateReviewCommentMarkers,
   summarizeGateReviewComments,
 } from "../_core-helpers.mjs";
+import { access } from "node:fs/promises";
+import path from "node:path";
 import { parsePrNumber, requireTokenValue, runChild } from "../_cli-primitives.mjs";
 import { fetchGithubReviewThreadsPayload } from "./capture-review-threads.mjs";
 import { parseRepoSlug } from "@dev-loops/core/github/repo-slug";
+import { loadDevLoopConfig, resolveGateConfig, resolveRequireFanoutEvidence } from "@dev-loops/core/config";
+import { buildLogPath } from "./write-gate-findings-log.mjs";
 import { ensureAsyncRunnerOwnership } from "../loop/_pr-runner-coordination.mjs";
 import { detectStaleRunner } from "../loop/_stale-runner-detection.mjs";
 const USAGE = `Usage: detect-checkpoint-evidence.mjs --repo <owner/name> --pr <number>
@@ -200,6 +204,8 @@ function emptyGateMarkerSummary() {
     verdict: null,
     findingsSummary: null,
     nextAction: null,
+    executionMode: null,
+    inlineReason: null,
     contractComplete: false,
     commentId: null,
     commentUrl: null,
@@ -216,13 +222,15 @@ function normalizeGateMarkerSummary(summary) {
     verdict: summary.verdict,
     findingsSummary: summary.findingsSummary,
     nextAction: summary.nextAction,
+    executionMode: summary.executionMode ?? null,
+    inlineReason: summary.inlineReason ?? null,
     contractComplete: summary.contractComplete === true,
     commentId: summary.commentId,
     commentUrl: summary.commentUrl,
     updatedAt: summary.updatedAt,
   };
 }
-export function buildPreMergeGateCheck(evidence, unresolvedThreadCount = null, staleRunnerCheck = null) {
+export function buildPreMergeGateCheck(evidence, unresolvedThreadCount = null, staleRunnerCheck = null, fanoutEnforcement = null) {
   const failures = [];
   if (!(evidence.draftGate.visible && evidence.draftGate.verdict === "clean")) {
     failures.push("missing visible clean draft_gate comment");
@@ -236,6 +244,24 @@ export function buildPreMergeGateCheck(evidence, unresolvedThreadCount = null, s
   )) {
     failures.push("missing visible clean current-head pre_approval_gate comment");
   }
+  // Fail-closed fan-out evidence enforcement (gates.requireFanoutEvidence, ON by
+  // default / opt-out). When disabled or config-unavailable, fanoutEnforcement is
+  // { required: false, gates: [] } so the `.required` guard skips this block.
+  if (fanoutEnforcement && fanoutEnforcement.required) {
+    for (const gate of fanoutEnforcement.gates) {
+      if (gate.executionMode !== "fanout_fanin") {
+        failures.push(
+          `${gate.name}: requireFanoutEvidence is enabled but executionMode is "${gate.executionMode ?? "unset"}" (expected "fanout_fanin"); inline gate verdicts are not accepted`,
+        );
+        continue;
+      }
+      if (!gate.ledgerExists) {
+        failures.push(
+          `${gate.name}: requireFanoutEvidence is enabled but no findings-log ledger exists for the reviewed head (${gate.ledgerPath})`,
+        );
+      }
+    }
+  }
   if (typeof unresolvedThreadCount === "number" && unresolvedThreadCount !== 0) {
     if (unresolvedThreadCount === -1) {
       failures.push("could not fetch review thread state from GitHub API; re-run gate evidence check when API connectivity is restored");
@@ -253,6 +279,52 @@ export function buildPreMergeGateCheck(evidence, unresolvedThreadCount = null, s
     failures,
   };
 }
+async function ledgerExists(fullPath) {
+  try {
+    await access(fullPath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+/**
+ * Build the fan-out evidence enforcement descriptor.
+ *
+ * Enforcement is ON by default (opt-out via gates.requireFanoutEvidence: false).
+ * Returns { required: false } when enforcement is disabled OR when config is
+ * unavailable (config == null — null or undefined — after a failed load) — config-unavailable must
+ * fail open and never enable enforcement. When enabled, records per-required-gate
+ * executionMode and whether the deterministic findings-log ledger exists for the
+ * reviewed head SHA so the pre-merge check can fail closed on inline verdicts or
+ * missing ledgers.
+ */
+async function buildFanoutEnforcement({ repo, pr, currentHeadSha, draftGateMarker, preApprovalGateMarker, config, cwd }) {
+  // Fail open when config could not be loaded/validated. `== null` covers both
+  // null and undefined; the loader only ever yields null on failure, but the
+  // loose check defensively treats an absent config as unavailable.
+  if (config == null || !resolveRequireFanoutEvidence(config)) {
+    return { required: false, gates: [] };
+  }
+  const draftRequired = resolveGateConfig(config, "draft").required;
+  const preApprovalRequired = resolveGateConfig(config, "preApproval").required;
+  const gateSpecs = [
+    { name: "draft_gate", marker: draftGateMarker, required: draftRequired },
+    { name: "pre_approval_gate", marker: preApprovalGateMarker, required: preApprovalRequired },
+  ].filter((spec) => spec.required && spec.marker.visible);
+  const gates = [];
+  for (const spec of gateSpecs) {
+    const headSha = spec.marker.headSha ?? currentHeadSha;
+    const ledgerPath = buildLogPath({ repo, pr, gate: spec.name, headSha, tmpRoot: "tmp" });
+    const fullPath = path.resolve(cwd, ledgerPath);
+    gates.push({
+      name: spec.name,
+      executionMode: spec.marker.executionMode ?? null,
+      ledgerPath,
+      ledgerExists: await ledgerExists(fullPath),
+    });
+  }
+  return { required: true, gates };
+}
 export async function detectCheckpointEvidence(options, { env = process.env, ghCommand = "gh", cwd = process.cwd() } = {}) {
   const runnerOwnership = await ensureAsyncRunnerOwnership({
     repo: options.repo,
@@ -299,6 +371,24 @@ export async function detectCheckpointEvidence(options, { env = process.env, ghC
   const allComments = [...commentsPayload, ...prReviews];
   const commentSummary = summarizeGateReviewComments(allComments);
   const markerSummary = summarizeGateReviewCommentMarkers(allComments, { headSha: currentHeadSha });
+  const draftGateMarker = normalizeGateMarkerSummary(markerSummary.draft_gate);
+  const preApprovalGateMarker = normalizeGateMarkerSummary(markerSummary.pre_approval_gate);
+  // loadDevLoopConfig never throws: it returns { config, warnings, errors }.
+  // A non-empty errors array means the config could not be loaded/validated, so
+  // treat it as config-unavailable and leave fan-out enforcement disabled
+  // (preserves default behavior). Other gate checks remain unaffected.
+  let config = null;
+  const { config: loadedConfig, errors: configErrors } = await loadDevLoopConfig({ repoRoot: cwd });
+  config = Array.isArray(configErrors) && configErrors.length > 0 ? null : loadedConfig;
+  const fanoutEnforcement = await buildFanoutEnforcement({
+    repo: options.repo,
+    pr: options.pr,
+    currentHeadSha,
+    draftGateMarker,
+    preApprovalGateMarker,
+    config,
+    cwd,
+  });
   return {
     ok: true,
     repo: options.repo,
@@ -306,9 +396,10 @@ export async function detectCheckpointEvidence(options, { env = process.env, ghC
     currentHeadSha,
     draftGate: normalizeGateSummary(commentSummary.draft_gate),
     preApprovalGate: normalizeGateSummary(commentSummary.pre_approval_gate),
-    draftGateMarker: normalizeGateMarkerSummary(markerSummary.draft_gate),
-    preApprovalGateMarker: normalizeGateMarkerSummary(markerSummary.pre_approval_gate),
+    draftGateMarker,
+    preApprovalGateMarker,
     draftGateSatisfied: commentSummary.draft_gate?.verdict === "clean" && typeof commentSummary.draft_gate?.headSha === "string",
+    fanoutEnforcement,
     ...(runnerOwnership.status !== "skipped_no_async_run_id" ? { runnerOwnership } : {}),
     staleRunner: {
       status: staleRunnerDetection.status,
@@ -351,7 +442,7 @@ async function main() {
         ? [`exit signal recorded for run ${result.staleRunner.activeRun?.runId}: refuse to merge`]
         : [],
     };
-    const preMergeGateCheck = buildPreMergeGateCheck(result, unresolvedThreadCount, staleRunnerCheck);
+    const preMergeGateCheck = buildPreMergeGateCheck(result, unresolvedThreadCount, staleRunnerCheck, result.fanoutEnforcement);
     const output = { ...result, preMergeGateCheck, staleRunnerCheck };
     if (!preMergeGateCheck.ok) {
       process.stderr.write(`${JSON.stringify({

package/scripts/github/post-gate-findings.mjs

@@ -0,0 +1,392 @@
+#!/usr/bin/env node
+import { parsePrNumber, requireOptionValue, runChild } from "../_cli-primitives.mjs";
+import { formatCliError, isDirectCliRun, parseJsonText } from "../_core-helpers.mjs";
+import { loadDevLoopConfig, resolveGatePostFindingsComments } from "@dev-loops/core/config";
+import { parseRepoSlug } from "@dev-loops/core/github/repo-slug";
+
+const USAGE = `Usage: post-gate-findings.mjs --repo <owner/name> --pr <number> --gate <draft_gate|pre_approval_gate> --head-sha <sha> --findings <json>
+Post (or idempotently update) a visible, marker-tagged PR issue comment that lists the
+consolidated gate fan-out findings, grouped by severity. The comment is idempotent
+per gate: there is exactly one comment per gate, updated in place on each run
+(the reviewed head is shown in the body) instead of duplicating it.
+
+The disposition ledger (write-gate-findings-log.mjs) is the durable source of truth and is
+written regardless of this comment. This helper only posts the auditable PR summary, and
+no-ops when gates.postFindingsComments is set to false in config.
+
+Required:
+  --repo <owner/name>
+  --pr <number>
+  --gate <draft_gate|pre_approval_gate>
+  --head-sha <sha>                 Current head SHA or hexadecimal prefix
+  --findings <json>                JSON array of findings in the findings-log shape
+                                   ([{severity, angle, summary, disposition?, files?}])
+Output (stdout, JSON):
+  { "ok": true, "action": "created"|"updated"|"noop"|"skipped", ... }
+Exit codes:
+  0  Success
+  1  Argument error or gh failure`.trim();
+
+const VALID_SEVERITIES = new Set(["must-fix", "worth-fixing-now", "defer"]);
+// Severity ordering for grouped rendering (most-blocking first).
+const SEVERITY_ORDER = ["must-fix", "worth-fixing-now", "defer"];
+const SEVERITY_LABELS = {
+  "must-fix": "Must fix",
+  "worth-fixing-now": "Worth fixing now",
+  "defer": "Defer",
+};
+
+function parseError(message) {
+  return Object.assign(new Error(message), { usage: USAGE });
+}
+
+function normalizeGate(value) {
+  const gates = new Set(["draft_gate", "pre_approval_gate"]);
+  const normalized = String(value).trim().toLowerCase();
+  return gates.has(normalized) ? normalized : null;
+}
+
+function normalizeHeadSha(value) {
+  const normalized = String(value).trim().toLowerCase();
+  return /^[0-9a-f]{7,64}$/i.test(normalized) ? normalized : null;
+}
+
+// Validate via the centralized repo-slug validator shared by sibling GitHub
+// scripts (parseRepoSlug). It enforces owner/name structure and rejects unsafe
+// segments (".", "..", slashes, whitespace); we re-throw as a parseError so the
+// CLI usage banner is preserved.
+function validateRepo(repo) {
+  try {
+    parseRepoSlug(repo);
+  } catch (error) {
+    throw parseError(error instanceof Error ? error.message : String(error));
+  }
+  return repo;
+}
+
+export function parseFindings(raw) {
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    throw parseError("--findings must be valid JSON");
+  }
+  if (!Array.isArray(parsed)) {
+    throw parseError("--findings must be a JSON array");
+  }
+  return parsed.map((f, i) => {
+    if (!f || typeof f !== "object") {
+      throw parseError(`--findings[${i}] must be an object`);
+    }
+    if (!f.severity || !VALID_SEVERITIES.has(f.severity)) {
+      throw parseError(`--findings[${i}].severity must be one of: must-fix, worth-fixing-now, defer`);
+    }
+    if (!f.angle || typeof f.angle !== "string" || f.angle.trim().length === 0) {
+      throw parseError(`--findings[${i}].angle is required`);
+    }
+    if (!f.summary || typeof f.summary !== "string" || f.summary.trim().length === 0) {
+      throw parseError(`--findings[${i}].summary is required`);
+    }
+    const entry = {
+      severity: f.severity,
+      angle: f.angle.trim(),
+      summary: f.summary.trim(),
+    };
+    if ("disposition" in f && typeof f.disposition === "string" && f.disposition.trim().length > 0) {
+      entry.disposition = f.disposition.trim();
+    }
+    if (Array.isArray(f.files)) {
+      entry.files = f.files.filter(x => typeof x === "string" && x.trim().length > 0).map(x => x.trim());
+    }
+    return entry;
+  });
+}
+
+export function parsePostGateFindingsCliArgs(argv) {
+  const args = [...argv];
+  const options = {
+    help: false,
+    repo: undefined,
+    pr: undefined,
+    gate: undefined,
+    headSha: undefined,
+    findings: undefined,
+  };
+  while (args.length > 0) {
+    const token = args.shift();
+    if (token === "--help" || token === "-h") {
+      options.help = true;
+      return options;
+    }
+    if (token === "--repo") {
+      options.repo = validateRepo(requireOptionValue(args, "--repo", parseError).trim());
+      continue;
+    }
+    if (token === "--pr") {
+      options.pr = parsePrNumber(requireOptionValue(args, "--pr", parseError), parseError);
+      continue;
+    }
+    if (token === "--gate") {
+      const gate = normalizeGate(requireOptionValue(args, "--gate", parseError));
+      if (!gate) throw parseError("--gate must be draft_gate or pre_approval_gate");
+      options.gate = gate;
+      continue;
+    }
+    if (token === "--head-sha") {
+      const sha = normalizeHeadSha(requireOptionValue(args, "--head-sha", parseError));
+      if (!sha) throw parseError("--head-sha must be a 7-64 character hex SHA");
+      options.headSha = sha;
+      continue;
+    }
+    if (token === "--findings") {
+      options.findings = requireOptionValue(args, "--findings", parseError);
+      continue;
+    }
+    throw parseError(`Unknown argument: ${token}`);
+  }
+  const missing = ["repo", "pr", "gate", "headSha", "findings"]
+    .filter(k => options[k] === undefined);
+  if (missing.length > 0) {
+    throw parseError(`Missing required arguments: ${missing.join(", ")}`);
+  }
+  return options;
+}
+
+// Hidden marker keyed by GATE ONLY. There is exactly one findings comment per
+// gate, updated in place each run. The marker deliberately does NOT include the
+// head SHA: --head-sha accepts any 7-64 hex prefix, so keying on its literal
+// value would let a different prefix length (or the full SHA) for the same head
+// miss the marker and post a duplicate. The reviewed head is still shown in the
+// comment body for context. The HTML comment is not rendered by GitHub but is
+// matched on the comment body.
+export function buildFindingsMarker({ gate }) {
+  return `<!-- dev-loops:gate-findings gate=${gate} -->`;
+}
+
+// Collapse any run of whitespace (newlines, tabs, repeated spaces) to a single
+// space and trim. LLM-generated free text often carries embedded newlines, which
+// would otherwise break a single Markdown list item across lines.
+//
+// Additionally neutralize any embedded HTML-comment delimiters (`<!--` / `-->`).
+// The findings comment is keyed by a hidden marker that IS an HTML comment
+// (buildFindingsMarker), and free text comes from scoped-review agents. Without
+// this, a finding field could inject a second `<!-- dev-loops:gate-findings ... -->`
+// marker (breaking idempotent comment matching) or otherwise smuggle an HTML
+// comment into the rendered body. We escape the opening/closing angle brackets so
+// the delimiter renders as visible literal text and cannot form a real comment.
+function sanitizeInline(value) {
+  return String(value)
+    .replace(/\s+/g, " ")
+    .replace(/<!--/g, "&lt;!--")
+    .replace(/-->/g, "--&gt;")
+    .trim();
+}
+
+// Sanitize free text that is rendered INSIDE an inline backtick code span
+// (`angle`, file refs). On top of sanitizeInline, strip any literal backtick:
+// a backtick inside the span would prematurely close it, breaking out into raw
+// Markdown (injection) for the remainder of the list item. Backticks are never
+// meaningful in an angle label or a file path, so dropping them is safe.
+function sanitizeCodeSpan(value) {
+  return sanitizeInline(String(value).replace(/`/g, ""));
+}
+
+export function renderFindingsCommentBody({ gate, headSha, findings }) {
+  const marker = buildFindingsMarker({ gate });
+  const lines = [
+    marker,
+    `### Gate fan-out findings: ${gate}`,
+    "",
+    // Plain text head SHA (no backticks) so GitHub autolinks the commit.
+    `Reviewed head: ${headSha}`,
+    "",
+  ];
+  if (findings.length === 0) {
+    lines.push("No findings. All review angles passed for this head.");
+    return lines.join("\n");
+  }
+  const grouped = new Map();
+  for (const sev of SEVERITY_ORDER) {
+    grouped.set(sev, []);
+  }
+  for (const finding of findings) {
+    grouped.get(finding.severity).push(finding);
+  }
+  for (const sev of SEVERITY_ORDER) {
+    const group = grouped.get(sev);
+    if (group.length === 0) continue;
+    lines.push(`#### ${SEVERITY_LABELS[sev]} (${group.length})`);
+    for (const finding of group) {
+      // Sanitize free-text fields so embedded newlines/whitespace don't break
+      // the single-line Markdown list item.
+      const summary = sanitizeInline(finding.summary);
+      const dispositionSuffix = finding.disposition ? ` — _${sanitizeInline(finding.disposition)}_` : "";
+      // angle is a code/label literal → backticks; summary is prose. angle is
+      // free text from a scoped-review agent and is rendered inside an inline
+      // code span, so it must be sanitized too: an embedded backtick or newline
+      // would otherwise break the code span (markdown injection) or split the
+      // list item. Use sanitizeCodeSpan (backtick-stripping) since it lives
+      // inside backticks, consistent with the file refs below.
+      const angle = sanitizeCodeSpan(finding.angle);
+      lines.push(`- \`${angle}\`: ${summary}${dispositionSuffix}`);
+      if (Array.isArray(finding.files) && finding.files.length > 0) {
+        // File refs go inside backticks; sanitize each so embedded whitespace,
+        // newlines, or backticks can't break the single Markdown list item /
+        // code span, and drop any that sanitize to empty.
+        const refs = finding.files
+          .map(f => sanitizeCodeSpan(f))
+          .filter(f => f.length > 0)
+          .map(f => `\`${f}\``)
+          .join(", ");
+        if (refs.length > 0) {
+          lines.push(`  - files: ${refs}`);
+        }
+      }
+    }
+    lines.push("");
+  }
+  // Drop trailing blank line.
+  while (lines.length > 0 && lines[lines.length - 1] === "") {
+    lines.pop();
+  }
+  return lines.join("\n");
+}
+
+async function runGhJson(args, { env, ghCommand }) {
+  const result = await runChild(ghCommand, args, env);
+  if (result.code !== 0) {
+    const detail = result.stderr.trim() || `exit code ${result.code}`;
+    throw new Error(`gh command failed: ${detail}`);
+  }
+  return parseJsonText(result.stdout, { label: `gh ${args.slice(0, 3).join(" ")}` });
+}
+
+async function listIssueComments({ repo, pr }, { env, ghCommand }) {
+  const payload = await runGhJson(
+    ["api", "--paginate", "--slurp", `repos/${repo}/issues/${pr}/comments?per_page=100`],
+    { env, ghCommand },
+  );
+  // --slurp returns an array of pages; flatten to a single comment list.
+  if (Array.isArray(payload) && payload.every(p => Array.isArray(p))) {
+    return payload.flat();
+  }
+  return Array.isArray(payload) ? payload : [];
+}
+
+function findMarkedComment(comments, marker) {
+  for (const comment of comments) {
+    if (comment && typeof comment.body === "string" && comment.body.includes(marker)) {
+      return comment;
+    }
+  }
+  return null;
+}
+
+function parseCommentMutationResponse(payload) {
+  const commentId = Number.isInteger(payload?.id) ? payload.id : null;
+  const commentUrl = typeof payload?.html_url === "string" && payload.html_url.trim().length > 0
+    ? payload.html_url.trim()
+    : null;
+  if (commentId === null || commentUrl === null) {
+    throw new Error("Gate findings comment mutation did not return a comment id and html_url");
+  }
+  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 },
+  );
+  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 },
+  );
+  return parseCommentMutationResponse(payload);
+}
+
+export async function postGateFindings(options, { env = process.env, ghCommand = "gh", repoRoot = process.cwd() } = {}) {
+  const findings = parseFindings(options.findings);
+  // loadDevLoopConfig never throws: it returns { config, warnings, errors }.
+  // A non-empty errors array means the config could not be loaded/validated, so
+  // log it (stderr) and fall back to default behavior (config-unavailable →
+  // null → resolveGatePostFindingsComments defaults on → proceed to post),
+  // rather than trusting a malformed/partial config object. Mirrors how
+  // detect-checkpoint-evidence treats config-unavailable.
+  const { config: loadedConfig, errors: configErrors } = await loadDevLoopConfig({ repoRoot });
+  let config = loadedConfig;
+  if (Array.isArray(configErrors) && configErrors.length > 0) {
+    process.stderr.write(
+      `post-gate-findings: dev-loop config could not be loaded/validated; using default behavior. errors=${JSON.stringify(configErrors)}\n`,
+    );
+    config = null;
+  }
+  if (!resolveGatePostFindingsComments(config)) {
+    return {
+      ok: true,
+      action: "skipped",
+      reason: "gates.postFindingsComments is false",
+      repo: options.repo,
+      pr: options.pr,
+      gate: options.gate,
+      headSha: options.headSha,
+      findingsCount: findings.length,
+    };
+  }
+  const marker = buildFindingsMarker({ gate: options.gate });
+  const desiredBody = renderFindingsCommentBody({ gate: options.gate, headSha: options.headSha, findings });
+  const comments = await listIssueComments({ repo: options.repo, pr: options.pr }, { env, ghCommand });
+  const existing = findMarkedComment(comments, marker);
+  const base = {
+    ok: true,
+    repo: options.repo,
+    pr: options.pr,
+    gate: options.gate,
+    headSha: options.headSha,
+    findingsCount: findings.length,
+  };
+  if (existing) {
+    if (typeof existing.body === "string" && existing.body === desiredBody) {
+      return {
+        ...base,
+        action: "noop",
+        commentId: Number.isInteger(existing.id) ? existing.id : null,
+        commentUrl: typeof existing.html_url === "string" ? existing.html_url : null,
+      };
+    }
+    const updated = await updateComment({ repo: options.repo, commentId: existing.id, body: desiredBody }, { env, ghCommand });
+    return { ...base, action: "updated", ...updated };
+  }
+  const created = await createComment({ repo: options.repo, pr: options.pr, body: desiredBody }, { env, ghCommand });
+  return { ...base, action: "created", ...created };
+}
+
+async function main() {
+  let options;
+  try {
+    options = parsePostGateFindingsCliArgs(process.argv.slice(2));
+  } catch (error) {
+    process.stderr.write(`${formatCliError(error, { usage: USAGE })}\n`);
+    process.exitCode = 1;
+    return;
+  }
+  if (options.help) {
+    process.stdout.write(`${USAGE}\n`);
+    return;
+  }
+  try {
+    const result = await postGateFindings(options);
+    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`);
+    process.exitCode = 1;
+  }
+}
+
+if (isDirectCliRun(import.meta.url)) {
+  await main();
+}

package/scripts/github/reconcile-draft-gate.mjs

@@ -124,7 +124,7 @@ async function resolvePrNodeId({ repo, pr }, { env, ghCommand }) {
   }
   return { id: prData.id, isDraft: prData.isDraft };
 }
-async function convertPrToDraft({ repo, pr }, { env, ghCommand }) {
+export async function convertPrToDraft({ repo, pr }, { env, ghCommand }) {
   const resolvedPr = await resolvePrNodeId({ repo, pr }, { env, ghCommand });
   if (resolvedPr.isDraft === true) {
     return {
@@ -154,7 +154,7 @@ async function convertPrToDraft({ repo, pr }, { env, ghCommand }) {
     alreadyDraft: false,
   };
 }
-async function markPrReady({ repo, pr }, { env, ghCommand }) {
+export async function markPrReady({ repo, pr }, { env, ghCommand }) {
   const result = await runChild(ghCommand, [
     "pr", "ready", String(pr),
     "--repo", repo,