@dev-loops/core 0.2.5 → 0.2.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dev-loops/core",
-  "version": "0.2.5",
+  "version": "0.2.7",
   "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/bash-exit-one.mjs

@@ -1,5 +1,6 @@
 import { appendFile, mkdir } from "node:fs/promises";
 import path from "node:path";
+import { parseArgs } from "node:util";
 
 export const DEFAULT_OUTPUT_LIMIT = 4000;
 
@@ -79,23 +80,40 @@ export async function appendBashExitOneRecord(logPath, record) {
 }
 
 export function parseCliArgs(argv) {
-  const args = [...argv];
+  const { tokens } = parseArgs({
+    args: [...argv],
+    options: {
+      log: { type: "string" },
+      record: { type: "string" },
+    },
+    allowPositionals: true,
+    strict: false,
+    tokens: true,
+  });
+
   let logPath;
   let recordJson;
 
-  while (args.length > 0) {
-    const token = args.shift();
-    if (token === "--log") {
-      logPath = args.shift();
+  for (const token of tokens) {
+    if (token.kind === "positional") {
+      throw new Error(`Unknown argument: ${token.value}`);
+    }
+
+    if (token.kind !== "option") {
+      continue;
+    }
+
+    if (token.name === "log") {
+      logPath = token.value;
       continue;
     }
 
-    if (token === "--record") {
-      recordJson = args.shift();
+    if (token.name === "record") {
+      recordJson = token.value;
       continue;
     }
 
-    throw new Error(`Unknown argument: ${token}`);
+    throw new Error(`Unknown argument: ${token.rawName}`);
   }
 
   if (!logPath) {

package/src/claude/asset-generation.mjs

@@ -72,6 +72,22 @@ export function stripPiOnlyBlocks(body) {
     .replace(/\n{3,}/g, "\n\n");
 }
 
+/**
+ * Rewrite the Pi package-local CLI invocation into the Claude version-pinned `npx` form (#801,
+ * #833). The Pi runtime sources invoke the CLI as `node <dev-loops-package-root>/cli/index.mjs`
+ * (resolves unambiguously from the installed package). The Claude plugin does NOT bundle `cli/`,
+ * so for the generated tree those tokens become `npx dev-loops@<version>` — pinning the version
+ * keeps the CLI from drifting against the published plugin version (#833). The Pi-only
+ * package-root resolution note is removed separately by `stripPiOnlyBlocks`.
+ *
+ * @param {string} body
+ * @param {string} version dev-loops package version to pin (e.g. "0.2.6").
+ * @returns {string}
+ */
+export function rewriteCliInvocation(body, version) {
+  return String(body).split("node <dev-loops-package-root>/cli/index.mjs").join(`npx dev-loops@${version}`);
+}
+
 /**
  * Map a single Pi tool name to its Claude tool name(s).
  * @param {string} name
@@ -131,12 +147,12 @@ function normalizeToolList(value) {
 
 /**
  * Transform a canonical `agents/*.agent.md` into a Claude `.claude/agents/*.md` document.
- * @param {{ source: string, raw: string }} input
+ * @param {{ source: string, raw: string, version?: string }} input
  * @returns {string} Full generated file content.
  */
-export function transformAgent({ source, raw }) {
+export function transformAgent({ source, raw, version = "latest" }) {
   const { frontmatter, body: rawBody } = splitFrontmatter(raw, source);
-  const body = stripPiOnlyBlocks(rawBody);
+  const body = rewriteCliInvocation(stripPiOnlyBlocks(rawBody), version);
   const tools = mapTools(normalizeToolList(frontmatter.tools));
 
   const lines = ["---"];
@@ -155,12 +171,12 @@ export function transformAgent({ source, raw }) {
 
 /**
  * Transform a canonical `skills/<name>/SKILL.md` into a Claude `.claude/skills/<name>/SKILL.md`.
- * @param {{ source: string, raw: string }} input
+ * @param {{ source: string, raw: string, version?: string }} input
  * @returns {string} Full generated file content.
  */
-export function transformSkill({ source, raw }) {
+export function transformSkill({ source, raw, version = "latest" }) {
   const { frontmatter, body: rawBody } = splitFrontmatter(raw, source);
-  const body = stripPiOnlyBlocks(rawBody);
+  const body = rewriteCliInvocation(stripPiOnlyBlocks(rawBody), version);
   const tools = mapTools(normalizeToolList(frontmatter["allowed-tools"]));
 
   const lines = ["---"];

package/src/cli/primitives.mjs

@@ -1,10 +1,75 @@
 import { spawn } from "node:child_process";
+import { parseArgs } from "node:util";
 
 /**
  * Shared CLI primitives for arg parsing, validation, and child process execution.
  * Extracted from scripts/_cli-primitives.mjs per issue #548 Phase 2.
  */
 
+/**
+ * Parse argv with node:util parseArgs while preserving the legacy hand-rolled
+ * parser semantics that several callers depend on:
+ *
+ * - Unknown options/positionals throw `Unknown argument: <raw>`.
+ * - A string option whose value is missing or looks like another flag throws
+ *   `Missing value for <--flag>` (matching {@link requireOptionValue}).
+ *
+ * Returns a Map of canonical option name -> value (last-wins for repeats, which
+ * matches the legacy while/shift loops that simply reassigned on each match).
+ *
+ * @param {string[]} argv
+ * @param {Record<string, { type: "string" | "boolean", short?: string }>} options
+ * @param {(message: string) => Error} [parseError]
+ * @param {{ allowPositionals?: boolean, flagPattern?: RegExp }} [config]
+ * @returns {{ values: Map<string, string | boolean>, positionals: string[] }}
+ */
+export function parseCliTokens(argv, options, parseError = null, { allowPositionals = false, flagPattern = /^--/u } = {}) {
+  const { tokens } = parseArgs({
+    args: [...argv],
+    options,
+    allowPositionals: true,
+    strict: false,
+    tokens: true,
+  });
+
+  const values = new Map();
+  const positionals = [];
+
+  for (const token of tokens) {
+    if (token.kind === "positional") {
+      if (allowPositionals) {
+        positionals.push(token.value);
+        continue;
+      }
+      throw toCliError(`Unknown argument: ${token.value}`, parseError);
+    }
+
+    if (token.kind !== "option") {
+      continue;
+    }
+
+    const spec = options[token.name];
+    if (!spec) {
+      throw toCliError(`Unknown argument: ${token.rawName}`, parseError);
+    }
+
+    if (spec.type === "boolean") {
+      // A bare boolean flag carries no value (parseArgs → undefined) and means true;
+      // an explicit inline value (e.g. --flag=false) is honored rather than forced true.
+      values.set(token.name, token.value === undefined ? true : token.value !== "false");
+      continue;
+    }
+
+    const value = token.value;
+    if (typeof value !== "string" || value.length === 0 || flagPattern.test(value)) {
+      throw toCliError(`Missing value for ${token.rawName}`, parseError);
+    }
+    values.set(token.name, value);
+  }
+
+  return { values, positionals };
+}
+
 function toCliError(message, parseError) {
   if (typeof parseError === "function") {
     return parseError(message);
@@ -20,6 +85,25 @@ export function requireOptionValue(args, flag, parseError = null, { flagPattern
   return value;
 }
 
+/**
+ * Token-based equivalent of {@link requireOptionValue} for callers that have
+ * migrated to node:util parseArgs with `tokens: true`. Validates the value
+ * attached to a parsed option token, rejecting missing or flag-like values with
+ * the same `Missing value for <--flag>` message the legacy parsers emitted.
+ *
+ * @param {{ value?: string, rawName?: string }} token - a parseArgs option token
+ * @param {(message: string) => Error} [parseError]
+ * @param {{ flagPattern?: RegExp }} [config]
+ * @returns {string}
+ */
+export function requireTokenValue(token, parseError = null, { flagPattern = /^--/u } = {}) {
+  const value = token?.value;
+  if (typeof value !== "string" || value.length === 0 || flagPattern.test(value)) {
+    throw toCliError(`Missing value for ${token?.rawName}`, parseError);
+  }
+  return value;
+}
+
 export function parsePositiveInteger(value, flag, parseError = null) {
   if (!/^\d+$/.test(value) || Number(value) === 0) {
     throw toCliError(`${flag} must be a positive integer`, parseError);

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/github/review-threads.mjs

@@ -1,5 +1,7 @@
 import { readFile } from "node:fs/promises";
 
+import { parseCliTokens } from "../cli/primitives.mjs";
+
 function normalizeId(value, fallback) {
   if (typeof value === "string" && value.trim().length > 0) {
     return value.trim();
@@ -266,34 +268,14 @@ export function classifyReviewThreadsSignal(parsedResult, isCopilotLoginFn) {
 }
 
 
-function requireOptionValue(args, flag) {
-  const value = args.shift();
-
-  if (typeof value !== "string" || value.length === 0 || value.startsWith("--")) {
-    throw new Error(`Missing value for ${flag}`);
-  }
-
-  return value;
-}
-
 export function parseCliArgs(argv) {
-  const args = [...argv];
-  const options = {
-    inputPath: undefined,
-  };
-
-  while (args.length > 0) {
-    const token = args.shift();
-
-    if (token === "--input") {
-      options.inputPath = requireOptionValue(args, "--input");
-      continue;
-    }
-
-    throw new Error(`Unknown argument: ${token}`);
-  }
+  const { values } = parseCliTokens(argv, {
+    input: { type: "string" },
+  });
 
-  return options;
+  return {
+    inputPath: values.get("input"),
+  };
 }
 
 export async function readInput({ inputPath, stdin = process.stdin } = {}) {

package/src/loop/copilot-loop-state.mjs

@@ -229,12 +229,6 @@ function isAutoRerequestEligible(snapshot, state) {
  */
 const VALID_SIGNAL_LEVELS = new Set(["high", "mid", "low"]);
 
-function hasExplicitCurrentHeadReviewSignal(raw) {
-  return Boolean(raw)
-    && typeof raw === "object"
-    && Object.prototype.hasOwnProperty.call(raw, "copilotReviewOnCurrentHead");
-}
-
 export function normalizeSnapshot(raw) {
   if (!raw || typeof raw !== "object") {
     throw new Error("Snapshot must be a non-null object");
@@ -351,34 +345,54 @@ export function interpretLoopState(snapshot, refinementConfig) {
 
   // Round-cap enforcement: when maxCopilotRounds is configured and the review-round
   // count has been exhausted, stop re-requests before entering fix/reply-resolve routing.
-  // Gating here (before unresolved-thread checks) ensures round cap takes priority over
-  // the normal fix loop, including unresolved threads, pending CI, and CI failures.
-  // Clean PRs are usually eligible for pre_approval_gate fallback; the only automatic
-  // exception is when the head has advanced since the last submitted Copilot review,
-  // all prior feedback is resolved, and CI is green/credibly green again. In that case
-  // the state re-opens to READY_TO_REREQUEST_REVIEW instead of terminating as clean fallback.
-  // Does NOT interrupt an in-flight review request (requested/already-requested).
+  // Gating here (before unresolved-thread checks) lets a CLEAN PR at the cap terminate as
+  // ROUND_CAP_CLEAN_FALLBACK ahead of the normal fix/wait routing. It does NOT blanket-
+  // override that routing: a NOT-clean PR (unresolved threads or non-green CI) with an
+  // in-flight request deliberately falls through to the normal fix/wait routing below
+  // (see the `!reviewInFlight` branch), and only a not-clean PR with no in-flight request
+  // hard-stops at ROUND_CAP_REACHED.
+  //
+  // Precedence at the cap: copilotReviewRoundCount counts COMPLETED rounds, so at
+  // `>= maxRounds` every permitted Copilot round is already done and any lingering
+  // in-flight request (requested/already-requested) is for a forbidden over-cap round.
+  // A stale Copilot reviewer assignment must therefore NOT block the clean fallback:
+  // when threads are clean and CI is green, route to ROUND_CAP_CLEAN_FALLBACK even if
+  // copilotReviewRequestStatus is requested/already-requested. Otherwise a lingering
+  // assignment would dead-end the loop at WAITING_FOR_COPILOT_REVIEW waiting for a
+  // review that can never come (no further round is permitted past the cap). The
+  // pre_approval_gate (current-head clean evidence, enforced elsewhere) reviews any
+  // post-cap head change, so this proceeds without skipping review of new code.
+  //
+  // An in-flight request only still blocks the cap block when the PR is NOT clean
+  // (unresolved threads or non-green CI) — that legitimately stays in the fix/wait
+  // routing below rather than terminating as a clean fallback.
+  //
+  // Head-advanced handling: even when the head has advanced past the last submitted
+  // Copilot review with clean threads and green CI, re-requesting another Copilot pass
+  // is forbidden at the cap, so this routes to ROUND_CAP_CLEAN_FALLBACK (not
+  // READY_TO_REREQUEST_REVIEW, which would trigger an illegal auto re-request). The
+  // pre_approval_gate handles the current head.
   const maxRounds = refinementConfig?.maxCopilotRounds;
   const reviewInFlight = s.copilotReviewRequestStatus === "requested"
     || s.copilotReviewRequestStatus === "already-requested";
   if (typeof maxRounds === "number" && maxRounds > 0
       && s.copilotReviewRoundCount >= maxRounds
-      && !reviewInFlight
       && state !== STATE.NO_PR && state !== STATE.DONE
       && state !== STATE.PR_DRAFT && state !== STATE.REVIEW_REQUEST_UNAVAILABLE
       && state !== STATE.BLOCKED_NEEDS_USER_DECISION) {
     const ciClean = s.ciStatus === "success" || s.ciStatus === "crediblyGreen";
     const cleanThreads = s.unresolvedThreadCount === 0;
-    const headAdvancedSinceLastSubmittedCopilotReview = s.copilotReviewPresent
-      && hasExplicitCurrentHeadReviewSignal(snapshot)
-      && !s.copilotReviewOnCurrentHead;
-    if (cleanThreads && ciClean && headAdvancedSinceLastSubmittedCopilotReview) {
-      state = STATE.READY_TO_REREQUEST_REVIEW;
-    } else if (cleanThreads && ciClean) {
+    if (cleanThreads && ciClean) {
+      // Clean PR at the cap: proceed to the pre_approval_gate fallback regardless of a
+      // lingering Copilot reviewer assignment or an advanced head — no further Copilot
+      // round is permitted, so never re-open for re-request or wait on Copilot here.
       state = STATE.ROUND_CAP_CLEAN_FALLBACK;
-    } else {
+    } else if (!reviewInFlight) {
+      // Not clean and no in-flight request: hard stop at the cap.
       state = STATE.ROUND_CAP_REACHED;
     }
+    // Not clean WITH an in-flight request: leave state undecided so the normal
+    // fix/reply-resolve/wait routing below handles it (do not force a clean fallback).
   }
 
   if (state === undefined) {

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/phase-files.mjs

@@ -1,6 +1,8 @@
 import { mkdir, readFile, writeFile } from "node:fs/promises";
 import path from "node:path";
 
+import { parseCliTokens } from "../cli/primitives.mjs";
+
 export function createDefaultPhaseManifest(phase) {
   return {
     phase,
@@ -134,45 +136,19 @@ export async function ensurePhaseFiles(projectRoot, phase, patch = {}) {
   };
 }
 
-function requireOptionValue(args, flag) {
-  const value = args.shift();
-
-  if (typeof value !== "string" || value.length === 0 || value.startsWith("--")) {
-    throw new Error(`Missing value for ${flag}`);
-  }
-
-  return value;
-}
-
 export function parseCliArgs(argv) {
-  const args = [...argv];
+  const { values } = parseCliTokens(argv, {
+    "project-root": { type: "string" },
+    phase: { type: "string" },
+    patch: { type: "string" },
+  });
+
   const options = {
-    projectRoot: process.cwd(),
-    phase: undefined,
-    patch: {},
+    projectRoot: values.has("project-root") ? values.get("project-root") : process.cwd(),
+    phase: values.get("phase"),
+    patch: values.has("patch") ? JSON.parse(values.get("patch")) : {},
   };
 
-  while (args.length > 0) {
-    const token = args.shift();
-
-    if (token === "--project-root") {
-      options.projectRoot = requireOptionValue(args, "--project-root");
-      continue;
-    }
-
-    if (token === "--phase") {
-      options.phase = requireOptionValue(args, "--phase");
-      continue;
-    }
-
-    if (token === "--patch") {
-      options.patch = JSON.parse(requireOptionValue(args, "--patch"));
-      continue;
-    }
-
-    throw new Error(`Unknown argument: ${token}`);
-  }
-
   if (!options.phase) {
     throw new Error("Missing required --phase <phase-name> argument");
   }

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;
+}

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

@@ -6,6 +6,107 @@ import { main as moveQueueItemMain } from "../../../../scripts/projects/move-que
 
 const DEFAULT_NON_SUCCESS_COLUMN = "Backlog";
 
+// ── State → board column mapping (AC1, AC3, AC5) ─────────────────────────
+//
+// The mapping is intentionally stateless: it is a pure function of the loop
+// state. Because of that, a reverted loop state (e.g. a merged PR reopened, or
+// a ready PR demoted back to draft) maps backward to the earlier column for
+// free (AC5) — there is no persisted "furthest reached" column to unwind.
+
+/** Logical board columns. Display names are config-driven (AC3). */
+export const LOGICAL_COLUMN = Object.freeze({
+  NEXT_UP: "next_up",
+  IN_PROGRESS: "in_progress",
+  READY_FOR_REVIEW: "ready_for_review",
+  DONE: "done",
+});
+
+/** Allow-list of recognized logical column tokens (for config validation). */
+const KNOWN_LOGICAL_COLUMNS = new Set(Object.values(LOGICAL_COLUMN));
+
+/** Keys that must never be copied from untrusted config (prototype pollution). */
+const DANGEROUS_KEYS = new Set(["__proto__", "prototype", "constructor"]);
+
+/** Default display name for each logical column (AC1 values). */
+export const DEFAULT_STATE_COLUMN_NAMES = Object.freeze({
+  [LOGICAL_COLUMN.NEXT_UP]: "Next Up",
+  [LOGICAL_COLUMN.IN_PROGRESS]: "In Progress",
+  // Ready for Review is opt-in: by default it resolves to In Progress so that
+  // final_approval_ready keeps "In Progress" unless a board configures it.
+  [LOGICAL_COLUMN.READY_FOR_REVIEW]: "In Progress",
+  [LOGICAL_COLUMN.DONE]: "Done",
+});
+
+/**
+ * Default loop-state → logical-column map. Covers both the lifecycle states
+ * (lifecycle-state.mjs) and the inner Copilot loop states (copilot-loop-state.mjs),
+ * plus the conceptual names used by issue #793. Unknown states fall back to
+ * IN_PROGRESS (a safe, visible "work is happening" column) rather than throwing.
+ */
+export const DEFAULT_STATE_LOGICAL_MAP = Object.freeze({
+  // Next Up — work not yet actively in flight
+  issue_opened: LOGICAL_COLUMN.NEXT_UP,
+  issue_intake: LOGICAL_COLUMN.NEXT_UP,
+  refinement: LOGICAL_COLUMN.NEXT_UP,
+  no_pr: LOGICAL_COLUMN.NEXT_UP,
+  pr_draft: LOGICAL_COLUMN.NEXT_UP,
+
+  // In Progress — active implementation / review / feedback resolution
+  implementation: LOGICAL_COLUMN.IN_PROGRESS,
+  // Tolerated alias for `implementation` (conceptual name from issue #793);
+  // the queue driver passes the real `implementation` lifecycle state.
+  local_implementation_active: LOGICAL_COLUMN.IN_PROGRESS,
+  draft_gate: LOGICAL_COLUMN.IN_PROGRESS,
+  pr_ready_no_feedback: LOGICAL_COLUMN.IN_PROGRESS,
+  feedback_resolution: LOGICAL_COLUMN.IN_PROGRESS,
+  copilot_review: LOGICAL_COLUMN.IN_PROGRESS,
+  waiting_for_copilot_review: LOGICAL_COLUMN.IN_PROGRESS,
+  ready_to_rerequest_review: LOGICAL_COLUMN.IN_PROGRESS,
+  unresolved_feedback_present: LOGICAL_COLUMN.IN_PROGRESS,
+  already_fixed_needs_reply_resolve: LOGICAL_COLUMN.IN_PROGRESS,
+  waiting_for_ci: LOGICAL_COLUMN.IN_PROGRESS,
+  review_request_unavailable: LOGICAL_COLUMN.IN_PROGRESS,
+  round_cap_reached: LOGICAL_COLUMN.IN_PROGRESS,
+  round_cap_clean_fallback: LOGICAL_COLUMN.IN_PROGRESS,
+  internal_tooling_direct_gate: LOGICAL_COLUMN.IN_PROGRESS,
+  low_signal_converged: LOGICAL_COLUMN.IN_PROGRESS,
+  blocked_needs_user_decision: LOGICAL_COLUMN.IN_PROGRESS,
+
+  // Ready for Review — final approval gate. Resolves to In Progress unless a
+  // board configures a distinct "Ready for Review" column name (AC1).
+  pre_approval_gate: LOGICAL_COLUMN.READY_FOR_REVIEW,
+  final_approval_ready: LOGICAL_COLUMN.READY_FOR_REVIEW,
+
+  // Done — terminal (lifecycle MERGE = "merge", queue terminal = "done")
+  merge: LOGICAL_COLUMN.DONE,
+  done: LOGICAL_COLUMN.DONE,
+  // Tolerated aliases (conceptual names from issue #793).
+  merged: LOGICAL_COLUMN.DONE,
+  issue_closed: LOGICAL_COLUMN.DONE,
+});
+
+/** Safe default logical column for any state we do not explicitly map. */
+const DEFAULT_LOGICAL_COLUMN = LOGICAL_COLUMN.IN_PROGRESS;
+
+/**
+ * Pure mapping: loop state → board column display name.
+ *
+ * @param {string|null|undefined} loopState - a lifecycle or inner loop state
+ *   name. `null`, `undefined`, and any unrecognized value fall through to the
+ *   safe default logical column (IN_PROGRESS).
+ * @param {{stateColumnMap?:Object, columnNames?:Object}} [mapping]
+ *   Optional overrides. `stateColumnMap` overrides state→logical-column;
+ *   `columnNames` overrides logical-column→display-name. Both fall back to
+ *   the AC1 defaults.
+ * @returns {string} the target board column display name.
+ */
+export function boardColumnForLoopState(loopState, mapping = {}) {
+  const stateMap = { ...DEFAULT_STATE_LOGICAL_MAP, ...(mapping.stateColumnMap ?? {}) };
+  const columnNames = { ...DEFAULT_STATE_COLUMN_NAMES, ...(mapping.columnNames ?? {}) };
+  const logical = stateMap[loopState] ?? DEFAULT_LOGICAL_COLUMN;
+  return columnNames[logical] ?? columnNames[DEFAULT_LOGICAL_COLUMN];
+}
+
 // ── Local config loader ─────────────────────────────────────────────────
 
 function readDevloopsSettings(repoRoot) {
@@ -46,6 +147,62 @@ export function loadBoardConfig(repoRoot) {
   return { enabled: false };
 }
 
+/**
+ * Load the config-driven state→column mapping from `.devloops` `queue` (AC3).
+ *
+ * Reads two optional config keys, both gated behind the same opt-in `queue`
+ * section as `loadBoardConfig` (AC2/AC6):
+ *   - `queue.statusColumns`  — logical-column → display-name overrides
+ *     (keys: next_up, in_progress, ready_for_review, done)
+ *   - `queue.stateColumnMap` — loop-state → logical-column overrides
+ *
+ * Returns a `{ stateColumnMap, columnNames }` shape consumable by
+ * `boardColumnForLoopState`. Missing config yields the AC1 defaults.
+ *
+ * Hardened against untrusted `.devloops` input:
+ *   - `statusColumns` keys are allow-listed to the known logical columns;
+ *     unrecognized keys are ignored.
+ *   - `stateColumnMap` entries whose value is not a known logical column are
+ *     ignored.
+ *   - Dangerous keys (`__proto__`, `prototype`, `constructor`) are skipped and
+ *     results are built on null-prototype objects, so a malicious config key
+ *     cannot pollute Object.prototype.
+ */
+export function loadStateColumnMap(repoRoot) {
+  const { settings: queue } = readDevloopsSettings(repoRoot);
+  // Null-prototype objects: untrusted keys can never reach Object.prototype.
+  const columnNames = Object.assign(Object.create(null), DEFAULT_STATE_COLUMN_NAMES);
+  const stateColumnMap = Object.create(null);
+
+  const statusColumns = queue?.statusColumns;
+  if (statusColumns && typeof statusColumns === "object") {
+    for (const logical of Object.keys(statusColumns)) {
+      if (DANGEROUS_KEYS.has(logical)) continue;
+      // Allow-list: only recognized logical columns may be renamed.
+      if (!KNOWN_LOGICAL_COLUMNS.has(logical)) continue;
+      const name = statusColumns[logical];
+      if (typeof name === "string" && name.trim().length > 0) {
+        columnNames[logical] = name.trim();
+      }
+    }
+  }
+
+  const stateMap = queue?.stateColumnMap;
+  if (stateMap && typeof stateMap === "object") {
+    for (const state of Object.keys(stateMap)) {
+      if (DANGEROUS_KEYS.has(state)) continue;
+      const logical = stateMap[state];
+      // Ignore values that are not a recognized logical column.
+      if (typeof logical !== "string") continue;
+      const trimmed = logical.trim();
+      if (!KNOWN_LOGICAL_COLUMNS.has(trimmed)) continue;
+      stateColumnMap[state] = trimmed;
+    }
+  }
+
+  return { columnNames, stateColumnMap };
+}
+
 // ── Minimal project lookup (read-only, no create/repair) ────────────────
 
 const GET_USER_ID = [
@@ -187,6 +344,14 @@ export async function syncBoardStatus(
   env = process.env,
   dependencies = {},
 ) {
+  // AC4: the not-on-board / fail-open path is a logged no-op. Default to
+  // console.error so it logs in real runs; tests inject their own stub. The
+  // log fires at most once per syncBoardStatus call (single catch, no internal
+  // retry), so it cannot spam.
+  const log = typeof dependencies.log === "function"
+    ? dependencies.log
+    : (msg) => console.error(msg);
+
   const config = loadBoardConfig(repoRoot);
   if (!config.enabled) {
     return { ok: true, skipped: true, reason: config.reason ?? "board not configured" };
@@ -210,7 +375,19 @@ export async function syncBoardStatus(
     );
     return { ok: true, skipped: false, result };
   } catch (err) {
-    return { ok: true, skipped: true, reason: err.message ?? "board sync failed" };
+    // Fail-open: a board hiccup (rate limit, missing column, item not on board)
+    // must never break the loop.
+    const reason = err?.message ?? "board sync failed";
+    // AC4: the explicit "item not on board" case is a clean, logged no-op.
+    // Other fail-open failures (rate limit, missing column, etc.) get a
+    // distinct, distinguishable message so they are not conflated with AC4.
+    const notOnBoard = err?.code === "ITEM_NOT_FOUND" || err?.code === "ITEM_NOT_ON_BOARD";
+    if (notOnBoard) {
+      log(`[board-sync] no-op: item ${itemNumber} is not on the board (${reason})`);
+    } else {
+      log(`[board-sync] sync failed (fail-open) for item ${itemNumber} → "${targetColumn}": ${reason}`);
+    }
+    return { ok: true, skipped: true, reason };
   }
 }
 

package/src/loop/queue-driver.mjs

@@ -13,7 +13,12 @@ import {
   RECOVERABLE_FAILURES,
   appendBugIssue,
 } from "./queue-state.mjs";
-import { syncBoardStatus, nonSuccessBoardColumn } from "./queue-board-sync.mjs";
+import {
+  syncBoardStatus,
+  nonSuccessBoardColumn,
+  boardColumnForLoopState,
+  loadStateColumnMap,
+} from "./queue-board-sync.mjs";
 import { resolveNextUpOrder } from "./queue-board-ordering.mjs";
 
 export const DEFAULT_QUEUE_DRIVER_OPTIONS = {
@@ -52,6 +57,19 @@ export async function runQueue(repoRoot, repo, options = {}) {
   const opts = { ...DEFAULT_QUEUE_DRIVER_OPTIONS, ...options };
   const queue = await readQueue(repoRoot);
 
+  // Config-driven loop-state → board-column mapping (#793, AC1/AC3). Loaded
+  // once per run; resolves logical columns to configured display names, with
+  // the AC1 defaults when no `queue.statusColumns`/`queue.stateColumnMap` is set.
+  const stateColumnMap = loadStateColumnMap(repoRoot);
+  const columnFor = (loopState) => boardColumnForLoopState(loopState, stateColumnMap);
+
+  // Per-item dedup: a single run may resolve consecutive loop states to the
+  // same display column (e.g. implementation → final_approval_ready both
+  // default to "In Progress"). Skip the redundant board write/API call when the
+  // target column is unchanged for that item; a genuinely different column
+  // (e.g. a configured "Ready for Review") still syncs. (#793 round-1 #1)
+  const lastSyncedColumn = new Map();
+
   // Optional board-aware ordering: fetch Next Up order before processing.
   // Fail-open: if the board is unreachable, orderHint stays empty and the
   // driver falls back to the existing queue order.
@@ -95,15 +113,26 @@ export async function runQueue(repoRoot, repo, options = {}) {
       boardSync.push(r);
       return r;
     };
+    // Sync a target to a column, short-circuiting (no API call) when the column
+    // is unchanged from the last sync for the same item in this run.
+    const syncColumn = async (target, column) => {
+      if (lastSyncedColumn.get(target) === column) {
+        return recordBoardSync(Promise.resolve({
+          ok: true, skipped: true, reason: "column unchanged",
+        }));
+      }
+      const r = await recordBoardSync(syncBoardStatus(
+        repo, repoRoot, target, column, opts.env ?? process.env, boardSyncDeps,
+      ));
+      // Only remember the column when the move actually landed, so a fail-open
+      // skip does not suppress a later retry to the same column.
+      if (r.ok && r.skipped !== true) lastSyncedColumn.set(target, column);
+      return r;
+    };
 
-    await recordBoardSync(syncBoardStatus(
-      repo,
-      repoRoot,
-      entry.target,
-      "In Progress",
-      opts.env ?? process.env,
-      boardSyncDeps,
-    ));
+    // Entry has been picked up and is actively running: implementation phase
+    // (real lifecycle state, lifecycle-state.mjs LIFECYCLE_STATE.IMPLEMENTATION).
+    await syncColumn(entry.target, columnFor("implementation"));
 
     try {
       const entryResult = opts.runEntry
@@ -117,12 +146,18 @@ export async function runQueue(repoRoot, repo, options = {}) {
           if (opts.mergeAuthorized) {
             await doTransition(entry, "merging", queue, repoRoot, opts);
             await doTransition(entry, "done", queue, repoRoot, opts, { retrospectiveWritten: true });
-            await recordBoardSync(syncBoardStatus(repo, repoRoot, entry.target, "Done", opts.env ?? process.env, boardSyncDeps));
+            await syncColumn(entry.target, columnFor("done"));
+          } else {
+            // PR is up with gates passing but merge is not authorized: the work
+            // is awaiting final approval/merge. Map to the final-approval column
+            // (configured "Ready for Review" if present, else "In Progress").
+            // Deduped: when this resolves to the same column already synced for
+            // this item, no extra board write/API call is made.
+            await syncColumn(entry.target, columnFor("final_approval_ready"));
           }
-          // else: stays at gates_passing for future merge run
         } else {
           await doTransition(entry, "done", queue, repoRoot, opts);
-          await recordBoardSync(syncBoardStatus(repo, repoRoot, entry.target, "Done", opts.env ?? process.env, boardSyncDeps));
+          await syncColumn(entry.target, columnFor("done"));
         }
         results.push({ target: entry.target, ok: true, entry: snapshotEntry(entry), boardSync });
       } else {