@dev-loops/core 0.7.1 → 0.7.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dev-loops/core",
-  "version": "0.7.1",
+  "version": "0.7.2",
   "type": "module",
   "engines": {
     "node": ">=24"
@@ -38,6 +38,7 @@
     "./loop/plan-file-promote-contract": "./src/loop/plan-file-promote-contract.mjs",
     "./loop/plan-file-refine-contract": "./src/loop/plan-file-refine-contract.mjs",
     "./loop/pr-gate-coordination": "./src/loop/pr-gate-coordination.mjs",
+    "./loop/pr-lifecycle": "./src/loop/pr-lifecycle.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-ordering": "./src/loop/queue-board-ordering.mjs",
@@ -55,6 +56,9 @@
     "./loop/timeout-policy": "./src/loop/timeout-policy.mjs",
     "./loop/tracker-pr-state": "./src/loop/tracker-pr-state.mjs",
     "./loop/ui-e2e-scoping": "./src/loop/ui-e2e-scoping.mjs",
+    "./projects/list-queue-items": "./src/projects/list-queue-items.mjs",
+    "./projects/move-queue-item": "./src/projects/move-queue-item.mjs",
+    "./projects/resolve-project": "./src/projects/resolve-project.mjs",
     "./harness": "./src/harness/index.mjs",
     "./loop/worktree-guard": "./src/loop/worktree-guard.mjs",
     "./loop/tracker-first-loop-state": "./src/loop/tracker-first-loop-state.mjs"

package/src/config/config.mjs

@@ -98,6 +98,12 @@ const GatesConfig = z.strictObject({
   // and every angle configured across this config's own draft/preApproval/
   // spike gates (angles + mandatoryAngles).
   anglePool: z.array(z.string().trim().min(1)).optional(),
+  // Fail-closed enforcement that a fanout_fanin gate's recorded per-angle
+  // provenance names only angles in the gate's configured pool (angles +
+  // mandatoryAngles) — ad-hoc/foreign angle labels are rejected rather than
+  // silently accepted. Default true (reject); set false to warn instead of
+  // fail. See resolveRejectForeignAngles / docs/gate-review-sub-loop-contract.md.
+  rejectForeignAngles: z.boolean().default(true),
 });
 
 const AutonomyConfig = z.strictObject({
@@ -143,6 +149,10 @@ const LocalImplementationConfig = z.strictObject({
     enabled: z.boolean(),
     maxFiles: z.number().int().min(1),
     maxLines: z.number().int().min(1),
+    // Copilot review round cap for light-dispatched PRs (#1210). Composes with
+    // (does not replace) refinement.maxCopilotRounds — see
+    // resolveEffectiveCopilotRoundCap.
+    maxCopilotRounds: z.number().int().nonnegative().default(1),
   }).optional(),
 });
 
@@ -193,6 +203,7 @@ const FileGatesConfig = z.strictObject({
   maxFanoutReviewers: z.number().int().min(1).max(64).optional(),
   postFindingsComments: z.boolean().optional(),
   anglePool: z.array(z.string().trim().min(1)).optional(),
+  rejectForeignAngles: z.boolean().optional(),
 });
 
 // Partial persona entries for file-level config (allows omitting fields)
@@ -252,7 +263,7 @@ export const BUILT_IN_DEFAULTS = Object.freeze({
     devModeDefault: false,
   }),
   localImplementation: Object.freeze({
-    lightMode: Object.freeze({ enabled: false, maxFiles: 3, maxLines: 200 }),
+    lightMode: Object.freeze({ enabled: false, maxFiles: 3, maxLines: 200, maxCopilotRounds: 1 }),
   }),
   queue: Object.freeze({
     maxParallel: 3,
@@ -1021,6 +1032,17 @@ export function resolveRequireFanoutProvenance(config) {
   return config?.gates?.requireFanoutProvenance === true;
 }
 
+/**
+ * Resolve whether a fan-out provenance entry naming an angle outside the
+ * gate's configured pool should FAIL (default) or only WARN.
+ *
+ * @param {DevLoopConfig} config
+ * @returns {boolean}
+ */
+export function resolveRejectForeignAngles(config) {
+  return config?.gates?.rejectForeignAngles !== false;
+}
+
 /**
  * Resolve whether the consolidated gate fan-out findings should be posted as a
  * visible, marker-tagged PR comment.
@@ -1061,6 +1083,33 @@ export function resolveLightMode(config) {
   };
 }
 
+/**
+ * Resolve the effective Copilot review round cap for a PR (#1210).
+ *
+ * Full PRs (lightweight=false) use `refinement.maxCopilotRounds` unchanged
+ * (default 5). Light-dispatched PRs compose with it rather than replacing it:
+ * `effective = min(localImplementation.lightMode.maxCopilotRounds ?? 1,
+ * refinement.maxCopilotRounds)` — so setting `refinement.maxCopilotRounds: 0`
+ * disables Copilot rounds everywhere, including lightweight, with that one
+ * setting.
+ *
+ * @param {DevLoopConfig} config
+ * @param {{ lightweight?: boolean }} [options]
+ * @returns {number}
+ */
+export function resolveEffectiveCopilotRoundCap(config, { lightweight = false } = {}) {
+  // Clamp here, not only in the zod schema: programmatically-built config
+  // objects bypass schema defaulting/validation, and a negative cap must never
+  // reach round-cap comparisons.
+  const maxCopilotRounds = Math.max(0, /** @type {number} */ (resolveRefinementConfig(config, "maxCopilotRounds")));
+  if (!lightweight) return maxCopilotRounds;
+  const lightMaxRounds = config?.localImplementation?.lightMode?.maxCopilotRounds;
+  const effectiveLightCap = typeof lightMaxRounds === "number" && Number.isFinite(lightMaxRounds)
+    ? Math.max(0, lightMaxRounds)
+    : 1;
+  return Math.min(effectiveLightCap, maxCopilotRounds);
+}
+
 /** Label that forces full fan-out regardless of change size. */
 export const GATE_FULL_LABEL = "gate:full";
 
@@ -1161,6 +1210,36 @@ export function resolveAnglePool(config) {
   return [...new Set([...Object.keys(BUILTIN_PERSONAS), ...configured])];
 }
 
+/**
+ * Resolve a gate's ANGLE ENFORCEMENT CONTRACT: the mandatory angles a
+ * fanout_fanin verdict must cover and the pool its recorded angles must stay
+ * within. Single source of truth for all angle-coverage enforcement consumers
+ * (ledger write, verdict-comment write, merge-evidence read) so they agree.
+ *
+ * - `mandatoryAngles` is filtered through `excludeAngles`: a config that
+ *   excludes a mandatory angle must not deadlock every fanout write (the
+ *   angle would be missing-mandatory if omitted yet foreign if recorded).
+ * - `pool` is `resolveGateAngles` (configured angles ∪ mandatoryAngles, minus
+ *   excludeAngles); when `additiveAngles` is enabled it widens to the global
+ *   lens catalog (`resolveAnglePool`) too — dynamic resolution may
+ *   legitimately dispatch catalog angles then — with `excludeAngles` still a
+ *   hard ceiling. A null pool skips the foreign-angle check entirely.
+ *
+ * @param {DevLoopConfig} config
+ * @param {"draft"|"preApproval"|"spike"} gate
+ * @returns {{ mandatoryAngles: string[], pool: string[]|null }}
+ */
+export function resolveGateAngleContract(config, gate) {
+  const gateConfig = resolveGateConfig(config, gate);
+  const excluded = new Set(gateConfig.excludeAngles);
+  const mandatoryAngles = gateConfig.mandatoryAngles.filter((a) => !excluded.has(a));
+  let pool = resolveGateAngles(config, gate);
+  if (gateConfig.additiveAngles && pool !== null) {
+    pool = [...new Set([...pool, ...resolveAnglePool(config)])].filter((a) => !excluded.has(a));
+  }
+  return { mandatoryAngles, pool };
+}
+
 /**
  * Resolve gate angles dynamically when `dynamicAngles` is enabled in config.
  *

package/src/config/extension-defaults.yaml

@@ -44,6 +44,9 @@ gates:
       - renderer-security
       - determinism
       - pr-comments
+      - contradiction-lens
+      - code-conformance
+      - semantic-drift
     excludeAngles: []
     required: true
     requireCi: true
@@ -66,6 +69,9 @@ gates:
       - dip
       - docs
       - pr-checklist-matrix
+      - contradiction-lens
+      - correctness-final
+      - ui-validation
     excludeAngles: []
     required: true
     mandatoryAngles:

package/src/github/copilot-helpers.mjs

@@ -15,6 +15,149 @@ export function isCopilotLogin(login) {
   return typeof login === "string" && /^copilot(?:[^a-z]|$)/i.test(login);
 }
 
+// Anti-summon literal: bare-text `@copilot` or a `/copilot*` slash command. Both
+// the write-side sanitizer and the read-side guard scan key off this shape so a
+// gate-evidence comment can quote the rule (inside a code span/fenced block)
+// without arming the request-copilot-review.mjs anti-summon guard. The token
+// regex carries the same left word-boundary as the guard regex so the sanitizer
+// never mangles text the guard would not arm on (e.g. user@copilot.example).
+const COPILOT_SUMMON_TOKEN_RE = /(?<=^|\W)(@copilot|\/copilot[a-z0-9_-]*)/gi;
+const COPILOT_SUMMON_WORD_BOUNDARY_RE = /(?:^|\W)(@copilot|\/copilot)(?:$|\W)/i;
+// GFM inline code span: an N-backtick run, lazy content, closed by a same-length
+// run. Covers single-backtick spans as well as double-backtick spans wrapping a
+// literal backtick.
+const INLINE_CODE_SPAN_RE = /(`+)[\s\S]*?\1(?!`)/g;
+const ZERO_WIDTH_JOINER = "\u200D";
+
+// Apply `transformLine` to every markdown line OUTSIDE a fenced code block
+// (```/~~~), leaving fence-delimiter lines and fenced content untouched.
+// Mirrors the fenced-block tracking scripts/docs/validate-rule-ownership.mjs
+// uses for its own lexical scan.
+function transformNonFencedLines(text, transformLine) {
+  const lines = String(text).split(/\r?\n/);
+  let inFencedBlock = false;
+  let fencedDelimiter = "";
+  const transformed = lines.map((line) => {
+    const rawTrimmed = line.trim();
+    const fenceMatch = rawTrimmed.match(/^(```|~~~)/);
+    if (fenceMatch) {
+      if (!inFencedBlock) {
+        inFencedBlock = true;
+        fencedDelimiter = fenceMatch[1];
+        return line;
+      }
+      if (rawTrimmed.startsWith(fencedDelimiter)) {
+        inFencedBlock = false;
+        fencedDelimiter = "";
+        return line;
+      }
+    }
+    if (inFencedBlock) {
+      return line;
+    }
+    return transformLine(line);
+  });
+  return transformed.join("\n");
+}
+
+// Apply `replaceSegment` to every part of a line that lies OUTSIDE an inline
+// code span (any N-backtick GFM span), leaving span content untouched.
+function transformOutsideSpans(line, replaceSegment) {
+  let result = "";
+  let last = 0;
+  for (const span of line.matchAll(INLINE_CODE_SPAN_RE)) {
+    result += replaceSegment(line.slice(last, span.index));
+    result += span[0];
+    last = span.index + span[0].length;
+  }
+  return result + replaceSegment(line.slice(last));
+}
+
+// Wrap bare `@copilot`/`/copilot*` tokens in backticks so a comment can quote the
+// anti-summon rule without arming it. Tokens already inside an inline code span
+// are left untouched.
+function wrapBareSummonTokensInLine(line) {
+  return transformOutsideSpans(line, (segment) => segment.replace(COPILOT_SUMMON_TOKEN_RE, "`$1`"));
+}
+
+// Does this single (non-fenced) line still arm the guard scan after inline code
+// spans are dropped? Mirrors stripMarkdownCodeForScan's per-line step. Spans are
+// replaced with a SPACE, not the empty string: the fragments flanking a span
+// must never be rejoined into a token that was not present ("@copi`x`lot" is not
+// a summon), while a token directly abutting a span ("text`x`@copilot", which
+// GitHub renders as a real mention) still arms.
+function lineArmsSummonGuard(line) {
+  return COPILOT_SUMMON_WORD_BOUNDARY_RE.test(line.replace(INLINE_CODE_SPAN_RE, " "));
+}
+
+const ZWJ_FALLBACK_RE = /(?<=^|\W)([@/])(copilot)/gi;
+
+// Sanitize one line, verifying against the guard scan. Backtick-wrapping is the
+// primary neutralization (visible, greppable), but pre-existing backticks on the
+// line can destabilize it two ways: an UNBALANCED stray backtick pairs with an
+// inserted one and re-exposes the token to the guard's span-stripping, and
+// adjacent spans (e.g. a span ending right before the token's new wrap) can make
+// the wrapped line re-tokenize differently on the next pass, re-wrapping the
+// token and growing the comment by one backtick per rewrite. The wrapped result
+// is therefore accepted only when it is BOTH guard-inert AND a fixed point of
+// the wrapper (re-wrapping it changes nothing); otherwise fall back to inserting
+// a zero-width joiner into the residual tokens still outside the wrapped line's
+// spans — invisible, guard-inert, and idempotent (the joined token no longer
+// matches the summon shape). Working on the wrapped line (not the original)
+// preserves every stable backtick wrap and keeps the joiner out of legitimate
+// pre-existing code spans.
+function sanitizeSummonLine(line) {
+  const wrapped = wrapBareSummonTokensInLine(line);
+  if (!lineArmsSummonGuard(wrapped) && wrapBareSummonTokensInLine(wrapped) === wrapped) {
+    return wrapped;
+  }
+  return transformOutsideSpans(wrapped, (segment) => segment.replace(ZWJ_FALLBACK_RE, `$1${ZERO_WIDTH_JOINER}$2`));
+}
+
+export function sanitizeCopilotSummonTokens(text) {
+  return transformNonFencedLines(String(text), sanitizeSummonLine);
+}
+
+// Drop all markdown code content (fenced blocks entirely, inline code spans
+// per line) from `text`, leaving only the bare-text markdown to scan. Unlike
+// transformNonFencedLines (which leaves fenced lines verbatim — correct for
+// sanitizing, where code content must not be rewritten), fenced content here
+// must be REMOVED rather than kept: leaving it in place would let bare text
+// inside a fence still match the anti-summon scan.
+function stripMarkdownCodeForScan(text) {
+  const lines = String(text).split(/\r?\n/);
+  let inFencedBlock = false;
+  let fencedDelimiter = "";
+  const kept = [];
+  for (const line of lines) {
+    const rawTrimmed = line.trim();
+    const fenceMatch = rawTrimmed.match(/^(```|~~~)/);
+    if (fenceMatch) {
+      if (!inFencedBlock) {
+        inFencedBlock = true;
+        fencedDelimiter = fenceMatch[1];
+      } else if (rawTrimmed.startsWith(fencedDelimiter)) {
+        inFencedBlock = false;
+        fencedDelimiter = "";
+      }
+      continue;
+    }
+    if (inFencedBlock) {
+      continue;
+    }
+    // Space (not empty-string) replacement: see lineArmsSummonGuard.
+    kept.push(line.replace(INLINE_CODE_SPAN_RE, " "));
+  }
+  return kept.join("\n");
+}
+
+// The request-copilot-review.mjs anti-summon guard scan: true when `text`
+// contains a bare-text (not code-spanned/fenced) `@copilot` or `/copilot`
+// occurrence. Quoting the rule inside backticks or a fenced block is exempt.
+export function containsBareCopilotSummon(text) {
+  return COPILOT_SUMMON_WORD_BOUNDARY_RE.test(stripMarkdownCodeForScan(text));
+}
+
 export function normalizeTimestamp(value) {
   if (typeof value !== "string" || value.trim().length === 0) {
     return null;

package/src/loop/gate-fanin.mjs

@@ -116,6 +116,51 @@ export function provenanceConsistencyError(prov) {
   return null;
 }
 
+/**
+ * Base angle name for a delta-suffixed re-review entry (`<angle>-delta-at-...`,
+ * e.g. `pr-checklist-matrix-delta-at-current-head`): a re-review scoped to only
+ * the current head's delta still counts toward its base angle for both
+ * mandatory-angle coverage and pool-membership checks.
+ *
+ * @param {string} angle
+ * @returns {string}
+ */
+function baseAngleName(angle) {
+  return angle.replace(/-delta-at-.+$/, "");
+}
+
+/**
+ * Validate a recorded fan-out angle list against a gate's configured angle
+ * contract: every mandatory angle must be represented, and — when a pool is
+ * supplied — every recorded angle must be a member of it (delta-suffixed
+ * angles count toward their {@link baseAngleName}). Pure; shared by the write
+ * path (write-gate-findings-log's `provenance.perAngle`, upsert-checkpoint-verdict's
+ * `--findings-json` per-angle results) and the merge-evidence read path
+ * (detect-checkpoint-evidence re-validating the ledger's `provenance.perAngle`)
+ * so all three enforce identically.
+ *
+ * @param {unknown} recordedAngles — array of `{ angle: string, ... }` entries (provenance.perAngle or normalized per-angle findings)
+ * @param {object} [gateAngleContract]
+ * @param {string[]} [gateAngleContract.mandatoryAngles] — angles that must always be represented
+ * @param {string[]|null} [gateAngleContract.pool] — configured angle pool; null/omitted skips the foreign-angle check
+ * @returns {{ missingMandatory: string[], foreignAngles: string[] }}
+ */
+export function checkFanoutAngleCoverage(recordedAngles, { mandatoryAngles = [], pool = null } = {}) {
+  const recorded = Array.isArray(recordedAngles)
+    ? recordedAngles
+      .map((e) => (e && typeof e === "object" && typeof e.angle === "string" ? e.angle.trim() : ""))
+      .filter((a) => a.length > 0)
+    : [];
+  const recordedBases = new Set(recorded.map(baseAngleName));
+  const missingMandatory = mandatoryAngles.filter((a) => !recordedBases.has(a));
+  let foreignAngles = [];
+  if (Array.isArray(pool) && pool.length > 0) {
+    const poolSet = new Set(pool);
+    foreignAngles = [...new Set(recorded.filter((a) => !poolSet.has(baseAngleName(a))))];
+  }
+  return { missingMandatory, foreignAngles };
+}
+
 /**
  * Default cap on parallel fan-out reviewers when a caller does not supply one.
  * Mirrors the config default (gates.maxFanoutReviewers).

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

@@ -411,18 +411,34 @@ function sectionHasBody(section) {
  * Validate that a PR body carries every invariant required to serve as the
  * lightweight spec-of-record: Objective/why, in-scope, explicit non-goals,
  * testable Acceptance criteria (>=1 checklist item), Definition of done
- * (>=1 checklist item), Open questions/risks, and a GitHub closing-keyword
- * issue reference (`Closes #N` and GitHub's other accepted forms — the
- * lightweight path's `Closes #N` linkage, issue #1181). Reuses the generic
- * markdown logic (parseMarkdownSections / AC + DoD patterns /
- * extractChecklistItems) so there is no parallel validator. Fails closed:
- * every missing invariant is reported under its distinct `missing_*` code.
- * Pure; no side effects.
+ * (>=1 checklist item), Open questions/risks, and — unless explicit
+ * issue-less mode is requested — a GitHub closing-keyword issue reference
+ * (`Closes #N` and GitHub's other accepted forms — the lightweight path's
+ * `Closes #N` linkage, issue #1181). Reuses the generic markdown logic
+ * (parseMarkdownSections / AC + DoD patterns / extractChecklistItems) so
+ * there is no parallel validator. Fails closed: every missing invariant is
+ * reported under its distinct `missing_*` code. Pure; no side effects.
  *
- * @param {{ body?: string, expectedIssue?: number }} input
+ * Issue-less mode (`issueLess: true`, issue #1210): the narrative invariants
+ * stay unconditional, but the closing-issue linkage flips from REQUIRED to
+ * FORBIDDEN — the PR is the sole artifact, so it MUST NOT carry a closing
+ * reference to an issue that doesn't back it. A present reference in this
+ * mode fails closed under `unexpected_closing_issue_reference`, distinct
+ * from `missing_closing_issue_reference` (tracker-backed mode, the default)
+ * so callers can tell "no issue expected" apart from "issue expected but
+ * absent". `expectedIssue` and `issueLess` are mutually exclusive; callers
+ * pick exactly one mode (tracker-backed, with or without a specific
+ * expected issue) or issue-less — never both.
+ *
+ * @param {{ body?: string, expectedIssue?: number, issueLess?: boolean }} input
  * @returns {{ checker: "validate-pr-body-spec", ok: boolean, errors: { code: string, message: string }[], sections: string[], acItems: string[], dodItems: string[], closesIssues: number[] }}
  */
-export function validatePrBodySpec({ body = "", expectedIssue = null } = {}) {
+export function validatePrBodySpec({ body = "", expectedIssue = null, issueLess = false } = {}) {
+  if (issueLess && Number.isInteger(expectedIssue)) {
+    // Fail closed at the library boundary too (not just the CLI): the two modes
+    // are contradictory and silently preferring one would hide caller bugs.
+    throw new Error("validatePrBodySpec: issueLess and expectedIssue are mutually exclusive; pass exactly one issue-linkage mode");
+  }
   const bodyText = typeof body === "string" ? body : "";
   const sections = parseMarkdownSections(bodyText);
   const errors = [];
@@ -453,7 +469,14 @@ export function validatePrBodySpec({ body = "", expectedIssue = null } = {}) {
   }
 
   const closesIssues = extractClosingIssueNumbers(bodyText);
-  if (closesIssues.length === 0) {
+  if (issueLess) {
+    if (closesIssues.length > 0) {
+      errors.push({
+        code: "unexpected_closing_issue_reference",
+        message: `Issue-less PR body MUST NOT carry a closing reference to an issue that doesn't back it (found ${closesIssues.map((n) => `#${n}`).join(", ")}).`,
+      });
+    }
+  } else if (closesIssues.length === 0) {
     errors.push({
       code: "missing_closing_issue_reference",
       message: "Missing a GitHub closing-keyword issue reference (e.g. `Closes #123`).",

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

@@ -470,6 +470,110 @@ const TITLE_MARKER_GUARDED_BOUNDARIES = Object.freeze([
   PR_CHECKPOINT.FINAL_APPROVAL_READY,
 ]);
 
+/**
+ * Independent gate-ENTRY re-check (issue #1190): even when the caller's
+ * lifecycleState/sameHeadCleanConverged claims a settled Copilot convergence,
+ * an outstanding (`requested`/`already-requested`) Copilot review request on
+ * the CURRENT head is a second, independent "unsettled" signal — not derived
+ * from sameHeadCleanConverged — that must refuse pre_approval_gate /
+ * final-approval entry outright.
+ *
+ * This mirrors the fail-closed predicate that previously only fired at
+ * *verdict-post* time (upsert-checkpoint-verdict.mjs, which refuses to post a
+ * pre_approval_gate verdict while this same evaluator forbids
+ * RUN_PRE_APPROVAL_GATE): asserting it here, at gate *entry*, refuses the
+ * pre-approval fan-out up front instead of only after reviewer tokens have
+ * already been spent.
+ *
+ * Skipped when Copilot review is not required at all — `reviewMode:
+ * "internal_only"` or `maxCopilotRounds: 0` — preserving the existing #613 /
+ * #1210 exemptions (internal-only and light-dispatched-with-disabled-review
+ * PRs never need a Copilot round in the first place).
+ */
+const PRE_APPROVAL_ENTRY_BOUNDARIES = Object.freeze([
+  PR_CHECKPOINT.PRE_APPROVAL_GATE_NEEDED,
+  PR_CHECKPOINT.PRE_APPROVAL_GATE_WINDOW,
+  PR_CHECKPOINT.FINAL_APPROVAL_READY,
+]);
+
+function applyUnsettledCopilotReviewEntryGuard(input, result) {
+  if (!result || typeof result !== "object" || !PRE_APPROVAL_ENTRY_BOUNDARIES.includes(result.gateBoundary)) {
+    return null;
+  }
+  if (input.maxCopilotRounds === 0) {
+    return null;
+  }
+  const reviewMode = typeof input.reviewMode === "string" ? input.reviewMode.trim().toLowerCase() : null;
+  if (reviewMode === "internal_only") {
+    return null;
+  }
+  const copilotReviewRequestStatus = typeof input.copilotReviewRequestStatus === "string"
+    ? input.copilotReviewRequestStatus.trim().toLowerCase()
+    : "none";
+  if (copilotReviewRequestStatus !== "requested" && copilotReviewRequestStatus !== "already-requested") {
+    return null;
+  }
+  // Round-cap exemption (mirrors shouldGuardCopilotReviewRequest, #896/#848):
+  // past the cap a lingering requested/already-requested status is for a review
+  // that can never come (no further round is permitted), so treating it as
+  // "unsettled" here would re-introduce the infinite-wait dead-end the
+  // ROUND_CAP_CLEAN_FALLBACK routing exists to prevent. When the cap is reached
+  // and the head is clean — either sameHeadCleanConverged or the interpreter's
+  // round_cap_clean_fallback state — the pre_approval_gate proceeds unless
+  // significant post-convergence changes require a new review cycle.
+  const roundCapReached = isCopilotRoundCapReached({
+    copilotReviewRoundCount: input.copilotReviewRoundCount,
+    maxCopilotRounds: input.maxCopilotRounds,
+  });
+  const lifecycleState = typeof input.lifecycleState === "string" ? input.lifecycleState.trim().toLowerCase() : "";
+  const roundCapCleanFallback = lifecycleState === STATE.ROUND_CAP_CLEAN_FALLBACK;
+  if (
+    roundCapReached
+    && (input.sameHeadCleanConverged === true || roundCapCleanFallback)
+    && input.postConvergenceSignificantChange !== true
+  ) {
+    return null;
+  }
+
+  const allowedNextActions = [];
+  const forbiddenActions = [];
+  pushUnique(allowedNextActions, [PR_CHECKPOINT_ACTION.WAIT_FOR_COPILOT_REVIEW]);
+  // Full postDraftForbidden set (matching the canonical WAITING_FOR_COPILOT_REVIEW
+  // result this guard synthesizes) plus the final-approval actions the replaced
+  // boundary result also forbade — dropping RUN_DRAFT_GATE/MARK_READY_FOR_REVIEW
+  // here would let a draft_gate verdict post on a non-draft PR slip through where
+  // the replaced result would have refused it.
+  pushUnique(forbiddenActions, [
+    PR_CHECKPOINT_ACTION.RUN_DRAFT_GATE,
+    PR_CHECKPOINT_ACTION.MARK_READY_FOR_REVIEW,
+    PR_CHECKPOINT_ACTION.RUN_PRE_APPROVAL_GATE,
+    PR_CHECKPOINT_ACTION.AWAIT_FINAL_HUMAN_APPROVAL,
+    PR_CHECKPOINT_ACTION.DECLARE_MERGE_READY,
+  ]);
+
+  return buildResult({
+    repo: input.repo ?? null,
+    pr: Number.isInteger(input.pr) ? input.pr : null,
+    currentHeadSha: result.currentHeadSha ?? null,
+    lifecycleState: STATE.WAITING_FOR_COPILOT_REVIEW,
+    loopDisposition: DISPOSITION.PENDING,
+    gateBoundary: PR_CHECKPOINT.POST_DRAFT_EXTERNAL_REVIEW,
+    draftGateAlreadySatisfied: result.draftGateAlreadySatisfied === true,
+    draftGate: result.draftGate,
+    preApprovalGate: result.preApprovalGate,
+    allowedNextActions,
+    forbiddenActions,
+    nextAction: PR_CHECKPOINT_ACTION.WAIT_FOR_COPILOT_REVIEW,
+    reason: "A Copilot review request is still outstanding on the current head (independent gate-entry "
+      + "re-check, issue #1190) — pre_approval_gate/final-approval entry is refused until the current-head "
+      + "review settles, even though the caller-reported convergence signal claims otherwise.",
+    mergeStateStatus: result.mergeStateStatus ?? null,
+    conflictFiles: result.conflictFiles ?? [],
+    refinementArtifact: result.refinementArtifact ?? null,
+    copilotReviewRoundCount: normalizeNonNegativeInteger(input.copilotReviewRoundCount),
+  });
+}
+
 /**
  * Evaluates PR gate coordination, then re-asserts the merge-blocking title guard
  * (issue #842) at the pre-approval / final-approval boundary for non-draft PRs.
@@ -482,6 +586,11 @@ const TITLE_MARKER_GUARDED_BOUNDARIES = Object.freeze([
 export function evaluatePrGateCoordination(input = {}) {
   const result = evaluatePrGateCoordinationCore(input);
 
+  const unsettledReviewResult = applyUnsettledCopilotReviewEntryGuard(input, result);
+  if (unsettledReviewResult) {
+    return unsettledReviewResult;
+  }
+
   const prDraft = input.prDraft === true;
   const prTitle = typeof input.prTitle === "string" ? input.prTitle : "";
   // Draft PRs may legitimately carry a WIP title; the marker only blocks once

package/src/loop/pr-lifecycle.mjs

@@ -0,0 +1,79 @@
+/**
+ * PR lifecycle: the 13-state vocabulary + required transitions from
+ * skills/docs/pr-lifecycle-contract.md (issue #1193), promoted to a real
+ * exported contract surface.
+ *
+ * This is the single source of truth for the family-local PR lifecycle graph:
+ * both scripts/pages/build-state-atlas.mjs (site diagram generator) and
+ * scripts/docs/validate-state-machine-conformance.mjs (the L2/L3 conformance
+ * harness) import this same table, instead of one importing the other's
+ * module (which would pull the whole page generator — eager mermaid diagram
+ * rendering, duplicate core module instances via relative imports — into the
+ * harness's process at load time).
+ *
+ * Pure data + one derivation, no imports, no side effects.
+ */
+export const PR_LIFECYCLE_STATES = Object.freeze([
+  'draft_local_review_gate',
+  'draft_local_remediation',
+  'ready_state_needs_copilot_request',
+  'waiting_for_copilot_review',
+  'copilot_feedback_remediation',
+  'copilot_reply_resolve_pending',
+  'merge_conflict_resolution',
+  'final_local_preapproval_gate',
+  'final_gate_remediation',
+  'waiting_for_human_pr_approval',
+  'waiting_for_merge',
+  'terminal_slice_complete',
+  'stopped_needs_user_decision',
+]);
+
+// '[*]' is the synthetic terminal-marker target (see build-state-atlas.mjs's
+// renderStateDiagram and validate-state-machine-conformance.mjs's realEdges):
+// a row `[state, '[*]']` marks `state` as absorbing without being a real edge.
+const TERMINAL_MARKER = '[*]';
+
+export const PR_LIFECYCLE_TRANSITIONS = Object.freeze([
+  Object.freeze(['draft_local_review_gate', 'draft_local_remediation']),
+  Object.freeze(['draft_local_review_gate', 'ready_state_needs_copilot_request']),
+  Object.freeze(['draft_local_review_gate', 'stopped_needs_user_decision']),
+  Object.freeze(['draft_local_remediation', 'draft_local_review_gate']),
+  Object.freeze(['ready_state_needs_copilot_request', 'waiting_for_copilot_review']),
+  Object.freeze(['ready_state_needs_copilot_request', 'stopped_needs_user_decision']),
+  Object.freeze(['waiting_for_copilot_review', 'copilot_feedback_remediation']),
+  Object.freeze(['copilot_feedback_remediation', 'copilot_reply_resolve_pending']),
+  Object.freeze(['copilot_reply_resolve_pending', 'ready_state_needs_copilot_request']),
+  Object.freeze(['waiting_for_copilot_review', 'merge_conflict_resolution']),
+  Object.freeze(['merge_conflict_resolution', 'waiting_for_copilot_review']),
+  Object.freeze(['waiting_for_copilot_review', 'final_local_preapproval_gate']),
+  Object.freeze(['final_local_preapproval_gate', 'final_gate_remediation']),
+  Object.freeze(['final_local_preapproval_gate', 'waiting_for_human_pr_approval']),
+  Object.freeze(['final_gate_remediation', 'final_local_preapproval_gate']),
+  Object.freeze(['waiting_for_human_pr_approval', 'waiting_for_merge']),
+  Object.freeze(['waiting_for_human_pr_approval', 'draft_local_review_gate']),
+  Object.freeze(['waiting_for_merge', 'terminal_slice_complete']),
+  Object.freeze(['terminal_slice_complete', TERMINAL_MARKER]),
+  Object.freeze(['stopped_needs_user_decision', TERMINAL_MARKER]),
+]);
+
+// Derived, not hand-listed (lesson from #1157: a hand-copied terminal list can
+// silently drift from the transition table it is supposed to describe). A
+// state is terminal when it has zero real (non-marker) outgoing edges.
+function deriveTerminalStates(states, transitions) {
+  const hasRealOutgoing = new Set(
+    transitions.filter(([, to]) => to !== TERMINAL_MARKER).map(([from]) => from),
+  );
+  return states.filter((state) => !hasRealOutgoing.has(state));
+}
+
+export const PR_LIFECYCLE_TERMINAL_STATES = Object.freeze(deriveTerminalStates(PR_LIFECYCLE_STATES, PR_LIFECYCLE_TRANSITIONS));
+
+// Enum-style access (SCREAMING_SNAKE_CASE key -> the same state string), so
+// handoff scripts can reference `PR_LIFECYCLE_STATE.READY_STATE_NEEDS_COPILOT_REQUEST`
+// instead of hardcoding the literal, mirroring the STATE/OUTER_STATE/REVIEWER_STATE
+// convention used by the other loop state machines. Derived from PR_LIFECYCLE_STATES
+// so a new state cannot be added to one without the other.
+export const PR_LIFECYCLE_STATE = Object.freeze(
+  Object.fromEntries(PR_LIFECYCLE_STATES.map((state) => [state.toUpperCase(), state])),
+);

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

@@ -1,5 +1,5 @@
 import { loadBoardConfig, resolveProjectNumber, loadStateColumnMap, LOGICAL_COLUMN } from "./queue-board-sync.mjs";
-import { main as listQueueItemsMain } from "../../../../scripts/projects/list-queue-items.mjs";
+import { main as listQueueItemsMain } from "../projects/list-queue-items.mjs";
 
 // Canonical fail-closed Next Up tokens — the SINGLE source of truth so the reason
 // codes and the empty-queue message stay byte-identical across every layer that

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

@@ -2,7 +2,7 @@ import { readFileSync } from "node:fs";
 import path from "node:path";
 import { parse as parseYaml } from "yaml";
 import { runChild as coreRunChild } from "../cli/primitives.mjs";
-import { main as moveQueueItemMain } from "../../../../scripts/projects/move-queue-item.mjs";
+import { main as moveQueueItemMain } from "../projects/move-queue-item.mjs";
 
 const DEFAULT_NON_SUCCESS_COLUMN = "Backlog";