@dev-loops/core 1.0.2-slim.0 → 1.0.3

package/src/loop/handoff-envelope.mjs

@@ -54,6 +54,16 @@ const STRATEGY_DEFAULT_STOP_RULES = Object.freeze({
   ],
 });
 
+const RECONCILIATION_ACCEPTANCE_TEMPLATE = deepFreeze({
+  criteria: [
+    { id: "reconcile", must: "Resolve the reported authoritative-state conflict before selecting or executing a strategy.", severity: "required" },
+  ],
+  evidence: ["commands-run", "validation-output"],
+  maxFinalizationTurns: 1,
+  needsAttentionAfterMs: DEFAULT_NEEDS_ATTENTION_MS,
+  activeNoticeAfterMs: DEFAULT_ACTIVE_NOTICE_MS,
+});
+
 // ---------------------------------------------------------------------------
 // Acceptance template table
 // ---------------------------------------------------------------------------
@@ -584,8 +594,45 @@ export function buildDevLoopHandoffEnvelope(resolverOutput, settings, gateState
     throw new Error("handoff-envelope: resolverOutput is required and must be an object");
   }
 
-  const bundle = resolverOutput.bundle ?? resolverOutput;
-  const strategy = requireString(bundle.selectedStrategy, "resolverOutput.selectedStrategy");
+  const isWrapped = Object.hasOwn(resolverOutput, "bundle");
+  if (isWrapped && (!resolverOutput.bundle || typeof resolverOutput.bundle !== "object")) {
+    throw new Error("handoff-envelope: resolverOutput.bundle must be an object when present");
+  }
+  const bundle = isWrapped ? resolverOutput.bundle : resolverOutput;
+  const strategy = bundle.selectedStrategy === null
+    ? null
+    : requireString(bundle.selectedStrategy, "resolverOutput.selectedStrategy");
+  const routeKind = strategy === null
+    ? requireString(bundle.routeKind, "resolverOutput.routeKind")
+    : (trimmedOrNull(bundle.routeKind) ?? "route");
+  const selectedGate = trimmedOrNull(bundle.selectedGate);
+  const outerBundleKind = isWrapped ? trimmedOrNull(resolverOutput.bundleKind) : null;
+  const nestedBundleKind = trimmedOrNull(bundle.bundleKind);
+  if (outerBundleKind && nestedBundleKind && outerBundleKind !== nestedBundleKind) {
+    throw new Error(`handoff-envelope: outer bundleKind (${outerBundleKind}) and inner bundleKind (${nestedBundleKind}) must agree`);
+  }
+  const bundleKind = outerBundleKind ?? nestedBundleKind;
+  const isReconciliation = routeKind === "needs_reconcile"
+    && strategy === null
+    && selectedGate === "fail_closed_reconcile"
+    && bundleKind === "needs_reconcile";
+  if (isWrapped && isReconciliation && (
+    resolverOutput.bundleKind !== "needs_reconcile"
+    || bundle.bundleKind !== "needs_reconcile"
+    || resolverOutput.selectedStrategy !== "none"
+    || bundle.selectedStrategy !== null
+  )) {
+    throw new Error("handoff-envelope: wrapped needs_reconcile output requires exact outer and inner bundleKind needs_reconcile markers, outer selectedStrategy none, and inner selectedStrategy null");
+  }
+  if (bundleKind === "needs_reconcile" && !isReconciliation) {
+    throw new Error("handoff-envelope: outer/inner bundleKind needs_reconcile requires inner routeKind needs_reconcile, selectedGate fail_closed_reconcile, and selectedStrategy null");
+  }
+  if (routeKind === "needs_reconcile" && !isReconciliation) {
+    throw new Error("handoff-envelope: routeKind needs_reconcile requires outer bundleKind needs_reconcile, selectedGate fail_closed_reconcile, and selectedStrategy null");
+  }
+  if (strategy === null && !isReconciliation) {
+    throw new Error("handoff-envelope: a null resolverOutput.selectedStrategy is allowed only for the canonical needs_reconcile/fail_closed_reconcile tuple");
+  }
   const executionMode = requireString(bundle.executionMode, "resolverOutput.executionMode");
   const nextAction = requireString(bundle.nextAction, "resolverOutput.nextAction");
 
@@ -598,7 +645,9 @@ export function buildDevLoopHandoffEnvelope(resolverOutput, settings, gateState
   // profile instead of the default local-implementation gate. The spike
   // marker lives at the TOP level of the resolver output (the bundle does not
   // carry it), so it is read off `resolverOutput` directly.
-  const subGate = (strategy === INTERNAL_DEV_LOOP_STRATEGY.LOCAL_IMPLEMENTATION && isSpikeRun(resolverOutput))
+  const subGate = isReconciliation
+    ? selectedGate
+    : (strategy === INTERNAL_DEV_LOOP_STRATEGY.LOCAL_IMPLEMENTATION && isSpikeRun(resolverOutput))
     ? "spike"
     : resolveSubGate(strategy, gs);
   // Normalize each source independently, then fall back on the normalized result
@@ -609,10 +658,14 @@ export function buildDevLoopHandoffEnvelope(resolverOutput, settings, gateState
 
   const target = deriveTarget(bundle, repo);
   const requiredReads = deriveRequiredReads(bundle, resolverOutput);
-  const stopRules = deriveStopRules(settings, strategy);
+  const stopRules = isReconciliation
+    ? ["reconcile", ...(resolveHumanMergeOnly(settings) ? ["merge"] : [])]
+    : deriveStopRules(settings, strategy);
   const gateConfig = deriveGateConfig(settings, subGate);
   const derivedCwd = deriveCwd(bundle, { repoRoot: options.repoRoot, worktreeCwd: options.worktreeCwd });
-  const template = lookupAcceptanceTemplate(strategy, subGate);
+  const template = isReconciliation
+    ? RECONCILIATION_ACCEPTANCE_TEMPLATE
+    : lookupAcceptanceTemplate(strategy, subGate);
   // Lightweight PR-body-as-spec: retarget the phase-doc criterion
   // text to the PR description. Null/phase_doc leaves the criteria untouched, so
   // the non-lightweight path stays byte-identical.
@@ -650,6 +703,8 @@ export function buildDevLoopHandoffEnvelope(resolverOutput, settings, gateState
     maxCopilotRounds: settings?.refinement?.maxCopilotRounds ?? 5,
     executionMode,
 
+    ...(isReconciliation ? { routeKind, selectedStrategy: null } : {}),
+
     nextAction,
     requiredReads,
 
@@ -660,7 +715,7 @@ export function buildDevLoopHandoffEnvelope(resolverOutput, settings, gateState
     requireDraftFirst: settings?.workflow?.requireDraftFirst ?? false,
 
     cwd: derivedCwd,
-    worktreeRequired: true,
+    worktreeRequired: !isReconciliation,
 
     acceptance: {
       criteria: acceptanceCriteria,
@@ -832,6 +887,58 @@ export function validateHandoffEnvelope(envelope) {
     });
   }
 
+  // ----- terminal reconciliation tuple -----
+  // routeKind/selectedStrategy are omitted for ordinary routed envelopes to
+  // preserve the v1 shape. If either is present, both must identify the one
+  // supported no-strategy terminal envelope exactly; serialized/tampered
+  // envelopes receive the same fail-closed enforcement as the builder.
+  const hasRouteKind = Object.hasOwn(envelope, "routeKind");
+  const hasSelectedStrategy = Object.hasOwn(envelope, "selectedStrategy");
+  if (hasRouteKind || hasSelectedStrategy || envelope.currentGate === "fail_closed_reconcile") {
+    const reconciliationStopRulesAreCanonical = Array.isArray(envelope.stopRules)
+      && envelope.stopRules[0] === "reconcile"
+      && (envelope.stopRules.length === 1
+        || (envelope.stopRules.length === 2 && envelope.stopRules[1] === "merge"));
+    // Routing invariants only: acceptance prose remains the resolver's
+    // business, while nextAction must begin with one of the known fail-closed
+    // directives rather than arbitrary non-empty text.
+    const reconciliationCriterion = envelope.acceptance?.criteria;
+    const reconciliationAcceptanceIsCanonical = Array.isArray(reconciliationCriterion)
+      && reconciliationCriterion.some((criterion) => criterion?.id === "reconcile" && criterion?.severity === "required");
+    const normalizedNextAction = typeof envelope.nextAction === "string" ? envelope.nextAction.trim() : "";
+    const reconciliationNextActionIsActionable = [
+      "Reconcile ",
+      "Stop and reconcile ",
+      "Complete or explicitly skip ",
+      "Local implementation requires worktree isolation",
+    ].some((directive) => normalizedNextAction.startsWith(directive));
+    if (
+      envelope.routeKind !== "needs_reconcile"
+      || envelope.selectedStrategy !== null
+      || envelope.currentGate !== "fail_closed_reconcile"
+      || envelope.worktreeRequired !== false
+      || !reconciliationStopRulesAreCanonical
+      || !reconciliationAcceptanceIsCanonical
+      || !reconciliationNextActionIsActionable
+    ) {
+      errors.push({
+        field: "routeKind/selectedStrategy/currentGate/worktreeRequired/stopRules/acceptance.criteria",
+        reason: "terminal reconciliation must use the exact needs_reconcile / null / fail_closed_reconcile tuple, require no worktree, instruct reconciliation, stop at reconcile (plus optional merge), and carry a required reconcile acceptance criterion",
+        got: {
+          routeKind: envelope.routeKind,
+          selectedStrategy: envelope.selectedStrategy,
+          currentGate: envelope.currentGate,
+          worktreeRequired: envelope.worktreeRequired,
+          stopRules: envelope.stopRules,
+          nextAction: envelope.nextAction,
+          acceptanceCriteria: envelope.acceptance?.criteria,
+          acceptanceEvidence: envelope.acceptance?.evidence,
+          maxFinalizationTurns: envelope.acceptance?.maxFinalizationTurns,
+        },
+      });
+    }
+  }
+
   // ----- requiredReads -----
   if (!Array.isArray(envelope.requiredReads)) {
     errors.push({ field: "requiredReads", reason: "must be an array", got: envelope.requiredReads });

package/src/loop/issue-refinement-artifact.mjs

@@ -442,6 +442,24 @@ function rowIsSemantic(criterion, evidence) {
   return cellProseWordCount(criterion) >= 1 && cellProseWordCount(evidence) >= 1;
 }
 
+/**
+ * Resolve which columns hold the criterion and evidence by HEADER NAME, so a
+ * leading index column (`#`, `No`, `Idx`, empty, …) shifts the mapped columns
+ * off positions 0/1 without breaking detection. Returns `{ criterionCol,
+ * evidenceCol }` when both header families are named in distinct columns.
+ * Falls back to positions 0/1 for a matrix-heading table whose columns are not
+ * explicitly named (the pre-index-aware behavior); returns null otherwise.
+ */
+function resolveMatrixColumns(headerCells, underHeading) {
+  const criterionCol = headerCells.findIndex((h) => MATRIX_CRITERION_HEADER.test(h ?? ""));
+  const evidenceCol = headerCells.findIndex((h) => MATRIX_EVIDENCE_HEADER.test(h ?? ""));
+  if (criterionCol >= 0 && evidenceCol >= 0 && criterionCol !== evidenceCol) {
+    return { criterionCol, evidenceCol };
+  }
+  if (underHeading) return { criterionCol: 0, evidenceCol: 1 };
+  return null;
+}
+
 /**
  * Parse every GFM pipe table in a Markdown body (skipping fenced code spans via
  * the shared `stepFence`). Returns an array of
@@ -508,26 +526,27 @@ function parseMarkdownTables(body) {
  */
 export function detectAcDodMatrix(body = "") {
   const tables = parseMarkdownTables(body);
-  const candidates = tables.filter((t) => {
-    if (!Array.isArray(t.headerCells) || t.headerCells.length < 2) return false;
+  const candidates = [];
+  for (const t of tables) {
+    if (!Array.isArray(t.headerCells) || t.headerCells.length < 2) continue;
     const underHeading = typeof t.heading === "string" &&
       MATRIX_SECTION_PATTERNS.some((p) => p.test(t.heading));
-    const headerNamesMap =
-      MATRIX_CRITERION_HEADER.test(t.headerCells[0] ?? "") &&
-      MATRIX_EVIDENCE_HEADER.test(t.headerCells[1] ?? "");
-    return underHeading || headerNamesMap;
-  });
+    const cols = resolveMatrixColumns(t.headerCells, underHeading);
+    if (cols) candidates.push({ ...t, ...cols });
+  }
   if (candidates.length === 0) {
     return { found: false, valid: false, rowCount: 0, rows: [], reason: "No AC→DoD mapping matrix table found." };
   }
   // Prefer the first candidate that has >=1 semantic row; otherwise report the
   // first candidate as malformed.
   for (const table of candidates) {
+    const { criterionCol, evidenceCol } = table;
+    const minCells = Math.max(criterionCol, evidenceCol) + 1;
     const semanticRows = [];
     for (const cells of table.rows) {
-      if (cells.length < 2) continue;
-      const criterion = cells[0] ?? "";
-      const evidence = cells[1] ?? "";
+      if (cells.length < minCells) continue;
+      const criterion = cells[criterionCol] ?? "";
+      const evidence = cells[evidenceCol] ?? "";
       if (rowIsSemantic(criterion, evidence)) {
         semanticRows.push({ criterion, evidence });
       }
@@ -884,7 +903,7 @@ export const PR_BODY_SPEC_NARRATIVE_SECTIONS = Object.freeze({
 const CLOSING_ISSUE_REFERENCE_PATTERN =
   /\b(?:close[sd]?|fix(?:e[sd])?|resolve[sd]?)\s+(?:[\w.-]+\/[\w.-]+)?#(\d+)/giu;
 
-function extractClosingIssueNumbers(body) {
+export function extractClosingIssueNumbers(body) {
   // Same fence-skip as sectionHasBody: a `Closes #N` line quoted inside a
   // ```fenced``` example (e.g. a PR-template sample) must not spoof the gate.
   let fence = null;

package/src/loop/merge-approval.mjs

@@ -0,0 +1,283 @@
+/**
+ * Sanctioned merge-wrapper decision logic. Pure, no I/O.
+ *
+ * The CLI wrapper `scripts/github/merge-pr.mjs` gathers live GitHub facts
+ * (mergeable state, CI rollup, gate evidence, size-budget outcome, reviews,
+ * comments) and feeds them here. This module owns the FAIL-CLOSED decisions:
+ *   - is `--human-approved-by` a real GitHub login;
+ *   - which merge class the PR is in (drain vs escalated);
+ *   - whether a fresh, agent-unforgeable, head-pinned human approval exists;
+ *   - and the aggregate precondition verdict that names each failing precondition.
+ *
+ * It reuses, never re-derives, the existing precondition set:
+ * `resolveSizeBudgetHumanApprovalRequired` (size-budget-merge-gate),
+ * `findBlockingTitleMarkers` (pr-title-markers), and the detect-checkpoint-evidence
+ * `preMergeGateCheck` bundle (draft/pre-approval verdicts, threads, runner lock,
+ * fan-out provenance). This module adds ONLY the human-approver identity, the
+ * merge-class split, and the aggregate naming.
+ */
+
+import { isCopilotLogin } from "../github/copilot-helpers.mjs";
+import { findBlockingTitleMarkers } from "./pr-title-markers.mjs";
+import { resolveSizeBudgetHumanApprovalRequired } from "./size-budget-merge-gate.mjs";
+import { deriveLoopCiStatusFromRollup } from "./copilot-ci-status.mjs";
+
+// A GitHub login: 1-39 chars, alphanumeric or single internal hyphens, never
+// leading/trailing hyphen. This rejects a bare boolean, empty/whitespace, and
+// free text, so `--human-approved-by` is a real login, not a boolean or free text.
+const GITHUB_LOGIN_RE = /^[A-Za-z0-9](?:-?[A-Za-z0-9])*$/;
+
+/** True when `login` is shaped like a real GitHub login (fails closed on non-string). */
+export function isValidGithubLogin(login) {
+  return typeof login === "string" && login.length >= 1 && login.length <= 39 && GITHUB_LOGIN_RE.test(login);
+}
+
+export const MERGE_CLASS = Object.freeze({ DRAIN: "drain", ESCALATED: "escalated" });
+
+/**
+ * Classify the merge. An `escalate`/`block` size outcome, a T1-touching diff,
+ * or an explicit stable-release merge is ESCALATED — a standing authorization
+ * never satisfies it; it needs a fresh per-merge operator approval. Everything
+ * else is a normal DRAIN merge.
+ */
+export function resolveMergeClass({ sizeOutcome = null, touchesT1 = false, stableRelease = false } = {}) {
+  if (stableRelease === true) return MERGE_CLASS.ESCALATED;
+  if (sizeOutcome === "escalate" || sizeOutcome === "block") return MERGE_CLASS.ESCALATED;
+  if (touchesT1 === true) return MERGE_CLASS.ESCALATED;
+  return MERGE_CLASS.DRAIN;
+}
+
+function escapeRegex(value) {
+  return String(value).replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+function reviewLogin(entry) {
+  if (typeof entry?.user?.login === "string" && entry.user.login.length > 0) return entry.user.login;
+  if (typeof entry?.login === "string" && entry.login.length > 0) return entry.login;
+  return null;
+}
+
+// A non-human login: the Copilot reviewer/bot (bracket-free `Copilot`
+// variants, caught by isCopilotLogin) or any GitHub App bot login, which
+// GitHub renders with a `[bot]` suffix (e.g. `github-actions[bot]`). Such a
+// login can never satisfy the human-approval requirement. (A `[bot]` login can
+// never be the named `--human-approved-by <login>` either — isValidGithubLogin
+// rejects the brackets — so this only ever fires on a review/comment AUTHOR.)
+function isNonHumanLogin(login) {
+  return isCopilotLogin(login) || /\[bot\]$/i.test(login);
+}
+
+// A non-human review/comment author. Beyond the login-shape check, a GitHub Bot
+// account carries `user.type === "Bot"` even when its login has no `[bot]`
+// suffix — reject it by that authoritative type so a bracket-free bot login can
+// never satisfy the named fresh approver.
+function isNonHumanAuthor(entry, login) {
+  return isNonHumanLogin(login) || (typeof entry?.type === "string" && entry.type.toLowerCase() === "bot");
+}
+
+function reviewCommit(entry) {
+  if (typeof entry?.commit_id === "string" && entry.commit_id.length > 0) return entry.commit_id;
+  if (typeof entry?.commitId === "string" && entry.commitId.length > 0) return entry.commitId;
+  return null;
+}
+
+/**
+ * Verify a fresh, agent-unforgeable, head-pinned human approval by `approvedBy`.
+ *
+ * Two accepted records, in preference order:
+ *  1. a genuine `APPROVED` review by `approvedBy` whose `commit_id` equals the
+ *     current head SHA — GitHub forbids approving your own PR, so an `APPROVED`
+ *     review can only have come from a real human distinct from the author;
+ *  2. else a head-pinned operator comment marker `approve merge <headSha>`
+ *     authored by `approvedBy` — the solo-operator path, since an author cannot
+ *     leave an `APPROVED` review on their own agent-authored PR.
+ *
+ * FAILS CLOSED (returns `{ satisfied: false }`) when the approval is stale (on
+ * an earlier commit), agent/bot-authored (a Copilot-login review/comment never
+ * satisfies), from a login other than `approvedBy`, or absent. Because both
+ * records are pinned to the current head SHA, this re-gates on every head bump.
+ *
+ * @returns {{ satisfied: boolean, via: "approved_review"|"comment_marker"|null, reason: string|null }}
+ */
+export function verifyFreshHumanApproval({ approvedBy, currentHeadSha, reviews = [], comments = [] } = {}) {
+  if (!isValidGithubLogin(approvedBy)) {
+    return { satisfied: false, via: null, reason: "approvedBy is not a valid GitHub login" };
+  }
+  if (typeof currentHeadSha !== "string" || currentHeadSha.trim().length === 0) {
+    return { satisfied: false, via: null, reason: "current head SHA is unknown" };
+  }
+  const head = currentHeadSha.trim();
+
+  // Reduce to each login's LATEST submitted review (reviews arrive oldest-first,
+  // so the last occurrence wins — matching resolveHumanReviewDecision). A login
+  // whose APPROVED review was later superseded by a COMMENTED / CHANGES_REQUESTED
+  // / DISMISSED review no longer satisfies: only their latest state counts.
+  const latestReviewByLogin = new Map();
+  for (const entry of Array.isArray(reviews) ? reviews : []) {
+    const login = reviewLogin(entry);
+    if (login === null) continue;
+    latestReviewByLogin.set(login, entry);
+  }
+  const approverReview = latestReviewByLogin.get(approvedBy);
+  if (
+    approverReview
+    && !isNonHumanAuthor(approverReview, approvedBy) // agent/bot review never satisfies
+    && (typeof approverReview.state === "string" ? approverReview.state : null) === "APPROVED"
+    && reviewCommit(approverReview) === head // head-pinned — a stale/earlier-commit approval never satisfies
+  ) {
+    return { satisfied: true, via: "approved_review", reason: null };
+  }
+
+  // The marker must OPEN its line (after only leading whitespace / list / quote
+  // markers) so a negating operator comment never reads as approval: an
+  // unanchored `approve merge <head>` would also match `disapprove merge <head>`
+  // and `not approve merge <head>` — a fail-open on the merge-authorization
+  // path. The trailing `(?:\b|$)` keeps `<head>abc` from matching `<head>`.
+  const markerRe = new RegExp(`^[ \\t>*-]*approve\\s+merge\\s+${escapeRegex(head)}(?:\\b|$)`, "im");
+  for (const entry of Array.isArray(comments) ? comments : []) {
+    const login = reviewLogin(entry);
+    const body = typeof entry?.body === "string" ? entry.body : "";
+    if (login === null || isNonHumanAuthor(entry, login)) continue; // agent/bot comment never satisfies
+    if (login !== approvedBy) continue; // wrong login
+    if (!markerRe.test(body)) continue; // not a head-pinned marker for this head
+    return { satisfied: true, via: "comment_marker", reason: null };
+  }
+
+  return {
+    satisfied: false,
+    via: null,
+    reason: `no fresh ${approvedBy} approval on head ${head} (need an APPROVED review or an "approve merge ${head}" operator comment)`,
+  };
+}
+
+/**
+ * Decide whether merge is authorized given the class, the standing
+ * authorization signal, and any fresh per-merge approval.
+ *
+ * DRAIN: satisfied by a recorded standing authorization OR a fresh approval.
+ * ESCALATED: a standing authorization does NOT satisfy it — a fresh per-merge
+ * operator approval is required.
+ *
+ * @returns {{ authorized: boolean, via: string|null, reason: string|null }}
+ */
+export function resolveMergeApprovalDecision({ mergeClass, standingAuthorized = false, freshApproval = null } = {}) {
+  const fresh = freshApproval != null && freshApproval.satisfied === true;
+  if (mergeClass === MERGE_CLASS.ESCALATED) {
+    if (fresh) return { authorized: true, via: freshApproval.via, reason: null };
+    return {
+      authorized: false,
+      via: null,
+      reason: `escalated/stable-release merge requires a fresh per-merge operator approval; a standing authorization does not satisfy it${freshApproval?.reason ? ` (${freshApproval.reason})` : ""}`,
+    };
+  }
+  if (standingAuthorized === true) return { authorized: true, via: "standing_authorization", reason: null };
+  if (fresh) return { authorized: true, via: freshApproval.via, reason: null };
+  return {
+    authorized: false,
+    via: null,
+    reason: `drain merge requires a recorded standing authorization or a fresh operator approval${freshApproval?.reason ? ` (${freshApproval.reason})` : ""}`,
+  };
+}
+
+/**
+ * Resolve CI-green from a `gh pr view --json statusCheckRollup` payload.
+ *
+ * Delegates to the canonical loop-safe normalizer `deriveLoopCiStatusFromRollup`,
+ * which EXCLUDES the loop-derived `gate-evidence` / `gate-evidence-runner` checks
+ * (detect-checkpoint-evidence validates those separately, so a cancelled/failing
+ * derived check must not block a merge whose real CI is green) and treats a
+ * completed-but-no-conclusion or otherwise-unreadable entry as non-success.
+ * Fails closed: only a real `success` is green; pending/failure/unavailable are
+ * not. An empty or no-CI rollup normalizes to `none`, which is NOT green (a PR
+ * with no visible CI does not auto-satisfy this precondition).
+ */
+export function resolveCiGreenFromRollup(rollup) {
+  if (!Array.isArray(rollup)) return { green: false, reason: "CI status rollup unavailable" };
+  const { status, excludedFailureDetails } = deriveLoopCiStatusFromRollup(rollup);
+  if (status === "success") return { green: true, reason: null };
+  return {
+    green: false,
+    reason: `CI is not green on the current head (status=${status})`,
+    ...(Array.isArray(excludedFailureDetails) && excludedFailureDetails.length > 0 ? { excludedFailureDetails } : {}),
+  };
+}
+
+/**
+ * Aggregate every merge precondition into one fail-closed verdict, naming the
+ * specific failing precondition(s). The CLI resolves the live facts and passes
+ * them in; this stays pure so each branch is unit-testable.
+ *
+ * @returns {{ ok: boolean, failures: Array<{ precondition: string, reason: string }>, mergeClass: string, approvalVia: string|null }}
+ */
+export function evaluateMergePreconditions({
+  humanApprovedBy,
+  mergeable = null,
+  mergeStateStatus = null,
+  ciGreen = null,
+  title = null,
+  gateEvidence = null,
+  sizeOutcome = null,
+  // Default null (not false): a missing/absent T1 signal must reach
+  // resolveSizeBudgetHumanApprovalRequired as a non-boolean so it fails closed,
+  // rather than being coerced to "T1 untouched".
+  touchesT1 = null,
+  unresolvedChangesRequestedCount = null,
+  currentHeadSha = null,
+  reviews = [],
+  comments = [],
+  standingAuthorized = false,
+  stableRelease = false,
+} = {}) {
+  const failures = [];
+
+  if (!isValidGithubLogin(humanApprovedBy)) {
+    failures.push({ precondition: "human_approver", reason: "--human-approved-by must be a real GitHub login (not empty, a boolean, or free text)" });
+  }
+
+  if (mergeable !== "MERGEABLE" || (typeof mergeStateStatus === "string" && ["DIRTY", "BEHIND", "UNKNOWN"].includes(mergeStateStatus.toUpperCase()))) {
+    failures.push({ precondition: "mergeable", reason: `PR is not conflict-free with base (mergeable=${mergeable ?? "unknown"}, mergeStateStatus=${mergeStateStatus ?? "unknown"}); expected mergeable=MERGEABLE` });
+  }
+
+  // Fail closed on anything but an explicit { green: true } — a `false`, null, or
+  // malformed ciGreen must NOT slip past this fail-closed aggregate.
+  if (!ciGreen || ciGreen.green !== true) {
+    failures.push({ precondition: "ci_green", reason: (ciGreen && ciGreen.reason) ? ciGreen.reason : "CI status could not be resolved for the current head" });
+  }
+
+  // findBlockingTitleMarkers returns [] for a non-string title, so an absent or
+  // malformed title payload would silently pass this fail-closed gate — refuse it.
+  if (typeof title !== "string" || title.trim().length === 0) {
+    failures.push({ precondition: "title_markers", reason: "PR title is missing or unreadable; cannot verify it is free of merge-blocking markers" });
+  } else {
+    const titleMarkers = findBlockingTitleMarkers(title);
+    if (titleMarkers.length > 0) {
+      failures.push({ precondition: "title_markers", reason: `PR title carries merge-blocking marker(s): ${titleMarkers.join(", ")}` });
+    }
+  }
+
+  if (!gateEvidence || gateEvidence.ok !== true) {
+    const reason = gateEvidence && Array.isArray(gateEvidence.failures) && gateEvidence.failures.length > 0
+      ? gateEvidence.failures.join("; ")
+      : "draft_gate / current-head pre_approval_gate evidence is missing or unverified";
+    failures.push({ precondition: "gate_evidence", reason });
+  }
+
+  // Computed once, ahead of the size gate, so both preconditions draw "valid
+  // human approval" from the one shared resolver instead of two divergent
+  // checks (verifyFreshHumanApproval already owns the comment token, head
+  // pinning, and bot exclusion; the size gate no longer re-derives it from
+  // reviewDecision alone).
+  const freshApproval = verifyFreshHumanApproval({ approvedBy: humanApprovedBy, currentHeadSha, reviews, comments });
+
+  if (resolveSizeBudgetHumanApprovalRequired({ sizeOutcome, touchesT1, humanApprovalSatisfied: freshApproval.satisfied, unresolvedChangesRequestedCount }) === true) {
+    failures.push({ precondition: "size_budget_human_approval", reason: "size-budget requires a human APPROVED review OR a head-pinned \"approve merge <headSha>\" operator comment, with zero unresolved CHANGES_REQUESTED, for this escalated/T1 PR" });
+  }
+
+  const mergeClass = resolveMergeClass({ sizeOutcome, touchesT1, stableRelease });
+  const decision = resolveMergeApprovalDecision({ mergeClass, standingAuthorized, freshApproval });
+  if (!decision.authorized) {
+    failures.push({ precondition: "merge_approval", reason: decision.reason });
+  }
+
+  return { ok: failures.length === 0, failures, mergeClass, approvalVia: decision.authorized ? decision.via : null };
+}

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

@@ -8,6 +8,7 @@ import {
   MISSING_AC_DOD_MATRIX_FINDING,
   MISSING_EXPLICIT_NON_GOALS_FINDING,
 } from "./issue-refinement-artifact.mjs";
+import { COMPLETE_FIXER_DISPOSITION_ACTION, FIXER_DISPOSITION_FORBIDDEN_ACTIONS } from "./fixer-disposition.mjs";
 
 export const PR_CHECKPOINT = Object.freeze({
   DRAFT_REVIEW: "draft_review",
@@ -70,6 +71,11 @@ export const PR_CHECKPOINT_ACTION = Object.freeze({
   REPORT_DONE: "report_done",
   RUN_UI_E2E_SUITE: "run_ui_e2e_suite",
   RECORD_DESIGNER_REVIEW: "record_designer_review",
+  // GATE-EXEC-FIXER-DISPOSITION-BOUNDARY: the only legal next action while a
+  // fixer's claimed-tackled threads have incomplete disposition. Value is the
+  // shared literal fixer-disposition.mjs's pure evaluator also returns as
+  // `nextAction` (asserted equal by test — see fixer-disposition.test.mjs).
+  COMPLETE_FIXER_DISPOSITION: COMPLETE_FIXER_DISPOSITION_ACTION,
 });
 
 function normalizeGateComment(summary = null) {
@@ -908,6 +914,49 @@ function evaluatePrGateCoordinationCore(input = {}) {
     });
   }
 
+  // GATE-EXEC-FIXER-DISPOSITION-BOUNDARY (skills/docs/gate-review-sub-loop-contract.md):
+  // a caller-supplied fixerDisposition input records whether every thread a
+  // fixer claims to have tackled since the last push is fully disposed
+  // (commit contained, replied with that commit's evidence, resolved, and
+  // re-verified live — see fixer-disposition.mjs's pure evaluator). Present
+  // and NOT complete fails this boundary CLOSED regardless of
+  // unresolvedThreadCount or lifecycleState — the failure this closes is a
+  // review round opening over a dirty surface even when the thread count
+  // itself reads clean (bogus/uncontained evidence), so it must run ahead of
+  // every lifecycle-state branch below, not be derived from one.
+  const fixerDisposition = input.fixerDisposition && typeof input.fixerDisposition === "object"
+    ? input.fixerDisposition
+    : null;
+  if (fixerDisposition && fixerDisposition.complete !== true) {
+    pushUnique(allowedNextActions, [PR_CHECKPOINT_ACTION.COMPLETE_FIXER_DISPOSITION]);
+    pushUnique(forbiddenActions, FIXER_DISPOSITION_FORBIDDEN_ACTIONS);
+    const incompleteThreads = Array.isArray(fixerDisposition.incomplete) ? fixerDisposition.incomplete : [];
+    const reasonParts = incompleteThreads.map((entry) => (
+      `thread ${entry.threadId} (expected commit ${entry.expectedCommit ?? "unknown"}, failed step: ${entry.failedStep})`
+    ));
+    return buildResult({
+      repo: input.repo ?? null,
+      pr: Number.isInteger(input.pr) ? input.pr : null,
+      currentHeadSha,
+      lifecycleState: effectiveLifecycleState,
+      loopDisposition: DISPOSITION.UNRESOLVED_FEEDBACK,
+      gateBoundary: PR_CHECKPOINT.FEEDBACK_RESOLUTION,
+      draftGateAlreadySatisfied,
+      draftGate,
+      preApprovalGate,
+      allowedNextActions,
+      forbiddenActions,
+      nextAction: PR_CHECKPOINT_ACTION.COMPLETE_FIXER_DISPOSITION,
+      reason: reasonParts.length > 0
+        ? `GATE-EXEC-FIXER-DISPOSITION-BOUNDARY forbids every review/gate-dispatch action for ${incompleteThreads.length} tackled thread(s) with incomplete disposition: ${reasonParts.join("; ")}. The only legal next action is ${PR_CHECKPOINT_ACTION.COMPLETE_FIXER_DISPOSITION}.`
+        : `GATE-EXEC-FIXER-DISPOSITION-BOUNDARY forbids every review/gate-dispatch action until fixer disposition is complete and re-verified. The only legal next action is ${PR_CHECKPOINT_ACTION.COMPLETE_FIXER_DISPOSITION}.`,
+      mergeStateStatus,
+      conflictFiles,
+      refinementArtifact,
+      copilotReviewRoundCount,
+    });
+  }
+
   // UI e2e auto-scoping precondition. Path-triggered + fail-closed:
   // if the PR's changed files touch a rendered artifact (a deck under
   // docs/articles|presentations, or the inspect-run viewer source), it MUST be

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

@@ -50,9 +50,11 @@ export const DEFAULT_STATE_LOGICAL_MAP = Object.freeze({
   issue_intake: LOGICAL_COLUMN.NEXT_UP,
   refinement: LOGICAL_COLUMN.NEXT_UP,
   no_pr: LOGICAL_COLUMN.NEXT_UP,
-  pr_draft: LOGICAL_COLUMN.NEXT_UP,
 
   // In Progress — active implementation / review / feedback resolution
+  // A draft PR exists, so a runner owns the item; it is no longer pickable.
+  // This reconciles with the outer `implementation` lifecycle mapping.
+  pr_draft: LOGICAL_COLUMN.IN_PROGRESS,
   implementation: LOGICAL_COLUMN.IN_PROGRESS,
   // Tolerated alias for `implementation` (conceptual name);
   // the queue driver passes the real `implementation` lifecycle state.
@@ -125,8 +127,9 @@ export function deriveReconcileColumn(facts = {}) {
   // Merged PR (item is a PR, or issue's linked PR merged) => Done.
   if (prState === "MERGED") return LOGICAL_COLUMN.DONE;
   if (itemKind === "issue" && issueState === "CLOSED") return LOGICAL_COLUMN.DONE;
-  // Open, ready (non-draft) PR => In Progress.
-  if (prState === "OPEN" && prIsDraft === false) return LOGICAL_COLUMN.IN_PROGRESS;
+  // Any OPEN linked PR (draft or ready) => In Progress: a runner owns the item,
+  // so it must never be advertised in the pickup queue.
+  if (prState === "OPEN") return LOGICAL_COLUMN.IN_PROGRESS;
   // Otherwise leave the item untouched (Backlog / Next Up ordering preserved).
   return null;
 }

package/src/loop/retrospective-checkpoint.mjs

@@ -149,14 +149,13 @@ export function normalizeCheckpointCycleIdentity(identity) {
  * cycle forever).
  *
  * A `complete` or `skipped` artifact is scoped by `hasNewerMergeSinceCheckpoint`:
- * when true, something has merged since the checkpoint's recorded discharge
- * point (or that point could not be verified at all), so the checkpoint
- * cannot cover the newer cycle — it fails closed to MISSING. The caller
- * derives `hasNewerMergeSinceCheckpoint` itself (this module stays
- * pure/I/O-free) by checking local git ancestry between the checkpoint's
- * recorded merge commit and the base branch, so this runs fresh on every
- * evaluation rather than depending on anything having written a fresh
- * `required` record for the new cycle.
+ * when true, a newer PR merged into the configured base branch since the
+ * checkpoint's recorded discharge point (or ancestry/association could not
+ * be verified), so the checkpoint cannot cover the newer cycle — it fails
+ * closed to MISSING. The caller derives the boolean itself (this module stays
+ * pure/I/O-free) from local git ancestry plus authoritative commit-to-PR
+ * association, so this runs fresh on every evaluation rather than depending
+ * on anything having written a fresh `required` record for the new cycle.
  *
  * `required`/`none` are not scoped by this comparison: `required` already
  * maps to MISSING regardless of recency (an outstanding requirement blocks