@dev-loops/core 0.2.7 → 0.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dev-loops/core",
-  "version": "0.2.7",
+  "version": "0.3.0",
   "type": "module",
   "description": "Shared deterministic support package for dev-loop skills, repo-local scripts, and GitHub automation.",
   "exports": {
@@ -28,6 +28,7 @@
     "./loop/copilot-ci-status": "./src/loop/copilot-ci-status.mjs",
     "./loop/copilot-loop-iterations": "./src/loop/copilot-loop-iterations.mjs",
     "./loop/copilot-loop-state": "./src/loop/copilot-loop-state.mjs",
+    "./loop/gate-fanin": "./src/loop/gate-fanin.mjs",
     "./loop/handoff-envelope": "./src/loop/handoff-envelope.mjs",
     "./loop/lifecycle-state": "./src/loop/lifecycle-state.mjs",
     "./loop/issue-refinement-artifact": "./src/loop/issue-refinement-artifact.mjs",
@@ -36,7 +37,9 @@
     "./loop/pr-gate-coordination": "./src/loop/pr-gate-coordination.mjs",
     "./loop/pr-title-markers": "./src/loop/pr-title-markers.mjs",
     "./loop/public-dev-loop-routing": "./src/loop/public-dev-loop-routing.mjs",
+    "./loop/queue-board-sync": "./src/loop/queue-board-sync.mjs",
     "./loop/queue-driver": "./src/loop/queue-driver.mjs",
+    "./loop/queue-membership": "./src/loop/queue-membership.mjs",
     "./loop/queue-parallel": "./src/loop/queue-parallel.mjs",
     "./loop/queue-state": "./src/loop/queue-state.mjs",
     "./loop/reviewer-loop-state": "./src/loop/reviewer-loop-state.mjs",

package/src/config/config.mjs

@@ -53,6 +53,22 @@ const GatesConfig = z.strictObject({
   // `requireCi` is only behaviorally configurable for the draft gate.
   // preApproval always requires CI even if config repeats `requireCi`.
   preApproval: GateConfig.optional(),
+  // Fail-closed enforcement that a gate verdict was produced by the
+  // fan-out/fan-in review sub-loop (executionMode === "fanout_fanin" plus a
+  // durable findings-log ledger), not an inline single-agent run. Default
+  // true (opt-out): a clean gate verdict requires fan-out/fan-in evidence
+  // unless explicitly disabled. See docs/gate-review-sub-loop-contract.md.
+  requireFanoutEvidence: z.boolean().default(true),
+  // Cap on how many scoped `review` reviewers the gate fan-out spawns in
+  // parallel. When the resolved angle set exceeds this cap, the overflow runs
+  // in sequential batches and the degradation is recorded in the gate evidence.
+  maxFanoutReviewers: z.number().int().min(1).max(64).default(8),
+  // Post the consolidated gate fan-out findings as a visible, marker-tagged PR
+  // comment so they are auditable and Copilot/humans are aware of them. Default
+  // true (opt-out). The disposition ledger is written regardless; this flag only
+  // suppresses the PR comment when explicitly false. See
+  // docs/gate-review-sub-loop-contract.md.
+  postFindingsComments: z.boolean().default(true),
 });
 
 const AutonomyConfig = z.strictObject({
@@ -85,6 +101,7 @@ const QueueConfig = z.strictObject({
   reDispatchMaxRetries: z.number().int().min(0).max(10).default(1),
   projectNumber: z.number().int().positive().optional(),
   boardTitle: z.string().trim().min(1).optional(),
+  archiveOlderThanDays: z.number().int().positive().optional(),
 });
 
 /** Internal path whitelist for internal-only PR detection — flat array of regex strings */
@@ -106,6 +123,9 @@ const FileGateConfig = GateConfig.partial();
 const FileGatesConfig = z.strictObject({
   draft: FileGateConfig.optional(),
   preApproval: FileGateConfig.optional(),
+  requireFanoutEvidence: z.boolean().optional(),
+  maxFanoutReviewers: z.number().int().min(1).max(64).optional(),
+  postFindingsComments: z.boolean().optional(),
 });
 
 // Partial persona entries for file-level config (allows omitting fields)
@@ -230,6 +250,8 @@ const BUILTIN_PERSONAS = Object.freeze({
   "state-concurrency": { persona: "review", defaultModel: null },
   "renderer-security": { persona: "review", defaultModel: null },
   determinism:          { persona: "review", defaultModel: null },
+  "acceptance-criteria": { persona: "review", defaultModel: null },
+  "ac-dod":              { persona: "review", defaultModel: null },
 });
 
 const DEFAULT_REVIEWER_PERSONA = "default-reviewer";
@@ -814,6 +836,66 @@ export function resolveGateConfig(config, gate) {
   };
 }
 
+/**
+ * Resolve whether fan-out/fan-in review evidence is required for a gate verdict.
+ *
+ * Default-on (opt-out): enforcement is ON unless `gates.requireFanoutEvidence`
+ * is explicitly set to false. When ON, the pre-merge evidence check fails
+ * closed unless a required gate's recorded executionMode is "fanout_fanin" and
+ * a durable findings-log ledger exists for that gate + head SHA. Using a
+ * `!== false` test (rather than `=== true`) keeps the opt-out semantics robust
+ * for programmatically-built config objects that bypass schema defaulting. See
+ * docs/gate-review-sub-loop-contract.md.
+ *
+ * @param {DevLoopConfig} config
+ * @returns {boolean}
+ */
+export function resolveRequireFanoutEvidence(config) {
+  return config?.gates?.requireFanoutEvidence !== false;
+}
+
+/** Default parallel fan-out reviewer cap (mirrors GatesConfig.maxFanoutReviewers). */
+export const DEFAULT_MAX_FANOUT_REVIEWERS = 8;
+
+/**
+ * Resolve the parallel fan-out reviewer cap for the gate sub-loop.
+ *
+ * Returns the configured `gates.maxFanoutReviewers` when it is an integer in
+ * the schema-bounded range 1..64; otherwise the built-in default (8). Clamping
+ * here (not just the Zod schema) keeps programmatically-constructed config
+ * objects that bypass schema validation within the same bound. The fan-out
+ * spawns at most this many scoped `review` reviewers in parallel; overflow runs
+ * sequentially.
+ *
+ * @param {DevLoopConfig} config
+ * @returns {number}
+ */
+export function resolveMaxFanoutReviewers(config) {
+  const raw = config?.gates?.maxFanoutReviewers;
+  if (typeof raw === "number" && Number.isInteger(raw) && raw >= 1 && raw <= 64) {
+    return raw;
+  }
+  return DEFAULT_MAX_FANOUT_REVIEWERS;
+}
+
+/**
+ * Resolve whether the consolidated gate fan-out findings should be posted as a
+ * visible, marker-tagged PR comment.
+ *
+ * Returns true (post the comment) unless `gates.postFindingsComments` is
+ * explicitly set to false. Using a `!== false` test (rather than `=== true`)
+ * keeps the opt-out semantics robust for programmatically-built config objects
+ * that bypass schema defaulting. The disposition ledger is written regardless;
+ * this flag only suppresses the auditable PR comment. See
+ * docs/gate-review-sub-loop-contract.md.
+ *
+ * @param {DevLoopConfig} config
+ * @returns {boolean}
+ */
+export function resolveGatePostFindingsComments(config) {
+  return config?.gates?.postFindingsComments !== false;
+}
+
 /**
  * Resolve local implementation light mode config.
  *

package/src/config/extension-defaults.yaml

@@ -382,6 +382,18 @@ personas:
       Do not block on formatting preferences other than checkbox correctness.
     defaultModel: null
 
+  acceptance-criteria:
+    persona: review
+    prompt: >-
+      Verify that each acceptance criterion and definition-of-done item from the
+      linked issue/PR is actually satisfied by the implementation — not merely
+      listed. For every criterion, cite the concrete code/test/behavior evidence
+      that meets it; flag any criterion that is unmet, only partially met, or
+      unverifiable from the diff as a blocking finding. Confirm definition-of-done
+      items (tests, docs, validation) are done and that declared non-goals are
+      respected (no scope creep).
+    defaultModel: null
+
   pr-checklist-matrix:
     persona: review
     prompt: >-

package/src/github/copilot-helpers.mjs

@@ -9,6 +9,7 @@
 const SUBMITTED_REVIEW_STATES = new Set(["APPROVED", "CHANGES_REQUESTED", "COMMENTED", "DISMISSED"]);
 const GATE_REVIEW_NAMES = new Set(["draft_gate", "pre_approval_gate"]);
 const GATE_REVIEW_VERDICTS = new Set(["clean", "findings_present", "blocked"]);
+const GATE_EXECUTION_MODES = new Set(["fanout_fanin", "inline_single_agent"]);
 
 export function isCopilotLogin(login) {
   return typeof login === "string" && /^copilot(?:[^a-z]|$)/i.test(login);
@@ -63,6 +64,11 @@ function normalizeGateReviewHeadSha(value) {
   return /^[0-9a-f]{7,64}$/i.test(normalized) ? normalized : null;
 }
 
+function normalizeGateExecutionMode(value) {
+  const normalized = stripOptionalCodeTicks(value).toLowerCase();
+  return GATE_EXECUTION_MODES.has(normalized) ? normalized : null;
+}
+
 function parseGateReviewCommentFields(body) {
   if (typeof body !== "string" || body.trim().length === 0) {
     return null;
@@ -74,6 +80,8 @@ function parseGateReviewCommentFields(body) {
     verdict: null,
     findingsSummary: null,
     nextAction: null,
+    executionMode: null,
+    inlineReason: null,
   };
 
   for (const rawLine of body.split(/\r?\n/u)) {
@@ -112,6 +120,24 @@ function parseGateReviewCommentFields(body) {
       fields.nextAction = match[1].trim();
       continue;
     }
+
+    match = line.match(/^(?:[-*]\s*)?execution\s+mode\s*:\s*(.+)$/iu);
+    if (match) {
+      const rest = match[1].trim();
+      // Split on the first em-dash / en-dash / " - " separator to recover an
+      // optional inline reason: "inline_single_agent — <reason>".
+      const sepMatch = rest.match(/^(.*?)\s*(?:[—–]|\s-\s)\s*(.*)$/u);
+      const modeToken = sepMatch ? sepMatch[1].trim() : rest;
+      const reasonToken = sepMatch ? sepMatch[2].trim() : "";
+      fields.executionMode = normalizeGateExecutionMode(modeToken);
+      // Only record an inline reason for inline_single_agent. A trailing
+      // "— text" on a fanout_fanin (or invalid) mode line must not surface an
+      // inconsistent mode/reason pair, so leave inlineReason null otherwise.
+      if (reasonToken.length > 0 && fields.executionMode === "inline_single_agent") {
+        fields.inlineReason = reasonToken;
+      }
+      continue;
+    }
   }
 
   // Lenient fallback: detect gate name and head SHA anywhere in body
@@ -178,6 +204,8 @@ export function parseGateReviewCommentMarkerBody(body) {
     verdict: fields.verdict,
     findingsSummary: fields.findingsSummary,
     nextAction: fields.nextAction,
+    executionMode: fields.executionMode,
+    inlineReason: fields.inlineReason,
     contractComplete: Boolean(fields.verdict && fields.findingsSummary && fields.nextAction),
   };
 }
@@ -205,6 +233,8 @@ export function summarizeGateReviewComments(comments) {
       verdict: parsed.verdict,
       findingsSummary: parsed.findingsSummary,
       nextAction: parsed.nextAction,
+      executionMode: parsed.executionMode ?? null,
+      inlineReason: parsed.inlineReason ?? null,
       commentId: Number.isInteger(comment?.id) ? comment.id : null,
       commentUrl: typeof comment?.html_url === "string" && comment.html_url.trim().length > 0 ? comment.html_url.trim() : null,
       updatedAt: typeof (comment?.updated_at ?? comment?.updatedAt) === "string"
@@ -253,6 +283,8 @@ export function summarizeGateReviewCommentMarkers(comments, { headSha } = {}) {
       verdict: parsed.verdict,
       findingsSummary: parsed.findingsSummary,
       nextAction: parsed.nextAction,
+      executionMode: parsed.executionMode ?? null,
+      inlineReason: parsed.inlineReason ?? null,
       contractComplete: parsed.contractComplete,
       commentId: Number.isInteger(comment?.id) ? comment.id : null,
       commentUrl: typeof comment?.html_url === "string" && comment.html_url.trim().length > 0 ? comment.html_url.trim() : null,
@@ -274,6 +306,39 @@ export function summarizeGateReviewCommentMarkers(comments, { headSha } = {}) {
   return summary;
 }
 
+/**
+ * Resolve the draft-gate round-reset timestamp (ms) used to suppress stale Copilot
+ * review rounds from the count (#896 consistency).
+ *
+ * When the draft gate was re-passed clean on a DIFFERENT head than the current one,
+ * only Copilot reviews submitted after that re-pass should count toward the round
+ * cap. Returning the re-pass `updatedAt` (ms) lets {@link summarizeCopilotReviews}
+ * drop earlier rounds. Returns null when no reset applies (no clean draft gate, or
+ * the clean draft gate is already on the current head).
+ *
+ * Both detect-pr-gate-coordination-state and request-copilot-review must derive the
+ * reset identically, or the two scripts disagree on the completed round count and
+ * the cap (the inconsistency reported in #896). This is the single shared source.
+ *
+ * @param {object} params
+ * @param {{ verdict?: string|null, headSha?: string|null, updatedAt?: string|null }|null} params.draftGate
+ * @param {string|null} params.currentHeadSha
+ * @returns {number|null} reset timestamp in ms, or null
+ */
+export function resolveDraftGateRoundResetMs({ draftGate, currentHeadSha } = {}) {
+  const draftGateHeadSha = typeof draftGate?.headSha === "string" ? draftGate.headSha : null;
+  const draftGateOnCurrentHead = typeof draftGateHeadSha === "string"
+    && typeof currentHeadSha === "string"
+    && currentHeadSha.startsWith(draftGateHeadSha);
+  if (draftGate?.verdict === "clean"
+    && typeof draftGateHeadSha === "string"
+    && !draftGateOnCurrentHead
+    && typeof draftGate?.updatedAt === "string") {
+    return normalizeTimestamp(draftGate.updatedAt);
+  }
+  return null;
+}
+
 export function summarizeCopilotReviews(reviews, { headSha, draftGateResetAtMs } = {}) {
   const allReviews = Array.isArray(reviews) ? reviews : [];
   const copilotReviews = allReviews.filter((review) => isCopilotLogin(review?.author?.login));

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/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-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-membership.mjs

@@ -0,0 +1,145 @@
+/**
+ * Queue membership reconciliation (issue #864).
+ *
+ * A configured GitHub Projects board is the authoritative source of queue
+ * MEMBERSHIP (which issues to work) and ordering — not just status. Before a
+ * queue run, this module folds the board's "Next Up" items into the local
+ * `.pi/dev-loop-queue.json` entries so the board drives membership, and reports
+ * a clear, non-misleading emptiness verdict.
+ *
+ * This is the testable orchestration seam used by `scripts/loop/run-queue.mjs`.
+ * Board config loading, Next Up resolution, and queue persistence are all
+ * injectable so the policy can be exercised without GitHub or the filesystem.
+ */
+
+import { loadBoardConfig } from "./queue-board-sync.mjs";
+import { resolveNextUpOrder } from "./queue-board-ordering.mjs";
+import { reconcileEntriesFromBoard, writeQueue, pendingEntries } from "./queue-state.mjs";
+
+/**
+ * Reconcile a configured board's Next Up membership into the queue, then
+ * classify emptiness.
+ *
+ * Behavior:
+ *   - Board NOT configured: no reconcile. Emptiness is judged purely on the
+ *     local queue (preserving the legacy "Queue is empty" behavior).
+ *   - Board configured: resolve Next Up targets and reconcile them in. If the
+ *     resolver fails-open (returns no targets) the board membership simply
+ *     contributes nothing; we never crash. Newly added targets are persisted
+ *     via `writeQueue`.
+ *
+ * Emptiness verdict (`emptiness`):
+ *   - `null`              — there is pending work; the caller should run the queue.
+ *   - "queue_empty"       — board not configured and the local queue is empty
+ *                           (legacy "Queue is empty" message).
+ *   - "board_empty"       — board IS configured, Next Up resolved successfully
+ *                           (reason == null) but is genuinely empty, and there is
+ *                           no pending local work. Distinct from the misleading
+ *                           generic empty case.
+ *   - "board_unavailable" — board IS configured but Next Up resolution failed
+ *                           (fail-open: empty order WITH a non-null reason) and
+ *                           the local queue had no pending work to fall back to.
+ *                           This must NOT be reported as "board_empty" — the
+ *                           board may well have items we simply could not read.
+ *
+ * @param {string} repoRoot
+ * @param {string} repo - "owner/name"
+ * @param {{version:number, entries:Array}} queue
+ * @param {object} [deps]
+ * @param {(repoRoot:string)=>{enabled:boolean}} [deps.loadBoardConfig]
+ * @param {(repo:string, repoRoot:string, env:object, d:object)=>Promise<{ok:boolean, order:number[], reason:?string}>} [deps.resolveNextUpOrder]
+ * @param {(repoRoot:string, queue:object)=>Promise<void>} [deps.writeQueue]
+ * @param {(msg:string)=>void} [deps.log]
+ * @returns {Promise<{queue:object, added:number[], boardConfigured:boolean, emptiness:(null|"queue_empty"|"board_empty"|"board_unavailable"), reason:(string|null)}>}
+ */
+export async function reconcileBoardMembership(repoRoot, repo, queue, deps = {}) {
+  const loadConfig = deps.loadBoardConfig ?? loadBoardConfig;
+  const resolveOrder = deps.resolveNextUpOrder ?? resolveNextUpOrder;
+  const persist = deps.writeQueue ?? writeQueue;
+  const log = typeof deps.log === "function" ? deps.log : (msg) => console.error(msg);
+
+  let boardConfigured = false;
+  try {
+    const config = loadConfig(repoRoot);
+    boardConfigured = Boolean(config?.enabled);
+    // loadBoardConfig does not throw on read/parse failures; it reports them
+    // via `{ enabled: false, reason: ... }`. Surface that reason so a genuine
+    // config read/parse error is visible instead of being silently treated as
+    // "board not configured". The ordinary "board not configured" case carries
+    // no reason and must stay quiet.
+    if (!boardConfigured && config?.reason) {
+      log(`[queue-membership] board config unavailable (fail-open): ${config.reason}`);
+    }
+  } catch (err) {
+    // Config read errors must not crash the queue; treat as unconfigured.
+    log(`[queue-membership] board config read failed (fail-open): ${err?.message ?? err}`);
+    boardConfigured = false;
+  }
+
+  let added = [];
+  let reason = null;
+  // True when the board is configured but Next Up could not be resolved: the
+  // resolver is fail-open, so this surfaces as an empty order WITH a non-null
+  // reason (or a thrown error caught below). We must not confuse this with a
+  // genuinely empty Next Up (empty order AND reason == null).
+  let resolutionFailed = false;
+
+  if (boardConfigured) {
+    let nextUp = [];
+    try {
+      // env/board dependencies use resolveNextUpOrder's own defaults
+      // (process.env / {}); the production caller never overrides them, and
+      // tests inject a stubbed resolveNextUpOrder.
+      const result = await resolveOrder(repo, repoRoot, process.env, {});
+      reason = result?.reason ?? null;
+      nextUp = Array.isArray(result?.order) ? result.order : [];
+      // Fail-open contract: an empty order paired with a non-null reason means
+      // resolution failed (API error, board lookup failure, etc.) — NOT that the
+      // board's Next Up is genuinely empty.
+      if (nextUp.length === 0 && reason != null) {
+        resolutionFailed = true;
+        log(`[queue-membership] Next Up resolution failed (fail-open), using local queue: ${reason}`);
+      }
+    } catch (err) {
+      // resolveNextUpOrder is itself fail-open, but guard anyway: a board
+      // resolution error falls back to the local queue without crashing.
+      reason = err?.message ?? "board resolution failed";
+      resolutionFailed = true;
+      log(`[queue-membership] Next Up resolution failed (fail-open), using local queue: ${reason}`);
+      nextUp = [];
+    }
+
+    if (nextUp.length > 0) {
+      const outcome = reconcileEntriesFromBoard(queue, nextUp);
+      added = outcome.added;
+      if (added.length > 0) {
+        log(`[queue-membership] added ${added.length} entr${added.length === 1 ? "y" : "ies"} from board Next Up: ${added.join(", ")}`);
+        try {
+          await persist(repoRoot, queue);
+        } catch (err) {
+          // A write failure should not crash the run; entries still drive this
+          // in-memory run, they just are not persisted for the next invocation.
+          log(`[queue-membership] failed to persist reconciled queue (continuing in-memory): ${err?.message ?? err}`);
+        }
+      }
+    }
+  }
+
+  const pending = pendingEntries(queue);
+  let emptiness = null;
+  if (pending.length === 0) {
+    if (!boardConfigured) {
+      emptiness = "queue_empty";
+    } else if (resolutionFailed) {
+      // Board configured but we could not read Next Up and the local queue is
+      // empty: the board may have items we simply failed to fetch. Report a
+      // distinct verdict instead of the misleading "board_empty".
+      emptiness = "board_unavailable";
+    } else {
+      // Board configured, Next Up resolved cleanly (reason == null) and empty.
+      emptiness = "board_empty";
+    }
+  }
+
+  return { queue, added, boardConfigured, emptiness, reason };
+}

package/src/loop/queue-state.mjs

@@ -81,7 +81,7 @@ export async function writeQueue(repoRoot, queue) {
 export function createEntry(target, kind, dependsOn = []) {
   return {
     target,
-    kind,           // "issue" | "pr"
+    kind,           // "issue" | "pr" | "board" (board = issue-or-PR, resolved by number at run time)
     status: "queued",
     dependsOn: Array.isArray(dependsOn) ? dependsOn : [],
     pr: null,
@@ -211,6 +211,61 @@ export function pendingEntries(queue) {
   );
 }
 
+// ── Board membership reconciliation ──────────────────────────────────
+
+/**
+ * Reconcile board-driven membership into the local queue (issue #864).
+ *
+ * A configured GitHub Projects board is the authoritative source of queue
+ * MEMBERSHIP (which issues should be worked), not just ordering/status. This
+ * pure helper folds the board's "Next Up" targets into the queue: for each
+ * target not already present (by `findEntry`), it appends a fresh queued
+ * `createEntry(target, "board")`. Existing entries — and their status, order,
+ * and metadata — are preserved untouched, and targets already present are
+ * skipped (dedup).
+ *
+ * Entry kind is `"board"` rather than `"issue"`: the board's Next Up can hold
+ * issues OR PRs, and `resolveNextUpOrder` collapses each item to a bare number
+ * (`issueNumber ?? prNumber`), discarding the artifact kind. The queue driver
+ * never branches on `entry.kind`; it dispatches purely by `entry.target` and
+ * the per-entry startup resolver resolves the actual artifact (issue or PR) by
+ * number at run time. So a neutral `"board"` kind correctly records the
+ * provenance without falsely asserting "issue" for PR-backed board items.
+ *
+ * Pure: performs no I/O. Mutates and returns the passed `queue` object (its
+ * `entries` array is appended to in place) plus the list of newly added
+ * targets so the caller can log/report.
+ *
+ * @param {{version:number, entries:Array}} queue - the current queue.
+ * @param {Array<number>} nextUpTargets - board "Next Up" issue/PR numbers.
+ * @returns {{queue:{version:number, entries:Array}, added:number[]}}
+ */
+export function reconcileEntriesFromBoard(queue, nextUpTargets) {
+  const added = [];
+  if (!queue || !Array.isArray(queue.entries)) {
+    return { queue, added };
+  }
+  if (!Array.isArray(nextUpTargets) || nextUpTargets.length === 0) {
+    return { queue, added };
+  }
+  for (const target of nextUpTargets) {
+    // Guard against malformed/duplicate board input: only positive-integer
+    // targets, and never add the same target twice (even if it repeats in the
+    // board list and was not yet in the queue at the start of this loop).
+    //
+    // The integer guard is critical for NaN: a NaN target never dedups via
+    // findEntry (NaN !== NaN), so accepting it would re-append a fresh NaN
+    // entry on every reconcile. Infinity, non-integers, negatives, and 0 are
+    // never valid issue/PR numbers either, so reject anything that is not a
+    // positive integer.
+    if (!Number.isInteger(target) || target <= 0) continue;
+    if (findEntry(queue, target)) continue;
+    queue.entries.push(createEntry(target, "board"));
+    added.push(target);
+  }
+  return { queue, added };
+}
+
 // ── Bug injection ────────────────────────────────────────────────────
 
 export function appendBugIssue(queue, issueNumber, dependsOn = null) {