@dev-loops/core 0.2.6 → 0.3.0

package/src/loop/gate-fanin.mjs

@@ -0,0 +1,222 @@
+/**
+ * gate-fanin.mjs — pure fan-in consolidation + cap/batch planning for the
+ * gate-review fork sub-loop (epic #867, Phase 3 / #878).
+ *
+ * IMPORTANT: this module is PURE. It performs no I/O and never spawns agents.
+ * Spawning the per-angle scoped `review` subagents is an agent-orchestrated
+ * skill procedure (a node script cannot spawn Claude subagents). This module
+ * only consolidates the structured per-angle findings artifacts the fan-out
+ * produced, decides the gate verdict, plans the parallel/sequential batching of
+ * the fan-out, and maps consolidated findings into the `--findings` JSON shape
+ * understood by scripts/github/write-gate-findings-log.mjs.
+ *
+ * Per-angle review artifact shape (produced by the scoped `review` agent):
+ *   {
+ *     angle: string,
+ *     verdict: "clean" | "findings_present",
+ *     findings: [{ severity, file?, line?, summary, recommendation? }]
+ *   }
+ *
+ * Severity vocabulary (mirrors write-gate-findings-log.mjs):
+ *   "must-fix" | "worth-fixing-now" | "defer"
+ */
+
+const VALID_SEVERITIES = new Set(["must-fix", "worth-fixing-now", "defer"]);
+const VALID_VERDICTS = new Set(["clean", "findings_present"]);
+
+/**
+ * Default cap on parallel fan-out reviewers when a caller does not supply one.
+ * Mirrors the config default (gates.maxFanoutReviewers).
+ */
+export const DEFAULT_MAX_FANOUT_REVIEWERS = 8;
+
+/**
+ * Validate a single per-angle review result. Returns an error string when the
+ * result is malformed, or null when it is well-formed.
+ *
+ * @param {unknown} result
+ * @returns {string|null}
+ */
+function validateAngleResult(result) {
+  if (!result || typeof result !== "object" || Array.isArray(result)) {
+    return "angle result must be an object";
+  }
+  const r = /** @type {Record<string, unknown>} */ (result);
+  if (typeof r.angle !== "string" || r.angle.trim().length === 0) {
+    return "angle result is missing a non-empty 'angle'";
+  }
+  if (typeof r.verdict !== "string" || !VALID_VERDICTS.has(r.verdict)) {
+    return `angle '${r.angle}' has invalid verdict (expected clean|findings_present)`;
+  }
+  if (!Array.isArray(r.findings)) {
+    return `angle '${r.angle}' is missing a 'findings' array`;
+  }
+  for (const f of r.findings) {
+    if (!f || typeof f !== "object" || Array.isArray(f)) {
+      return `angle '${r.angle}' has a non-object finding`;
+    }
+    const finding = /** @type {Record<string, unknown>} */ (f);
+    if (typeof finding.severity !== "string" || !VALID_SEVERITIES.has(finding.severity)) {
+      return `angle '${r.angle}' has a finding with invalid severity (expected must-fix|worth-fixing-now|defer)`;
+    }
+    if (typeof finding.summary !== "string" || finding.summary.trim().length === 0) {
+      return `angle '${r.angle}' has a finding without a summary`;
+    }
+  }
+  // findings_present must carry at least one finding; clean must carry none.
+  if (r.verdict === "findings_present" && r.findings.length === 0) {
+    return `angle '${r.angle}' reported findings_present but has no findings`;
+  }
+  if (r.verdict === "clean" && r.findings.length > 0) {
+    return `angle '${r.angle}' reported clean but carries findings`;
+  }
+  return null;
+}
+
+/**
+ * Consolidate the parallel per-angle review results into one gate verdict +
+ * a merged, flattened findings list. Pure.
+ *
+ * Verdict rules:
+ *   - "blocked": any angle result is malformed/missing (the gate could not
+ *     produce a trustworthy verdict).
+ *   - "clean": all results valid AND no finding carries a severity present in
+ *     `blockCleanOnFindingSeverities`.
+ *   - "findings_present": all results valid AND at least one finding carries a
+ *     blocking severity.
+ *
+ * @param {object} input
+ * @param {Array<unknown>} input.angleResults — per-angle review artifacts
+ * @param {string[]} [input.blockCleanOnFindingSeverities] — blocking severities (default ["must-fix"])
+ * @returns {{
+ *   verdict: "clean"|"findings_present"|"blocked",
+ *   findings: Array<{severity: string, angle: string, summary: string, file?: string, line?: number, recommendation?: string, disposition: string}>,
+ *   counts: { angles: number, findings: number, blocking: number, bySeverity: Record<string, number> },
+ *   malformed: Array<{ index: number, reason: string }>
+ * }}
+ */
+export function consolidateFanin({ angleResults, blockCleanOnFindingSeverities } = {}) {
+  const results = Array.isArray(angleResults) ? angleResults : [];
+  const blocking = new Set(
+    Array.isArray(blockCleanOnFindingSeverities) && blockCleanOnFindingSeverities.length > 0
+      ? blockCleanOnFindingSeverities
+      : ["must-fix"],
+  );
+
+  const malformed = [];
+  results.forEach((r, index) => {
+    const err = validateAngleResult(r);
+    if (err) malformed.push({ index, reason: err });
+  });
+
+  const bySeverity = { "must-fix": 0, "worth-fixing-now": 0, "defer": 0 };
+  /** @type {Array<{severity: string, angle: string, summary: string, file?: string, line?: number, recommendation?: string, disposition: string}>} */
+  const findings = [];
+  let blockingCount = 0;
+
+  if (malformed.length === 0) {
+    for (const r of results) {
+      const angle = r.angle.trim();
+      for (const f of r.findings) {
+        const isBlocking = blocking.has(f.severity);
+        if (isBlocking) blockingCount += 1;
+        bySeverity[f.severity] += 1;
+        const entry = {
+          severity: f.severity,
+          angle,
+          summary: String(f.summary).trim(),
+          // Blocking findings default to accepted-for-fix; non-blocking default
+          // to deferred. The fix cycle / operator can override the disposition.
+          disposition: isBlocking ? "accepted-for-fix" : "deferred",
+        };
+        if (typeof f.file === "string" && f.file.trim().length > 0) entry.file = f.file.trim();
+        if (typeof f.line === "number" && Number.isFinite(f.line)) entry.line = f.line;
+        if (typeof f.recommendation === "string" && f.recommendation.trim().length > 0) {
+          entry.recommendation = f.recommendation.trim();
+        }
+        findings.push(entry);
+      }
+    }
+  }
+
+  let verdict;
+  if (malformed.length > 0) {
+    verdict = "blocked";
+  } else if (blockingCount > 0) {
+    verdict = "findings_present";
+  } else {
+    verdict = "clean";
+  }
+
+  return {
+    verdict,
+    findings,
+    counts: {
+      angles: results.length,
+      findings: findings.length,
+      blocking: blockingCount,
+      bySeverity,
+    },
+    malformed,
+  };
+}
+
+/**
+ * Map consolidated findings into the `--findings` JSON shape consumed by
+ * scripts/github/write-gate-findings-log.mjs (severity, angle, summary,
+ * disposition, optional files). Pure.
+ *
+ * @param {Array<{severity: string, angle: string, summary: string, file?: string, disposition?: string}>} findings
+ * @returns {Array<{severity: string, angle: string, summary: string, disposition?: string, files?: string[]}>}
+ */
+export function toFindingsLogShape(findings) {
+  const list = Array.isArray(findings) ? findings : [];
+  return list.map((f) => {
+    const entry = {
+      severity: f.severity,
+      angle: f.angle,
+      summary: f.summary,
+    };
+    if (typeof f.disposition === "string" && f.disposition.trim().length > 0) {
+      entry.disposition = f.disposition.trim();
+    }
+    if (typeof f.file === "string" && f.file.trim().length > 0) {
+      entry.files = [f.file.trim()];
+    } else if (Array.isArray(f.files)) {
+      const files = f.files.filter((x) => typeof x === "string" && x.trim().length > 0).map((x) => x.trim());
+      if (files.length > 0) entry.files = files;
+    }
+    return entry;
+  });
+}
+
+/**
+ * Plan how a resolved angle set fans out across the reviewer cap. Pure.
+ *
+ * When `angles.length <= maxReviewers`, all reviewers run in a single parallel
+ * batch (no degradation). When it exceeds the cap, the overflow is split into
+ * sequential batches of at most `maxReviewers` each, and `degraded` is true so
+ * the skill can record the sequential degradation in the gate evidence.
+ *
+ * @param {string[]} angles
+ * @param {number} [maxReviewers] — default DEFAULT_MAX_FANOUT_REVIEWERS (8)
+ * @returns {{ batches: string[][], degraded: boolean }}
+ */
+export function planFanoutBatches(angles, maxReviewers = DEFAULT_MAX_FANOUT_REVIEWERS) {
+  const list = Array.isArray(angles)
+    ? angles.filter((a) => typeof a === "string" && a.trim().length > 0).map((a) => a.trim())
+    : [];
+  const cap = Number.isInteger(maxReviewers) && maxReviewers > 0
+    ? maxReviewers
+    : DEFAULT_MAX_FANOUT_REVIEWERS;
+
+  if (list.length === 0) {
+    return { batches: [], degraded: false };
+  }
+
+  const batches = [];
+  for (let i = 0; i < list.length; i += cap) {
+    batches.push(list.slice(i, i + cap));
+  }
+  return { batches, degraded: batches.length > 1 };
+}

package/src/loop/phase-files.mjs

@@ -1,6 +1,8 @@
 import { mkdir, readFile, writeFile } from "node:fs/promises";
 import path from "node:path";
 
+import { parseCliTokens } from "../cli/primitives.mjs";
+
 export function createDefaultPhaseManifest(phase) {
   return {
     phase,
@@ -134,45 +136,19 @@ export async function ensurePhaseFiles(projectRoot, phase, patch = {}) {
   };
 }
 
-function requireOptionValue(args, flag) {
-  const value = args.shift();
-
-  if (typeof value !== "string" || value.length === 0 || value.startsWith("--")) {
-    throw new Error(`Missing value for ${flag}`);
-  }
-
-  return value;
-}
-
 export function parseCliArgs(argv) {
-  const args = [...argv];
+  const { values } = parseCliTokens(argv, {
+    "project-root": { type: "string" },
+    phase: { type: "string" },
+    patch: { type: "string" },
+  });
+
   const options = {
-    projectRoot: process.cwd(),
-    phase: undefined,
-    patch: {},
+    projectRoot: values.has("project-root") ? values.get("project-root") : process.cwd(),
+    phase: values.get("phase"),
+    patch: values.has("patch") ? JSON.parse(values.get("patch")) : {},
   };
 
-  while (args.length > 0) {
-    const token = args.shift();
-
-    if (token === "--project-root") {
-      options.projectRoot = requireOptionValue(args, "--project-root");
-      continue;
-    }
-
-    if (token === "--phase") {
-      options.phase = requireOptionValue(args, "--phase");
-      continue;
-    }
-
-    if (token === "--patch") {
-      options.patch = JSON.parse(requireOptionValue(args, "--patch"));
-      continue;
-    }
-
-    throw new Error(`Unknown argument: ${token}`);
-  }
-
   if (!options.phase) {
     throw new Error("Missing required --phase <phase-name> argument");
   }

package/src/loop/pr-gate-coordination.mjs

@@ -479,6 +479,11 @@ function buildResult({
  * @param {number} params.copilotReviewRoundCount
  * @param {number|null} params.maxCopilotRounds
  * @param {boolean} params.sameHeadCleanConverged
+ * @param {boolean} [params.roundCapCleanFallback=false] - interpreter resolved the
+ *   round-cap clean fallback (#896): rounds exhausted + clean threads + green CI on
+ *   the current head, including a post-cap head Copilot has not (and will not)
+ *   re-review. No further Copilot round is permitted, so the formal-request guard
+ *   must not fire — the pre_approval_gate reviews the post-cap head (per #848).
  * @param {string} params.gateBoundary - current gate boundary
  * @returns {boolean}
  */
@@ -488,6 +493,7 @@ export function shouldGuardCopilotReviewRequest({
   copilotReviewEverFormallyRequested = false,
   maxCopilotRounds = null,
   sameHeadCleanConverged = false,
+  roundCapCleanFallback = false,
   gateBoundary,
 }) {
   const gateBoundariesRequiringCopilotFormalRequest = new Set([
@@ -513,12 +519,17 @@ export function shouldGuardCopilotReviewRequest({
   if (copilotReviewEverFormallyRequested) {
     return false;
   }
-  // Round-cap clean fallback: exhausted rounds + clean converged
-  // does not require a formal re-request.
+  // Round-cap clean fallback: exhausted rounds + clean converged does not require
+  // a formal re-request. This covers two shapes of "clean at the cap":
+  //  - sameHeadCleanConverged: the current head itself carries a clean Copilot review;
+  //  - roundCapCleanFallback (#896): the head is clean (zero unresolved threads + green
+  //    CI) but Copilot has NOT reviewed THIS head (e.g. a post-cap commit). No further
+  //    Copilot round is permitted, so forcing a formal request would dead-end the loop;
+  //    the pre_approval_gate reviews the post-cap head instead (per #848).
   const roundCapReached = maxCopilotRounds !== null
     && typeof copilotReviewRoundCount === "number"
     && copilotReviewRoundCount >= maxCopilotRounds;
-  if (roundCapReached && sameHeadCleanConverged) {
+  if (roundCapReached && (sameHeadCleanConverged || roundCapCleanFallback)) {
     return false;
   }
   return true;
@@ -1266,6 +1277,175 @@ function evaluatePrGateCoordinationCore(input = {}) {
     });
   }
 
+  // Round-cap clean fallback (#896, #848): the Copilot review round cap is
+  // exhausted and the current head is clean (zero unresolved threads + green CI)
+  // — including a POST-CAP head Copilot has not (and will not) re-review, since
+  // no further Copilot round is permitted. Re-requesting review is illegal here,
+  // so this MUST NOT dead-end at READY_TO_REREQUEST_REVIEW. It routes to the
+  // pre_approval_gate, which reviews the post-cap head itself (per #848). The CI
+  // guards below still hold (failing / credibly-green CI blocks), and conflicts /
+  // blocked states are handled earlier, so genuinely-blocked states still forbid
+  // pre_approval. Mirrors LOW_SIGNAL_CONVERGED routing with round-cap reasoning.
+  if (effectiveLifecycleState === STATE.ROUND_CAP_CLEAN_FALLBACK) {
+    if (ciStatus === "failure" || ciStatus === "crediblyGreen") {
+      pushUnique(allowedNextActions, [PR_CHECKPOINT_ACTION.REPORT_BLOCKED]);
+      pushUnique(forbiddenActions, postDraftForbidden);
+      return buildResult({
+        repo: input.repo ?? null,
+        pr: Number.isInteger(input.pr) ? input.pr : null,
+        currentHeadSha,
+        lifecycleState: STATE.BLOCKED_NEEDS_USER_DECISION,
+        loopDisposition: DISPOSITION.BLOCKED,
+        gateBoundary: PR_CHECKPOINT.BLOCKED,
+        draftGateAlreadySatisfied: true,
+        draftGate,
+        preApprovalGate,
+        allowedNextActions,
+        forbiddenActions,
+        nextAction: PR_CHECKPOINT_ACTION.REPORT_BLOCKED,
+        reason: ciStatus === "crediblyGreen"
+          ? "The Copilot round cap is exhausted, but the current head has unconfirmed CI (credibly green), so gate progression remains blocked until CI is confirmed green."
+          : "The Copilot round cap is exhausted, but the current head still has failing CI, so gate progression remains blocked until the failing checks are fixed and revalidated.",
+        mergeStateStatus,
+        conflictFiles,
+          refinementArtifact,
+      });
+    }
+    if (ciStatus === "pending" || ciStatus === "none") {
+      pushUnique(allowedNextActions, [PR_CHECKPOINT_ACTION.WAIT_FOR_CI]);
+      pushUnique(forbiddenActions, postDraftForbidden);
+      return buildResult({
+        repo: input.repo ?? null,
+        pr: Number.isInteger(input.pr) ? input.pr : null,
+        currentHeadSha,
+        lifecycleState: STATE.WAITING_FOR_CI,
+        loopDisposition: DISPOSITION.PENDING,
+        gateBoundary: PR_CHECKPOINT.POST_DRAFT_EXTERNAL_REVIEW,
+        draftGateAlreadySatisfied: true,
+        draftGate,
+        preApprovalGate,
+        allowedNextActions,
+        forbiddenActions,
+        nextAction: PR_CHECKPOINT_ACTION.WAIT_FOR_CI,
+        reason: "The Copilot round cap is exhausted, but the current head does not yet have green or credibly green CI, so `pre_approval_gate` remains illegal until CI settles.",
+        mergeStateStatus,
+        conflictFiles,
+          refinementArtifact,
+      });
+    }
+    if (preApprovalGate.currentHeadClean) {
+      const titleMarkers = findBlockingTitleMarkers(prTitle);
+      if (titleMarkers.length > 0) {
+        return buildTitleMarkerBlockedResult({
+          input,
+          currentHeadSha,
+          draftGateAlreadySatisfied: true,
+          draftGate,
+          preApprovalGate,
+          mergeStateStatus,
+          conflictFiles,
+          markers: titleMarkers,
+          refinementArtifact,
+        });
+      }
+      if (requireRetrospectiveGate) {
+        const retrospectiveGate = evaluateRetrospectiveMergeApproval(retrospectiveCheckpoint);
+        if (!retrospectiveGate.approved) {
+          return buildRetrospectiveGatePendingResult({
+            input,
+            currentHeadSha,
+            draftGateAlreadySatisfied: true,
+            draftGate,
+            preApprovalGate,
+            mergeStateStatus,
+            conflictFiles,
+            reason: `Merge remains blocked: retrospective_gate_pending. ${retrospectiveGate.reason}`,
+            refinementArtifact,
+          });
+        }
+      }
+
+      // Mirror LOW_SIGNAL_CONVERGED (#579): a clean current head with no clean
+      // draft_gate evidence must reconcile the draft gate rather than jump to
+      // final approval. This keeps the core handler consistent with the
+      // detect-pr-gate-coordination-state #579 post-pass, which unconditionally
+      // downgrades FINAL_APPROVAL_READY → DRAFT_GATE_NEEDED when
+      // draftGate.cleanEvidenceExists is false (no ROUND_CAP_CLEAN_FALLBACK
+      // exemption). Without this guard the final-approval-without-draft-gate
+      // branch is dead through the real script and asserts behavior it never
+      // produces.
+      if (!draftGate.cleanEvidenceExists) {
+        return buildDraftGateNeededForMergeResult({
+          input,
+          currentHeadSha,
+          draftGate,
+          preApprovalGate,
+          mergeStateStatus,
+          conflictFiles,
+          underlyingReason: "Round-cap clean fallback has clean pre_approval_gate but no clean draft_gate evidence.",
+          refinementArtifact,
+          effectiveLifecycleState,
+        });
+      }
+
+      // Round-cap clean fallback with clean draft_gate evidence reaches final
+      // approval when the current head also has clean pre_approval_gate evidence.
+      pushUnique(allowedNextActions, [PR_CHECKPOINT_ACTION.AWAIT_FINAL_HUMAN_APPROVAL]);
+      pushUnique(forbiddenActions, [
+        PR_CHECKPOINT_ACTION.RUN_DRAFT_GATE,
+        PR_CHECKPOINT_ACTION.MARK_READY_FOR_REVIEW,
+        PR_CHECKPOINT_ACTION.REQUEST_COPILOT_REVIEW,
+        PR_CHECKPOINT_ACTION.DECLARE_MERGE_READY,
+      ]);
+      return buildResult({
+        repo: input.repo ?? null,
+        pr: Number.isInteger(input.pr) ? input.pr : null,
+        currentHeadSha,
+        lifecycleState: effectiveLifecycleState,
+        loopDisposition: loopDisposition ?? DISPOSITION.CLEAN_CONVERGED,
+        gateBoundary: PR_CHECKPOINT.FINAL_APPROVAL_READY,
+        draftGateAlreadySatisfied: true,
+        draftGate,
+        preApprovalGate,
+        allowedNextActions,
+        forbiddenActions,
+        nextAction: PR_CHECKPOINT_ACTION.AWAIT_FINAL_HUMAN_APPROVAL,
+        reason: `Round-cap clean fallback accepted as draft gate equivalent (${copilotReviewRoundCount}/${maxCopilotRounds} rounds, zero unresolved threads, ${ciStatus === "crediblyGreen" ? "credibly green" : "green"} CI). The current head has clean \`pre_approval_gate\` evidence, so the PR is at the final approval boundary.`,
+        mergeStateStatus,
+        conflictFiles,
+          refinementArtifact,
+      });
+    }
+    pushUnique(allowedNextActions, [PR_CHECKPOINT_ACTION.RUN_PRE_APPROVAL_GATE]);
+    pushUnique(forbiddenActions, [
+      PR_CHECKPOINT_ACTION.RUN_DRAFT_GATE,
+      PR_CHECKPOINT_ACTION.MARK_READY_FOR_REVIEW,
+      PR_CHECKPOINT_ACTION.REQUEST_COPILOT_REVIEW,
+      PR_CHECKPOINT_ACTION.REREQUEST_COPILOT_REVIEW,
+      PR_CHECKPOINT_ACTION.DECLARE_MERGE_READY,
+    ]);
+    return buildResult({
+      repo: input.repo ?? null,
+      pr: Number.isInteger(input.pr) ? input.pr : null,
+      currentHeadSha,
+      lifecycleState: effectiveLifecycleState,
+      loopDisposition: loopDisposition ?? DISPOSITION.CLEAN_CONVERGED,
+      gateBoundary: PR_CHECKPOINT.PRE_APPROVAL_GATE_WINDOW,
+      draftGateAlreadySatisfied: true,
+      draftGate,
+      preApprovalGate,
+      allowedNextActions,
+      forbiddenActions,
+      nextAction: PR_CHECKPOINT_ACTION.RUN_PRE_APPROVAL_GATE,
+      reason: `The Copilot round limit is exhausted (${copilotReviewRoundCount}/${maxCopilotRounds}), and the current head has zero unresolved threads with ${ciStatus === "crediblyGreen" ? "credibly green" : "green"} CI, so \`pre_approval_gate\` fallback is now the next legal boundary (it reviews the current post-cap head; no further Copilot re-request is permitted).`,
+      mergeStateStatus,
+      conflictFiles,
+      refinementArtifact,
+      gateEvidenceNote: buildRoundExhaustionGateEvidenceNote({ copilotReviewRoundCount, maxCopilotRounds }),
+    copilotReviewRoundCount,
+    });
+  }
+
   if (effectiveLifecycleState === STATE.LOW_SIGNAL_CONVERGED) {
     if (ciStatus === "failure" || ciStatus === "crediblyGreen") {
       pushUnique(allowedNextActions, [PR_CHECKPOINT_ACTION.REPORT_BLOCKED]);