@dev-loops/core 1.0.2-slim.0 → 1.0.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dev-loops/core",
-  "version": "1.0.2-slim.0",
+  "version": "1.0.3",
   "type": "module",
   "engines": {
     "node": ">=24"
@@ -22,24 +22,31 @@
     "./debt/signal": "./src/debt/debt-signal.mjs",
     "./github/copilot-helpers": "./src/github/copilot-helpers.mjs",
     "./github/comment-id-guard": "./src/github/comment-id-guard.mjs",
+    "./github/closing-ref-guard": "./src/github/closing-ref-guard.mjs",
     "./github/gh": "./src/github/gh.mjs",
     "./github/issue-ops": "./src/github/issue-ops.mjs",
     "./github/ownership-helpers": "./src/github/ownership-helpers.mjs",
     "./github/repo-slug": "./src/github/repo-slug.mjs",
     "./github/review-threads": "./src/github/review-threads.mjs",
+    "./github/test-mode-write-guard": "./src/github/test-mode-write-guard.mjs",
     "./loop/async-start-contract": "./src/loop/async-start-contract.mjs",
     "./loop/agent-stall": "./src/loop/agent-stall.mjs",
     "./loop/bash-command-classify": "./src/loop/bash-command-classify.mjs",
+    "./loop/child-launch-bound": "./src/loop/child-launch-bound.mjs",
+    "./loop/reviewer-unit-bound": "./src/loop/reviewer-unit-bound.mjs",
     "./loop/conductor-routing": "./src/loop/conductor-routing.mjs",
     "./loop/copilot-ci-status": "./src/loop/copilot-ci-status.mjs",
     "./loop/copilot-loop-iterations": "./src/loop/copilot-loop-iterations.mjs",
     "./loop/copilot-loop-state": "./src/loop/copilot-loop-state.mjs",
+    "./loop/finding-cluster": "./src/loop/finding-cluster.mjs",
+    "./loop/fixer-disposition": "./src/loop/fixer-disposition.mjs",
     "./loop/gate-carry-forward": "./src/loop/gate-carry-forward.mjs",
     "./loop/gate-evidence-reconcile": "./src/loop/gate-evidence-reconcile.mjs",
     "./loop/gate-fanin": "./src/loop/gate-fanin.mjs",
     "./loop/handoff-envelope": "./src/loop/handoff-envelope.mjs",
     "./loop/lifecycle-state": "./src/loop/lifecycle-state.mjs",
     "./loop/markdown-sections": "./src/loop/markdown-sections.mjs",
+    "./loop/merge-approval": "./src/loop/merge-approval.mjs",
     "./loop/issue-refinement-artifact": "./src/loop/issue-refinement-artifact.mjs",
     "./loop/phase-files": "./src/loop/phase-files.mjs",
     "./loop/policy-constants": "./src/loop/policy-constants.mjs",
@@ -62,9 +69,11 @@
     "./loop/queue-state": "./src/loop/queue-state.mjs",
     "./loop/size-budget-merge-gate": "./src/loop/size-budget-merge-gate.mjs",
     "./loop/cache-telemetry-evidence": "./src/loop/cache-telemetry-evidence.mjs",
+    "./loop/execution-record": "./src/loop/execution-record.mjs",
     "./loop/primer-evidence": "./src/loop/primer-evidence.mjs",
     "./loop/review-dispatch-plan": "./src/loop/review-dispatch-plan.mjs",
     "./loop/reviewer-loop-state": "./src/loop/reviewer-loop-state.mjs",
+    "./loop/role-budget-bound": "./src/loop/role-budget-bound.mjs",
     "./loop/run-context": "./src/loop/run-context.mjs",
     "./loop/run-inspection": "./src/loop/run-inspection.mjs",
     "./loop/run-post-merge-actions": "./src/loop/run-post-merge-actions.mjs",
@@ -74,6 +83,7 @@
     "./loop/steering": "./src/loop/steering.mjs",
     "./loop/timeout-policy": "./src/loop/timeout-policy.mjs",
     "./loop/tracker-pr-state": "./src/loop/tracker-pr-state.mjs",
+    "./loop/watcher-exclusivity": "./src/loop/watcher-exclusivity.mjs",
     "./loop/ui-e2e-scoping": "./src/loop/ui-e2e-scoping.mjs",
     "./loop/ui-review-provision": "./src/loop/ui-review-provision.mjs",
     "./loop/ui-review-drive": "./src/loop/ui-review-drive.mjs",

package/src/claude/asset-generation.mjs

@@ -114,6 +114,67 @@ export function rewriteGeneratedRepoDocLinks(body) {
   return String(body).replace(/(\]\(<?)(\.\.\/docs\/)/g, "$1../$2");
 }
 
+/**
+ * Name of the resolver launcher committed at `.claude/bin/dev-loops-run`. It self-locates a
+ * source checkout by walking up from `process.cwd()` (unconditional priority), else by walking
+ * up from the launcher's own real binary location, else falls back to the plugin's auto-installed
+ * `dev-loops` package, and hard-stops (never falls back to raw `gh`) when none resolve.
+ */
+export const WRAPPER_LAUNCHER = "dev-loops-run";
+
+/**
+ * CLI namespaces the routed `dev-loops <ns> <sub>` form recognizes — the real top-level keys of
+ * `SUBCOMMAND_ROUTES` in `cli/index.mjs` (locked by
+ * `test/contracts/claude-no-bare-invocation.test.mjs`'s recurrence guard, which reads those keys
+ * directly). `release` and `security` are NOT CLI namespaces (no such routes exist); `issue` and
+ * `inspect` are and were previously missing here, which left e.g. `dev-loops issue edit …` bare
+ * and unrouted in the generated tree.
+ */
+export const WRAPPER_NS = "gate|loop|pr|issue|queue|project|inspect|refine";
+
+/**
+ * Regex source (no flags) matching a bare `node scripts/<dir>/…/<file>.mjs` invocation, at ANY
+ * subdirectory depth (one-or-more `dir/` segments), not just one subdirectory level, so a
+ * nested wrapper is caught too. The `node`→`scripts/` gap matches ANY whitespace (`\s+`),
+ * including a source line-wrap (`node` at a line end, `scripts/…mjs` beginning the next), so a
+ * prose-wrapped invocation is routed and the guard test that shares this source catches it too —
+ * a single-space-only pattern silently left wrapped invocations bare and passed the guard falsely.
+ * The `.mjs` path anchor keeps false positives impossible. Capture group 1 is the matched
+ * `scripts/…mjs` path. Exported so the no-bare-invocation guard test can build the identical regex
+ * rather than re-deriving it (single source of truth).
+ */
+export const BARE_NODE_SCRIPTS_SOURCE = String.raw`\bnode\s+(scripts\/(?:[a-z0-9-]+\/)+[A-Za-z0-9._-]+\.mjs)`;
+
+/**
+ * Regex source (no flags) matching a bare, unrouted `dev-loops <namespace> <sub>` invocation.
+ * Requires an immediate lowercase-starting subcommand (lookahead) so prose (`dev-loops gate.`,
+ * `dev-loops gate — …`, `` `dev-loops queue` ``) and the already-pinned `npx dev-loops@<version>`
+ * CLI form never match. Exported so the no-bare-invocation guard test can build the identical
+ * regex from the same `WRAPPER_NS` rather than re-deriving it (single source of truth).
+ */
+export const BARE_DEV_LOOPS_NS_SOURCE = String.raw`\bdev-loops (${WRAPPER_NS}) (?=[a-z])`;
+
+/**
+ * Route real wrapper invocations in a generated body through the resolver launcher so a
+ * plugin-only install (no `scripts/`, no `node_modules`) still resolves every wrapper.
+ * Two disjoint forms; args are preserved byte-for-byte:
+ *   node scripts/<dir>/<file>.mjs …  → <launcher> scripts/<dir>/<file>.mjs …
+ *   dev-loops <namespace> <sub> …    → <launcher> cli/index.mjs <namespace> <sub> …
+ * The namespace form requires an immediate lowercase-starting subcommand (lookahead), so prose
+ * (`dev-loops gate.`, `dev-loops gate — …`, `` `dev-loops queue` ``) and the already-pinned
+ * `npx dev-loops@<version>` CLI form are never touched. Idempotent: the rewritten output never
+ * re-matches (the launcher name is followed by a path/`cli/index.mjs`, not `scripts/` or a bare
+ * namespace token).
+ * @param {string} body
+ * @param {string} [launcher]
+ * @returns {string}
+ */
+export function rewriteWrapperInvocation(body, launcher = WRAPPER_LAUNCHER) {
+  return String(body)
+    .replace(new RegExp(BARE_NODE_SCRIPTS_SOURCE, "g"), `${launcher} $1`)
+    .replace(new RegExp(BARE_DEV_LOOPS_NS_SOURCE, "g"), `${launcher} cli/index.mjs $1 `);
+}
+
 /**
  * Map a single Pi tool name to its Claude tool name(s).
  * @param {string} name
@@ -184,7 +245,7 @@ function normalizeToolList(value) {
  */
 export function transformAgent({ source, raw, version = "latest", config = {} }) {
   const { frontmatter, body: rawBody } = splitFrontmatter(raw, source);
-  const body = rewriteGeneratedRepoDocLinks(rewriteCliInvocation(stripPiOnlyBlocks(rawBody), version));
+  const body = rewriteWrapperInvocation(rewriteGeneratedRepoDocLinks(rewriteCliInvocation(stripPiOnlyBlocks(rawBody), version)));
   const tools = mapTools(normalizeToolList(frontmatter.tools));
   const model = resolveRoleModel(config, { role: String(frontmatter.name ?? ""), harness: "claude" });
 
@@ -219,7 +280,7 @@ export function transformAgent({ source, raw, version = "latest", config = {} })
  */
 export function transformCommand({ source, raw, version = "latest" }) {
   const { frontmatter, body: rawBody } = splitFrontmatter(raw, source);
-  const body = rewriteGeneratedRepoDocLinks(rewriteCliInvocation(stripPiOnlyBlocks(rawBody), version));
+  const body = rewriteWrapperInvocation(rewriteGeneratedRepoDocLinks(rewriteCliInvocation(stripPiOnlyBlocks(rawBody), version)));
 
   const lines = ["---"];
   if (frontmatter.description != null) {
@@ -241,7 +302,7 @@ export function transformCommand({ source, raw, version = "latest" }) {
  */
 export function transformSkill({ source, raw, version = "latest" }) {
   const { frontmatter, body: rawBody } = splitFrontmatter(raw, source);
-  const body = rewriteCliInvocation(stripPiOnlyBlocks(rawBody), version);
+  const body = rewriteWrapperInvocation(rewriteCliInvocation(stripPiOnlyBlocks(rawBody), version));
   const tools = mapTools(normalizeToolList(frontmatter["allowed-tools"]));
 
   const lines = ["---"];

package/src/claude/hook-decisions.mjs

@@ -12,14 +12,15 @@
 import { resolveRunId } from "../loop/run-context.mjs";
 import { isUnderWorktreePath } from "../loop/worktree-guard.mjs";
 import {
+  deriveInManagedRepo,
   commandContainsGhPrReady,
   commandContainsGhPrMerge,
   commandContainsGhPrCreate,
   extractPrNumberFromGhPrReadyAnywhere,
-  extractRepoFlagFromGhPrReadyAnywhere,
   extractPrNumberFromGhPrMergeAnywhere,
-  extractRepoFlagFromGhPrMergeAnywhere,
   extractRepoFlagsFromGhPrCreateSegments,
+  extractRepoFlagsFromGhPrMergeSegments,
+  extractRepoFlagsFromGhPrReadySegments,
   commandContainsRawExternalWrite,
   extractRepoFlagsFromExternalWriteSegments,
   commandContainsGitStash,
@@ -31,7 +32,6 @@ import {
   commandContainsCopilotSummonComment,
   commandContainsDetachedWaitTool,
   commandContainsInlineInterpreter,
-  TARGET_REPO_SLUG,
 } from "../loop/bash-command-classify.mjs";
 
 /**
@@ -79,6 +79,11 @@ export const DEV_LOOP_AGENT_TYPE = "dev-loop";
  * @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 {string|null} [params.managedRepoSlug] - Resolved owner/name of the dev-loops-managed
+ *   repo (the repo `inManagedContext` refers to), or null when the identity can't be resolved.
+ * @param {boolean} [params.inManagedContext] - Whether the current repo is dev-loops-managed (a
+ *   `.devloops` config exists at its root). Replaces the old hardcoded-slug `TARGET_REPO_SLUG`
+ *   comparison so the guard suite applies in any managed consumer repo, not only mfittko/dev-loops.
  * @param {boolean} [params.gatePassed] - Whether the relevant gate evidence exists for the PR.
  * @param {string|null} [params.gateError] - Error detail when the gate guard could not run.
  * @param {string|null} [params.agentType] - Claude `agent_type` from the hook payload; non-null
@@ -89,19 +94,33 @@ export const DEV_LOOP_AGENT_TYPE = "dev-loop";
  *   subagent-only deny would enforce nothing.
  * @returns {HookDecision}
  */
-export function decideBashGate({ command, repoSlug = null, gatePassed = false, gateError = null, agentType = null, humanMergeOnly = false }) {
+export function decideBashGate({
+  command,
+  repoSlug = null,
+  managedRepoSlug = null,
+  inManagedContext = false,
+  gatePassed = false,
+  gateError = null,
+  agentType = null,
+  humanMergeOnly = false,
+}) {
   if (typeof command !== "string") {
     return ALLOW;
   }
   // Normalize (trim + case-fold) so a divergent slug (surrounding whitespace, casing) does not
-  // silently fail OPEN and disable every guard that depends on inTargetRepo.
-  const inTargetRepo = (repoSlug ?? "").trim().toLowerCase() === TARGET_REPO_SLUG.trim().toLowerCase();
+  // silently fail OPEN. A repo is dev-loops-managed when inManagedContext is true (a .devloops
+  // config exists at its root); the managed slug is that repo's resolved identity, which may be
+  // unresolvable (null). FAIL CLOSED: inside a managed context whose identity can't be resolved,
+  // every guard below still applies (inManagedRepo stays true) rather than silently allowing
+  // everything — an unresolvable identity must never disable the guard suite.
+  const managedSlug = (managedRepoSlug ?? "").trim().toLowerCase() || null;
+  const inManagedRepo = deriveInManagedRepo({ inManagedContext, managedRepoSlug, repoSlug });
 
   // OPS-NO-INLINE-INTERPRETER: inline interpreters (`node -e`/`--eval`/`-p`, `python3 -c`,
   // heredocs fed to node/python) are barred actor-independently on the target repo — the rule bars
   // "Coordinator and agent flows"; sanctioned output parsing uses `--jq`/`--silent`, never an
   // inline interpreter.
-  if (inTargetRepo && commandContainsInlineInterpreter(command)) {
+  if (inManagedRepo && commandContainsInlineInterpreter(command)) {
     return {
       decision: "deny",
       reason:
@@ -116,7 +135,7 @@ export function decideBashGate({ command, repoSlug = null, gatePassed = false, g
   // form identifies the target repo; the bare relative form (`gh api issues/5/sub_issues`) resolves
   // against the cwd repo, so it is in scope only when running in the target repo (mirrors the
   // explicit-`--repo`/cwd-target posture).
-  if (inTargetRepo && commandContainsSubIssueAdHocBypass(command)) {
+  if (inManagedRepo && commandContainsSubIssueAdHocBypass(command, managedSlug)) {
     return {
       decision: "deny",
       reason:
@@ -129,7 +148,7 @@ export function decideBashGate({ command, repoSlug = null, gatePassed = false, g
   // to pulls/<n>/comments/<m>/replies, or a `gh api graphql` resolveReviewThread mutation (the Rest
   // path names the target repo; the graphql form has no path-host repo, so it is scoped to the cwd
   // repo). Actor-independent: reply through reply-resolve-review-thread(s).mjs.
-  if (inTargetRepo && (commandContainsReplyResolveBypass(command) || commandContainsGraphqlResolveReviewThread(command))) {
+  if (inManagedRepo && (commandContainsReplyResolveBypass(command, managedSlug) || commandContainsGraphqlResolveReviewThread(command))) {
     return {
       decision: "deny",
       reason:
@@ -142,7 +161,7 @@ export function decideBashGate({ command, repoSlug = null, gatePassed = false, g
   // COPILOT-FOLLOWUP-REQUEST-HELPER-ONLY: ad-hoc Copilot review requests — raw `gh api` writes
   // to pulls/<n>/requested_reviewers, or a bare `/copilot` / `/copilot re-review` comment summon on the
   // target repo. Actor-independent: request Copilot via scripts/github/request-copilot-review.mjs.
-  if (inTargetRepo && (commandContainsCopilotRequestBypass(command) || commandContainsCopilotSummonComment(command))) {
+  if (inManagedRepo && (commandContainsCopilotRequestBypass(command, managedSlug) || commandContainsCopilotSummonComment(command))) {
     return {
       decision: "deny",
       reason:
@@ -156,7 +175,7 @@ export function decideBashGate({ command, repoSlug = null, gatePassed = false, g
   // `.git` directory — a stash from one worktree can pop into another's. Block it outright on the
   // target repo; see skills/docs/worktree-guidance.md#never-git-stash-in-a-shared-git-layout for the
   // stash-free alternative (git diff / a patch file / a scratch checkout).
-  if (commandContainsGitStash(command) && inTargetRepo) {
+  if (commandContainsGitStash(command) && inManagedRepo) {
     return {
       decision: "deny",
       reason:
@@ -169,14 +188,19 @@ export function decideBashGate({ command, repoSlug = null, gatePassed = false, g
   // `gh issue edit`/`gh pr comment` on the target repo from a subagent, so external writes flow through the
   // sanctioned node wrappers. The main-agent/operator path (agentType null) is unaffected.
   if (typeof agentType === "string" && commandContainsRawExternalWrite(command)) {
-    const cwdTargets = (repoSlug ?? "").toLowerCase() === TARGET_REPO_SLUG.toLowerCase();
+    // The cwd repo IS the managed/target repo exactly when inManagedRepo.
+    const cwdTargets = inManagedRepo;
     // Scope PER segment, mirroring the `gh pr create` block: in scope when no explicit --repo and
-    // cwd is the target, or an explicit --repo/-R equals the target. An explicit non-target --repo
-    // passes through. DENY if ANY external-write segment is in scope.
+    // cwd is the target, or an explicit --repo/-R equals the managed slug. An explicit repo that is
+    // PROVEN foreign (managedSlug resolves and differs) passes through; otherwise (managedSlug
+    // unresolvable) we cannot prove the explicit repo is foreign, so a managed context fails closed
+    // (in scope). DENY if ANY external-write segment is in scope.
     const anyWriteInScope = extractRepoFlagsFromExternalWriteSegments(command).some((seg) =>
       seg.explicitRepo == null
         ? cwdTargets
-        : seg.explicitRepo.toLowerCase() === TARGET_REPO_SLUG.toLowerCase(),
+        : managedSlug !== null
+          ? seg.explicitRepo.toLowerCase() === managedSlug
+          : inManagedContext,
     );
     if (anyWriteInScope) {
       return {
@@ -202,7 +226,7 @@ export function decideBashGate({ command, repoSlug = null, gatePassed = false, g
   // refused actor-independently — the main agent is the actor that performs GitHub writes, so only an
   // actor-independent deny enforces the human-merge invariant (an agent-scoped deny would enforce
   // nothing on the main-agent write path).
-  if (humanMergeOnly && isMerge && inTargetRepo) {
+  if (humanMergeOnly && isMerge && inManagedRepo) {
     return {
       decision: "deny",
       reason:
@@ -217,7 +241,7 @@ export function decideBashGate({ command, repoSlug = null, gatePassed = false, g
     // rule is classified `agent` (behavioral guidance for the dev-loop driving agent); the main
     // agent/operator retains manual wait tooling. The main agent's own sanctioned wait path is still
     // the deterministic tools.
-    if (typeof agentType === "string" && inTargetRepo && commandContainsDetachedWaitTool(command)) {
+    if (typeof agentType === "string" && inManagedRepo && commandContainsDetachedWaitTool(command)) {
       return {
         decision: "deny",
         reason:
@@ -234,16 +258,21 @@ export function decideBashGate({ command, repoSlug = null, gatePassed = false, g
   // exists yet): PR creation must flow through the canonical wrapper, which always drafts and
   // self-assigns. This closes the draft-first hole where raw `gh pr create` opens a ready PR.
   if (isCreate) {
-    const cwdTargets = (repoSlug ?? "").toLowerCase() === TARGET_REPO_SLUG.toLowerCase();
+    // The cwd repo IS the managed/target repo exactly when inManagedRepo.
+    const cwdTargets = inManagedRepo;
     // Evaluate scope PER create segment, not just the first: a create is in scope when it
     // explicitly targets the repo, or (with no explicit --repo) the cwd is the repo. An explicit
-    // `--repo <target>` is denied regardless of cwd. DENY if ANY create segment is in
-    // scope — otherwise a leading out-of-scope create (`gh pr create --repo other/repo`) would
-    // short-circuit and shield a later in-scope raw create (`&& gh pr create --fill`).
+    // `--repo <target>` is denied regardless of cwd — unless it is PROVEN foreign (managedSlug
+    // resolves and differs); when managedSlug is unresolvable we cannot prove foreignness, so a
+    // managed context fails closed (in scope). DENY if ANY create segment is in scope — otherwise a
+    // leading out-of-scope create (`gh pr create --repo other/repo`) would short-circuit and shield
+    // a later in-scope raw create (`&& gh pr create --fill`).
     const anyCreateInScope = extractRepoFlagsFromGhPrCreateSegments(command).some((seg) =>
       seg.explicitRepo == null
         ? cwdTargets
-        : seg.explicitRepo.toLowerCase() === TARGET_REPO_SLUG.toLowerCase(),
+        : managedSlug !== null
+          ? seg.explicitRepo.toLowerCase() === managedSlug
+          : inManagedContext,
     );
     if (anyCreateInScope) {
       return {
@@ -265,15 +294,28 @@ export function decideBashGate({ command, repoSlug = null, gatePassed = false, g
   // When both verbs appear in a compound command, apply the stricter merge gate — if it passes,
   // the draft_gate (a subset of the pre-merge evidence check) is also satisfied.
   const verb = isMerge ? "gh pr merge" : "gh pr ready";
-  // An explicit `--repo other/repo` that is not the target → not our concern, pass through.
-  const explicitRepo = isMerge
-    ? extractRepoFlagFromGhPrMergeAnywhere(command)
-    : extractRepoFlagFromGhPrReadyAnywhere(command);
-  if (explicitRepo && explicitRepo.toLowerCase() !== TARGET_REPO_SLUG.toLowerCase()) {
+  // Pass through only when EVERY gated verb segment is PROVEN foreign (explicit repo, managed slug
+  // resolves, and demonstrably differs). A segment with no explicit repo, or an unresolvable managed
+  // slug, is NOT proven foreign — fail closed (preserves the fail-closed default). Mirrors the
+  // per-segment `.some()` scoping on the create/external-write paths: a proven-foreign FIRST segment
+  // must not shield a later managed segment (`gh pr merge --repo other/x 1 && gh pr merge 2`).
+  const gatedVerbSegments = [
+    ...(isMerge ? extractRepoFlagsFromGhPrMergeSegments(command) : []),
+    ...(isReady ? extractRepoFlagsFromGhPrReadySegments(command) : []),
+  ];
+  const allSegmentsProvenForeign =
+    gatedVerbSegments.length > 0 &&
+    gatedVerbSegments.every(
+      (seg) =>
+        seg.explicitRepo != null &&
+        managedSlug !== null &&
+        seg.explicitRepo.toLowerCase() !== managedSlug,
+    );
+  if (allSegmentsProvenForeign) {
     return ALLOW;
   }
-  // Only gate within the target repo (case-insensitive — callers may pass an un-lowercased slug).
-  if ((repoSlug ?? "").toLowerCase() !== TARGET_REPO_SLUG.toLowerCase()) {
+  // Only gate within the managed repo.
+  if (!inManagedRepo) {
     return ALLOW;
   }
 
@@ -287,31 +329,38 @@ export function decideBashGate({ command, repoSlug = null, gatePassed = false, g
     };
   }
 
-  if (gateError) {
-    const which = isMerge ? "pre-merge gate" : "draft-gate";
+  // Raw `gh pr merge` is FORBIDDEN outright (RAW-GH-PR-MERGE-BYPASS): the only
+  // sanctioned merge path is the wrapper, which enforces the mandatory approver,
+  // merge class, and fresh-approval checks a bare evidence gate cannot. A
+  // gate-passed raw merge would bypass all of those, so this denies
+  // unconditionally (not only when evidence is missing) and points to the wrapper.
+  // The wrapper's own internal `gh pr merge` is a child_process spawn, never a
+  // Bash tool call, so it is never seen here.
+  if (isMerge) {
+    // This hook evaluates PreToolUse — BEFORE the Bash tool call runs. A compound command that
+    // writes gate evidence (findings-log ledger, checkpoint verdict) and merges in the same call
+    // is blocked here with the write never having executed. Hint the split when the command
+    // carries an evidence-writing invocation alongside the merge.
+    const alsoWritesEvidence = commandContainsEvidenceWrite(command);
     return {
       decision: "deny",
-      reason: `${verb} blocked: ${which} evidence check failed (${gateError}).`,
+      reason:
+        `gh pr merge is forbidden: route the merge through the sanctioned wrapper \`node scripts/github/merge-pr.mjs --repo <owner/name> --pr ${prNumber} --human-approved-by <login>\`, which runs the full precondition set fail-closed (mandatory approver, merge class, fresh approval) — a raw \`gh pr merge\` bypasses those (RAW-GH-PR-MERGE-BYPASS).` +
+        (gateError ? ` (pre-merge gate evidence check also failed: ${gateError})` : "") +
+        (alsoWritesEvidence
+          ? " This command also writes gate evidence, but hooks evaluate before the command runs — never chain an evidence write with the merge."
+          : ""),
     };
   }
 
+  // `gh pr ready` keeps its gate-conditional behavior.
+  if (gateError) {
+    return {
+      decision: "deny",
+      reason: `${verb} blocked: draft-gate evidence check failed (${gateError}).`,
+    };
+  }
   if (!gatePassed) {
-    if (isMerge) {
-      // This hook evaluates PreToolUse — BEFORE the Bash tool call runs. A compound command that
-      // writes gate evidence (findings-log ledger, checkpoint verdict) and merges in the same call
-      // is blocked here with the write never having executed, which looks like the evidence
-      // "vanished". Hint the split when the command carries an evidence-writing invocation
-      // alongside the merge, so the failure is self-explaining instead of looking like data loss.
-      const alsoWritesEvidence = commandContainsEvidenceWrite(command);
-      return {
-        decision: "deny",
-        reason:
-          `gh pr merge blocked: missing pre-merge gate evidence for PR #${prNumber} (need clean current-head draft_gate + pre_approval_gate; inline verdicts are not accepted). Run the dev-loop gates instead of merging directly.` +
-          (alsoWritesEvidence
-            ? " This command also writes gate evidence, but hooks evaluate before the command runs — write the evidence in a separate call, then merge alone."
-            : ""),
-      };
-    }
     return {
       decision: "deny",
       reason: `gh pr ready blocked: no visible clean draft_gate checkpoint verdict comment found for PR #${prNumber}.`,