@dev-loops/core 0.4.0 → 0.6.0

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

@@ -0,0 +1,229 @@
+/**
+ * Local-planning plan-file refine + human-review checkpoint (off-tracker).
+ *
+ * This is the P3 core noise-reduction step. It generalizes the proposal-first
+ * intake pattern (emit a local artifact, human-gate it, make zero tracker
+ * mutation, stop and ask) to plan files: the refined plan is written in-place to
+ * the single canonical plan file, the autonomous docs-grill runs as a step
+ * within refinement, and the loop stops at a local human-review checkpoint with
+ * the intake state advanced to `plan_refined_ready_for_promotion`.
+ *
+ * This module is pure: it transforms markdown text and reports a disposition. It
+ * performs no GitHub mutation, no network calls, and no filesystem I/O. The
+ * caller supplies the section-presence facts it already read (mirroring the
+ * `evaluatePlanFileIntakeState` precedent) and the refiner-produced payload, and
+ * writes the returned markdown back. That keeps the zero-tracker-mutation
+ * guarantee structural: there is no gh/network surface to reach from here.
+ *
+ * It composes the already-shipped contracts: P2 `evaluatePlanFileIntakeState` +
+ * `PLAN_FILE_REFINEMENT_SECTIONS` (this step acts on `new_plan_needs_refinement`
+ * and drives the transition to `plan_refined_ready_for_promotion`) and #948's
+ * docs-grill: the caller classifies each finding with `classifyDocsGrillFinding`
+ * and passes the dispositions in, and this module validates and records them.
+ */
+
+import {
+  evaluatePlanFileIntakeState,
+  PLAN_FILE_INTAKE_STATE,
+  PLAN_FILE_REFINEMENT_SECTIONS,
+} from "./plan-file-intake-contract.mjs";
+
+/** The local human-review checkpoint surface the loop stops at on success. */
+export const PLAN_FILE_REFINE_STOP = Object.freeze({
+  /** Refinement wrote the plan in-place; stop for local human review before any promotion. */
+  LOCAL_HUMAN_REVIEW: "local_human_review",
+});
+
+/** The heading the recorded docs-grill findings live under in the plan file. */
+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";
+
+/**
+ * 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 match = headingPattern.exec(markdownText);
+  if (!match || match.index === undefined) return markdownText;
+  const start = match.index;
+  const afterHeading = start + match[0].length;
+  const remaining = markdownText.slice(afterHeading);
+  const nextHeadingMatch = /^##\s+/imu.exec(remaining);
+  const end = nextHeadingMatch && nextHeadingMatch.index !== undefined
+    ? afterHeading + nextHeadingMatch.index
+    : markdownText.length;
+  // Drop the section and collapse the blank-line gap it leaves behind.
+  return `${markdownText.slice(0, start)}${markdownText.slice(end)}`.replace(/\n{3,}/gu, "\n\n");
+}
+
+/**
+ * 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/.
+ */
+function hasSection(markdownText, headingText) {
+  const escaped = headingText.replace(/[.*+?^${}()|[\]\\]/gu, "\\$&");
+  return new RegExp(`^##\\s+${escaped}\\s*$`, "imu").test(markdownText);
+}
+
+/** Append a `## <heading>` section with the given body to markdown. */
+function appendSection(markdownText, headingText, body) {
+  const trimmed = markdownText.replace(/\s+$/u, "");
+  return `${trimmed}\n\n## ${headingText}\n\n${String(body).trim()}\n`;
+}
+
+/**
+ * Render recorded docs-grill findings as a markdown body. Each finding lists the
+ * disposition `classifyDocsGrillFinding` assigned it. When the grill produced no
+ * findings, an explicit "none recorded" line keeps the section idempotent and
+ * non-empty so the plan file always carries the grill evidence.
+ */
+function renderGrillFindings(classified) {
+  if (classified.length === 0) {
+    return "- None recorded; the docs-grill step ran and surfaced no findings.";
+  }
+  return classified
+    .map((entry) => {
+      const summary = String(entry.summary ?? "").trim() || "(no summary)";
+      return `- [${entry.disposition}] (${entry.kind}) ${summary}`;
+    })
+    .join("\n");
+}
+
+/**
+ * Refine a plan file in-place and advance its intake state, then stop at the
+ * local human-review checkpoint.
+ *
+ * The caller reads the plan file and supplies the section-presence facts plus
+ * the refiner payload. On success it writes `refinedMarkdown` back to the same
+ * path (the single canonical artifact) and stops; it never promotes here.
+ *
+ * @param {object} params
+ * @param {string} params.markdownText  current plan-file markdown
+ * @param {boolean} params.baseSectionsValid  whether the plan passes the base-section validator
+ * @param {boolean} params.hasAcceptanceCriteria  whether the plan already carries a non-empty Acceptance criteria section marker (per the intake contract)
+ * @param {boolean} params.hasDefinitionOfDone  whether the plan already carries a non-empty Definition of done section marker (per the intake contract)
+ * @param {object} params.payload  refiner-produced refinement output
+ * @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.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
+ * @returns {{
+ *   ok: boolean,
+ *   reason?: string,
+ *   planFileIntakeState?: string,
+ *   refinedMarkdown?: string,
+ *   grillDispositions?: object[],
+ *   stop?: { kind: string },
+ * }}
+ */
+export function refinePlanFileInPlace({
+  markdownText,
+  baseSectionsValid,
+  hasAcceptanceCriteria,
+  hasDefinitionOfDone,
+  payload,
+} = {}) {
+  if (typeof markdownText !== "string" || markdownText.length === 0) {
+    return { ok: false, reason: "missing_plan_markdown" };
+  }
+
+  // Gate on the starting intake state: this step only acts on a base-valid plan
+  // that has not yet been refined. A plan already carrying refinement markers, a
+  // partially-refined plan, or one failing the base contract is ambiguous here;
+  // fail closed without writing or advancing.
+  const startState = evaluatePlanFileIntakeState({
+    baseSectionsValid,
+    hasAcceptanceCriteria,
+    hasDefinitionOfDone,
+  }).state;
+  if (startState !== PLAN_FILE_INTAKE_STATE.NEW_PLAN_NEEDS_REFINEMENT) {
+    return { ok: false, reason: "not_in_new_plan_needs_refinement", planFileIntakeState: startState };
+  }
+
+  // The refiner payload must carry the refinement contract: AC, DoD, and the
+  // coverage matrix. A missing/empty piece is a failed refine; fail closed.
+  if (!payload || typeof payload !== "object") {
+    return { ok: false, reason: "missing_refinement_payload", planFileIntakeState: startState };
+  }
+  const acceptanceCriteria = String(payload.acceptanceCriteria ?? "").trim();
+  const definitionOfDone = String(payload.definitionOfDone ?? "").trim();
+  const coverageMatrix = String(payload.coverageMatrix ?? "").trim();
+  if (!acceptanceCriteria) {
+    return { ok: false, reason: "missing_acceptance_criteria", planFileIntakeState: startState };
+  }
+  if (!definitionOfDone) {
+    return { ok: false, reason: "missing_definition_of_done", planFileIntakeState: startState };
+  }
+  if (!coverageMatrix) {
+    return { ok: false, reason: "missing_coverage_matrix", 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
+  // validates and renders them but does NOT import the classifier — keeping it
+  // free of any scripts/ import so the published @dev-loops/core package does not
+  // break for consumers. A missing or invalid disposition fails the grill closed
+  // so a malformed grill cannot advance the state.
+  const grillDispositions = Array.isArray(payload.grillDispositions) ? payload.grillDispositions : [];
+  for (const d of grillDispositions) {
+    if (!d || typeof d.disposition !== "string" || d.disposition.length === 0) {
+      return { ok: false, reason: "docs_grill_failed", planFileIntakeState: startState };
+    }
+  }
+
+  // A managed section body must not contain a top-level `## ` heading: stripSection
+  // finds a section's end by scanning to the next `## `, so an embedded H2 in a body
+  // 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)))) {
+    return { ok: false, reason: "section_body_contains_heading", planFileIntakeState: startState };
+  }
+
+  // Write the refinement sections in-place. Strip any prior copy first so a
+  // re-run replaces rather than duplicates (idempotency), then append the fresh
+  // 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]) {
+    refinedMarkdown = stripSection(refinedMarkdown, heading);
+  }
+  refinedMarkdown = appendSection(refinedMarkdown, acHeading, acceptanceCriteria);
+  refinedMarkdown = appendSection(refinedMarkdown, dodHeading, definitionOfDone);
+  refinedMarkdown = appendSection(refinedMarkdown, COVERAGE_MATRIX_HEADING, coverageMatrix);
+  refinedMarkdown = appendSection(refinedMarkdown, DOCS_GRILL_FINDINGS_HEADING, grillBody);
+
+  // Re-derive the section-presence facts from the text the write just produced
+  // (not from the inputs) so this check actually verifies the append landed: a
+  // correct refine carries the base sections forward and adds both refinement
+  // markers, flipping the intake state to ready. A buggy rewrite that dropped a
+  // section is caught here and fails closed rather than advancing the state.
+  const endState = evaluatePlanFileIntakeState({
+    baseSectionsValid,
+    hasAcceptanceCriteria: hasSection(refinedMarkdown, acHeading),
+    hasDefinitionOfDone: hasSection(refinedMarkdown, dodHeading),
+  }).state;
+  if (endState !== PLAN_FILE_INTAKE_STATE.PLAN_REFINED_READY_FOR_PROMOTION) {
+    return { ok: false, reason: "refine_did_not_reach_ready", planFileIntakeState: endState };
+  }
+
+  return {
+    ok: true,
+    planFileIntakeState: endState,
+    refinedMarkdown,
+    grillDispositions,
+    // 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.
+    stop: { kind: PLAN_FILE_REFINE_STOP.LOCAL_HUMAN_REVIEW },
+  };
+}

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

@@ -1,11 +1,13 @@
 import { DISPOSITION, STATE } from "./copilot-loop-state.mjs";
 import { findBlockingTitleMarkers } from "./pr-title-markers.mjs";
+import { evaluateUiE2eScoping } from "./ui-e2e-scoping.mjs";
 
 export const PR_CHECKPOINT = Object.freeze({
   DRAFT_REVIEW: "draft_review",
   POST_DRAFT_EXTERNAL_REVIEW: "post_draft_external_review",
   FEEDBACK_RESOLUTION: "feedback_resolution",
   CONFLICT_RESOLUTION: "conflict_resolution",
+  UI_E2E_SCOPING: "ui_e2e_scoping",
   PRE_APPROVAL_GATE_WINDOW: "pre_approval_gate_window",
   FINAL_APPROVAL_READY: "final_approval_ready",
   PRE_APPROVAL_GATE_NEEDED: "pre_approval_gate_needed",
@@ -48,6 +50,7 @@ export const PR_CHECKPOINT_ACTION = Object.freeze({
   RECONCILE_DRAFT_GATE: "reconcile_draft_gate",
   REPORT_BLOCKED: "report_blocked",
   REPORT_DONE: "report_done",
+  RUN_UI_E2E_SUITE: "run_ui_e2e_suite",
 });
 
 function normalizeGateComment(summary = null) {
@@ -119,6 +122,19 @@ function normalizeMergeStateStatus(value) {
   return value.trim().toUpperCase();
 }
 
+function normalizeMergeable(value) {
+  if (typeof value !== "string" || value.trim().length === 0) {
+    return null;
+  }
+
+  const upper = value.trim().toUpperCase();
+  if (upper === "MERGEABLE" || upper === "CONFLICTING" || upper === "UNKNOWN") {
+    return upper;
+  }
+
+  return null;
+}
+
 function normalizeConflictFiles(value) {
   if (!Array.isArray(value)) {
     return [];
@@ -142,14 +158,18 @@ function hasBlockedMergeStatus(mergeStateStatus) {
   return mergeStateStatus !== null && BLOCKED_MERGE_STATE_STATUSES.has(mergeStateStatus);
 }
 
-function formatBlockedMergeReason(mergeStateStatus, conflictFiles) {
+function formatBlockedMergeReason(mergeStateStatus, conflictFiles, mergeable = null) {
   if (mergeStateStatus === "BEHIND") {
     let reason = "Branch must be updated from base before entering any gate.";
     reason += ` GitHub mergeStateStatus: ${mergeStateStatus}.`;
     return reason;
   }
 
-  let reason = "The current branch conflicts with the base branch, so resolve the conflict locally on the PR branch, rerun validation, rerun gate detection, and only then resume the normal gate path.";
+  let reason = "The current branch conflicts with the base branch, so resolve the conflict locally on the PR branch (run `node scripts/loop/resolve-pr-conflicts.mjs --push` for the safe additive-CHANGELOG case), rerun validation, rerun gate detection, and only then resume the normal gate path.";
+
+  if (mergeable === "CONFLICTING") {
+    reason += " GitHub mergeable: CONFLICTING.";
+  }
 
   if (mergeStateStatus !== null) {
     reason += ` GitHub mergeStateStatus: ${mergeStateStatus}.`;
@@ -218,7 +238,23 @@ function buildRoundExhaustionGateEvidenceNote({ copilotReviewRoundCount, maxCopi
   return `Copilot review rounds exhausted (${copilotReviewRoundCount}/${maxCopilotRounds}); current head has zero unresolved threads and green or credibly green CI, so pre_approval_gate fallback is allowed without another Copilot re-request.`;
 }
 
-function evaluateRetrospectiveMergeApproval(checkpoint) {
+/**
+ * Render the (user-authored) rawCallViolations array into a bounded, single-line
+ * fragment for the gate failure reason. Collapses whitespace/newlines per entry,
+ * caps per-entry length, and caps the number of entries shown so a large or
+ * garbled checkpoint cannot bloat or break gate output. Still fails closed —
+ * this only formats the reason; the violation count above does the gating.
+ */
+function summarizeRawCallViolations(violations, { maxEntries = 10, maxEntryLen = 200 } = {}) {
+  const shown = violations.slice(0, maxEntries).map((v) => {
+    const flat = String(v).replace(/\s+/g, " ").trim();
+    return flat.length > maxEntryLen ? `${flat.slice(0, maxEntryLen)}…` : flat;
+  });
+  const more = violations.length - shown.length;
+  return more > 0 ? `${shown.join("; ")}; …(+${more} more)` : shown.join("; ");
+}
+
+function evaluateRetrospectiveMergeApproval(checkpoint, { developerMode = false } = {}) {
   if (!checkpoint || typeof checkpoint !== "object") {
     return { approved: false, reason: "No retrospective checkpoint was found." };
   }
@@ -278,6 +314,37 @@ function evaluateRetrospectiveMergeApproval(checkpoint) {
     return { approved: false, reason: "Retrospective is missing explicit `mergeRecommendation`." };
   }
 
+  // internalToolingOnly: the loop's own execution must have used internal dev-loops
+  // tooling only — no agent-level raw `gh`/`python`/`python3`/`node -e` (issue #982).
+  // This is a DEVELOPER-MODE retro step: it enforces the dev-loops maintainers'
+  // own dogfooding discipline and is opt-in via `workflow.requireRetrospectiveInternalTooling`
+  // (default OFF). CONSUMERS of the extension are never blocked by it — they may
+  // legitimately use raw gh/python/node -e in their own workflow — so when the flag
+  // is OFF these fields are neither required nor enforced (a complete checkpoint
+  // without them passes exactly as it did before #982). When ON it fails closed:
+  // a complete checkpoint must explicitly attest a clean tooling record, and an OLD
+  // checkpoint missing `internalToolingOnly` fails (not a silent pass). Re-record the
+  // retrospective with the new fields to clear it.
+  if (developerMode) {
+    const internalToolingOnly = br !== null ? br.internalToolingOnly : checkpoint.internalToolingOnly;
+    if (internalToolingOnly !== true) {
+      return {
+        approved: false,
+        reason: "Retrospective does not attest internal-tooling-only execution (`internalToolingOnly: true` is required in developer mode; agent-level raw gh/python/node -e is a violation). — re-record the retrospective with internalToolingOnly + rawCallViolations.",
+      };
+    }
+    const rawCallViolations = br !== null ? br.rawCallViolations : checkpoint.rawCallViolations;
+    if (!Array.isArray(rawCallViolations)) {
+      return { approved: false, reason: "Retrospective is missing `rawCallViolations` (array; empty when clean). — re-record the retrospective with internalToolingOnly + rawCallViolations." };
+    }
+    if (rawCallViolations.length > 0) {
+      return {
+        approved: false,
+        reason: `Retrospective records ${rawCallViolations.length} raw-call violation(s) (agent-level gh/python/node -e): ${summarizeRawCallViolations(rawCallViolations)}.`,
+      };
+    }
+  }
+
   return { approved: true, reason: null };
 }
 
@@ -610,6 +677,7 @@ function evaluatePrGateCoordinationCore(input = {}) {
     ? "internal_only"
     : (typeof input.reviewMode === "string" ? input.reviewMode.trim().toLowerCase() : null);
   const mergeStateStatus = normalizeMergeStateStatus(input.mergeStateStatus);
+  const mergeable = normalizeMergeable(input.mergeable);
   const conflictFiles = normalizeConflictFiles(input.conflictFiles);
   const ciStatus = normalizeCiStatus(input.ciStatus);
   const draftGateRequireCi = input.draftGateRequireCi !== false;
@@ -617,8 +685,15 @@ function evaluatePrGateCoordinationCore(input = {}) {
   const maxCopilotRounds = normalizePositiveInteger(input.maxCopilotRounds);
   const roundCapReached = maxCopilotRounds !== null && copilotReviewRoundCount >= maxCopilotRounds;
   const requireRetrospectiveGate = input.requireRetrospectiveGate === true;
+  // Developer-mode flag (#982): only the dev-loops repo dogfooding itself enforces the
+  // internal-tooling-only retro discipline. Default OFF so consumer state changes pass.
+  const requireRetrospectiveInternalTooling = input.requireRetrospectiveInternalTooling === true;
   const retrospectiveCheckpoint = input.retrospectiveCheckpoint;
   const prTitle = typeof input.prTitle === "string" ? input.prTitle : "";
+  // UI e2e auto-scoping (#976): the PR changed-file set + whether the shared UI
+  // 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);
   const refinementArtifact = input.refinementArtifact && typeof input.refinementArtifact === "object"
     ? input.refinementArtifact
     : null;
@@ -694,7 +769,44 @@ function evaluatePrGateCoordinationCore(input = {}) {
     });
   }
 
-  if (hasBlockedMergeStatus(mergeStateStatus) || conflictFiles.length > 0) {
+  // Mergeability is a required precondition at every gate (issue #980). GitHub
+  // computes `mergeable` asynchronously, so an unsettled UNKNOWN must fail closed
+  // to a recheck — never a pass. The detect layer already re-polls a bounded
+  // number of times; if it still reads UNKNOWN here, hold gate progression and
+  // recheck rather than guess.
+  if (mergeable === "UNKNOWN") {
+    pushUnique(allowedNextActions, [PR_CHECKPOINT_ACTION.WAIT_FOR_CI]);
+    pushUnique(forbiddenActions, [
+      PR_CHECKPOINT_ACTION.RUN_DRAFT_GATE,
+      PR_CHECKPOINT_ACTION.RECONCILE_DRAFT_GATE,
+      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.PENDING,
+      gateBoundary: PR_CHECKPOINT.CONFLICT_RESOLUTION,
+      draftGateAlreadySatisfied,
+      draftGate,
+      preApprovalGate,
+      allowedNextActions,
+      forbiddenActions,
+      nextAction: PR_CHECKPOINT_ACTION.WAIT_FOR_CI,
+      reason: "GitHub has not yet computed mergeability (mergeable=UNKNOWN), so gate progression is held: recheck before proceeding rather than treating an unsettled merge state as clean.",
+      mergeStateStatus,
+      conflictFiles,
+      refinementArtifact,
+      copilotReviewRoundCount,
+    });
+  }
+
+  if (hasBlockedMergeStatus(mergeStateStatus) || mergeable === "CONFLICTING" || conflictFiles.length > 0) {
     pushUnique(allowedNextActions, [PR_CHECKPOINT_ACTION.RESOLVE_MERGE_CONFLICTS]);
     pushUnique(forbiddenActions, [
       PR_CHECKPOINT_ACTION.RUN_DRAFT_GATE,
@@ -723,7 +835,7 @@ function evaluatePrGateCoordinationCore(input = {}) {
       allowedNextActions,
       forbiddenActions,
       nextAction: PR_CHECKPOINT_ACTION.RESOLVE_MERGE_CONFLICTS,
-      reason: formatBlockedMergeReason(mergeStateStatus, conflictFiles),
+      reason: formatBlockedMergeReason(mergeStateStatus, conflictFiles, mergeable),
       mergeStateStatus,
       conflictFiles,
         refinementArtifact,
@@ -731,6 +843,45 @@ function evaluatePrGateCoordinationCore(input = {}) {
     });
   }
 
+  // UI e2e auto-scoping precondition (#976). Path-triggered + fail-closed:
+  // if the PR's changed files touch a rendered artifact (a deck under
+  // docs/articles|presentations, or the inspect-run viewer source), it MUST be
+  // registered in the shared UI e2e suite AND that suite must have passed for
+  // this head. A rendered-artifact change with no registered/passing coverage
+  // blocks here with a reason naming the artifact. Distinct seam from the
+  // mergeability (#980) and retrospective (#982) preconditions to minimize
+  // merge-time conflict. Non-UI changes pass through untouched (required=false).
+  const uiE2eScoping = evaluateUiE2eScoping(changedFiles, { uiE2ePassed });
+  if (uiE2eScoping.required && !uiE2eScoping.satisfied) {
+    pushUnique(allowedNextActions, [PR_CHECKPOINT_ACTION.RUN_UI_E2E_SUITE]);
+    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.UI_E2E_SCOPING,
+      draftGateAlreadySatisfied,
+      draftGate,
+      preApprovalGate,
+      allowedNextActions,
+      forbiddenActions,
+      nextAction: PR_CHECKPOINT_ACTION.RUN_UI_E2E_SUITE,
+      reason: uiE2eScoping.reason,
+      mergeStateStatus,
+      conflictFiles,
+      refinementArtifact,
+      copilotReviewRoundCount,
+    });
+  }
+
   if (prDraft || effectiveLifecycleState === STATE.PR_DRAFT) {
     if (refinementArtifactStatus === REFINEMENT_ARTIFACT_STATUS.MISSING) {
       pushUnique(allowedNextActions, [PR_CHECKPOINT_ACTION.REPORT_BLOCKED]);
@@ -911,7 +1062,7 @@ function evaluatePrGateCoordinationCore(input = {}) {
           });
         }
         if (requireRetrospectiveGate) {
-          const retrospectiveGate = evaluateRetrospectiveMergeApproval(retrospectiveCheckpoint);
+          const retrospectiveGate = evaluateRetrospectiveMergeApproval(retrospectiveCheckpoint, { developerMode: requireRetrospectiveInternalTooling });
           if (!retrospectiveGate.approved) {
             return buildRetrospectiveGatePendingResult({
               input,
@@ -1183,7 +1334,7 @@ function evaluatePrGateCoordinationCore(input = {}) {
         });
       }
       if (requireRetrospectiveGate) {
-        const retrospectiveGate = evaluateRetrospectiveMergeApproval(retrospectiveCheckpoint);
+        const retrospectiveGate = evaluateRetrospectiveMergeApproval(retrospectiveCheckpoint, { developerMode: requireRetrospectiveInternalTooling });
         if (!retrospectiveGate.approved) {
           return buildRetrospectiveGatePendingResult({
             input,
@@ -1349,7 +1500,7 @@ function evaluatePrGateCoordinationCore(input = {}) {
         });
       }
       if (requireRetrospectiveGate) {
-        const retrospectiveGate = evaluateRetrospectiveMergeApproval(retrospectiveCheckpoint);
+        const retrospectiveGate = evaluateRetrospectiveMergeApproval(retrospectiveCheckpoint, { developerMode: requireRetrospectiveInternalTooling });
         if (!retrospectiveGate.approved) {
           return buildRetrospectiveGatePendingResult({
             input,
@@ -1509,7 +1660,7 @@ function evaluatePrGateCoordinationCore(input = {}) {
         });
       }
       if (requireRetrospectiveGate) {
-        const retrospectiveGate = evaluateRetrospectiveMergeApproval(retrospectiveCheckpoint);
+        const retrospectiveGate = evaluateRetrospectiveMergeApproval(retrospectiveCheckpoint, { developerMode: requireRetrospectiveInternalTooling });
         if (!retrospectiveGate.approved) {
           return buildRetrospectiveGatePendingResult({
             input,

package/src/loop/run-context.mjs

@@ -4,8 +4,14 @@
  * The dev-loop async path keys off the harness-neutral `DEVLOOPS_RUN_ID` env var to
  * identify an inspectable per-subagent run (runner ownership, async-start enforcement,
  * human-comment gating), and provides a mint-and-propagate path for harnesses (e.g. Claude
- * Code) that inject no native per-subagent run id. The harness sets `DEVLOOPS_RUN_ID` when
- * dispatching an async subagent.
+ * Code) that inject no native per-subagent run id. For those harnesses dev-loops itself mints
+ * and sets `DEVLOOPS_RUN_ID` when dispatching an async subagent.
+ *
+ * Other harnesses may already inject their own run-id var: the Pi runtime injects
+ * `PI_SUBAGENT_RUN_ID` (not `DEVLOOPS_RUN_ID`) into each async subagent's child env, so that
+ * name is honored as a recognized run-id alias (precedence after the neutral primary). It is
+ * an externally-injected Pi-runtime contract var, not a dev-loops-owned var — dev-loops still
+ * mints/propagates only the neutral `DEVLOOPS_RUN_ID`.
  *
  * This module is pure except for the explicit file/IO helpers (writeRunContext/readRunContext),
  * which take an injectable `fs` and `root` for testability.
@@ -17,9 +23,10 @@ import path from "node:path";
 
 /**
  * Env var names that carry the async-context run id, in resolution precedence order.
- * The neutral `DEVLOOPS_RUN_ID` is the sole marker.
+ * The neutral `DEVLOOPS_RUN_ID` is primary; `PI_SUBAGENT_RUN_ID` is the alias the Pi
+ * runtime injects into async-subagent child envs (the only run-id marker present under Pi).
  */
-export const RUN_ID_MARKERS = Object.freeze(["DEVLOOPS_RUN_ID"]);
+export const RUN_ID_MARKERS = Object.freeze(["DEVLOOPS_RUN_ID", "PI_SUBAGENT_RUN_ID"]);
 
 /** Neutral env var name used when minting/propagating a run id. */
 export const NEUTRAL_RUN_ID_VAR = "DEVLOOPS_RUN_ID";