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

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

@@ -9,6 +9,13 @@
  * `Acceptance criteria` or `DoD` section cause the draft gate to post
  * `verdict=blocked` with the `missing_refinement_artifact` finding.
  *
+ * Since #1866 the check ALSO requires an explicit Non-goals section on the
+ * issue body (see `MISSING_EXPLICIT_NON_GOALS_FINDING` below).
+ */
+import { existsSync } from "node:fs";
+import path from "node:path";
+
+/**
  * This module owns:
  * - canonical section-name matching for AC / DoD blocks
  * - bullet-item extraction (checklist `- [ ]`/`- [x]` and top-level `- ` bullets)
@@ -38,6 +45,15 @@ export const REFINEMENT_ARTIFACT_SOURCES = Object.freeze([
   "linked refinement doc",
 ]);
 
+/**
+ * #1866: finding reported when the issue body carries a refinement artifact
+ * (AC/DoD checklist or a resolvable linked doc) but no explicit Non-goals
+ * section. Mirrors the PR-path narrative-invariant code
+ * (`PR_BODY_SPEC_NARRATIVE_SECTIONS.non_goals.code`) so both spec surfaces
+ * name the missing invariant identically.
+ */
+export const MISSING_EXPLICIT_NON_GOALS_FINDING = "missing_explicit_non_goals";
+
 /**
  * Canonical list of section headings that satisfy the refinement check.
  * Matching is case-insensitive and tolerates trailing/leading whitespace.
@@ -248,6 +264,13 @@ export function detectLinkedRefinementDoc(body) {
 
   const pathMatch = /(?:^|\s|[`(\[<])(tmp\/refinement\/[A-Za-z0-9._/\-]+\.md)\b/u.exec(body);
   if (pathMatch) {
+    // Containment guard: reject actual '..' path segments (not benign
+    // double-dot filenames) so the new fs-probe wiring can never be used as a
+    // filesystem existence oracle outside tmp/refinement
+    // (e.g. `tmp/refinement/../../docs/some-existing.md`).
+    if (pathMatch[1].split("/").some((segment) => segment === "..")) {
+      return { found: false, path: null, reason: "path-escapes-refinement-dir" };
+    }
     return { found: true, path: pathMatch[1], reason: "explicit-path" };
   }
 
@@ -261,6 +284,11 @@ export function detectLinkedRefinementDoc(body) {
   if (refinementSection) {
     const inlinePath = /(?:^|\s)(tmp\/refinement\/[^\s)`'"]+\.md)\b/u.exec(refinementSection.bodyLines.join("\n"));
     if (inlinePath) {
+      // Containment guard: same segment-based '..' rejection as the
+      // explicit-path branch.
+      if (inlinePath[1].split("/").some((segment) => segment === "..")) {
+        return { found: false, path: null, reason: "path-escapes-refinement-dir" };
+      }
       return { found: true, path: inlinePath[1], reason: "refinement-section-path" };
     }
   }
@@ -271,25 +299,56 @@ export function detectLinkedRefinementDoc(body) {
 /**
  * Detect the refinement artifact on a parsed issue body.
  *
+ * #1866: the tracker-backed refinement floor is the artifact (AC checklist,
+ * DoD checklist, or a resolvable linked refinement doc) AND an explicit,
+ * non-empty Non-goals section — the loop-grill / artifact-authority contract
+ * requires Non-goals on a refined issue body, so the deterministic check
+ * enforces it (fail-closed) with the distinct finding
+ * `MISSING_EXPLICIT_NON_GOALS_FINDING`. The non-goals matcher is shared with
+ * `validatePrBodySpec` (`PR_BODY_SPEC_NARRATIVE_SECTIONS.non_goals.patterns`),
+ * so the two spec surfaces cannot drift on what counts as an explicit
+ * Non-goals section. `hasACs` keeps its caller-facing meaning: true only when
+ * the FULL check passes, so every `.hasACs` consumer (enqueue gate, draft
+ * gate, parked-items discovery, gate context) fails closed with no call-site
+ * change.
+ *
+ * `resolveLinkedDoc` (optional, #1866): a `(path) => boolean` callback used to
+ * verify that a linked `tmp/refinement/*.md` doc actually resolves (e.g.
+ * `existsSync`). Enforcement-point callers (enqueue gate, draft-gate
+ * linked-issue path) supply it; a linked doc found in the body then satisfies
+ * the artifact check only when the callback returns true. When the callback is
+ * not supplied the predicate stays pure/no-I/O and behavior is unchanged, and
+ * the `linkedDoc` result carries no `resolves` field. When supplied and the
+ * doc does not resolve, `linkedDoc.resolves === false` and the linked doc does
+ * not satisfy the artifact check (other artifact sources still count).
+ *
+ * Result-shape note: on a `missing_explicit_non_goals` result, `source` keeps
+ * the detected artifact origin (e.g. `issue-body-ac`) so callers/reporting can
+ * still see what artifact exists; `hasACs` is false because the full
+ * refinement check did not pass.
+ *
  * @param {object} input
  * @param {string} [input.body]  Raw issue body Markdown.
  * @param {number} [input.issueNumber]  Issue number, used for linked-doc convention.
+ * @param {Function} [input.resolveLinkedDoc]  Optional `(path) => boolean` doc-resolution check.
  * @returns {{
  *   hasACs: boolean,
+ *   hasNonGoals: boolean,
  *   source: string,
  *   acItems: string[],
  *   uncheckedAcItems: string[],
  *   dodItems: string[],
  *   sections: string[],
- *   linkedDoc: { found: boolean, path: string|null, reason: string },
+ *   linkedDoc: { found: boolean, path: string|null, reason: string, resolves?: boolean },
  *   reason: string,
  *   finding: string|null,
  * }}
  */
-export function detectIssueRefinementArtifact({ body = "", issueNumber = null } = {}) {
+export function detectIssueRefinementArtifact({ body = "", issueNumber = null, resolveLinkedDoc = null } = {}) {
   if (typeof body !== "string" || body.length === 0) {
     return {
       hasACs: false,
+      hasNonGoals: false,
       source: REFINEMENT_SOURCE.MISSING,
       acItems: [],
       uncheckedAcItems: [],
@@ -315,58 +374,88 @@ export function detectIssueRefinementArtifact({ body = "", issueNumber = null }
   const uncheckedAcItems = acceptanceSection ? extractUncheckedChecklistItems(acceptanceSection.bodyLines.join("\n")) : [];
   const dodItems = dodSection ? extractChecklistItems(dodSection.bodyLines.join("\n")) : [];
 
-  const linkedDoc = detectLinkedRefinementDoc(body);
-
-  if (acItems.length > 0) {
-    return {
-      hasACs: true,
-      source: REFINEMENT_SOURCE.ISSUE_BODY_AC,
-      acItems,
-      uncheckedAcItems,
-      dodItems,
-      sections: sectionNames,
-      linkedDoc,
-      reason: `Found ${acItems.length} Acceptance criteria checklist item(s) in the issue body.`,
-      finding: null,
-    };
+  let linkedDoc = detectLinkedRefinementDoc(body);
+  let linkedDocResolves = linkedDoc.found;
+  if (linkedDoc.found && typeof resolveLinkedDoc === "function") {
+    linkedDocResolves = resolveLinkedDoc(linkedDoc.path) === true;
+    linkedDoc = { ...linkedDoc, resolves: linkedDocResolves };
   }
 
-  if (dodItems.length > 0) {
-    return {
-      hasACs: true,
-      source: REFINEMENT_SOURCE.ISSUE_BODY_DOD,
-      acItems,
-      uncheckedAcItems,
-      dodItems,
-      sections: sectionNames,
-      linkedDoc,
-      reason: `Found ${dodItems.length} DoD checklist item(s) in the issue body.`,
-      finding: null,
-    };
-  }
+  // #1866: explicit Non-goals section required on a refined tracker-backed
+  // issue body — same matcher the PR-body spec path uses, so the two cannot
+  // drift. A heading-only or fenced-only section does not count
+  // (sectionHasBody anti-spoof).
+  const hasNonGoals = sectionHasBody(
+    findSectionByPatterns(sections, PR_BODY_SPEC_NARRATIVE_SECTIONS.non_goals.patterns),
+  );
+
+  const artifactSource = acItems.length > 0
+    ? REFINEMENT_SOURCE.ISSUE_BODY_AC
+    : dodItems.length > 0
+      ? REFINEMENT_SOURCE.ISSUE_BODY_DOD
+      : linkedDocResolves
+        ? REFINEMENT_SOURCE.LINKED_DOC
+        : null;
 
-  if (linkedDoc.found) {
+  const base = {
+    hasNonGoals,
+    acItems,
+    uncheckedAcItems,
+    dodItems,
+    sections: sectionNames,
+    linkedDoc,
+  };
+
+  if (artifactSource !== null) {
+    if (!hasNonGoals) {
+      return {
+        ...base,
+        hasACs: false,
+        source: artifactSource,
+        reason:
+          `Issue body carries a refinement artifact (${artifactSource}) but no explicit Non-goals section; ` +
+          "the tracker-backed refinement contract requires one (rule ARTIFACT-TRACKER-ISSUE-REFINEMENT-FLOOR; " +
+          "e.g. run the loop-grill synthesis). Refusing: the refinement check fails closed without an explicit Non-goals section.",
+        finding: MISSING_EXPLICIT_NON_GOALS_FINDING,
+      };
+    }
+    if (artifactSource === REFINEMENT_SOURCE.ISSUE_BODY_AC) {
+      return {
+        ...base,
+        hasACs: true,
+        source: REFINEMENT_SOURCE.ISSUE_BODY_AC,
+        reason: `Found ${acItems.length} Acceptance criteria checklist item(s) in the issue body.`,
+        finding: null,
+      };
+    }
+    if (artifactSource === REFINEMENT_SOURCE.ISSUE_BODY_DOD) {
+      return {
+        ...base,
+        hasACs: true,
+        source: REFINEMENT_SOURCE.ISSUE_BODY_DOD,
+        reason: `Found ${dodItems.length} DoD checklist item(s) in the issue body.`,
+        finding: null,
+      };
+    }
     return {
+      ...base,
       hasACs: true,
       source: REFINEMENT_SOURCE.LINKED_DOC,
       acItems: [],
       uncheckedAcItems: [],
       dodItems: [],
-      sections: sectionNames,
-      linkedDoc,
       reason: `Issue body links a refinement doc at ${linkedDoc.path}; treating that as the refinement artifact source.`,
       finding: null,
     };
   }
 
   return {
+    ...base,
     hasACs: false,
     source: REFINEMENT_SOURCE.MISSING,
     acItems: [],
     uncheckedAcItems: [],
     dodItems: [],
-    sections: sectionNames,
-    linkedDoc,
     reason: "Issue body has no Acceptance criteria section, no DoD section, and no linked refinement doc.",
     finding: REFINEMENT_ARTIFACT_FINDING,
   };
@@ -484,7 +573,16 @@ function sectionHasBody(section) {
  * 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
+ * `requireOpenQuestions` (default `true`, issue #1863): the lightweight
+ * PR-body-as-spec contract (this function's original scope) requires an Open
+ * questions/risks section; the ordinary tracker-backed PR-description
+ * contract (skills/docs/copilot-loop-operations.md "PR description
+ * contract") does not name one. Pass `false` (see
+ * `validateTrackerBackedPrBodySpec` below) to skip the `missing_open_questions`
+ * check without touching any other invariant — the lightweight caller's
+ * default stays byte-identical.
+ *
+ * @param {{ body?: string, expectedIssue?: number, issueLess?: boolean, requireOpenQuestions?: boolean }} input
  * @returns {{ checker: "validate-pr-body-spec", ok: boolean, errors: { code: string, message: string }[], sections: string[], acItems: string[], dodItems: string[], closesIssues: number[] }}
  */
 
@@ -540,7 +638,7 @@ export function detectGrillEmbedHeading(body = "") {
   return null;
 }
 
-export function validatePrBodySpec({ body = "", expectedIssue = null, issueLess = false } = {}) {
+export function validatePrBodySpec({ body = "", expectedIssue = null, issueLess = false, requireOpenQuestions = true } = {}) {
   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.
@@ -550,7 +648,8 @@ export function validatePrBodySpec({ body = "", expectedIssue = null, issueLess
   const sections = parseMarkdownSections(bodyText);
   const errors = [];
 
-  for (const { code, label, patterns } of Object.values(PR_BODY_SPEC_NARRATIVE_SECTIONS)) {
+  for (const [key, { code, label, patterns }] of Object.entries(PR_BODY_SPEC_NARRATIVE_SECTIONS)) {
+    if (key === "open_questions" && !requireOpenQuestions) continue;
     const section = findSectionByPatterns(sections, patterns);
     if (!sectionHasBody(section)) {
       errors.push({ code, message: `Missing or empty ${label} section.` });
@@ -606,6 +705,31 @@ export function validatePrBodySpec({ body = "", expectedIssue = null, issueLess
   };
 }
 
+/**
+ * Validate a TRACKER-BACKED PR's own body against the PR-description contract
+ * (skills/docs/copilot-loop-operations.md "PR description contract", issue
+ * #1863): Acceptance criteria + Definition of done checklists, an explicit
+ * Non-goals section, and a `Closes #N`/`Fixes #N` reference — regardless of
+ * whether the linked issue itself already carries a refinement artifact. A
+ * linked issue with real ACs is necessary but not sufficient: the PR body is
+ * the portable spec-of-record a tracker-agnostic consumer reads.
+ *
+ * Thin wrapper over `validatePrBodySpec`, not a second divergent checker:
+ * `requireOpenQuestions: false` because the tracker-backed contract, unlike
+ * the lightweight PR-body-as-spec path, does not require an Open
+ * questions/risks section. `expectedIssue` is only checked when the PR closes
+ * exactly ONE issue — an umbrella PR closing several is not required to name
+ * any single one of them in the `expectedIssue` slot (each linked issue's
+ * refinement is verified separately by the caller).
+ *
+ * @param {{ body?: string, closingIssues?: number[] }} input
+ * @returns {ReturnType<typeof validatePrBodySpec>}
+ */
+export function validateTrackerBackedPrBodySpec({ body = "", closingIssues = [] } = {}) {
+  const expectedIssue = Array.isArray(closingIssues) && closingIssues.length === 1 ? closingIssues[0] : null;
+  return validatePrBodySpec({ body, expectedIssue, requireOpenQuestions: false });
+}
+
 /**
  * Decide what an enqueue caller should do with a refinement-artifact result,
  * so an un-refined item never lands in the Next Up pickup column in the first
@@ -623,12 +747,22 @@ export function validatePrBodySpec({ body = "", expectedIssue = null, issueLess
  * @returns {{ action: "enqueue" } | { action: "block"|"divert", reason: string, missing: string[] }}
  */
 export function decideEnqueueRefinementGate({ artifact, targetIsPickup, auto = false }) {
-  // `artifact.finding === null` is the explicit "has ANY refinement artifact"
-  // signal (AC checklist OR DoD checklist OR linked doc) — clearer than reading
-  // `hasACs`, whose name understates that a DoD or linked doc also satisfies it.
+  // `artifact.finding === null` is the explicit "passes the full refinement
+  // check" signal (artifact AND — since #1866 — an explicit Non-goals
+  // section), clearer than reading `hasACs`, whose name understates what it
+  // covers.
   if (!targetIsPickup || artifact.finding === null) {
     return { action: "enqueue" };
   }
+  // #1866: artifact present but the contract-mandated Non-goals section is
+  // absent/empty — a distinct failure with its own guidance.
+  if (artifact.finding === MISSING_EXPLICIT_NON_GOALS_FINDING) {
+    const reason =
+      "Issue carries a refinement artifact but no explicit Non-goals section. " +
+      "Add an explicit `## Non-goals` section to the issue body " +
+      "(rule ARTIFACT-TRACKER-ISSUE-REFINEMENT-FLOOR; e.g. run `/dev-loops:loop-grill <issue> --auto` (or `/loop-grill <issue> --auto` in the dev-loops repo itself)) — refusing to enqueue without an explicit Non-goals section.";
+    return { action: auto ? "divert" : "block", reason, missing: ["explicit Non-goals section"] };
+  }
   const missing = [...REFINEMENT_ARTIFACT_SOURCES];
   const reason =
     `Issue has no refinement artifact (none of: ${missing.join(", ")}). ` +
@@ -649,7 +783,7 @@ export function decideEnqueueRefinementGate({ artifact, targetIsPickup, auto = f
  * @param {{ issueNumber: number, repo: string, env: object, runChild: Function, auto?: boolean }} input
  * @returns {Promise<{ action: "enqueue" } | { action: "divert"|"block", reason: string, missing: string[] }>}
  */
-export async function runPickupRefinementGate({ issueNumber, repo, env, runChild, auto = false }) {
+export async function runPickupRefinementGate({ issueNumber, repo, env, runChild, auto = false, repoRoot = null }) {
   const bodyResult = await runChild(
     "gh",
     ["issue", "view", String(issueNumber), "--repo", repo, "--json", "body"],
@@ -666,7 +800,17 @@ export async function runPickupRefinementGate({ issueNumber, repo, env, runChild
     throw new Error("Invalid JSON input");
   }
   const body = typeof bodyPayload?.body === "string" ? bodyPayload.body : "";
-  const artifact = detectIssueRefinementArtifact({ body, issueNumber });
+  // #1866: a linked refinement doc satisfies the gate only when it actually
+  // resolves. Paths follow the `tmp/refinement/*.md` convention and are
+  // anchored to the caller's repo root (`repoRoot` option, falling back to
+  // process.cwd()) — never the ambient cwd of whichever subdirectory the
+  // gate happened to run from.
+  const docAnchor = repoRoot ?? process.cwd();
+  const artifact = detectIssueRefinementArtifact({
+    body,
+    issueNumber,
+    resolveLinkedDoc: (p) => existsSync(path.isAbsolute(p) ? p : path.resolve(docAnchor, p)),
+  });
   const decision = decideEnqueueRefinementGate({ artifact, targetIsPickup: true, auto });
   if (decision.action === "block") {
     throw Object.assign(new Error(decision.reason), {

package/src/loop/lifecycle-state.mjs

@@ -164,6 +164,14 @@ function normalizeLifecycleState(value) {
  *   mergeAuthorized,    // boolean: explicit merge authorization granted
  *   humanMergeOnly,     // boolean: repo invariant — agent may never merge (fails closed)
  *   isMerged,           // boolean: PR has been merged
+ *   sizeBudgetHumanApprovalRequired, // boolean: the size-budget merge gate
+ *                       // (resolveSizeBudgetHumanApprovalRequired,
+ *                       // @dev-loops/core/loop/size-budget-merge-gate) says
+ *                       // this escalated/T1 PR still needs a human APPROVED
+ *                       // review — consulted IN ADDITION TO mergeAuthorized/
+ *                       // humanMergeOnly, defaults false (opt-in; callers
+ *                       // that do not evaluate the size budget see unchanged
+ *                       // behavior)
  * }
  * ```
  *
@@ -180,7 +188,8 @@ function normalizeLifecycleState(value) {
  * Resolution order (first-match):
  * 1. Explicit phase → return canonical if recognized, fall through if not
  * 2. Merged → merge (terminal)
- * 3. Merge authorized + pre-approval passed + linked PR → merge
+ * 3. Merge authorized + pre-approval passed + linked PR + size-budget gate
+ *    clear (not sizeBudgetHumanApprovalRequired) → merge
  * 4. Pre-approval passed + PR exists → pre_approval_gate
  * 5. Unresolved threads + PR exists → feedback_resolution
  * 6. Draft PR → implementation
@@ -197,6 +206,7 @@ export function resolveLifecycleState(input = {}) {
     mergeAuthorized = false,
     humanMergeOnly = false,
     isMerged = false,
+    sizeBudgetHumanApprovalRequired = false,
   } = input;
 
   // Fail closed: when the repo enforces human-only merge, the agent is never
@@ -205,7 +215,16 @@ export function resolveLifecycleState(input = {}) {
   // exact `true` clears merge), matching the authoritative
   // `resolveEffectiveMergeAuthorized` gate. An already-merged PR (isMerged) is
   // still terminal below.
-  const effectiveMergeAuthorized = humanMergeOnly !== true && mergeAuthorized === true;
+  //
+  // The size-budget merge gate (resolveSizeBudgetHumanApprovalRequired) is
+  // consulted IN ADDITION TO the two invariants above, never in their place:
+  // an escalated/T1 PR without a human APPROVED review (and zero unresolved
+  // CHANGES_REQUESTED) parks at PRE_APPROVAL_GATE — the existing "await human
+  // approval" phase — instead of advancing to MERGE, even under a standing
+  // merge authorization.
+  const effectiveMergeAuthorized = humanMergeOnly !== true
+    && mergeAuthorized === true
+    && sizeBudgetHumanApprovalRequired !== true;
 
   // 1. Explicit phase override — canonical or fail closed
   if (phase !== null && phase !== undefined) {

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

@@ -95,3 +95,37 @@ export function buildWorktreeCleanupCommand(mainCheckout, prNumber) {
   // 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");
 }