dev-loops 0.2.5 → 0.2.6

package/.claude/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "dev-loops",
-  "version": "0.2.5",
+  "version": "0.2.6",
   "description": "Agent-harness-agnostic dev-loop: agents, skills, and hooks for GitHub/Copilot-driven development loops.",
   "author": {
     "name": "Manuel Fittko",
@@ -9,5 +9,12 @@
   "license": "MIT",
   "homepage": "https://github.com/mfittko/dev-loops#readme",
   "repository": "https://github.com/mfittko/dev-loops.git",
-  "keywords": ["dev-loop", "workflow", "github", "copilot", "claude-code", "plugin"]
+  "keywords": [
+    "dev-loop",
+    "workflow",
+    "github",
+    "copilot",
+    "claude-code",
+    "plugin"
+  ]
 }

package/.claude/hooks/_bash-command-classify.mjs

@@ -0,0 +1,164 @@
+// GENERATED from packages/core/src/loop/bash-command-classify.mjs by scripts/claude/generate-claude-assets.mjs — do not edit; edit the source and regenerate.
+/**
+ * Pure classification of shell command strings for the dev-loop gate boundary.
+ *
+ * Shared by the Pi extension (`extension/post-merge-update.ts`, which re-exports these so its
+ * behavior is unchanged) and the Claude Code PreToolUse Bash hook. Keeping one source of truth
+ * means the `gh pr ready` / merge detection is identical across harnesses.
+ *
+ * Pure and side-effect free.
+ */
+
+/** The repository these gate guards apply to. */
+export const TARGET_REPO_SLUG = "mfittko/dev-loops";
+
+/** Flags known to take a value argument for `gh pr ready` (not boolean flags). */
+export const FLAGS_THAT_TAKE_VALUE = new Set(["-r", "--repo"]);
+
+/** @param {string|null|undefined} value @returns {string|null} */
+export function trimToNull(value) {
+  const trimmed = `${value ?? ""}`.trim();
+  return trimmed ? trimmed : null;
+}
+
+/**
+ * Normalize a git remote URL into an `owner/name` slug (lowercased), or null.
+ * @param {string} remoteUrl
+ * @returns {string|null}
+ */
+export function normalizeGitHubRepoSlug(remoteUrl) {
+  const normalized = trimToNull(remoteUrl);
+  if (!normalized) {
+    return null;
+  }
+
+  const patterns = [
+    /^git@github\.com:([^\s]+?)(?:\.git)?$/i,
+    /^https?:\/\/github\.com\/([^\s]+?)(?:\.git)?$/i,
+    /^ssh:\/\/git@github\.com\/([^\s]+?)(?:\.git)?$/i,
+    /^git:\/\/github\.com\/([^\s]+?)(?:\.git)?$/i,
+    /^git:github\.com\/([^\s]+?)(?:\.git)?$/i,
+  ];
+
+  for (const pattern of patterns) {
+    const match = normalized.match(pattern);
+    if (!match) {
+      continue;
+    }
+    return trimToNull(match[1])?.toLowerCase() ?? null;
+  }
+
+  return null;
+}
+
+function isGhPrMergeCommand(segment) {
+  if (!/^gh\s+pr\s+merge(?:\s|$)/i.test(segment)) {
+    return false;
+  }
+  const remainder = segment.replace(/^gh\s+pr\s+merge(?:\s|$)/i, "").trim();
+  if (!remainder) {
+    return true;
+  }
+  const firstArg = remainder.match(/^(\S+)/)?.[1]?.toLowerCase() ?? "";
+  return !["--help", "-h"].includes(firstArg);
+}
+
+function isGitMergeCompletionCommand(segment) {
+  if (!/^git\s+merge(?:\s|$)/i.test(segment)) {
+    return false;
+  }
+  const remainder = segment.replace(/^git\s+merge(?:\s|$)/i, "").trim();
+  if (!remainder) {
+    return true;
+  }
+  const firstArg = remainder.match(/^(\S+)/)?.[1]?.toLowerCase() ?? "";
+  return !["--abort", "--continue", "--quit", "--help", "-h"].includes(firstArg);
+}
+
+/** @param {string} command @returns {boolean} */
+export function isMergeCapableCommand(command) {
+  const normalized = command.trim();
+  if (!normalized) {
+    return false;
+  }
+  return normalized
+    .split(/\s*(?:&&|\|\||;|\|)\s*/)
+    .some((segment) => isGhPrMergeCommand(segment) || isGitMergeCompletionCommand(segment));
+}
+
+/** @param {string} command @returns {string} */
+export function firstShellSegment(command) {
+  return command.trim().split(/\s*(?:&&|\|\||;|\|)\s*/)[0]?.trim() ?? "";
+}
+
+/** @param {string} command @returns {boolean} */
+export function isGhPrReadyCommand(command) {
+  const segment = firstShellSegment(command);
+  if (!segment || !/^gh\s+pr\s+ready(?:\s|$)/i.test(segment)) {
+    return false;
+  }
+  const remainder = segment.replace(/^gh\s+pr\s+ready(?:\s|$)/i, "").trim();
+  if (!remainder) {
+    return true;
+  }
+  const args = remainder.split(/\s+/).map((a) => a.toLowerCase());
+  return !args.includes("--help") && !args.includes("-h");
+}
+
+/** @param {string} command @returns {number|null} */
+export function extractPrNumberFromGhPrReady(command) {
+  const segment = firstShellSegment(command);
+  if (!/^gh\s+pr\s+ready(?:\s|$)/i.test(segment)) {
+    return null;
+  }
+  const remainder = segment.replace(/^gh\s+pr\s+ready(?:\s|$)/i, "").trim();
+  if (!remainder) {
+    return null;
+  }
+  const tokens = remainder.split(/\s+/);
+  for (let i = 0; i < tokens.length; i++) {
+    const token = tokens[i];
+    if (token.startsWith("-")) {
+      const flagName = token.replace(/=.*$/, "").toLowerCase();
+      if (!token.includes("=") && FLAGS_THAT_TAKE_VALUE.has(flagName)) {
+        i++;
+      }
+      continue;
+    }
+    if (/^\d+$/.test(token)) {
+      const num = Number(token);
+      if (num > 0) {
+        return num;
+      }
+    }
+    return null;
+  }
+  return null;
+}
+
+/** @param {string} command @returns {string|null} */
+export function extractRepoFlagFromGhPrReady(command) {
+  const segment = firstShellSegment(command);
+  if (!/^gh\s+pr\s+ready(?:\s|$)/i.test(segment)) {
+    return null;
+  }
+  const remainder = segment.replace(/^gh\s+pr\s+ready(?:\s|$)/i, "").trim();
+  if (!remainder) {
+    return null;
+  }
+  const tokens = remainder.split(/\s+/);
+  for (let i = 0; i < tokens.length; i++) {
+    const token = tokens[i];
+    const lower = token.toLowerCase();
+    if (lower === "-r" || lower === "--repo") {
+      if (i + 1 < tokens.length && !tokens[i + 1].startsWith("-")) {
+        return tokens[i + 1];
+      }
+    }
+    const repoEqMatch = token.match(/^(?:--repo|-R)=(.+)$/i);
+    if (repoEqMatch) {
+      return repoEqMatch[1];
+    }
+  }
+  return null;
+}

package/.claude/hooks/_hook-decisions.mjs

@@ -0,0 +1,130 @@
+// GENERATED from packages/core/src/claude/hook-decisions.mjs by scripts/claude/generate-claude-assets.mjs — do not edit; edit the source and regenerate.
+/**
+ * Pure decision logic for the Claude Code dev-loop hooks (#773).
+ *
+ * The hook *scripts* are thin: they read the PreToolUse/PostToolUse stdin payload, gather facts
+ * (git tracked/ignored status, gate-evidence result), and call these pure deciders. Keeping the
+ * decisions here makes the deny/allow boundary fully unit-testable without spawning hooks, and
+ * keeps the Claude-specific stdin/stdout IO at the edge.
+ *
+ * Pure and side-effect free.
+ */
+
+import { resolveRunId } from "./_run-context.mjs";
+import {
+  isGhPrReadyCommand,
+  extractPrNumberFromGhPrReady,
+  extractRepoFlagFromGhPrReady,
+  TARGET_REPO_SLUG,
+} from "./_bash-command-classify.mjs";
+
+/**
+ * @typedef {Object} HookDecision
+ * @property {"allow"|"deny"} decision
+ * @property {string} [reason] - Human-readable reason (shown to Claude on deny).
+ */
+
+const ALLOW = Object.freeze({ decision: "allow" });
+
+/**
+ * The agent type (Claude `agent_type` / the canonical agent name) that owns repo mutations.
+ * Only this subagent — not arbitrary subagents (Explore, Plan, generic Task agents) — may
+ * bypass the main-agent read-only boundary.
+ */
+export const DEV_LOOP_AGENT_TYPE = "dev-loop";
+
+/**
+ * Decide whether a PreToolUse Bash command must be blocked by the draft-gate boundary.
+ *
+ * Mirrors the Pi extension's `onUserBash`: the only blocked case is `gh pr ready` for the
+ * target repo without clean draft_gate evidence. Everything else (including merges, which
+ * trigger the post-merge step, not a block) is allowed through.
+ *
+ * @param {Object} params
+ * @param {string} params.command - The Bash command string.
+ * @param {string|null} [params.repoSlug] - Resolved owner/name of the cwd repo (null if unknown).
+ * @param {boolean} [params.gatePassed] - Whether `pre-pr-ready-gate` evidence exists for the PR.
+ * @param {string|null} [params.gateError] - Error detail when the gate guard could not run.
+ * @returns {HookDecision}
+ */
+export function decideBashGate({ command, repoSlug = null, gatePassed = false, gateError = null }) {
+  if (typeof command !== "string" || !isGhPrReadyCommand(command)) {
+    return ALLOW;
+  }
+
+  // An explicit `--repo other/repo` that is not the target → not our concern, pass through.
+  const explicitRepo = extractRepoFlagFromGhPrReady(command);
+  if (explicitRepo && explicitRepo.toLowerCase() !== TARGET_REPO_SLUG.toLowerCase()) {
+    return ALLOW;
+  }
+  // Only gate within the target repo (case-insensitive — callers may pass an un-lowercased slug).
+  if ((repoSlug ?? "").toLowerCase() !== TARGET_REPO_SLUG.toLowerCase()) {
+    return ALLOW;
+  }
+
+  const prNumber = extractPrNumberFromGhPrReady(command);
+  if (prNumber === null) {
+    return {
+      decision: "deny",
+      reason:
+        "gh pr ready blocked: could not determine the PR number from the command. Include the PR number explicitly.",
+    };
+  }
+
+  if (gateError) {
+    return {
+      decision: "deny",
+      reason: `gh pr ready blocked: draft-gate evidence check failed (${gateError}).`,
+    };
+  }
+
+  if (!gatePassed) {
+    return {
+      decision: "deny",
+      reason: `gh pr ready blocked: no visible clean draft_gate checkpoint verdict comment found for PR #${prNumber}.`,
+    };
+  }
+
+  return ALLOW;
+}
+
+/**
+ * Decide whether a PreToolUse Write/Edit must be blocked by the main-agent read-only boundary.
+ *
+ * Denies a mutation whose target is inside the repo working tree AND not gitignored, when the
+ * call originates from the MAIN agent. Allows it only inside the *dev-loop* subagent context:
+ * the CA2 run id (`DEVLOOPS_RUN_ID`) is present, or the Claude `agent_type` is the dev-loop
+ * agent. A generic subagent (Explore, Plan, an arbitrary Task agent) is NOT authorized — the
+ * contract requires mutations to flow through the dev-loop subagent specifically. Non-repo /
+ * gitignored paths are always allowed. Strict enforcement is opt-in via `enforce` (the hook
+ * derives it from `DEVLOOPS_MAIN_AGENT_READONLY=1`) so adopting the harness does not
+ * retroactively break a repo's own interactive dev; default is fail-open.
+ *
+ * @param {Object} params
+ * @param {string} params.filePath - Target file path.
+ * @param {boolean} params.isRepoMutation - True if inside the repo working tree AND not gitignored.
+ * @param {boolean} [params.enforce] - Strict mode (DEVLOOPS_MAIN_AGENT_READONLY=1).
+ * @param {Record<string,string|undefined>} [params.env] - Environment (for the CA2 run id).
+ * @param {string|null} [params.agentType] - Claude `agent_type` from the hook payload, if any.
+ * @returns {HookDecision}
+ */
+export function decideWriteGuard({ filePath, isRepoMutation, enforce = false, env = {}, agentType = null }) {
+  if (!enforce) {
+    return ALLOW; // strict enforcement not enabled — fail open
+  }
+  if (!isRepoMutation) {
+    return ALLOW; // non-repo or gitignored path (e.g. /tmp, tmp/) — allowed by the contract
+  }
+  // Authorized only inside the dev-loop subagent context: CA2 run id, or the dev-loop agent
+  // type. Any other subagent type is treated like the main agent and denied.
+  if (resolveRunId(env) || agentType === DEV_LOOP_AGENT_TYPE) {
+    return ALLOW;
+  }
+  return {
+    decision: "deny",
+    reason:
+      `Main-agent read-only boundary: refusing to mutate repository path "${filePath}". ` +
+      "All repository mutations must flow through the dev-loop subagent. " +
+      "See skills/docs/main-agent-contract.md.",
+  };
+}

package/.claude/hooks/_hook-io.mjs

@@ -4,7 +4,7 @@
  * Hooks receive the event payload as JSON on stdin and signal a PreToolUse decision either via
  * exit code 2 (stderr → Claude) or exit 0 with a `hookSpecificOutput` JSON object. We use the
  * structured JSON form so the deny reason is explicit. The decision logic itself lives in the
- * pure `@dev-loops/core/claude/hook-decisions` deciders — these helpers are only the edge IO.
+ * pure deciders in the vendored `./_hook-decisions.mjs` bundle — these helpers are only edge IO.
  */
 import { readFileSync } from "node:fs";
 

package/.claude/hooks/_run-context.mjs

@@ -0,0 +1,179 @@
+// GENERATED from packages/core/src/loop/run-context.mjs by scripts/claude/generate-claude-assets.mjs — do not edit; edit the source and regenerate.
+/**
+ * Neutral run-id / async-context contract.
+ *
+ * The dev-loop async path historically keyed off Pi's `PI_SUBAGENT_RUN_ID` env var to
+ * identify an inspectable per-subagent run (runner ownership, async-start enforcement,
+ * human-comment gating). This module generalizes that into a harness-neutral
+ * `DEVLOOPS_RUN_ID`, keeping `PI_SUBAGENT_RUN_ID` as a backward-compatible alias, and
+ * provides a mint-and-propagate path for harnesses (e.g. Claude Code) that inject no
+ * native per-subagent run id.
+ *
+ * Marker precedence is neutral-first: a present `DEVLOOPS_RUN_ID` wins; otherwise the Pi
+ * alias is honored. Existing Pi runs that set only `PI_SUBAGENT_RUN_ID` behave identically.
+ *
+ * This module is pure except for the explicit file/IO helpers (writeRunContext/readRunContext),
+ * which take an injectable `fs` and `root` for testability.
+ */
+
+import crypto from "node:crypto";
+import fsDefault from "node:fs";
+import path from "node:path";
+
+/**
+ * Env var names that carry the async-context run id, in resolution precedence order.
+ * Neutral `DEVLOOPS_RUN_ID` first; Pi `PI_SUBAGENT_RUN_ID` retained as a compatibility alias.
+ */
+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";
+
+/** Pi-compatibility alias env var name. */
+export const PI_RUN_ID_ALIAS_VAR = "PI_SUBAGENT_RUN_ID";
+
+/** State-file name (under `.pi/`, consistent with existing dev-loop checkpoint files). */
+export const RUN_CONTEXT_FILENAME = "dev-loop-run-context.json";
+
+/**
+ * Env var Claude Code sets in every tool/subagent shell it spawns.
+ * Used as the harness signal — see `isClaudeHarness`.
+ */
+export const CLAUDE_HARNESS_MARKER = "CLAUDECODE";
+
+/**
+ * True when running under the Claude Code harness.
+ *
+ * Claude Code sets `CLAUDECODE=1` in the environment of every Bash tool and
+ * subagent it spawns. This is the harness-detection seam used to relax
+ * Pi-specific runtime contracts (e.g. the async-start contract) that do not
+ * apply to Claude's execution model.
+ *
+ * @param {Record<string, string|undefined>} [env]
+ * @returns {boolean}
+ */
+export function isClaudeHarness(env = process.env) {
+  return env?.[CLAUDE_HARNESS_MARKER] === "1";
+}
+
+/**
+ * Resolve the active run id from the environment, neutral marker first.
+ *
+ * @param {Record<string, string|undefined>} [env]
+ * @returns {string|null} The trimmed run id, or null when none is set.
+ */
+export function resolveRunId(env = process.env) {
+  for (const marker of RUN_ID_MARKERS) {
+    const value = env?.[marker];
+    if (typeof value === "string" && value.trim().length > 0) {
+      return value.trim();
+    }
+  }
+  return null;
+}
+
+/**
+ * Mint a fresh neutral run id.
+ *
+ * @returns {string} `devloops-<uuid>` (e.g. "devloops-3f2c1e84-...-9a0b")
+ */
+export function mintRunId() {
+  return `devloops-${crypto.randomUUID()}`;
+}
+
+/**
+ * Build the env fragment that propagates a run id to child processes.
+ *
+ * Sets the neutral var; child Bash scripts observe it via `resolveRunId`. Callers merge
+ * this into the child env (e.g. `{ ...process.env, ...runContextEnv(runId) }`).
+ *
+ * @param {string} runId
+ * @returns {{ DEVLOOPS_RUN_ID: string }}
+ */
+export function runContextEnv(runId) {
+  return { [NEUTRAL_RUN_ID_VAR]: runId };
+}
+
+/**
+ * Absolute path to the run-context state file for a repo root.
+ *
+ * @param {string} root - Repository root (or any base dir).
+ * @returns {string}
+ */
+export function runContextPath(root) {
+  return path.join(root, ".pi", RUN_CONTEXT_FILENAME);
+}
+
+/**
+ * Persist the run-context state file (for inspection/recovery).
+ *
+ * @param {object} params
+ * @param {string} params.runId
+ * @param {string} params.root
+ * @param {string} [params.mintedAt] - ISO timestamp; defaults to now. Tests pass a fixed
+ *   value for determinism; real runs get a useful inspection/recovery timestamp.
+ * @param {typeof import("node:fs")} [params.fs]
+ * @returns {string} The path written.
+ */
+export function writeRunContext({ runId, root, mintedAt, fs = fsDefault }) {
+  if (typeof runId !== "string" || runId.trim().length === 0) {
+    throw new TypeError("writeRunContext: runId must be a non-empty string");
+  }
+  const file = runContextPath(root);
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const payload = {
+    runId: runId.trim(),
+    mintedAt: mintedAt ?? new Date().toISOString(),
+  };
+  fs.writeFileSync(file, `${JSON.stringify(payload, null, 2)}\n`, "utf8");
+  return file;
+}
+
+/**
+ * Read the run-context state file, or null when absent/unparseable.
+ *
+ * @param {object} params
+ * @param {string} params.root
+ * @param {typeof import("node:fs")} [params.fs]
+ * @returns {{ runId: string, mintedAt: string|null }|null}
+ */
+export function readRunContext({ root, fs = fsDefault }) {
+  const file = runContextPath(root);
+  try {
+    const raw = fs.readFileSync(file, "utf8");
+    const parsed = JSON.parse(raw);
+    if (parsed && typeof parsed.runId === "string" && parsed.runId.trim().length > 0) {
+      return { runId: parsed.runId.trim(), mintedAt: parsed.mintedAt ?? null };
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Resolve the active run id, or mint one and persist a run-context state file.
+ *
+ * This is the "mint at startup and propagate" primitive a Claude dev-loop agent (or a
+ * headless entry) calls before dispatching child work. When the env already carries a run
+ * id (Pi alias or neutral), it is reused and no new id is minted.
+ *
+ * @param {object} [params]
+ * @param {Record<string, string|undefined>} [params.env]
+ * @param {string} [params.root]
+ * @param {string} [params.mintedAt] - ISO timestamp for the state file (determinism).
+ * @param {typeof import("node:fs")} [params.fs]
+ * @returns {{ runId: string, minted: boolean, statePath: string|null }}
+ */
+export function ensureRunId({ env = process.env, root, mintedAt, fs = fsDefault } = {}) {
+  const existing = resolveRunId(env);
+  if (existing) {
+    return { runId: existing, minted: false, statePath: null };
+  }
+  const runId = mintRunId();
+  let statePath = null;
+  if (typeof root === "string" && root.length > 0) {
+    statePath = writeRunContext({ runId, root, mintedAt, fs });
+  }
+  return { runId, minted: true, statePath };
+}

package/.claude/hooks/post-tool-use-merge.mjs

@@ -9,7 +9,7 @@
  * action is a no-op. There is therefore nothing to run on Stop/SubagentStop; the merge is simply
  * detected here on PostToolUse and an informational, non-blocking note is surfaced. Never blocks.
  */
-import { isMergeCapableCommand } from "@dev-loops/core/loop/bash-command-classify";
+import { isMergeCapableCommand } from "./_bash-command-classify.mjs";
 
 import { readHookInput } from "./_hook-io.mjs";
 

package/.claude/hooks/pre-tool-use-bash-gate.mjs

@@ -10,13 +10,13 @@
 import { execFileSync } from "node:child_process";
 import path from "node:path";
 
-import { decideBashGate } from "@dev-loops/core/claude/hook-decisions";
+import { decideBashGate } from "./_hook-decisions.mjs";
 import {
   isGhPrReadyCommand,
   extractPrNumberFromGhPrReady,
   normalizeGitHubRepoSlug,
   TARGET_REPO_SLUG,
-} from "@dev-loops/core/loop/bash-command-classify";
+} from "./_bash-command-classify.mjs";
 
 import { readHookInput, emitDeny, emitAllow } from "./_hook-io.mjs";
 

package/.claude/hooks/pre-tool-use-write-guard.mjs

@@ -12,7 +12,7 @@
 import { execFileSync } from "node:child_process";
 import path from "node:path";
 
-import { decideWriteGuard } from "@dev-loops/core/claude/hook-decisions";
+import { decideWriteGuard } from "./_hook-decisions.mjs";
 
 import { readHookInput, emitDeny, emitAllow } from "./_hook-io.mjs";
 

package/.claude/skills/docs/merge-preconditions.md

@@ -10,6 +10,21 @@ Canonical owner for merge preconditions across all workflow families.
 4. ✅ All review threads resolved
 5. ✅ Explicit merge authorization from operator
 6. ✅ PR body contains `Closes #N` or `Fixes #N`
+7. ✅ PR **title** free of merge-blocking markers — `WIP`, `[WIP]`, `DRAFT`, `DO NOT MERGE`, `🚧` (case-insensitive)
+
+## Title markers
+
+The PR title is a contract surface, so a merge-blocking marker in the title is enforced
+deterministically (`findBlockingTitleMarkers` in `@dev-loops/core/loop/pr-title-markers`), not
+just reviewed:
+
+- At the **draft → ready-for-review** transition: `ready-for-review` refuses `gh pr ready` while the
+  title carries a marker.
+- At the **pre-approval gate boundary and final approval** (for non-draft PRs): the gate coordinator
+  returns `title_marker_blocked` so a PR un-drafted externally still cannot enter pre-approval or
+  reach merge-ready with a marked title.
+
+A marker is allowed only while the PR is still in draft; it must be removed before the PR leaves draft.
 
 ## Merge authorization
 

package/.claude/skills/docs/pr-lifecycle-contract.md

@@ -44,6 +44,7 @@ It does not redefine helper transport mechanics, reviewer-loop internals, conduc
 - Draft existence alone is **not** draft-gate readiness.
 - A PR must clear the draft-stage gate for the current head before Copilot review may be requested.
 - Ready -> draft resets the lifecycle back into draft-stage gating.
+- A merge-blocking marker in the PR **title** (`WIP`/`[WIP]`/`DRAFT`/`DO NOT MERGE`/`🚧`, case-insensitive) blocks the draft -> ready transition and, for non-draft PRs, blocks entry to the pre-approval gate and final approval (`title_marker_blocked`). Markers are permitted only while the PR remains draft. See [Merge preconditions](merge-preconditions.md#title-markers).
 - Human approval / merge are explicit external waits, not hidden remediation states.
 
 ## Two required local gates

package/CHANGELOG.md

@@ -2,6 +2,41 @@
 
 All notable changes to this project will be documented in this file.
 
+## 0.2.6
+
+### Fixed
+
+- **Claude plugin hooks are self-contained** (#843). The bundled PreToolUse/PostToolUse hooks
+  imported a bare `@dev-loops/core`, which is unresolvable from the marketplace plugin cache (no
+  `node_modules` there), so every hook crashed on load — the two PreToolUse gates were silently
+  failing open. The asset generator now emits a vendored, relative-import hook bundle
+  (`.claude/hooks/_*.mjs`) from the canonical core modules, drift-guarded by the no-drift check.
+- **Retrospective gate is opt-in for consumers** (#841). `extension-defaults.yaml` shipped
+  `requireRetrospective`/`requireRetrospectiveGate: true`, forcing the retrospective merge gate on
+  every consumer's product PRs against the code default and the contract. Both now default `false`;
+  the dev-loops repo opts in via its own `.devloops`.
+- **Dev mode is opt-in for consumers** (#846). `extension-defaults.yaml` shipped
+  `devModeDefault: true`, pushing every consumer's product phases into the loop's self-improvement
+  mode (which edits the loop's own skill/agent prompts). Now defaults `false`; the dev-loops repo
+  opts in via `.devloops`.
+
+### Added
+
+- **Merge-blocking PR-title gate** (#842). The gate pipeline now flags `WIP`/`[WIP]`/`DRAFT`/
+  `DO NOT MERGE`/`🚧` (case-insensitive) in the PR **title**, blocking the draft→ready transition
+  and — for non-draft PRs — entry to the pre-approval gate and final approval. Documented in the
+  merge-preconditions and PR-lifecycle contracts.
+- **Effective async-start mode is surfaced** (#834). The handoff envelope now reports
+  `asyncStartEffective` and `asyncStartRelaxedBy` alongside the unchanged configured
+  `asyncStartMode`, so the Claude harness relaxation (`required`→`allowed`) is visible instead of
+  reading as a contradiction.
+
+### Changed
+
+- **Deduplicated PR aggregation** (#809). The duplicated `listOpenPrs` helper is extracted into a
+  shared `scripts/loop/_loop-pr-aggregation.mjs` and reused by `conductor-monitor.mjs` and
+  `run-conductor-cycle.mjs`. No behavior change.
+
 ## 0.2.5
 
 ### Changed

package/package.json

@@ -68,7 +68,7 @@
   },
   "dependencies": {
     "mermaid": "11.15.0",
-    "@dev-loops/core": "^0.2.5"
+    "@dev-loops/core": "^0.2.6"
   },
   "repository": {
     "type": "git",
@@ -78,7 +78,7 @@
     "url": "https://github.com/mfittko/dev-loops/issues"
   },
   "homepage": "https://github.com/mfittko/dev-loops#readme",
-  "version": "0.2.5",
+  "version": "0.2.6",
   "files": [
     "cli/",
     "lib/",

package/scripts/claude/generate-claude-assets.mjs

@@ -60,9 +60,54 @@ export function collectGeneratedAssets({ repoRoot = process.cwd() } = {}) {
     assets.push(...collectBundle(repoRoot, srcRel, targetRel));
   }
 
+  // Self-contained hook bundle (#843). The PreToolUse/PostToolUse hook scripts under
+  // .claude/hooks/ ship inside the Claude plugin, which has no node_modules — so they cannot
+  // import `@dev-loops/core` (it is unresolvable from the plugin cache and crashes the hook on
+  // load). Vendor the pure deciders/classifiers they need as self-contained relative `_*.mjs`
+  // modules generated from the canonical core sources, with cross-module imports rewritten to
+  // local paths. The no-drift check keeps them in sync with packages/core/src.
+  assets.push(...collectHookBundle(repoRoot));
+
   return assets;
 }
 
+/**
+ * The core modules vendored into `.claude/hooks/` for the self-contained hook bundle (#843).
+ * `rewrites` rewrites cross-module import specifiers to the sibling vendored copies; node:
+ * builtins are left untouched.
+ */
+const HOOK_BUNDLE = [
+  { source: "packages/core/src/loop/bash-command-classify.mjs", target: ".claude/hooks/_bash-command-classify.mjs", rewrites: [] },
+  { source: "packages/core/src/loop/run-context.mjs", target: ".claude/hooks/_run-context.mjs", rewrites: [] },
+  {
+    source: "packages/core/src/claude/hook-decisions.mjs",
+    target: ".claude/hooks/_hook-decisions.mjs",
+    rewrites: [
+      ['"../loop/run-context.mjs"', '"./_run-context.mjs"'],
+      ['"../loop/bash-command-classify.mjs"', '"./_bash-command-classify.mjs"'],
+    ],
+  },
+];
+
+/** Marker that identifies a generated hook-bundle module (a JS comment, distinct from the
+ * markdown `<!-- GENERATED -->` banner used by generated skills/agents/docs). Used both to
+ * stamp generated bundle modules and to scope orphan detection to them within `.claude/hooks/`. */
+const HOOK_BUNDLE_BANNER_PREFIX = "// GENERATED from ";
+
+/** Collect the vendored self-contained hook bundle modules (#843). */
+function collectHookBundle(repoRoot) {
+  const out = [];
+  for (const { source, target, rewrites } of HOOK_BUNDLE) {
+    const abs = path.join(repoRoot, source);
+    if (!fs.existsSync(abs)) continue; // no-op when core sources are absent (e.g. consumer tree)
+    let body = fs.readFileSync(abs, "utf8");
+    for (const [from, to] of rewrites) body = body.split(from).join(to);
+    const banner = `${HOOK_BUNDLE_BANNER_PREFIX}${source} by scripts/claude/generate-claude-assets.mjs — do not edit; edit the source and regenerate.\n`;
+    out.push({ target, content: banner + body });
+  }
+  return out;
+}
+
 /**
  * Recursively collect `*.md` files under a source dir as {target, content} bundle assets.
  * Bodies are passed through `stripPiOnlyBlocks` so bundled contract docs can scope Pi-runtime
@@ -114,10 +159,23 @@ function listFilesRecursive(repoRoot, rel) {
  * bundled docs/templates whose source was removed — are detected, not just SKILL.md files.
  */
 function listExistingAssetFiles(repoRoot) {
-  return [
+  const files = [
     ...listFilesRecursive(repoRoot, ".claude/agents"),
     ...listFilesRecursive(repoRoot, ".claude/skills"),
   ];
+  // `.claude/hooks/` mixes hand-authored scripts (hooks.json, _hook-io.mjs, the three hook
+  // scripts) with generated bundle modules (#843). Only the generated ones — identified by the
+  // generator banner — participate in orphan detection, so a dropped/renamed HOOK_BUNDLE entry
+  // is caught without false-flagging the hand-authored files.
+  for (const rel of listFilesRecursive(repoRoot, ".claude/hooks")) {
+    const abs = path.join(repoRoot, rel);
+    try {
+      if (fs.readFileSync(abs, "utf8").startsWith(HOOK_BUNDLE_BANNER_PREFIX)) files.push(rel);
+    } catch {
+      // unreadable — skip
+    }
+  }
+  return files;
 }
 
 /**

package/scripts/github/ready-for-review.mjs

@@ -3,10 +3,11 @@ import { buildParseError, formatCliError, isDirectCliRun, parseJsonText, summari
 import { parsePrNumber, requireOptionValue, runChild } from "../_cli-primitives.mjs";
 import { parseRepoSlug } from "@dev-loops/core/github/repo-slug";
 import { loadDevLoopConfig, resolveGateConfig } from "@dev-loops/core/config";
+import { findBlockingTitleMarkers } from "@dev-loops/core/loop/pr-title-markers";
 
 const USAGE = `Usage: ready-for-review.mjs --repo <owner/name> --pr <number>\nWrapper around gh pr ready that enforces gate-evidence validation.`;
 const parseError = buildParseError(USAGE);
-const PR_VIEW_QUERY = `query($owner:String!, $name:String!, $number:Int!) { repository(owner:$owner, name:$name) { pullRequest(number:$number) { id, isDraft, headRefOid, state, mergeStateStatus } } }`;
+const PR_VIEW_QUERY = `query($owner:String!, $name:String!, $number:Int!) { repository(owner:$owner, name:$name) { pullRequest(number:$number) { id, isDraft, headRefOid, state, mergeStateStatus, title } } }`;
 
 export function parseReadyForReviewCliArgs(argv) {
   const args = [...argv], opts = { help: false, repo: undefined, pr: undefined };
@@ -33,7 +34,7 @@ async function fetchPrState({ repo, pr }, { env, ghCommand }) {
   const r = await runGhJson(["api", "graphql", "-f", `query=${PR_VIEW_QUERY}`, "-f", `owner=${owner}`, "-f", `name=${name}`, "-F", `number=${pr}`], { env, ghCommand });
   const d = r?.data?.repository?.pullRequest;
   if (!d) throw new Error(`Could not fetch PR #${pr}`);
-  return { id: d.id, isDraft: d.isDraft === true, headRefOid: typeof d.headRefOid === "string" ? d.headRefOid.trim() : null, state: typeof d.state === "string" ? d.state.trim() : null, mergeStateStatus: typeof d.mergeStateStatus === "string" ? d.mergeStateStatus.trim() : null };
+  return { id: d.id, isDraft: d.isDraft === true, headRefOid: typeof d.headRefOid === "string" ? d.headRefOid.trim() : null, state: typeof d.state === "string" ? d.state.trim() : null, mergeStateStatus: typeof d.mergeStateStatus === "string" ? d.mergeStateStatus.trim() : null, title: typeof d.title === "string" ? d.title : null };
 }
 
 async function fetchCiStatus({ repo, pr }, { env, ghCommand }) {
@@ -71,6 +72,8 @@ export async function readyForReview(options, { env = process.env, ghCommand = "
   const headSha = prState.headRefOid;
   if (!headSha) throw new Error(`Could not resolve head SHA`);
   if (!prState.isDraft) throw new Error(`PR #${options.pr} is not in draft state`);
+  const titleMarkers = findBlockingTitleMarkers(prState.title);
+  if (titleMarkers.length > 0) throw new Error(`PR #${options.pr} cannot be marked ready: title contains merge-blocking marker(s): ${titleMarkers.join(", ")}. Remove them from the title first.`);
   if (requireCi) { const ci = await fetchCiStatus({ repo: options.repo, pr: options.pr }, { env, ghCommand }); if (ci.status === "blocked") throw new Error(`PR #${options.pr} has blocking CI checks`); if (ci.status !== "success") throw new Error(`PR #${options.pr} CI is not green`); }
   const gate = await fetchGateEvidence({ repo: options.repo, pr: options.pr, headSha }, { env, ghCommand });
   if (!gate.cleanEvidenceExists && !gate.effectiveHeadClean) throw new Error(`No visible clean draft_gate evidence on ${headSha.slice(0,7)}`);

package/scripts/loop/_loop-pr-aggregation.mjs

@@ -0,0 +1,45 @@
+// Shared loop PR-aggregation helpers used by both conductor-monitor.mjs and
+// run-conductor-cycle.mjs. Spawns `gh`, so this lives at the scripts level
+// rather than in @dev-loops/core.
+import { runChild } from "../_cli-primitives.mjs";
+import { parseJsonText } from "../_core-helpers.mjs";
+
+export const OPEN_PR_LIST_LIMIT = 1000;
+
+export async function listOpenPrs({ repo }, { env, ghCommand }) {
+  const result = await runChild(
+    ghCommand,
+    [
+      "pr",
+      "list",
+      "--repo",
+      repo,
+      "--state",
+      "open",
+      "--limit",
+      String(OPEN_PR_LIST_LIMIT),
+      "--json",
+      "number,title,url,isDraft,headRefName,author",
+    ],
+    env,
+  );
+  if (result.code !== 0) {
+    const detail = result.stderr.trim() || `exit code ${result.code}`;
+    throw new Error(`gh command failed: ${detail}`);
+  }
+  const payload = parseJsonText(result.stdout);
+  if (!Array.isArray(payload)) {
+    throw new Error("Invalid gh pr list payload: expected an array");
+  }
+  return payload
+    .map((pr) => ({
+      number: Number.isInteger(pr?.number) ? pr.number : null,
+      title: typeof pr?.title === "string" ? pr.title : "",
+      url: typeof pr?.url === "string" ? pr.url : null,
+      isDraft: Boolean(pr?.isDraft),
+      headRefName: typeof pr?.headRefName === "string" ? pr.headRefName : null,
+      authorLogin: typeof pr?.author?.login === "string" ? pr.author.login : null,
+    }))
+    .filter((pr) => pr.number !== null)
+    .sort((left, right) => left.number - right.number);
+}

package/scripts/loop/conductor-monitor.mjs

@@ -3,7 +3,7 @@ import { existsSync } from "node:fs";
 import { access, open, readFile, readdir } from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
-import { runChild, requireOptionValue } from "../_cli-primitives.mjs";
+import { requireOptionValue } from "../_cli-primitives.mjs";
 import { buildParseError, formatCliError, isDirectCliRun, parseJsonText } from "../_core-helpers.mjs";
 import { parseRepoSlug } from "@dev-loops/core/github/repo-slug";
 import { autoDetectSnapshot } from "./detect-copilot-loop-state.mjs";
@@ -13,6 +13,7 @@ import {
   parseRecordedHandoffContract,
 } from "./_handoff-contract.mjs";
 import { interpretLoopState, summarizeLoopInterpretation } from "@dev-loops/core/loop/copilot-loop-state";
+import { listOpenPrs } from "./_loop-pr-aggregation.mjs";
 const USAGE = `Usage: conductor-monitor.mjs --repo <owner/name> [--auto-resume]
 Aggregate Copilot-loop status across all open PRs in one repo.
 Required:
@@ -80,7 +81,6 @@ Exit codes:
   0  Success
   1  Argument error, gh failure, or indeterminate PR status`.trim();
 const parseError = buildParseError(USAGE);
-const OPEN_PR_LIST_LIMIT = 1000;
 const DEFAULT_SESSION_ROOT = path.join(os.homedir(), ".pi", "agent", "sessions");
 const RUN_STATE = {
   COMPLETED: "completed",
@@ -145,43 +145,6 @@ function parseCliArgs(argv) {
   }
   return options;
 }
-async function listOpenPrs({ repo }, { env, ghCommand }) {
-  const result = await runChild(
-    ghCommand,
-    [
-      "pr",
-      "list",
-      "--repo",
-      repo,
-      "--state",
-      "open",
-      "--limit",
-      String(OPEN_PR_LIST_LIMIT),
-      "--json",
-      "number,title,url,isDraft,headRefName,author",
-    ],
-    env,
-  );
-  if (result.code !== 0) {
-    const detail = result.stderr.trim() || `exit code ${result.code}`;
-    throw new Error(`gh command failed: ${detail}`);
-  }
-  const payload = parseJsonText(result.stdout);
-  if (!Array.isArray(payload)) {
-    throw new Error("Invalid gh pr list payload: expected an array");
-  }
-  return payload
-    .map((pr) => ({
-      number: Number.isInteger(pr?.number) ? pr.number : null,
-      title: typeof pr?.title === "string" ? pr.title : "",
-      url: typeof pr?.url === "string" ? pr.url : null,
-      isDraft: Boolean(pr?.isDraft),
-      headRefName: typeof pr?.headRefName === "string" ? pr.headRefName : null,
-      authorLogin: typeof pr?.author?.login === "string" ? pr.author.login : null,
-    }))
-    .filter((pr) => pr.number !== null)
-    .sort((left, right) => left.number - right.number);
-}
 function summarizePrDisposition(loopDisposition) {
   switch (loopDisposition) {
     case "pending":

package/scripts/loop/detect-pr-gate-coordination-state.mjs

@@ -147,7 +147,7 @@ async function fetchRequestedReviewers({ repo, pr }, { env = process.env, ghComm
 async function fetchPrFacts({ repo, pr }, { env = process.env, ghCommand = "gh" } = {}) {
   const result = await runChild(
     ghCommand,
-    ["pr", "view", String(pr), "--repo", repo, "--json", "number,state,isDraft,headRefOid,mergeStateStatus,body,closingIssuesReferences,reviews,statusCheckRollup"],
+    ["pr", "view", String(pr), "--repo", repo, "--json", "number,state,isDraft,headRefOid,mergeStateStatus,body,title,closingIssuesReferences,reviews,statusCheckRollup"],
     env,
   );
   if (result.code !== 0) {
@@ -381,6 +381,7 @@ export async function detectPrGateCoordinationState(options, runtime = {}) {
     prDraft: Boolean(context.prData?.isDraft),
     prClosed: String(context.prData?.state || "").toUpperCase() === "CLOSED",
     prMerged: String(context.prData?.state || "").toUpperCase() === "MERGED",
+    prTitle: context.prData?.title,
     mergeStateStatus: context.mergeStateStatus,
     conflictFiles: context.conflictFiles,
     lifecycleState: context.interpretation.state,

package/scripts/loop/run-conductor-cycle.mjs

@@ -1,10 +1,9 @@
 #!/usr/bin/env node
-import { runChild, requireOptionValue } from "../_cli-primitives.mjs";
+import { requireOptionValue } from "../_cli-primitives.mjs";
 import {
   buildParseError,
   formatCliError,
   isDirectCliRun,
-  parseJsonText,
 } from "../_core-helpers.mjs";
 import { parseRepoSlug } from "@dev-loops/core/github/repo-slug";
 import { detectPrGateCoordinationState } from "./detect-pr-gate-coordination-state.mjs";
@@ -14,9 +13,10 @@ import {
   SUBAGENT_ACTIONS as SHARED_SUBAGENT_ACTIONS,
   buildHandoffContractForConductorAction,
 } from "./_handoff-contract.mjs";
+import { listOpenPrs } from "./_loop-pr-aggregation.mjs";
+export { listOpenPrs };
 const USAGE = `Usage: run-conductor-cycle.mjs --repo <owner/name>
 Poll all open PRs, detect state, and output an ordered action queue.`.trim();
-const OPEN_PR_LIST_LIMIT = 1000;
 export const CHECKPOINT_ACTION_TO_CONDUCTOR_ACTION = Object.freeze({
   [PR_CHECKPOINT_ACTION.ADDRESS_REVIEW_FEEDBACK]: "fix_threads",
   [PR_CHECKPOINT_ACTION.REPLY_RESOLVE_REVIEW_THREADS]: "fix_threads",
@@ -90,43 +90,6 @@ export function parseCliArgs(argv) {
   }
   return options;
 }
-export async function listOpenPrs({ repo }, { env, ghCommand }) {
-  const result = await runChild(
-    ghCommand,
-    [
-      "pr",
-      "list",
-      "--repo",
-      repo,
-      "--state",
-      "open",
-      "--limit",
-      String(OPEN_PR_LIST_LIMIT),
-      "--json",
-      "number,title,url,isDraft,headRefName,author",
-    ],
-    env,
-  );
-  if (result.code !== 0) {
-    const detail = result.stderr.trim() || `exit code ${result.code}`;
-    throw new Error(`gh command failed: ${detail}`);
-  }
-  const payload = parseJsonText(result.stdout);
-  if (!Array.isArray(payload)) {
-    throw new Error("Invalid gh pr list payload: expected an array");
-  }
-  return payload
-    .map((pr) => ({
-      number: Number.isInteger(pr?.number) ? pr.number : null,
-      title: typeof pr?.title === "string" ? pr.title : "",
-      url: typeof pr?.url === "string" ? pr.url : null,
-      isDraft: Boolean(pr?.isDraft),
-      headRefName: typeof pr?.headRefName === "string" ? pr.headRefName : null,
-      authorLogin: typeof pr?.author?.login === "string" ? pr.author.login : null,
-    }))
-    .filter((pr) => pr.number !== null)
-    .sort((left, right) => left.number - right.number);
-}
 export async function detectPrState(
   pr,
   {

package/skills/docs/merge-preconditions.md

@@ -10,6 +10,21 @@ Canonical owner for merge preconditions across all workflow families.
 4. ✅ All review threads resolved
 5. ✅ Explicit merge authorization from operator
 6. ✅ PR body contains `Closes #N` or `Fixes #N`
+7. ✅ PR **title** free of merge-blocking markers — `WIP`, `[WIP]`, `DRAFT`, `DO NOT MERGE`, `🚧` (case-insensitive)
+
+## Title markers
+
+The PR title is a contract surface, so a merge-blocking marker in the title is enforced
+deterministically (`findBlockingTitleMarkers` in `@dev-loops/core/loop/pr-title-markers`), not
+just reviewed:
+
+- At the **draft → ready-for-review** transition: `ready-for-review` refuses `gh pr ready` while the
+  title carries a marker.
+- At the **pre-approval gate boundary and final approval** (for non-draft PRs): the gate coordinator
+  returns `title_marker_blocked` so a PR un-drafted externally still cannot enter pre-approval or
+  reach merge-ready with a marked title.
+
+A marker is allowed only while the PR is still in draft; it must be removed before the PR leaves draft.
 
 ## Merge authorization
 

package/skills/docs/pr-lifecycle-contract.md

@@ -44,6 +44,7 @@ It does not redefine helper transport mechanics, reviewer-loop internals, conduc
 - Draft existence alone is **not** draft-gate readiness.
 - A PR must clear the draft-stage gate for the current head before Copilot review may be requested.
 - Ready -> draft resets the lifecycle back into draft-stage gating.
+- A merge-blocking marker in the PR **title** (`WIP`/`[WIP]`/`DRAFT`/`DO NOT MERGE`/`🚧`, case-insensitive) blocks the draft -> ready transition and, for non-draft PRs, blocks entry to the pre-approval gate and final approval (`title_marker_blocked`). Markers are permitted only while the PR remains draft. See [Merge preconditions](merge-preconditions.md#title-markers).
 - Human approval / merge are explicit external waits, not hidden remediation states.
 
 ## Two required local gates