@dev-loops/core 1.0.0-rc.6 → 1.0.0

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,

package/src/loop/public-dev-loop-routing.mjs

@@ -2,12 +2,16 @@ import {
   evaluateRetrospectiveGate,
   normalizeRetrospectiveCheckpointState,
   normalizeCheckpointCycleIdentity,
+  normalizeRetroProvenance,
   resolveCheckpointStateFromArtifact,
+  RETROSPECTIVE_PROVENANCE,
 } from "./retrospective-checkpoint.mjs";
 import {
   EXTERNAL_HEALTHY_WAIT_TIMEOUT_POLICY,
   PERSISTENT_INTERNAL_WAIT_TIMEOUT_POLICY,
 } from "./timeout-policy.mjs";
+import { trimmedOrNull } from "./normalize.mjs";
+import { normalizeGateReviewVerdict } from "./policy-constants.mjs";
 import {
   DEV_LOOP_ACTOR,
   DEV_LOOP_ARTIFACT_STATE,
@@ -41,7 +45,9 @@ export * from "./public-dev-loop-routing-contract.mjs";
 // package export (see skills/docs/retrospective-checkpoint-contract.md).
 export {
   normalizeCheckpointCycleIdentity,
+  normalizeRetroProvenance,
   resolveCheckpointStateFromArtifact,
+  RETROSPECTIVE_PROVENANCE,
 };
 
 const COPILOT_ISSUE_ASSIGNEE = "copilot-swe-agent";
@@ -57,7 +63,6 @@ const ISSUE_READINESS_SET = new Set(Object.values(DEV_LOOP_ISSUE_READINESS));
 const ISSUE_ASSIGNMENT_STATE_SET = new Set(Object.values(DEV_LOOP_ISSUE_ASSIGNMENT_STATE));
 const VARIATION_MODE_SET = new Set(DEV_LOOP_VARIATION_PARAMETER_CONTRACT.allowedModeValues);
 const TARGET_PREFERENCE_SET = new Set(DEV_LOOP_VARIATION_PARAMETER_CONTRACT.allowedTargetPreferenceValues);
-const GATE_REVIEW_VERDICT_SET = new Set(["clean", "findings_present", "blocked"]);
 const ALLOWED_MODE_VALUES_TEXT = DEV_LOOP_VARIATION_PARAMETER_CONTRACT.allowedModeValues.join(", ");
 const ALLOWED_TARGET_PREFERENCE_VALUES_TEXT = DEV_LOOP_VARIATION_PARAMETER_CONTRACT.allowedTargetPreferenceValues.join(", ");
 const LINKED_PR_READY_FOR_FOLLOWUP_LOOP_STATE = "linked_pr_ready_for_followup";
@@ -83,8 +88,8 @@ function normalizeTarget(target) {
   const pr = Number.isInteger(target.pr) && target.pr > 0 ? target.pr : null;
   const hasLinkedPr = Object.hasOwn(target, "linkedPr") && target.linkedPr !== null && target.linkedPr !== undefined;
   const linkedPr = Number.isInteger(target.linkedPr) && target.linkedPr > 0 ? target.linkedPr : null;
-  const branch = typeof target.branch === "string" && target.branch.trim().length > 0 ? target.branch.trim() : null;
-  const phase = typeof target.phase === "string" && target.phase.trim().length > 0 ? target.phase.trim() : null;
+  const branch = trimmedOrNull(target.branch);
+  const phase = trimmedOrNull(target.phase);
 
   if (kind === DEV_LOOP_TARGET_KIND.ISSUE && issue === null) {
     return null;
@@ -116,15 +121,6 @@ function normalizeActor(value) {
   return ACTOR_SET.has(normalized) ? normalized : null;
 }
 
-function normalizeSha(value) {
-  return typeof value === "string" && value.trim().length > 0 ? value.trim() : null;
-}
-
-function normalizeGateReviewVerdict(value) {
-  const normalized = typeof value === "string" ? value.trim().toLowerCase() : "";
-  return GATE_REVIEW_VERDICT_SET.has(normalized) ? normalized : null;
-}
-
 function normalizeGateReviewEvidence(evidence) {
   if (evidence === undefined || evidence === null) {
     return null;
@@ -139,10 +135,10 @@ function normalizeGateReviewEvidence(evidence) {
   }
 
   return {
-    currentHeadSha: normalizeSha(evidence.currentHeadSha),
+    currentHeadSha: trimmedOrNull(evidence.currentHeadSha),
     preApprovalGate: {
       visible: preApprovalGate.visible === true,
-      headSha: normalizeSha(preApprovalGate.headSha),
+      headSha: trimmedOrNull(preApprovalGate.headSha),
       verdict: normalizeGateReviewVerdict(preApprovalGate.verdict),
     },
   };
@@ -197,7 +193,7 @@ function normalizeOptionalLoopState(value) {
 }
 
 function normalizeAsyncRunId(value) {
-  const asString = normalizeSha(value);
+  const asString = trimmedOrNull(value);
   if (asString !== null) return asString;
   return null;
 }

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

@@ -1,8 +1,8 @@
 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 "../projects/move-queue-item.mjs";
+import { ghGraphql } from "../github/gh.mjs";
 
 const DEFAULT_NON_SUCCESS_COLUMN = "Backlog";
 
@@ -315,31 +315,6 @@ const LIST_ORG_PROJECTS = [
   "}"
 ].join("\n");
 
-async function ghGraphql(query, vars, env, runChild) {
-  const child = runChild ?? coreRunChild;
-  const fieldArgs = [];
-  for (const [key, value] of Object.entries(vars)) {
-    fieldArgs.push("--field", `${key}=${value}`);
-  }
-  const result = await child(
-    "gh",
-    ["api", "graphql", "--field", `query=${query}`, ...fieldArgs],
-    env,
-  );
-  if (result.code !== 0) {
-    const detail = result.stderr.trim() || `exit code ${result.code}`;
-    throw Object.assign(new Error(`gh api graphql failed: ${detail}`), { code: "GH_API_ERROR" });
-  }
-  const payload = JSON.parse(result.stdout);
-  if (payload.errors && payload.errors.length > 0) {
-    throw Object.assign(
-      new Error(`GraphQL errors: ${payload.errors.map((e) => e.message).join("; ")}`),
-      { code: "GRAPHQL_ERROR" },
-    );
-  }
-  return payload;
-}
-
 async function resolveOwner(login, env, runChild) {
   const userPayload = await ghGraphql(GET_USER_ID, { login }, env, runChild);
   if (userPayload?.data?.user?.id) {

package/src/loop/queue-driver.mjs

@@ -27,6 +27,7 @@ import {
   REASON_NEXT_UP_TARGET_MISSING_LOCALLY,
   EMPTY_NEXT_UP_MESSAGE,
 } from "./queue-board-ordering.mjs";
+import { resolveSizeBudgetHumanApprovalRequired } from "./size-budget-merge-gate.mjs";
 
 export const DEFAULT_QUEUE_DRIVER_OPTIONS = {
   mergeAuthorized: false,
@@ -237,7 +238,19 @@ export async function runQueue(repoRoot, repo, options = {}) {
         if (entryResult.pr) {
           await doTransition(entry, "waiting_review", queue, repoRoot, opts, { pr: entryResult.pr });
           await doTransition(entry, "gates_passing", queue, repoRoot, opts);
-          if (opts.mergeAuthorized) {
+          // Size-budget merge gate (phase 3 of the fail-closed PR size budget): consulted IN
+          // ADDITION TO opts.mergeAuthorized, never in its place. Opt-in per
+          // entry — only engaged when the orchestrator's entryResult carries
+          // a `sizeBudget` object (the size-budget-aware evaluation actually
+          // ran for this PR); an orchestrator that has not been updated to
+          // evaluate the size budget sees unchanged behavior. When engaged,
+          // an escalated/T1 PR without a human APPROVED review (zero
+          // unresolved CHANGES_REQUESTED) is never auto-merged, even under a
+          // standing mergeAuthorized authorization — it routes to the same
+          // "final_approval_ready" column an unauthorized merge would.
+          const sizeBudgetBlocksMerge = entryResult.sizeBudget
+            && resolveSizeBudgetHumanApprovalRequired(entryResult.sizeBudget) === true;
+          if (opts.mergeAuthorized && !sizeBudgetBlocksMerge) {
             await doTransition(entry, "merging", queue, repoRoot, opts);
             await doTransition(entry, "done", queue, repoRoot, opts, { retrospectiveWritten: true });
             await syncColumn(entry.target, columnFor("done"));

package/src/loop/refinement-grill-state.mjs

@@ -19,6 +19,8 @@
  * rather than fabricating an answer to force convergence.
  */
 
+import { trimmedOrNull } from "./normalize.mjs";
+
 export const GRILL_STATE = Object.freeze({
   LOAD_TARGET: "load_target",
   DETECT_GAPS: "detect_gaps",
@@ -85,10 +87,6 @@ function normalizeCount(value) {
     : 0;
 }
 
-function normalizeStringOrNull(value) {
-  return typeof value === "string" && value.trim().length > 0 ? value.trim() : null;
-}
-
 /**
  * Canonicalize a raw grill snapshot into a deterministic shape.
  *
@@ -102,7 +100,7 @@ export function normalizeGrillSnapshot(raw) {
 
   return {
     surface: VALID_SURFACES.has(raw.surface) ? raw.surface : "issue",
-    targetRef: normalizeStringOrNull(raw.targetRef),
+    targetRef: trimmedOrNull(raw.targetRef),
 
     loaded: Boolean(raw.loaded),
     loadFailed: Boolean(raw.loadFailed),

package/src/loop/retrospective-checkpoint.mjs

@@ -55,6 +55,54 @@ export const RETROSPECTIVE_QUALIFYING_GATES = Object.freeze([
   "issue_intake",
 ]);
 
+/**
+ * Provenance context values for a recorded retrospective (issue #1870).
+ *
+ * A retrospective MUST be produced by a FRESH-CONTEXT, independent dispatch
+ * (analogous to a gate reviewer) seeded with the cycle's full agent/subagent
+ * tool-call/action/result record — never written inline by the same working
+ * context that did the work. A self-authored retro reflects the working
+ * agent's own blind spots back at it; it validates consistency, not
+ * conformance, so an inline retro fails the checkpoint.
+ */
+export const RETROSPECTIVE_PROVENANCE = Object.freeze({
+  /** Dispatched as a fresh, independent context (the only accepting value). */
+  CONTEXT_FRESH: "fresh",
+  /** Self-authored by the working context — rejected, fails closed. */
+  CONTEXT_INLINE: "inline",
+  /** The retro was seeded with the full agent/subagent tool-call record. */
+  SEEDED_FROM_RECORD: "agent_tool_call_record",
+});
+
+/**
+ * Normalizes a retrospective provenance record from a durable checkpoint
+ * artifact. Returns the normalized provenance only when it pins a valid
+ * fresh-context pass over the full tool-call record:
+ * - `context` must normalize to "fresh" (trimmed, case-insensitive; an
+ *   "inline"/self-authored retro is rejected — it fails closed, never accepted)
+ * - `seededFrom` must be exactly "agent_tool_call_record" (the retro audited
+ *   the cycle's actual behavior, not a summary)
+ * - `recordSource` must be a non-blank string (the transcript/journal path
+ *   the retro was seeded with)
+ *
+ * Returns null for anything else — absent, malformed, inline, or partial.
+ *
+ * @param {unknown} value
+ * @returns {{context: "fresh", seededFrom: "agent_tool_call_record", recordSource: string}|null}
+ */
+export function normalizeRetroProvenance(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    return null;
+  }
+  const context = typeof value.context === "string" ? value.context.trim().toLowerCase() : "";
+  const seededFrom = typeof value.seededFrom === "string" ? value.seededFrom.trim().toLowerCase() : "";
+  const recordSource = typeof value.recordSource === "string" ? value.recordSource.trim() : "";
+  if (context !== RETROSPECTIVE_PROVENANCE.CONTEXT_FRESH || seededFrom !== RETROSPECTIVE_PROVENANCE.SEEDED_FROM_RECORD || recordSource.length === 0) {
+    return null;
+  }
+  return { context: RETROSPECTIVE_PROVENANCE.CONTEXT_FRESH, seededFrom: RETROSPECTIVE_PROVENANCE.SEEDED_FROM_RECORD, recordSource };
+}
+
 /**
  * Normalizes an external retrospective checkpoint-state input to one of the
  * stable RETROSPECTIVE_CHECKPOINT_STATE values. Returns null when the value is
@@ -149,7 +197,17 @@ export function resolveCheckpointStateFromArtifact(artifact, { hasNewerMergeSinc
     return hasNewerMergeSinceCheckpoint ? RETROSPECTIVE_CHECKPOINT_STATE.MISSING : RETROSPECTIVE_CHECKPOINT_STATE.SKIPPED;
   }
   if (rawState === "complete") {
-    return hasNewerMergeSinceCheckpoint ? RETROSPECTIVE_CHECKPOINT_STATE.MISSING : RETROSPECTIVE_CHECKPOINT_STATE.COMPLETE;
+    if (hasNewerMergeSinceCheckpoint) {
+      return RETROSPECTIVE_CHECKPOINT_STATE.MISSING;
+    }
+    // Fresh-context provenance is mandatory (issue #1870): a `complete` record
+    // without provenance that pins a fresh-context pass over the full
+    // tool-call record — including legacy inline/self-authored retros — fails
+    // closed to MISSING. The old inline self-review path is disallowed.
+    if (normalizeRetroProvenance(artifact.provenance) === null) {
+      return RETROSPECTIVE_CHECKPOINT_STATE.MISSING;
+    }
+    return RETROSPECTIVE_CHECKPOINT_STATE.COMPLETE;
   }
   // Malformed/unrecognized durable state — fail closed.
   return RETROSPECTIVE_CHECKPOINT_STATE.MISSING;