@dev-loops/core 0.2.4 → 0.2.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dev-loops/core",
-  "version": "0.2.4",
+  "version": "0.2.6",
   "type": "module",
   "description": "Shared deterministic support package for dev-loop skills, repo-local scripts, and GitHub automation.",
   "exports": {
@@ -34,6 +34,7 @@
     "./loop/phase-files": "./src/loop/phase-files.mjs",
     "./loop/policy-constants": "./src/loop/policy-constants.mjs",
     "./loop/pr-gate-coordination": "./src/loop/pr-gate-coordination.mjs",
+    "./loop/pr-title-markers": "./src/loop/pr-title-markers.mjs",
     "./loop/public-dev-loop-routing": "./src/loop/public-dev-loop-routing.mjs",
     "./loop/queue-driver": "./src/loop/queue-driver.mjs",
     "./loop/queue-parallel": "./src/loop/queue-parallel.mjs",

package/src/config/extension-defaults.yaml

@@ -76,10 +76,18 @@ autonomy:
 # Workflow enforcement defaults.
 workflow:
   asyncStartMode: required
-  requireRetrospective: true
-  requireRetrospectiveGate: true
+  # The retrospective is a dev-loop-development artifact; shipped defaults stay permissive so an
+  # ordinary consumer's product PRs do not carry the meta-process gate (#841). Matches the code
+  # default (DEFAULT_WORKFLOW_CONFIG) and the contract. The dev-loops repo opts in via its own
+  # repo-root .devloops, which takes precedence over these extension defaults.
+  requireRetrospective: false
+  requireRetrospectiveGate: false
   requireDraftFirst: true
-  devModeDefault: true
+  # Dev mode is the dev-loop self-improvement mode — it edits the loop's own skill/agent prompts
+  # after a phase, which is only meaningful in the dev-loops repo. Shipped defaults must not force
+  # it on consumers' product phases (#846). Matches the code default; the dev-loops repo opts in
+  # via its own repo-root .devloops (which takes precedence over these extension defaults).
+  devModeDefault: false
 
 # Light-mode threshold for small local changes.
 localImplementation:

package/src/loop/handoff-envelope.mjs

@@ -20,6 +20,7 @@ import {
 } from "./public-dev-loop-routing-contract.mjs";
 import { normalizeRepoSlug } from "../github/repo-slug.mjs";
 import { COPILOT_REVIEW_WAIT_TIMEOUT_MS } from "./policy-constants.mjs";
+import { resolveEffectiveAsyncStartMode } from "./async-start-contract.mjs";
 
 // ---------------------------------------------------------------------------
 // Constants
@@ -430,6 +431,16 @@ export function buildDevLoopHandoffEnvelope(resolverOutput, settings, gateState
     ? { ...options.overrides }
     : undefined;
 
+  // Surface the *effective* async-start posture alongside the *configured* one (#834). The
+  // configured `asyncStartMode` is echoed verbatim from settings (back-compat), but the contract
+  // is relaxed at validation time under the Claude harness (resolveEffectiveAsyncStartMode →
+  // "allowed" when CLAUDECODE=1). Without surfacing the effective value, a `required` envelope
+  // reads as if it should still block even though the resolver correctly proceeds.
+  const env = options.env ?? (typeof process !== "undefined" ? process.env : {});
+  const configuredAsyncStartMode = settings?.workflow?.asyncStartMode ?? "required";
+  const effectiveAsyncStartMode = resolveEffectiveAsyncStartMode(configuredAsyncStartMode, env);
+  const asyncStartRelaxedBy = effectiveAsyncStartMode !== configuredAsyncStartMode ? "claude-harness" : null;
+
   const envelope = {
     handoffVersion: ENVELOPE_HANDOFF_VERSION,
     derivedAt: (now ?? new Date()).toISOString(),
@@ -447,7 +458,9 @@ export function buildDevLoopHandoffEnvelope(resolverOutput, settings, gateState
     requiredReads,
 
     stopRules,
-    asyncStartMode: settings?.workflow?.asyncStartMode ?? "required",
+    asyncStartMode: configuredAsyncStartMode,
+    asyncStartEffective: effectiveAsyncStartMode,
+    asyncStartRelaxedBy,
     requireDraftFirst: settings?.workflow?.requireDraftFirst ?? false,
 
     cwd: derivedCwd,
@@ -697,6 +710,21 @@ export function validateHandoffEnvelope(envelope) {
     });
   }
 
+  // ----- asyncStartEffective (required field; the harness-resolved posture, #834) -----
+  if (envelope.asyncStartEffective === undefined || envelope.asyncStartEffective === null) {
+    errors.push({
+      field: "asyncStartEffective",
+      reason: "must be present",
+      got: envelope.asyncStartEffective,
+    });
+  } else if (!VALID_ASYNC_START_MODES.includes(envelope.asyncStartEffective)) {
+    errors.push({
+      field: "asyncStartEffective",
+      reason: `must be one of: ${VALID_ASYNC_START_MODES.join(", ")}`,
+      got: envelope.asyncStartEffective,
+    });
+  }
+
   // ----- refinementContract (optional) -----
   if (envelope.refinementContract !== undefined && envelope.refinementContract !== null) {
     if (typeof envelope.refinementContract !== "object" || Array.isArray(envelope.refinementContract)) {

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

@@ -1,4 +1,5 @@
 import { DISPOSITION, STATE } from "./copilot-loop-state.mjs";
+import { findBlockingTitleMarkers } from "./pr-title-markers.mjs";
 
 export const PR_CHECKPOINT = Object.freeze({
   DRAFT_REVIEW: "draft_review",
@@ -324,6 +325,56 @@ function buildRetrospectiveGatePendingResult({
 }
 
 
+/**
+ * Blocked result for a PR that would otherwise reach final_approval_ready but
+ * still carries a merge-blocking marker in its title (issue #842). The title is
+ * the most visible contract surface, so a WIP/DRAFT/DO NOT MERGE title must
+ * block the final-approval boundary just like the mark-ready transition does.
+ */
+function buildTitleMarkerBlockedResult({
+  input,
+  currentHeadSha,
+  draftGateAlreadySatisfied,
+  draftGate,
+  preApprovalGate,
+  mergeStateStatus,
+  conflictFiles,
+  markers,
+  refinementArtifact = null,
+}) {
+  const allowedNextActions = [];
+  const forbiddenActions = [];
+  pushUnique(allowedNextActions, [PR_CHECKPOINT_ACTION.REPORT_BLOCKED]);
+  pushUnique(forbiddenActions, [
+    PR_CHECKPOINT_ACTION.RUN_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: "title_marker_blocked",
+    loopDisposition: DISPOSITION.BLOCKED,
+    gateBoundary: PR_CHECKPOINT.BLOCKED,
+    draftGateAlreadySatisfied,
+    draftGate,
+    preApprovalGate,
+    allowedNextActions,
+    forbiddenActions,
+    nextAction: PR_CHECKPOINT_ACTION.REPORT_BLOCKED,
+    reason: `Blocked: the PR title contains merge-blocking marker(s): ${markers.join(", ")}. Remove them from the title before the PR can leave draft, enter the pre-approval gate, or reach final approval.`,
+    mergeStateStatus,
+    conflictFiles,
+      refinementArtifact,
+  });
+}
+
+
 function buildDraftGateNeededForMergeResult({
   input,
   currentHeadSha,
@@ -473,7 +524,63 @@ export function shouldGuardCopilotReviewRequest({
   return true;
 }
 
+/**
+ * Boundaries at which a non-draft PR must NOT carry a merge-blocking title
+ * marker (issue #842 / AC2). A WIP/DRAFT/DO NOT MERGE/🚧 title is acceptable
+ * while the PR is still in draft, but the moment the PR leaves draft and reaches
+ * the pre-approval gate boundary (entry) or the final-approval boundary, the
+ * title is a live merge-contract surface and must be clean. The guard is applied
+ * once, as a post-pass over the core evaluation result, so no individual return
+ * site can be missed even if a PR was un-drafted externally (bypassing
+ * ready-for-review).
+ */
+const TITLE_MARKER_GUARDED_BOUNDARIES = Object.freeze([
+  PR_CHECKPOINT.PRE_APPROVAL_GATE_NEEDED,
+  PR_CHECKPOINT.PRE_APPROVAL_GATE_WINDOW,
+  PR_CHECKPOINT.FINAL_APPROVAL_READY,
+]);
+
+/**
+ * Evaluates PR gate coordination, then re-asserts the merge-blocking title guard
+ * (issue #842) at the pre-approval / final-approval boundary for non-draft PRs.
+ *
+ * The title check is also performed inline at the three FINAL_APPROVAL_READY
+ * sites (defense in depth); this wrapper additionally covers the pre-approval
+ * gate boundary, which is reached before any pre-approval evidence exists and so
+ * is not protected by the inline checks.
+ */
 export function evaluatePrGateCoordination(input = {}) {
+  const result = evaluatePrGateCoordinationCore(input);
+
+  const prDraft = input.prDraft === true;
+  const prTitle = typeof input.prTitle === "string" ? input.prTitle : "";
+  // Draft PRs may legitimately carry a WIP title; the marker only blocks once
+  // the PR has left draft and is at a pre-approval/final-approval boundary.
+  if (prDraft || !result || typeof result !== "object") {
+    return result;
+  }
+  if (!TITLE_MARKER_GUARDED_BOUNDARIES.includes(result.gateBoundary)) {
+    return result;
+  }
+  const markers = findBlockingTitleMarkers(prTitle);
+  if (markers.length === 0) {
+    return result;
+  }
+
+  return buildTitleMarkerBlockedResult({
+    input,
+    currentHeadSha: result.currentHeadSha ?? null,
+    draftGateAlreadySatisfied: result.draftGateAlreadySatisfied === true,
+    draftGate: result.draftGate,
+    preApprovalGate: result.preApprovalGate,
+    mergeStateStatus: result.mergeStateStatus ?? null,
+    conflictFiles: result.conflictFiles ?? [],
+    markers,
+    refinementArtifact: result.refinementArtifact ?? null,
+  });
+}
+
+function evaluatePrGateCoordinationCore(input = {}) {
   const currentHeadSha = typeof input.currentHeadSha === "string" && input.currentHeadSha.trim().length > 0
     ? input.currentHeadSha.trim()
     : null;
@@ -500,6 +607,7 @@ export function evaluatePrGateCoordination(input = {}) {
   const roundCapReached = maxCopilotRounds !== null && copilotReviewRoundCount >= maxCopilotRounds;
   const requireRetrospectiveGate = input.requireRetrospectiveGate === true;
   const retrospectiveCheckpoint = input.retrospectiveCheckpoint;
+  const prTitle = typeof input.prTitle === "string" ? input.prTitle : "";
   const refinementArtifact = input.refinementArtifact && typeof input.refinementArtifact === "object"
     ? input.refinementArtifact
     : null;
@@ -777,6 +885,20 @@ export function evaluatePrGateCoordination(input = {}) {
         });
       }
       if (preApprovalGate.currentHeadClean) {
+        const titleMarkers = findBlockingTitleMarkers(prTitle);
+        if (titleMarkers.length > 0) {
+          return buildTitleMarkerBlockedResult({
+            input,
+            currentHeadSha,
+            draftGateAlreadySatisfied: roundCapReached ? true : draftGateAlreadySatisfied,
+            draftGate,
+            preApprovalGate,
+            mergeStateStatus,
+            conflictFiles,
+            markers: titleMarkers,
+            refinementArtifact,
+          });
+        }
         if (requireRetrospectiveGate) {
           const retrospectiveGate = evaluateRetrospectiveMergeApproval(retrospectiveCheckpoint);
           if (!retrospectiveGate.approved) {
@@ -1035,6 +1157,20 @@ export function evaluatePrGateCoordination(input = {}) {
     }
 
     if (preApprovalGate.currentHeadClean) {
+      const titleMarkers = findBlockingTitleMarkers(prTitle);
+      if (titleMarkers.length > 0) {
+        return buildTitleMarkerBlockedResult({
+          input,
+          currentHeadSha,
+          draftGateAlreadySatisfied: roundCapReached ? true : draftGateAlreadySatisfied,
+          draftGate,
+          preApprovalGate,
+          mergeStateStatus,
+          conflictFiles,
+          markers: titleMarkers,
+          refinementArtifact,
+        });
+      }
       if (requireRetrospectiveGate) {
         const retrospectiveGate = evaluateRetrospectiveMergeApproval(retrospectiveCheckpoint);
         if (!retrospectiveGate.approved) {
@@ -1178,6 +1314,20 @@ export function evaluatePrGateCoordination(input = {}) {
       });
     }
     if (preApprovalGate.currentHeadClean) {
+      const titleMarkers = findBlockingTitleMarkers(prTitle);
+      if (titleMarkers.length > 0) {
+        return buildTitleMarkerBlockedResult({
+          input,
+          currentHeadSha,
+          draftGateAlreadySatisfied: roundCapReached ? true : draftGateAlreadySatisfied,
+          draftGate,
+          preApprovalGate,
+          mergeStateStatus,
+          conflictFiles,
+          markers: titleMarkers,
+          refinementArtifact,
+        });
+      }
       if (requireRetrospectiveGate) {
         const retrospectiveGate = evaluateRetrospectiveMergeApproval(retrospectiveCheckpoint);
         if (!retrospectiveGate.approved) {

package/src/loop/pr-title-markers.mjs

@@ -0,0 +1,56 @@
+/**
+ * Merge-blocking marker detection for PR titles (issue #842).
+ *
+ * The PR title is the single most visible contract surface of a pull request:
+ * it shows up in the PR list, in notifications, in the merge commit, and in the
+ * changelog. A "WIP"/"DRAFT"/"DO NOT MERGE" title on an otherwise merge-ready PR
+ * directly contradicts the gate's assertion that the work is done. The gate
+ * pipeline historically only inspected the PR body, so a stale work-in-progress
+ * title could slip through both the mark-ready transition and the final-approval
+ * boundary. This module provides the pure detection seam used at both points.
+ *
+ * It is intentionally pure and side-effect free.
+ */
+
+/**
+ * Canonical merge-blocking markers and how to detect them.
+ *
+ * Word-boundary matching is used for the alphabetic markers so that real words
+ * are not false-positives (e.g. "swipe"/"wiped" must not match WIP;
+ * "drafting"/"redraft" must not match DRAFT). Bracket/paren/colon punctuation
+ * (`[WIP]`, `(wip)`, `WIP:`) are non-word characters, so `\b` boundaries still
+ * match those variants. The construction emoji has no word boundary, so it is
+ * matched literally anywhere in the title.
+ */
+const MARKER_MATCHERS = [
+  { label: "WIP", pattern: /\bWIP\b/i },
+  { label: "DRAFT", pattern: /\bDRAFT\b/i },
+  // Flexible (any) whitespace between the phrase words, case-insensitive.
+  { label: "DO NOT MERGE", pattern: /\bDO\s+NOT\s+MERGE\b/i },
+  { label: "🚧", pattern: /🚧/u },
+];
+
+/**
+ * Finds merge-blocking markers in a PR title.
+ *
+ * Returns the canonical labels of every matched marker, de-duped and in a
+ * stable order (the declaration order of {@link MARKER_MATCHERS}). Returns an
+ * empty array when the title is clean, empty, or not a string.
+ *
+ * @param {unknown} title - The PR title to inspect.
+ * @returns {string[]} Canonical labels of matched markers, e.g. ["WIP"] or
+ *   ["DO NOT MERGE", "🚧"]. Empty when no markers are present.
+ */
+export function findBlockingTitleMarkers(title) {
+  if (typeof title !== "string" || title.length === 0) {
+    return [];
+  }
+
+  const matched = [];
+  for (const { label, pattern } of MARKER_MATCHERS) {
+    if (pattern.test(title) && !matched.includes(label)) {
+      matched.push(label);
+    }
+  }
+  return matched;
+}