dev-loops 0.2.6 → 0.3.0

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

@@ -1,4 +1,5 @@
 #!/usr/bin/env node
+import { parseArgs } from "node:util";
 import {
   buildParseError,
   formatCliError,
@@ -8,9 +9,13 @@ import {
   summarizeGateReviewCommentMarkers,
   summarizeGateReviewComments,
 } from "../_core-helpers.mjs";
-import { parsePrNumber, requireOptionValue, runChild } from "../_cli-primitives.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>
@@ -84,30 +89,46 @@ Exit codes:
   1  Argument error, gh failure, malformed gh JSON, or missing required pre-merge gate evidence.`.trim();
 const parseError = buildParseError(USAGE);
 export function parseDetectCheckpointEvidenceCliArgs(argv) {
-  const args = [...argv];
+  const { tokens } = parseArgs({
+    args: [...argv],
+    options: {
+      help: { type: "boolean", short: "h" },
+      repo: { type: "string" },
+      pr: { type: "string" },
+      "require-before-merge": { type: "boolean" },
+    },
+    allowPositionals: true,
+    strict: false,
+    tokens: true,
+  });
   const options = {
     help: false,
     repo: undefined,
     pr: 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 (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 === "--require-before-merge") {
+    if (token.name === "require-before-merge") {
       throw parseError(`--require-before-merge has been removed: gate evidence enforcement is now always-on by default. Omit the flag.`);
     }
-    throw parseError(`Unknown argument: ${token}`);
+    throw parseError(`Unknown argument: ${token.rawName}`);
   }
   if (options.repo === undefined || options.pr === undefined) {
     throw parseError("detect-checkpoint-evidence requires both --repo <owner/name> and --pr <number>");
@@ -183,6 +204,8 @@ function emptyGateMarkerSummary() {
     verdict: null,
     findingsSummary: null,
     nextAction: null,
+    executionMode: null,
+    inlineReason: null,
     contractComplete: false,
     commentId: null,
     commentUrl: null,
@@ -199,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");
@@ -219,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");
@@ -236,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,
@@ -282,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,
@@ -289,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,
@@ -334,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/detect-linked-issue-pr.mjs

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
+import { parseArgs } from "node:util";
 import { buildParseError, formatCliError, isDirectCliRun, parseJsonText } from "../_core-helpers.mjs";
-import { parseIssueNumber, requireOptionValue, runChild } from "../_cli-primitives.mjs";
+import { parseIssueNumber, requireTokenValue, runChild } from "../_cli-primitives.mjs";
 import { parseRepoSlug } from "@dev-loops/core/github/repo-slug";
 export const LINKED_ISSUE_PR_QUERY = [
   "query($owner:String!, $name:String!, $issue:Int!, $after:String) {",
@@ -75,27 +76,38 @@ Error output (stderr, JSON):
     { "ok": false, "error": "..." }`.trim();
 const parseError = buildParseError(USAGE);
 export function parseDetectLinkedIssuePrCliArgs(argv) {
-  const args = [...argv];
+  const { tokens } = parseArgs({
+    args: [...argv],
+    options: { help: { type: "boolean", short: "h" }, repo: { type: "string" }, issue: { type: "string" } },
+    allowPositionals: true,
+    strict: false,
+    tokens: true,
+  });
   const options = {
     help: false,
     repo: undefined,
     issue: 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 (token === "--repo") {
-      options.repo = requireOptionValue(args, "--repo", parseError).trim();
+    if (token.name === "repo") {
+      options.repo = requireTokenValue(token, parseError).trim();
       continue;
     }
-    if (token === "--issue") {
-      options.issue = parseIssueNumber(requireOptionValue(args, "--issue", parseError), parseError);
+    if (token.name === "issue") {
+      options.issue = parseIssueNumber(requireTokenValue(token, parseError), parseError);
       continue;
     }
-    throw parseError(`Unknown argument: ${token}`);
+    throw parseError(`Unknown argument: ${token.rawName}`);
   }
   if (options.repo === undefined || options.issue === undefined) {
     throw parseError("Linked PR detection requires both --repo <owner/name> and --issue <number>");

package/scripts/github/manage-sub-issues.mjs

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
+import { parseArgs } from "node:util";
 import { buildParseError, formatCliError, isDirectCliRun, parseJsonText } from "../_core-helpers.mjs";
-import { parsePositiveInteger, requireOptionValue, runChild } from "../_cli-primitives.mjs";
+import { parsePositiveInteger, requireTokenValue, runChild } from "../_cli-primitives.mjs";
 import { parseRepoSlug } from "@dev-loops/core/github/repo-slug";
 const USAGE = `Usage: manage-sub-issues.mjs <command> --repo <owner/name> --issue <number> [options]
 Deterministic helper for reading, linking, ordering, and verifying GitHub sub-issue trees.
@@ -76,37 +77,57 @@ export function parseManageSubIssuesCliArgs(argv) {
     expected: undefined,
     ordered: false,
   };
-  while (args.length > 0) {
-    const token = args.shift();
-    if (token === "--help" || token === "-h") {
+  const { tokens } = parseArgs({
+    args,
+    options: {
+      help: { type: "boolean", short: "h" },
+      repo: { type: "string" },
+      issue: { type: "string" },
+      child: { type: "string" },
+      order: { type: "string" },
+      expected: { type: "string" },
+      ordered: { type: "boolean" },
+    },
+    allowPositionals: true,
+    strict: false,
+    tokens: true,
+  });
+  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 (token === "--repo") {
-      options.repo = requireOptionValue(args, "--repo", parseError).trim();
+    if (token.name === "repo") {
+      options.repo = requireTokenValue(token, parseError).trim();
       continue;
     }
-    if (token === "--issue") {
-      options.issue = parsePositiveInteger(requireOptionValue(args, "--issue", parseError), "Issue number", parseError);
+    if (token.name === "issue") {
+      options.issue = parsePositiveInteger(requireTokenValue(token, parseError), "Issue number", parseError);
       continue;
     }
-    if (token === "--child") {
-      options.child = parsePositiveInteger(requireOptionValue(args, "--child", parseError), "Issue number", parseError);
+    if (token.name === "child") {
+      options.child = parsePositiveInteger(requireTokenValue(token, parseError), "Issue number", parseError);
       continue;
     }
-    if (token === "--order") {
-      options.order = parseIssueList(requireOptionValue(args, "--order", parseError));
+    if (token.name === "order") {
+      options.order = parseIssueList(requireTokenValue(token, parseError));
       continue;
     }
-    if (token === "--expected") {
-      options.expected = parseIssueList(requireOptionValue(args, "--expected", parseError));
+    if (token.name === "expected") {
+      options.expected = parseIssueList(requireTokenValue(token, parseError));
       continue;
     }
-    if (token === "--ordered") {
+    if (token.name === "ordered") {
       options.ordered = true;
       continue;
     }
-    throw parseError(`Unknown argument: ${token}`);
+    throw parseError(`Unknown argument: ${token.rawName}`);
   }
   if (options.repo === undefined || options.issue === undefined) {
     throw parseError("Both --repo <owner/name> and --issue <number> are required");