@dev-loops/core 0.2.7 → 0.4.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/handoff-envelope.mjs

@@ -21,6 +21,7 @@ import {
 import { normalizeRepoSlug } from "../github/repo-slug.mjs";
 import { COPILOT_REVIEW_WAIT_TIMEOUT_MS } from "./policy-constants.mjs";
 import { resolveEffectiveAsyncStartMode } from "./async-start-contract.mjs";
+import { resolveHumanMergeOnly } from "../config/config.mjs";
 
 // ---------------------------------------------------------------------------
 // Constants
@@ -243,10 +244,18 @@ function deriveTarget(bundle, repo) {
 // ---------------------------------------------------------------------------
 
 function deriveStopRules(settings, strategy) {
-  if (settings?.autonomy?.stopAt && Array.isArray(settings.autonomy.stopAt)) {
-    return [...settings.autonomy.stopAt];
+  const base = (settings?.autonomy?.stopAt && Array.isArray(settings.autonomy.stopAt))
+    ? [...settings.autonomy.stopAt]
+    : [...(STRATEGY_DEFAULT_STOP_RULES[strategy] ?? [])];
+  // Fail closed: humanMergeOnly forces "merge" into the dispatched agent's
+  // stopRules regardless of configured stopAt, mirroring the authoritative
+  // resolveAutonomyStopAt(config) invariant. Without this, a custom
+  // stopAt that omits "merge" (e.g. [] or ["draft-pr"]) would tell the agent
+  // NOT to stop at merge — a direct humanMergeOnly bypass.
+  if (resolveHumanMergeOnly(settings) && !base.includes("merge")) {
+    base.push("merge");
   }
-  return [...(STRATEGY_DEFAULT_STOP_RULES[strategy] ?? [])];
+  return base;
 }
 
 // ---------------------------------------------------------------------------
@@ -316,28 +325,61 @@ function deriveCwd(bundle, options = {}) {
   const kind = normalizeTargetKind(artifact.kind);
 
   if (root) {
+    // issue/pr go through the single source of truth (resolveWorktreePath); other
+    // slug kinds (local_branch/local_phase) still use the namespace + slug.
+    if (kind === DEV_LOOP_TARGET_KIND.ISSUE && Number.isInteger(artifact.issue) && artifact.issue > 0) {
+      return resolveWorktreePath({ repoRoot: root, kind: "issue", number: artifact.issue });
+    }
+    if (kind === DEV_LOOP_TARGET_KIND.PR && Number.isInteger(artifact.pr) && artifact.pr > 0) {
+      return resolveWorktreePath({ repoRoot: root, kind: "pr", number: artifact.pr });
+    }
     const slug = buildWorktreeSlug(artifact, kind);
     if (slug) {
-      return `${root}/tmp/worktrees/${slug}`;
+      return `${root}/${WORKTREE_NAMESPACE}/${slug}`;
     }
   }
 
   return null;
 }
 
+/** Repo-relative root for loop-owned worktrees. The `dev-loops/` namespace */
+/** marks them so cleanup can only ever remove its own (issue #909). */
+export const WORKTREE_NAMESPACE = "tmp/worktrees/dev-loops";
+
+/**
+ * Resolve the canonical, namespaced worktree path for an issue/PR. Sole source
+ * of truth shared by create, provision, and cleanup. No branch suffix, so the
+ * path is recomputable from the issue/PR number alone.
+ *
+ * @param {{ repoRoot: string, kind: "issue"|"pr", number: number }} args
+ * @returns {string} Absolute path `<repoRoot>/tmp/worktrees/dev-loops/<kind>-<number>`
+ */
+export function resolveWorktreePath({ repoRoot, kind, number } = {}) {
+  const root = normalizeString(repoRoot);
+  if (!root) throw new Error("resolveWorktreePath: repoRoot is required and must be a non-empty string");
+  const k = typeof kind === "string" ? kind.trim().toLowerCase() : "";
+  if (k !== DEV_LOOP_TARGET_KIND.ISSUE && k !== DEV_LOOP_TARGET_KIND.PR) {
+    throw new Error(`resolveWorktreePath: kind must be "issue" or "pr", got "${kind}"`);
+  }
+  if (!Number.isInteger(number) || number < 1) {
+    throw new Error(`resolveWorktreePath: number must be a positive integer, got ${number}`);
+  }
+  return `${root}/${WORKTREE_NAMESPACE}/${k}-${number}`;
+}
+
 function flattenSlugSegment(s) {
   if (typeof s !== "string") return "";
   return s.replace(/[/\\]/g, "-").replace(/[^a-zA-Z0-9._-]/g, "");
 }
 
 function buildWorktreeSlug(artifact, kind) {
+  // Canonical naming is namespaced + no branch suffix (issue #909) so the path
+  // is recomputable from the issue/PR number alone (cleanup can find it).
   if (kind === DEV_LOOP_TARGET_KIND.ISSUE && Number.isInteger(artifact.issue) && artifact.issue > 0) {
-    const branch = normalizeString(artifact.branch);
-    return branch ? `issue-${artifact.issue}-${flattenSlugSegment(branch)}` : `issue-${artifact.issue}`;
+    return `issue-${artifact.issue}`;
   }
   if (kind === DEV_LOOP_TARGET_KIND.PR && Number.isInteger(artifact.pr) && artifact.pr > 0) {
-    const branch = normalizeString(artifact.branch);
-    return branch ? `pr-${artifact.pr}-${flattenSlugSegment(branch)}` : `pr-${artifact.pr}`;
+    return `pr-${artifact.pr}`;
   }
   if (kind === DEV_LOOP_TARGET_KIND.LOCAL_BRANCH) {
     const branch = normalizeString(artifact.branch);

package/src/loop/lifecycle-state.mjs

@@ -162,6 +162,7 @@ function normalizeLifecycleState(value) {
  *   hasUnresolvedThreads, // boolean: unresolved review threads exist
  *   preApprovalGatePassed, // boolean: current-head pre_approval_gate clean
  *   mergeAuthorized,    // boolean: explicit merge authorization granted
+ *   humanMergeOnly,     // boolean: repo invariant — agent may never merge (fails closed)
  *   isMerged,           // boolean: PR has been merged
  * }
  * ```
@@ -194,9 +195,18 @@ export function resolveLifecycleState(input = {}) {
     hasUnresolvedThreads = false,
     preApprovalGatePassed = false,
     mergeAuthorized = false,
+    humanMergeOnly = false,
     isMerged = false,
   } = input;
 
+  // Fail closed: when the repo enforces human-only merge, the agent is never
+  // cleared to advance to the merge action — the per-run mergeAuthorized signal
+  // is ignored. Also fail closed on a non-boolean `mergeAuthorized` (only an
+  // exact `true` clears merge), matching the authoritative
+  // `resolveEffectiveMergeAuthorized` gate. An already-merged PR (isMerged) is
+  // still terminal below.
+  const effectiveMergeAuthorized = humanMergeOnly !== true && mergeAuthorized === true;
+
   // 1. Explicit phase override — canonical or fail closed
   if (phase !== null && phase !== undefined) {
     const normalized = normalizeLifecycleState(phase);
@@ -212,7 +222,9 @@ export function resolveLifecycleState(input = {}) {
   }
 
   // 3. Merge authorized with pre-approval + linked PR → merge
-  if (mergeAuthorized && preApprovalGatePassed && hasLinkedPr) {
+  // (humanMergeOnly forces effectiveMergeAuthorized=false above, so the loop
+  // stays at the pre_approval_gate human-merge handoff instead.)
+  if (effectiveMergeAuthorized && preApprovalGatePassed && hasLinkedPr) {
     return buildResult(LIFECYCLE_STATE.MERGE);
   }
 

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]);

package/src/loop/queue-board-ordering.mjs

@@ -25,7 +25,11 @@ export async function resolveNextUpOrder(
   const listItems = dependencies.listQueueItems ?? listQueueItemsMain;
   try {
     const result = await listItems(
-      { repo, project: projectNumber, column: "Next Up" },
+      // list-queue-items validates `project` as a string ref (CLI contract);
+      // resolveProjectNumber yields a number, so stringify it. Passing the raw
+      // number trips parseProjectRef's `typeof raw !== "string"` guard, which
+      // surfaces as a misleading "--project is required" (#901).
+      { repo, project: String(projectNumber), column: "Next Up" },
       { env, runChild: dependencies.runChild },
     );
     const order = (result?.items ?? [])

package/src/loop/queue-board-sync.mjs

@@ -370,7 +370,10 @@ export async function syncBoardStatus(
   const moveItem = dependencies.moveQueueItem ?? moveQueueItemMain;
   try {
     const result = await moveItem(
-      { repo, project: projectNumber, item: itemNumber, toColumn: targetColumn },
+      // move-queue-item validates project + item as string refs (CLI contract);
+      // resolveProjectNumber yields a number and itemNumber is numeric, so
+      // stringify both.
+      { repo, project: String(projectNumber), item: String(itemNumber), toColumn: targetColumn },
       { env, runChild: dependencies.runChild },
     );
     return { ok: true, skipped: false, result };

package/src/loop/queue-driver.mjs

@@ -57,6 +57,28 @@ export async function runQueue(repoRoot, repo, options = {}) {
   const opts = { ...DEFAULT_QUEUE_DRIVER_OPTIONS, ...options };
   const queue = await readQueue(repoRoot);
 
+  // Data-integrity guard (#913): this driver is a deterministic ADAPTER over the
+  // board, not the orchestration harness. Completion (`done` / move to Done) may
+  // only ever REFLECT a real terminal signal supplied by an orchestrator via
+  // `runEntry` (e.g. a merged PR). With no `runEntry` wired in the current
+  // harness there is nothing that can produce a verifiable terminal state, so
+  // the run MUST be a no-op: leave every entry and board column untouched and
+  // report the reason. Previously the missing-orchestrator path fell back to a
+  // fabricated `{ ok: true, pr: null }` per entry, which silently marked an
+  // entire Next Up `done` and moved it to Done without any work happening.
+  if (typeof opts.runEntry !== "function") {
+    return {
+      ok: true,
+      noop: true,
+      reason: "no-orchestrator",
+      message:
+        "queue run is a deterministic adapter with no orchestrator wired (no runEntry); " +
+        "leaving board columns unchanged. Items move to Done only on a real terminal signal.",
+      results: [],
+      queue,
+    };
+  }
+
   // Config-driven loop-state → board-column mapping (#793, AC1/AC3). Loaded
   // once per run; resolves logical columns to configured display names, with
   // the AC1 defaults when no `queue.statusColumns`/`queue.stateColumnMap` is set.
@@ -135,9 +157,9 @@ export async function runQueue(repoRoot, repo, options = {}) {
     await syncColumn(entry.target, columnFor("implementation"));
 
     try {
-      const entryResult = opts.runEntry
-        ? await opts.runEntry(entry, repo, opts)
-        : { ok: true, pr: null };
+      // runEntry is guaranteed a function here (guarded at function entry):
+      // the adapter never fabricates a terminal result for an undispatched item.
+      const entryResult = await opts.runEntry(entry, repo, opts);
 
       if (entryResult.ok) {
         if (entryResult.pr) {