@dev-loops/core 1.0.0-rc.5 → 1.0.0-rc.7

package/src/loop/main-checkout-ff.mjs

@@ -24,6 +24,7 @@
  * No imports so this file vendors into the `.claude/hooks/` bundle unchanged
  * (vendored modules may only import `node:` builtins or relative paths).
  */
+import path from "node:path";
 
 /**
  * Timeout (ms) for the `git worktree list` resolution step (the fetch-half budget;
@@ -56,3 +57,75 @@ export function buildMainCheckoutFastForwardCommand(mainCheckout) {
   // wrong branch. No state change, no git switch.
   return `git -C ${quoted} fetch origin main && [ "$(git -C ${quoted} rev-parse --abbrev-ref HEAD)" = main ] && git -C ${quoted} merge --ff-only origin/main`;
 }
+
+/**
+ * Worktree-cleanup timeout (ms) for the post-merge `git worktree remove` half.
+ */
+export const WORKTREE_CLEANUP_TIMEOUT_MS = 60_000;
+
+/**
+ * Build the best-effort post-merge worktree-removal command string (#1627).
+ *
+ * The dev-loop mandates removing the branch's worktree after merge, but neither
+ * the merge procedure nor the post-merge hooks performed it. This builds the
+ * shell command that runs the shared `cleanup-worktree.mjs` script FROM the main
+ * checkout (the hook's cwd can be inside the worktree being removed, which makes
+ * `git worktree remove` fail), and stays non-fatal: the script itself is fail-soft
+ * (refuses any path outside tmp/worktrees/dev-loops/, exits 0 on git errors), and
+ * the surrounding guard makes a consumer checkout without the script a silent no-op.
+ * `prNumber` is shell-escaped as a double-quoted argument; `mainCheckout` and the
+ * script path are POSIX single-quoted. Returns an empty string when no PR number
+ * (or no meaningful target) is available, so callers can skip cleanly.
+ *
+ * @param {string} mainCheckout - Absolute path to the main (primary) git checkout.
+ * @param {string | number | undefined} prNumber - Merged PR number (drives `--pr`).
+ * @returns {string} the cleanup command, or "" when `prNumber` is absent.
+ */
+export function buildWorktreeCleanupCommand(mainCheckout, prNumber) {
+  const pr = String(prNumber ?? "").trim();
+  // Validate the PR number is a positive integer BEFORE embedding it into the
+  // shell string; a caller passing a non-numeric string (could carry command
+  // substitution) is refused by returning "" — defense-in-depth in a public helper.
+  if (!/^[0-9]+$/u.test(pr)) {
+    return "";
+  }
+  const quotedMain = shellQuotePath(mainCheckout);
+  const script = shellQuotePath(path.join(mainCheckout, "scripts", "loop", "cleanup-worktree.mjs"));
+  // Guard the script's existence (consumer no-op) and keep the whole thing
+  // non-fatal with `|| true` — removal must never break a merge-completion flow.
+  return `if [ -f ${script} ]; then node ${script} --repo-root ${quotedMain} --pr "${pr}"; fi || true`;
+}
+
+/**
+ * Overall timeout (ms) for the post-merge actions runner invocation. Generous:
+ * the runner itself bounds each declared action by its own timeoutMs/verify
+ * budget (each individually capped at the config-schema ceiling), and this is
+ * only the outer harness-hook guard against a runner that never returns.
+ */
+export const POST_MERGE_ACTIONS_TIMEOUT_MS = 900_000;
+
+/**
+ * Build the best-effort `postMerge.actions` runner command (#1457): the shared,
+ * dependency-free command string both harness hooks (Pi `post-merge-update`,
+ * Claude `post-tool-use-merge`) run after a successful merge, for the repo that
+ * merged. Existence-guarded (a checkout without the runner script is a silent
+ * no-op) and non-fatal (`|| true` — a runner failure must never break a
+ * merge-completion flow; the runner itself reports per-action failures in its
+ * own JSON result). `mainCheckout` and the script path are POSIX
+ * single-quoted; `prNumber` (when a valid positive integer) is passed as a
+ * double-quoted `--pr` argument — never interpolated into `run`/`verify`
+ * command strings, which the runner executes verbatim from the repo's own
+ * `.devloops`.
+ *
+ * @param {string} mainCheckout - Absolute path to the main (primary) git checkout.
+ * @param {string | number | undefined} [prNumber] - Merged PR number, when known.
+ * @returns {string} the runner command (always non-empty; a missing PR number
+ *   just omits `--pr`, since `onlyIfChanged` scoping bypasses cleanly without one).
+ */
+export function buildPostMergeActionsCommand(mainCheckout, prNumber) {
+  const quotedMain = shellQuotePath(mainCheckout);
+  const script = shellQuotePath(path.join(mainCheckout, "scripts", "loop", "run-post-merge-actions.mjs"));
+  const pr = String(prNumber ?? "").trim();
+  const prArg = /^[0-9]+$/u.test(pr) ? ` --pr "${pr}"` : "";
+  return `if [ -f ${script} ]; then node ${script} --repo-root ${quotedMain}${prArg}; fi || true`;
+}

package/src/loop/markdown-sections.mjs

@@ -0,0 +1,40 @@
+/**
+ * Shared `## <heading>` markdown-section helpers. A "section" is an H2
+ * heading line and everything up to (but not including) the next H2.
+ */
+
+/** Build the case-insensitive, multiline `^## <heading>$` matcher shared by
+ * extractSection/hasSection/stripSection. */
+export function buildSectionHeadingPattern(headingText) {
+  // Public export: a non-string or empty heading has no section to match, so
+  // return a never-match pattern rather than throwing (non-string) or building
+  // a bare `^##\s+\s*$` that matches any H2 (empty). Every in-repo caller passes
+  // a canonical heading string; this only hardens the new public boundary.
+  if (typeof headingText !== "string" || headingText.length === 0) {
+    return /(?!)/u;
+  }
+  const escapedHeading = headingText.replace(/[.*+?^${}()|[\]\\]/gu, "\\$&");
+  return new RegExp(`^##\\s+${escapedHeading}\\s*$`, "imu");
+}
+
+/**
+ * Extract the trimmed body of a `## <headingText>` section from `body`, or
+ * null when the heading isn't present.
+ */
+export function extractSection(body, headingText) {
+  if (typeof body !== "string" || body.length === 0) {
+    return null;
+  }
+  const headingPattern = buildSectionHeadingPattern(headingText);
+  const match = headingPattern.exec(body);
+  if (!match || match.index === undefined) {
+    return null;
+  }
+  const start = match.index + match[0].length;
+  const remaining = body.slice(start);
+  const nextHeadingMatch = /^##\s+/imu.exec(remaining);
+  const end = nextHeadingMatch && nextHeadingMatch.index !== undefined
+    ? start + nextHeadingMatch.index
+    : body.length;
+  return body.slice(start, end).trim();
+}

package/src/loop/normalize.mjs

@@ -0,0 +1,7 @@
+/**
+ * Shared string-normalization primitive used across the loop layer:
+ * trim a value and return it, or null when it isn't a non-empty string.
+ */
+export function trimmedOrNull(value) {
+  return typeof value === "string" && value.trim().length > 0 ? value.trim() : null;
+}

package/src/loop/plan-file-promote-contract.mjs

@@ -219,16 +219,28 @@ function neutralizeIssueCloseKeywords(text) {
  * authority. Issue-closing keywords inside the embedded AC/DoD are neutralized
  * so untrusted plan content cannot smuggle one in.
  *
+ * The plan's `## Size estimate` section (phase 4 of #1480's plan-time size budget —
+ * see `validatePhaseSizeEstimate` in `plan-file-refine-contract.mjs`) is carried
+ * through verbatim when present, so an over-budget-but-cohesive phase's
+ * `oversize: justified` note flows into the PR the fail-closed post-hoc size
+ * budget (`check-size-budget.mjs`, wired at draft-exit) later escalates: a human
+ * reading that PR's escalated review sees the plan-time reasoning right in the
+ * body, not just that the diff came out large. Optional — an already-promoted
+ * or hand-authored plan without the section still promotes; the section is
+ * simply omitted from the PR body.
+ *
  * @param {object} params
  * @param {string} params.planDocPath  repo-relative path of the committed plan doc
  * @param {string} params.acceptanceCriteria  full Acceptance criteria section body
  * @param {string} params.definitionOfDone  full Definition of done section body
+ * @param {string} [params.sizeEstimate]  full Size estimate section body, if present
  * @returns {string}
  */
-export function buildPromotionPrBody({ planDocPath, acceptanceCriteria, definitionOfDone } = {}) {
+export function buildPromotionPrBody({ planDocPath, acceptanceCriteria, definitionOfDone, sizeEstimate } = {}) {
   const docPath = String(planDocPath ?? "").trim();
   const ac = String(acceptanceCriteria ?? "").trim();
   const dod = String(definitionOfDone ?? "").trim();
+  const size = String(sizeEstimate ?? "").trim();
   if (docPath.length === 0) {
     throw new Error("buildPromotionPrBody requires a planDocPath");
   }
@@ -252,5 +264,6 @@ export function buildPromotionPrBody({ planDocPath, acceptanceCriteria, definiti
     "",
     safeDod,
     "",
+    ...(size.length > 0 ? ["## Size estimate", "", neutralizeIssueCloseKeywords(size), ""] : []),
   ].join("\n");
 }

package/src/loop/plan-file-refine-contract.mjs

@@ -27,6 +27,7 @@ import {
   PLAN_FILE_INTAKE_STATE,
   PLAN_FILE_REFINEMENT_SECTIONS,
 } from "./plan-file-intake-contract.mjs";
+import { buildSectionHeadingPattern, extractSection } from "./markdown-sections.mjs";
 
 /** The local human-review checkpoint surface the loop stops at on success. */
 export const PLAN_FILE_REFINE_STOP = Object.freeze({
@@ -40,14 +41,79 @@ export const DOCS_GRILL_FINDINGS_HEADING = "Docs-grill findings";
 /** The heading the refiner coverage matrix lives under in the plan file. */
 export const COVERAGE_MATRIX_HEADING = "Coverage matrix";
 
+/** The heading the per-phase size estimate lives under in the plan file. */
+export const SIZE_ESTIMATE_HEADING = "Size estimate";
+
+/** Size-budget tiers this contract accepts — the same enum check-size-budget.mjs's
+ * `resolveFileTier` resolves a changed file into (Phase 1 of #1480). */
+const VALID_SIZE_TIERS = new Set(["default", "t1", "t3"]);
+
+// Fallback default-tier soft-LOC threshold, used only when the caller omits
+// `sizeSoftLoc`. Mirrors check-size-budget.mjs's exported `DEFAULT_TIER_DEFAULTS.softLoc`
+// value exactly (400) — duplicated as a literal rather than imported because this module
+// is published as @dev-loops/core and must not import a scripts/ CLI module (same
+// import-boundary rule the docs-grill classifier note above documents). A repo-configured
+// `gates.size.tiers.default.softLoc` should always be threaded through by the caller
+// instead of relying on this fallback.
+const DEFAULT_SIZE_SOFT_LOC = 400;
+
+/**
+ * Parse a refiner-authored size-estimate payload into the rendered section body,
+ * validating it against the SAME vocabulary/thresholds check-size-budget.mjs's
+ * `computeSizeBudget` uses for the actual post-hoc diff measurement: `logicLoc`,
+ * tier (`default`|`t1`|`t3`), and the default tier's `softLoc` escalation threshold.
+ *
+ * This is the plan-time counterpart of that post-hoc computation (see the issue's
+ * "Refinement budget (plan time)" design intent): an over-`softLoc` estimate must
+ * carry an explicit, non-empty `oversizeJustification` — the refiner looked for a
+ * seam to split the phase and, finding none, records why the phase is cohesive.
+ * A missing justification on an over-budget estimate fails closed rather than
+ * silently accepting an unexplained oversize phase.
+ *
+ * @param {object} sizeEstimate
+ * @param {number} sizeEstimate.logicLoc  estimated logic LOC for the phase (non-negative integer)
+ * @param {string} [sizeEstimate.tier]  "default" (implicit) | "t1" | "t3"
+ * @param {string} [sizeEstimate.oversizeJustification]  required non-empty text when logicLoc exceeds softLoc
+ * @param {number} [softLoc]  default-tier soft-LOC escalation threshold (falls back to DEFAULT_SIZE_SOFT_LOC)
+ * @returns {{ ok: boolean, reason?: string, logicLoc?: number, tier?: string, softLoc?: number, overBudget?: boolean, oversizeNote?: string|null, body?: string }}
+ */
+export function validatePhaseSizeEstimate(sizeEstimate, softLoc = DEFAULT_SIZE_SOFT_LOC) {
+  if (!sizeEstimate || typeof sizeEstimate !== "object") {
+    return { ok: false, reason: "missing_size_estimate" };
+  }
+  const { logicLoc, tier = "default", oversizeJustification } = sizeEstimate;
+  if (!Number.isInteger(logicLoc) || logicLoc < 0) {
+    return { ok: false, reason: "invalid_size_estimate_loc" };
+  }
+  if (!VALID_SIZE_TIERS.has(tier)) {
+    return { ok: false, reason: "invalid_size_estimate_tier" };
+  }
+  const effectiveSoftLoc = typeof softLoc === "number" && softLoc > 0 ? softLoc : DEFAULT_SIZE_SOFT_LOC;
+  const overBudget = logicLoc > effectiveSoftLoc;
+  const justification = typeof oversizeJustification === "string" ? oversizeJustification.trim() : "";
+  if (overBudget && justification.length === 0) {
+    // Fail closed: this is the refiner's prompt to look for a seam and split the
+    // phase before proceeding; a cohesive phase must say so explicitly instead.
+    return { ok: false, reason: "size_estimate_oversize_not_justified" };
+  }
+  const oversizeNote = overBudget ? justification : null;
+  const body = [
+    `- Estimated logic LOC: ${logicLoc}`,
+    `- Tier: ${tier}`,
+    overBudget
+      ? `- Oversize: justified — ${oversizeNote}`
+      : `- Oversize: n/a (within default tier's softLoc budget of ${effectiveSoftLoc})`,
+  ].join("\n");
+  return { ok: true, logicLoc, tier, softLoc: effectiveSoftLoc, overBudget, oversizeNote, body };
+}
+
 /**
  * Remove an existing `## <heading>` section (heading + body up to the next H2)
  * from markdown so a refine re-run replaces it rather than appending a duplicate.
  * Returns the markdown unchanged when the heading is absent.
  */
 function stripSection(markdownText, headingText) {
-  const escapedHeading = headingText.replace(/[.*+?^${}()|[\]\\]/gu, "\\$&");
-  const headingPattern = new RegExp(`^##\\s+${escapedHeading}\\s*$`, "imu");
+  const headingPattern = buildSectionHeadingPattern(headingText);
   const match = headingPattern.exec(markdownText);
   if (!match || match.index === undefined) return markdownText;
   const start = match.index;
@@ -65,12 +131,10 @@ function stripSection(markdownText, headingText) {
  * Whether markdown carries a `## <heading>` section marker. Used to re-derive
  * the section-presence facts from the freshly-written text so the end-state
  * check verifies the append actually happened (rather than re-asserting the
- * inputs). ponytail: local copy of the section-detect regex; the shared section
- * helper belongs in core once extractSection is lifted out of scripts/.
+ * inputs).
  */
 function hasSection(markdownText, headingText) {
-  const escaped = headingText.replace(/[.*+?^${}()|[\]\\]/gu, "\\$&");
-  return new RegExp(`^##\\s+${escaped}\\s*$`, "imu").test(markdownText);
+  return extractSection(markdownText, headingText) !== null;
 }
 
 /** Append a `## <heading>` section with the given body to markdown. */
@@ -114,13 +178,16 @@ function renderGrillFindings(classified) {
  * @param {string} params.payload.acceptanceCriteria  Acceptance criteria section body
  * @param {string} params.payload.definitionOfDone  Definition of done section body
  * @param {string} params.payload.coverageMatrix  AC/DoD/Non-goal coverage matrix (markdown table)
+ * @param {object} params.payload.sizeEstimate  per-phase size estimate (see `validatePhaseSizeEstimate`); an over-`sizeSoftLoc` estimate must carry a non-empty `oversizeJustification` or the refine fails closed, prompting a seam search
  * @param {object[]} [params.payload.grillDispositions]  docs-grill dispositions the caller pre-classified via #948's `classifyDocsGrillFinding`; each entry is `{ kind, summary, disposition }` and a null/invalid `disposition` fails the grill closed
+ * @param {number} [params.sizeSoftLoc]  default-tier soft-LOC escalation threshold the size estimate is checked against — the caller threads this from `gates.size.tiers.default.softLoc` (falls back to check-size-budget.mjs's own default when config carries none)
  * @returns {{
  *   ok: boolean,
  *   reason?: string,
  *   planFileIntakeState?: string,
  *   refinedMarkdown?: string,
  *   grillDispositions?: object[],
+ *   sizeEstimate?: { logicLoc: number, tier: string, softLoc: number, overBudget: boolean, oversizeNote: string|null },
  *   stop?: { kind: string },
  * }}
  */
@@ -130,6 +197,7 @@ export function refinePlanFileInPlace({
   hasAcceptanceCriteria,
   hasDefinitionOfDone,
   payload,
+  sizeSoftLoc,
 } = {}) {
   if (typeof markdownText !== "string" || markdownText.length === 0) {
     return { ok: false, reason: "missing_plan_markdown" };
@@ -166,6 +234,14 @@ export function refinePlanFileInPlace({
     return { ok: false, reason: "missing_coverage_matrix", planFileIntakeState: startState };
   }
 
+  // Plan-time size estimate (phase 4 of #1480): the same fail-closed check as an
+  // over-budget PR, run at plan time instead of on a real diff. `validatePhaseSizeEstimate`
+  // owns the vocabulary/threshold and the oversize-without-justification fail-closed reason.
+  const sizeEstimateResult = validatePhaseSizeEstimate(payload.sizeEstimate, sizeSoftLoc);
+  if (!sizeEstimateResult.ok) {
+    return { ok: false, reason: sizeEstimateResult.reason, planFileIntakeState: startState };
+  }
+
   // The docs-grill runs as a step of refinement. The caller (the CLI, which owns
   // I/O and the scripts/ boundary) classifies each finding with #948's
   // `classifyDocsGrillFinding` and passes the dispositions in. This core module
@@ -185,7 +261,7 @@ export function refinePlanFileInPlace({
   // would break the strip-then-append idempotency on a re-run (the inner heading and
   // its text would orphan into the document body). Fail closed on such a payload.
   const grillBody = renderGrillFindings(grillDispositions);
-  if ([acceptanceCriteria, definitionOfDone, coverageMatrix, grillBody].some((b) => /^##\s/mu.test(String(b)))) {
+  if ([acceptanceCriteria, definitionOfDone, coverageMatrix, sizeEstimateResult.body, grillBody].some((b) => /^##\s/mu.test(String(b)))) {
     return { ok: false, reason: "section_body_contains_heading", planFileIntakeState: startState };
   }
 
@@ -194,11 +270,12 @@ export function refinePlanFileInPlace({
   // sections in a stable order.
   const [acHeading, dodHeading] = PLAN_FILE_REFINEMENT_SECTIONS;
   let refinedMarkdown = markdownText;
-  for (const heading of [acHeading, dodHeading, COVERAGE_MATRIX_HEADING, DOCS_GRILL_FINDINGS_HEADING]) {
+  for (const heading of [acHeading, dodHeading, SIZE_ESTIMATE_HEADING, COVERAGE_MATRIX_HEADING, DOCS_GRILL_FINDINGS_HEADING]) {
     refinedMarkdown = stripSection(refinedMarkdown, heading);
   }
   refinedMarkdown = appendSection(refinedMarkdown, acHeading, acceptanceCriteria);
   refinedMarkdown = appendSection(refinedMarkdown, dodHeading, definitionOfDone);
+  refinedMarkdown = appendSection(refinedMarkdown, SIZE_ESTIMATE_HEADING, sizeEstimateResult.body);
   refinedMarkdown = appendSection(refinedMarkdown, COVERAGE_MATRIX_HEADING, coverageMatrix);
   refinedMarkdown = appendSection(refinedMarkdown, DOCS_GRILL_FINDINGS_HEADING, grillBody);
 
@@ -221,6 +298,13 @@ export function refinePlanFileInPlace({
     planFileIntakeState: endState,
     refinedMarkdown,
     grillDispositions,
+    sizeEstimate: {
+      logicLoc: sizeEstimateResult.logicLoc,
+      tier: sizeEstimateResult.tier,
+      softLoc: sizeEstimateResult.softLoc,
+      overBudget: sizeEstimateResult.overBudget,
+      oversizeNote: sizeEstimateResult.oversizeNote,
+    },
     // Generalized proposal-first stop: the refined plan is the local artifact,
     // it is written in-place, and the loop stops here for human review before
     // any promotion. No tracker artifact is created or mutated.

package/src/loop/policy-constants.mjs

@@ -12,3 +12,12 @@ export const COPILOT_FIRST_DURABLE_WAIT_TIMEOUT_MS = 3_600_000;
 
 /** Copilot review wait: external healthy-wait budget */
 export const COPILOT_REVIEW_WAIT_TIMEOUT_MS = 1_800_000;
+
+/** Gate review verdict vocabulary shared by tracker/public-routing normalizers. */
+export const GATE_REVIEW_VERDICT_SET = new Set(["clean", "findings_present", "blocked"]);
+
+/** Normalize a raw gate review verdict to a member of GATE_REVIEW_VERDICT_SET, or null. */
+export function normalizeGateReviewVerdict(value) {
+  const normalized = typeof value === "string" ? value.trim().toLowerCase() : "";
+  return GATE_REVIEW_VERDICT_SET.has(normalized) ? normalized : null;
+}

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

@@ -1,6 +1,8 @@
 import { DISPOSITION, isCopilotRoundCapReached, STATE } from "./copilot-loop-state.mjs";
 import { findBlockingTitleMarkers } from "./pr-title-markers.mjs";
 import { evaluateUiE2eScoping } from "./ui-e2e-scoping.mjs";
+import { evaluateUiDesignerReviewScoping } from "./ui-designer-review-scoping.mjs";
+import { trimmedOrNull } from "./normalize.mjs";
 
 export const PR_CHECKPOINT = Object.freeze({
   DRAFT_REVIEW: "draft_review",
@@ -8,6 +10,7 @@ export const PR_CHECKPOINT = Object.freeze({
   FEEDBACK_RESOLUTION: "feedback_resolution",
   CONFLICT_RESOLUTION: "conflict_resolution",
   UI_E2E_SCOPING: "ui_e2e_scoping",
+  DESIGNER_REVIEW_SCOPING: "designer_review_scoping",
   PRE_APPROVAL_GATE_WINDOW: "pre_approval_gate_window",
   FINAL_APPROVAL_READY: "final_approval_ready",
   PRE_APPROVAL_GATE_NEEDED: "pre_approval_gate_needed",
@@ -61,6 +64,7 @@ export const PR_CHECKPOINT_ACTION = Object.freeze({
   REPORT_BLOCKED: "report_blocked",
   REPORT_DONE: "report_done",
   RUN_UI_E2E_SUITE: "run_ui_e2e_suite",
+  RECORD_DESIGNER_REVIEW: "record_designer_review",
 });
 
 function normalizeGateComment(summary = null) {
@@ -77,14 +81,10 @@ function normalizeGateComment(summary = null) {
 
   return {
     visible: summary.visible === true,
-    headSha: typeof summary.headSha === "string" && summary.headSha.trim().length > 0 ? summary.headSha.trim() : null,
+    headSha: trimmedOrNull(summary.headSha),
     verdict: typeof summary.verdict === "string" && summary.verdict.trim().length > 0 ? summary.verdict.trim().toLowerCase() : null,
-    findingsSummary: typeof summary.findingsSummary === "string" && summary.findingsSummary.trim().length > 0
-      ? summary.findingsSummary.trim()
-      : null,
-    nextAction: typeof summary.nextAction === "string" && summary.nextAction.trim().length > 0
-      ? summary.nextAction.trim()
-      : null,
+    findingsSummary: trimmedOrNull(summary.findingsSummary),
+    nextAction: trimmedOrNull(summary.nextAction),
     contractComplete: summary.contractComplete === true,
   };
 }
@@ -676,9 +676,7 @@ export function evaluatePrGateCoordination(input = {}) {
 }
 
 function evaluatePrGateCoordinationCore(input = {}) {
-  const currentHeadSha = typeof input.currentHeadSha === "string" && input.currentHeadSha.trim().length > 0
-    ? input.currentHeadSha.trim()
-    : null;
+  const currentHeadSha = trimmedOrNull(input.currentHeadSha);
   const lifecycleState = typeof input.lifecycleState === "string" ? input.lifecycleState.trim().toLowerCase() : "";
   const loopDisposition = typeof input.loopDisposition === "string" ? input.loopDisposition.trim().toLowerCase() : null;
   const prDraft = input.prDraft === true;
@@ -730,6 +728,12 @@ function evaluatePrGateCoordinationCore(input = {}) {
   // e2e suite passed for this head. Inclusion is path-triggered, never annotated.
   const changedFiles = Array.isArray(input.changedFiles) ? input.changedFiles : [];
   const uiE2ePassed = input.uiE2ePassed === true ? true : (input.uiE2ePassed === false ? false : null);
+  // Designer/vision recorded-evidence scoping (#1443, ADR 0041 UI half). See
+  // the designer-review scoping block below. Evidence reuses the loop's
+  // existing outcome + artifact-bundle record; exempt when a light/spike
+  // relaxed-gate carve-out applies.
+  const designerReviewEvidence = input.designerReviewEvidence ?? null;
+  const designerReviewExempt = input.designerReviewExempt === true;
   const refinementArtifact = input.refinementArtifact && typeof input.refinementArtifact === "object"
     ? input.refinementArtifact
     : null;
@@ -918,6 +922,48 @@ function evaluatePrGateCoordinationCore(input = {}) {
     });
   }
 
+  // Designer/vision recorded-evidence precondition (#1443, ADR 0041 UI half).
+  // Path-triggered + fail-closed, modeled on the UI e2e scoping block above: if
+  // the PR's changed files touch a rendered artifact (docs/articles|presentations
+  // HTML), it MUST carry recorded designer/vision review evidence (the loop's
+  // existing outcome + artifact bundle) and the recorded outcome MUST be
+  // `ui_review_satisfied`. A rendered-artifact change with missing or unsatisfied
+  // recorded evidence blocks here, naming the artifact. Light/spike relaxed-gate
+  // carve-outs exempt the requirement. Non-UI changes pass through untouched.
+  const uiDesignerScoping = evaluateUiDesignerReviewScoping(changedFiles, {
+    designerReviewEvidence,
+    designerReviewExempt,
+  });
+  if (uiDesignerScoping.required && !uiDesignerScoping.satisfied) {
+    pushUnique(allowedNextActions, [PR_CHECKPOINT_ACTION.RECORD_DESIGNER_REVIEW]);
+    pushUnique(forbiddenActions, [
+      PR_CHECKPOINT_ACTION.MARK_READY_FOR_REVIEW,
+      PR_CHECKPOINT_ACTION.REQUEST_COPILOT_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,
+      lifecycleState: effectiveLifecycleState,
+      loopDisposition: DISPOSITION.ACTION_REQUIRED,
+      gateBoundary: PR_CHECKPOINT.DESIGNER_REVIEW_SCOPING,
+      draftGateAlreadySatisfied,
+      draftGate,
+      preApprovalGate,
+      allowedNextActions,
+      forbiddenActions,
+      nextAction: PR_CHECKPOINT_ACTION.RECORD_DESIGNER_REVIEW,
+      reason: uiDesignerScoping.reason,
+      mergeStateStatus,
+      conflictFiles,
+      refinementArtifact,
+      copilotReviewRoundCount,
+    });
+  }
+
   if (prDraft || effectiveLifecycleState === STATE.PR_DRAFT) {
     if (refinementArtifactStatus === REFINEMENT_ARTIFACT_STATUS.MISSING) {
       pushUnique(allowedNextActions, [PR_CHECKPOINT_ACTION.REPORT_BLOCKED]);
@@ -1313,7 +1359,14 @@ function evaluatePrGateCoordinationCore(input = {}) {
       ? buildRoundExhaustionGateEvidenceNote({ copilotReviewRoundCount, maxCopilotRounds, ciStatus, preApprovalRequireCi })
       : null;
 
-    if (!sameHeadCleanConverged && !postConvergenceReviewSuppressed && (!roundCapReached || roundCapNewCycleRequired)) {
+    // reviewMode "internal_only" (which also folds in maxCopilotRounds:0 via
+    // copilotReviewDisabled) suppresses Copilot: the handoff routes such a PR
+    // straight to pre_approval_gate, so this branch must not force a re-request
+    // for a missing Copilot convergence point that will never exist. The
+    // sibling PR_READY_NO_FEEDBACK branch already honors internal_only; this
+    // reconciles READY_TO_REREQUEST_REVIEW with it (issue 1771). Non-suppressed
+    // external-review PRs keep reviewMode null and hit the guard unchanged.
+    if (!sameHeadCleanConverged && !postConvergenceReviewSuppressed && reviewMode !== "internal_only" && (!roundCapReached || roundCapNewCycleRequired)) {
       pushUnique(allowedNextActions, [PR_CHECKPOINT_ACTION.REREQUEST_COPILOT_REVIEW]);
       pushUnique(forbiddenActions, postDraftForbidden);
       return buildResult({
@@ -1331,7 +1384,7 @@ function evaluatePrGateCoordinationCore(input = {}) {
         nextAction: PR_CHECKPOINT_ACTION.REREQUEST_COPILOT_REVIEW,
         reason: roundCapNewCycleRequired
           ? "The previous Copilot cycle converged at the round cap, but significant post-convergence changes landed on a newer head; start a new Copilot review cycle and re-request review before `pre_approval_gate`."
-          : "The review loop is between passes, but the current head does not yet have a clean settled Copilot convergence point, so `pre_approval_gate` is still forbidden.",
+          : "The review loop is between passes, but the current head does not yet have a clean settled Copilot convergence point, so `pre_approval_gate` is still forbidden. If a Copilot round just landed at this head, it may not be visible to the evaluator yet; re-check after a short propagation wait before treating this as a needed re-request.",
         mergeStateStatus,
         conflictFiles,
           refinementArtifact,