dev-loops 0.2.5 → 0.2.7

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

@@ -1,6 +1,6 @@
 {
   "name": "dev-loops",
-  "version": "0.2.5",
+  "version": "0.2.7",
   "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/agents/dev-loop.md

@@ -21,7 +21,8 @@ The envelope is the primary handoff artifact — it is derived from resolver out
 - `acceptance` — self-validation criteria for declaring completion
 
 **Construction sequence:**
-1. Run the deterministic startup resolver to produce the authoritative state bundle: `npx dev-loops loop startup --issue <n>` for issues, or `npx dev-loops loop startup --pr <n>` for PRs.
+
+1. Run the deterministic startup resolver to produce the authoritative state bundle: `npx dev-loops@0.2.7 loop startup --issue <n>` for issues, or `npx dev-loops@0.2.7 loop startup --pr <n>` for PRs.
 2. Pass the resolver output, resolved settings (merged from `.devloops` and `.pi/dev-loop/defaults.yaml`), and current gate state to `buildDevLoopHandoffEnvelope()`.
 3. **Validate the envelope** with `validateHandoffEnvelope()` before consuming any field. If validation returns `ok: false`, reject the handoff with the structured error — do not load requiredReads, do not execute nextAction, do not delegate.
 4. Read the envelope as the first artifact.

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/dev-loop/SKILL.md

@@ -25,7 +25,7 @@ Required installed runtime contract docs are shared bundled copies under `../doc
 
 > Under the Claude Code harness the dev-loop runs as a single agent: run these steps directly — no read-only boundary and no separate async-subagent dispatch. See [Main Agent Contract](../docs/main-agent-contract.md).
 
-Resolve authoritative state via the startup resolver (`npx dev-loops loop startup --issue <n>` for issues, `npx dev-loops loop startup --pr <n>` for PRs), then immediately build the handoff envelope via `npx dev-loops loop build-envelope --input <resolver-output.json>`. The envelope determines `requiredReads`, `nextAction`, `stopRules`, and `acceptance` — load only those files, execute only that bounded task. It is the first handoff artifact consumed before loading any route pack. See [Workflow Handoff Contract](../docs/workflow-handoff-contract.md) for the derivation contract.
+Resolve authoritative state via the startup resolver (`npx dev-loops@0.2.7 loop startup --issue <n>` for issues, `npx dev-loops@0.2.7 loop startup --pr <n>` for PRs), then immediately build the handoff envelope via `npx dev-loops@0.2.7 loop build-envelope --input <resolver-output.json>`. The envelope determines `requiredReads`, `nextAction`, `stopRules`, and `acceptance` — load only those files, execute only that bounded task. It is the first handoff artifact consumed before loading any route pack. See [Workflow Handoff Contract](../docs/workflow-handoff-contract.md) for the derivation contract.
 
 **Retrospective checkpoint gate:** the resolver reads `.pi/dev-loop-retrospective-checkpoint.json` and injects the state. When the checkpoint is `missing` and the repo config `workflow.requireRetrospective` (set via `.devloops` at repo root) is `true`, the resolver returns `needs_reconcile`. Complete or explicitly skip the retrospective before starting.
 
@@ -99,10 +99,10 @@ When `@dev-loops/core` is available again, switch back to the full helper. The f
 
 ## Read-only info shortcut
 
-Info/handoff requests can be served directly via `npx dev-loops loop info` (read-only; no full dev-loop run required):
-- `npx dev-loops loop info --issue <n>` — human-readable issue state summary (strategy, route, linked PR, next action)
-- `npx dev-loops loop info --pr <n>` — human-readable PR state summary (branch, CI, threads, rounds, action)
-- `npx dev-loops loop info --issue <n> --json` — machine-readable JSON output
+Info/handoff requests can be served directly via `npx dev-loops@0.2.7 loop info` (read-only; no full dev-loop run required):
+- `npx dev-loops@0.2.7 loop info --issue <n>` — human-readable issue state summary (strategy, route, linked PR, next action)
+- `npx dev-loops@0.2.7 loop info --pr <n>` — human-readable PR state summary (branch, CI, threads, rounds, action)
+- `npx dev-loops@0.2.7 loop info --issue <n> --json` — machine-readable JSON output
 
 ## Guard rules
 

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,58 @@
 
 All notable changes to this project will be documented in this file.
 
+## 0.2.7
+
+### Fixed
+
+- **Deterministic, harness-aware dev-loops CLI invocation** (#801, #833). Pi runtime skills/agents now invoke the package-local `node <dev-loops-package-root>/cli/index.mjs`; the generated Claude tree pins `npx dev-loops@<version>` (version injected at generation time) so the plugin and CLI no longer drift.
+- **Round-cap Copilot-gate deadlock resolved** (#848). At the round cap with clean threads + green CI, the loop routes to a clean fallback instead of dead-ending at `waiting_for_copilot_review` when a lingering reviewer assignment / post-cap push leaves the head unreviewed. The pre-approval gate still reviews any post-cap head.
+- **Draft-gate ordering after external un-draft** (#836). Verified + regression-guarded: a non-draft PR without clean `draft_gate` evidence is routed to `reconcile_draft_gate` and cannot merge; the relayed-authorization deadlock is moot under the single-agent Claude harness.
+
+### Added
+
+- **Projects board reorder + Done-cleanup CLI** (#789). `project reorder move-to-top|move-after|order` (with `--dry-run`, diff-friendly output, cross-column fail-closed) and `project archive-done [--older-than]`.
+- **Loop-state-driven board status sync** (#793). Board Status column is derived from the loop state via a pure, config-driven mapping (`queue.statusColumns` / `queue.stateColumnMap`), opt-in, fail-open, reverse-safe.
+
+### Changed
+
+- **Arg parsing migrated to `node:util.parseArgs`** (#808). All hand-rolled `while/shift` parsers (49 scripts/modules + 3 core files) now use `parseArgs` via shared adapters, with CLI contracts preserved. (Index-based parsers tracked in #857.)
+
+## 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