dev-loops 0.2.7 → 0.4.0

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/offer-human-handoff.mjs

@@ -0,0 +1,147 @@
+#!/usr/bin/env node
+import { buildParseError, formatCliError, isDirectCliRun } from "../_core-helpers.mjs";
+import { parsePrNumber, runChild } from "../_cli-primitives.mjs";
+import { parseRepoSlug } from "@dev-loops/core/github/repo-slug";
+import { loadDevLoopConfig } from "@dev-loops/core/config";
+import { resolveHandoffCandidates } from "./resolve-handoff-candidates.mjs";
+
+const USAGE = `Usage: offer-human-handoff.mjs --repo <owner/name> --pr <number> [--assign <login>...] [--request-review <login>...] [--changed-files <csv>] [--pr-author <login>]
+Human-handoff offer at the pre-approval / merge-handoff boundary (#920, Request B
+of #910). OFFER-only: without --assign/--request-review it resolves and prints
+the candidate list (the "offer"); the operator confirms who takes it. With
+--assign / --request-review it performs the confirmed action via \`gh pr edit\`.
+
+This pairs with autonomy.humanMergeOnly: when human-merge is enforced, the offer
+names who should take the merge. No-op when approval.humanHandoff is disabled
+(default) — prints an empty offer.
+
+Required:
+  --repo <owner/name>
+  --pr <number>
+Optional:
+  --assign <login>          Add a confirmed assignee (repeatable). Performs
+                            \`gh pr edit --add-assignee\`.
+  --request-review <login>  Request review from a confirmed reviewer (repeatable).
+                            Performs \`gh pr edit --add-reviewer\`.
+  --changed-files <csv>     Forwarded to the candidate resolver.
+  --pr-author <login>       Forwarded to the candidate resolver.
+Output (stdout, JSON):
+  Offer mode:  { "ok": true, "mode": "offer", "enabled", "candidates": [...], ... }
+  Apply mode:  { "ok": true, "mode": "apply", "assigned": [...], "requestedReview": [...] }
+Exit codes:
+  0  Success (including disabled no-op offer)
+  1  Argument error or gh failure`.trim();
+
+const parseError = buildParseError(USAGE);
+
+function nextValue(args, i, flag) {
+  const value = args[i];
+  if (typeof value !== "string" || value.length === 0 || value.startsWith("--")) {
+    throw parseError(`Missing value for ${flag}`);
+  }
+  return value;
+}
+
+// A login flag value with the leading `@` stripped and trimmed. Reject an empty
+// result (e.g. `--assign @`) so a blank login can never reach `gh pr edit
+// --add-assignee ""`.
+function loginValue(args, i, flag) {
+  const login = nextValue(args, i, flag).trim().replace(/^@/, "").trim();
+  if (login === "") throw parseError(`${flag} requires a non-empty login`);
+  return login;
+}
+
+export function parseOfferCliArgs(argv) {
+  const args = [...argv];
+  if (args.includes("--help") || args.includes("-h")) return { help: true };
+  const options = {
+    help: false, repo: undefined, pr: undefined,
+    assign: [], requestReview: [], changedFiles: undefined, prAuthor: undefined,
+  };
+  for (let i = 0; i < args.length; i += 1) {
+    const token = args[i];
+    if (token === "--repo") { options.repo = nextValue(args, ++i, "--repo"); continue; }
+    if (token === "--pr") { options.pr = parsePrNumber(nextValue(args, ++i, "--pr"), parseError); continue; }
+    if (token === "--assign") { options.assign.push(loginValue(args, ++i, "--assign")); continue; }
+    if (token === "--request-review") { options.requestReview.push(loginValue(args, ++i, "--request-review")); continue; }
+    if (token === "--changed-files") {
+      options.changedFiles = nextValue(args, ++i, "--changed-files")
+        .split(",").map((s) => s.trim()).filter((s) => s.length > 0);
+      continue;
+    }
+    if (token === "--pr-author") { options.prAuthor = nextValue(args, ++i, "--pr-author").trim().replace(/^@/, ""); continue; }
+    throw parseError(`Unknown argument: ${token}`);
+  }
+  if (options.repo === undefined || options.pr === undefined) {
+    throw parseError("Offering human handoff requires both --repo <owner/name> and --pr <number>");
+  }
+  try {
+    parseRepoSlug(options.repo);
+  } catch (error) {
+    throw parseError(error instanceof Error ? error.message : String(error));
+  }
+  return options;
+}
+
+/**
+ * Perform the confirmed assign / request-review actions via `gh pr edit`.
+ * OFFER-only contract: this is reached only when the operator passed
+ * --assign / --request-review (the confirmation). It never auto-assigns.
+ * @returns {Promise<{ ok: boolean, mode: "apply", assigned: string[], requestedReview: string[] }>}
+ */
+export async function applyHandoff({ repo, pr, assign, requestReview }, { run = (cmd, args) => runChild(cmd, args), ghCommand = "gh" } = {}) {
+  const ghArgs = ["pr", "edit", String(pr), "--repo", repo];
+  for (const login of assign) ghArgs.push("--add-assignee", login);
+  for (const login of requestReview) ghArgs.push("--add-reviewer", login);
+  const result = await run(ghCommand, ghArgs);
+  if (result.code !== 0) {
+    throw new Error(result.stderr.trim() || `gh pr edit exited ${result.code}`);
+  }
+  return { ok: true, mode: "apply", assigned: assign, requestedReview: requestReview };
+}
+
+export async function main(argv = process.argv.slice(2), deps = {}) {
+  let options;
+  try {
+    options = parseOfferCliArgs(argv);
+  } catch (error) {
+    process.stderr.write(`${formatCliError(error)}\n`);
+    return 1;
+  }
+  if (options.help) {
+    process.stdout.write(`${USAGE}\n`);
+    return 0;
+  }
+
+  const run = deps.run ?? ((cmd, args) => runChild(cmd, args));
+  const ghCommand = deps.ghCommand ?? "gh";
+
+  // Apply mode: operator confirmed an assignee/reviewer.
+  if (options.assign.length > 0 || options.requestReview.length > 0) {
+    try {
+      const applied = await applyHandoff(
+        { repo: options.repo, pr: options.pr, assign: options.assign, requestReview: options.requestReview },
+        { run, ghCommand },
+      );
+      process.stdout.write(`${JSON.stringify(applied)}\n`);
+      return 0;
+    } catch (error) {
+      process.stderr.write(`${formatCliError(error)}\n`);
+      return 1;
+    }
+  }
+
+  // Offer mode: resolve + print candidates, assign nobody.
+  const repoRoot = deps.repoRoot ?? process.cwd();
+  const config = deps.config !== undefined ? deps.config : (await loadDevLoopConfig({ repoRoot })).config;
+  const offer = await resolveHandoffCandidates(
+    { repo: options.repo, pr: options.pr, changedFiles: options.changedFiles, prAuthor: options.prAuthor ?? null },
+    { ...deps, config, repoRoot, run, ghCommand },
+  );
+  process.stdout.write(`${JSON.stringify({ ...offer, mode: "offer" })}\n`);
+  return 0;
+}
+
+if (isDirectCliRun(import.meta.url)) {
+  main().then((code) => { process.exitCode = code; });
+}