@dev-loops/core 0.6.0 → 0.7.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dev-loops/core",
-  "version": "0.6.0",
+  "version": "0.7.1",
   "type": "module",
   "engines": {
     "node": ">=24"
@@ -16,12 +16,9 @@
     "./claude/hook-decisions": "./src/claude/hook-decisions.mjs",
     "./config": "./src/config/config.mjs",
     "./debt/cluster": "./src/debt/cluster.mjs",
-    "./debt/finding": "./src/debt/debt-finding.mjs",
     "./debt/remediation-to-issue": "./src/debt/remediation-to-issue.mjs",
-    "./debt/score": "./src/debt/score.mjs",
     "./debt/shape": "./src/debt/shape.mjs",
     "./debt/signal": "./src/debt/debt-signal.mjs",
-    "./debt/signals": "./src/debt/deep-persona-signals.mjs",
     "./github/copilot-helpers": "./src/github/copilot-helpers.mjs",
     "./github/repo-slug": "./src/github/repo-slug.mjs",
     "./github/review-threads": "./src/github/review-threads.mjs",
@@ -43,6 +40,7 @@
     "./loop/pr-gate-coordination": "./src/loop/pr-gate-coordination.mjs",
     "./loop/pr-title-markers": "./src/loop/pr-title-markers.mjs",
     "./loop/public-dev-loop-routing": "./src/loop/public-dev-loop-routing.mjs",
+    "./loop/queue-board-ordering": "./src/loop/queue-board-ordering.mjs",
     "./loop/queue-board-sync": "./src/loop/queue-board-sync.mjs",
     "./loop/queue-driver": "./src/loop/queue-driver.mjs",
     "./loop/queue-membership": "./src/loop/queue-membership.mjs",
@@ -57,7 +55,6 @@
     "./loop/timeout-policy": "./src/loop/timeout-policy.mjs",
     "./loop/tracker-pr-state": "./src/loop/tracker-pr-state.mjs",
     "./loop/ui-e2e-scoping": "./src/loop/ui-e2e-scoping.mjs",
-    "./refinement/ac-dod-matrix": "./src/refinement/ac-dod-matrix.mjs",
     "./harness": "./src/harness/index.mjs",
     "./loop/worktree-guard": "./src/loop/worktree-guard.mjs",
     "./loop/tracker-first-loop-state": "./src/loop/tracker-first-loop-state.mjs"
@@ -65,8 +62,7 @@
   "bin": {
     "dev-loops-log-bash-exit-1": "./bin/log-bash-exit-1.mjs",
     "dev-loops-ensure-phase-files": "./bin/ensure-phase-files.mjs",
-    "dev-loops-parse-review-threads": "./bin/parse-review-threads.mjs",
-    "dev-loops-capture-deep-persona-signals": "./bin/capture-deep-persona-signals.mjs"
+    "dev-loops-parse-review-threads": "./bin/parse-review-threads.mjs"
   },
   "files": [
     "src/**/*.mjs",

package/src/analysis/change-classifier.mjs

@@ -51,9 +51,11 @@ const CATEGORY_ANGLE_MAP = {
   [ChangeCategory.COMMENT_ONLY]: [
     "dry",
   ],
+  // Core review subset for any non-trivial code change. Peripheral lenses
+  // (ci-guard, link-check, packaging-runtime, config-drift, etc.) are pulled in
+  // only when the diff's other categories implicate them, not by logic alone.
   [ChangeCategory.LOGIC_CHANGE]: [
-    "correctness", "coverage", "kiss", "dry", "srp", "soc", "deep",
-    "ocp", "lsp", "isp", "dip", "yagni", "scope", "no-op", "determinism",
+    "scope", "correctness", "coverage", "determinism", "contract-surface",
   ],
 };
 
@@ -70,28 +72,43 @@ const ALWAYS_INCLUDE = new Set(["gate-evidence", "renderer-security", "pr-descri
 
 /**
  * @typedef {object} DynamicAngleResult
- * @property {string[]} recommendedAngles — angles to run
+ * @property {string[]} recommendedAngles — angles to run, limited to the
+ *   configured pool (subtractive result); in additive mode the caller
+ *   merges addedAngles on top to form the full effective run set
  * @property {string[]} skippedAngles — angles skipped with reasons
  * @property {Record<string, string>} reasons — why each angle was skipped
  * @property {boolean} fallbackToAll — true when ambiguous → all angles recommended
+ * @property {string[]} addedAngles — catalog angles added (additive mode only, see #1048)
+ * @property {Record<string, string>} addedReasons — why each added angle was added
  */
 
 /**
  * Resolve which gate angles to run based on detected change categories.
  *
- * When the diff is ambiguous (contains LOGIC_CHANGE or multiple mixed categories),
- * all configured angles are recommended (fallback-to-all).
+ * When the diff is ambiguous (no detected categories / analysis failure),
+ * all configured angles are recommended (fallback-to-all). A LOGIC_CHANGE
+ * diff resolves to its core review subset, not fallback-to-all.
+ *
+ * When `anglePool` is provided (additive mode, see #1048), catalog angles in
+ * the pool that the change categories recommend but that are not already in
+ * `configuredAngles` are additively selected and reported as `addedAngles`.
+ * When `anglePool` is omitted, additive mode is off and `addedAngles` is
+ * always empty.
  *
  * @param {object} options
  * @param {string[]} options.configuredAngles — all angles configured for this gate
  * @param {string[]} options.changeCategories — from diff analysis
  * @param {boolean} [options.ambiguous] — from diff analysis
+ * @param {string[]} [options.anglePool] — catalog of angles eligible for additive
+ *   selection (caller pre-filters this against excludeAngles); when undefined,
+ *   additive selection is disabled
  * @returns {DynamicAngleResult}
  */
 export function resolveDynamicAngles({
   configuredAngles,
   changeCategories,
   ambiguous = false,
+  anglePool,
 }) {
   // Fallback: ambiguous diff → all angles
   if (ambiguous) {
@@ -100,6 +117,8 @@ export function resolveDynamicAngles({
       skippedAngles: [],
       reasons: {},
       fallbackToAll: true,
+      addedAngles: [],
+      addedReasons: {},
     };
   }
 
@@ -110,21 +129,30 @@ export function resolveDynamicAngles({
       skippedAngles: [],
       reasons: {},
       fallbackToAll: true,
+      addedAngles: [],
+      addedReasons: {},
     };
   }
 
-  // Build recommended set from category union
+  // Build recommended set from category union, tracking the first trigger per angle
   const recommended = new Set();
+  const triggers = new Map();
   for (const cat of changeCategories) {
     const angles = CATEGORY_ANGLE_MAP[cat] ?? [];
     for (const angle of angles) {
       recommended.add(angle);
+      if (!triggers.has(angle)) {
+        triggers.set(angle, cat);
+      }
     }
   }
 
   // Always-include angles
   for (const angle of ALWAYS_INCLUDE) {
     recommended.add(angle);
+    if (!triggers.has(angle)) {
+      triggers.set(angle, "always-include");
+    }
   }
 
   // Filter to only angles that are configured
@@ -137,10 +165,26 @@ export function resolveDynamicAngles({
     reasons[angle] = `Skipped: detected categories (${changeCategories.join(", ") || "none"}) do not trigger this angle`;
   }
 
+  // Additive: pull in recommended catalog angles not already configured (#1048)
+  const configuredSet = new Set(configuredAngles);
+  const anglePoolSet = Array.isArray(anglePool) ? new Set(anglePool) : null;
+  const addedAngles = anglePoolSet
+    ? [...recommended].filter((a) => anglePoolSet.has(a) && !configuredSet.has(a))
+    : [];
+  const addedReasons = {};
+  for (const angle of addedAngles) {
+    const trigger = triggers.get(angle);
+    addedReasons[angle] = trigger === "always-include"
+      ? "Added: always-include lens not in the configured pool"
+      : `Added: triggered by change category ${trigger}`;
+  }
+
   return {
     recommendedAngles,
     skippedAngles,
     reasons,
     fallbackToAll: false,
+    addedAngles,
+    addedReasons,
   };
 }

package/src/analysis/diff-analyzer.mjs

@@ -199,13 +199,16 @@ export function analyzeT1(diffOutput, t0) {
     }
   }
 
-  // Build categories from T0 + hunk analysis
-  if (t0.renameOnly) categories.add("RENAME_ONLY");
-  if (t0.allDocs) categories.add("DOCS_ONLY");
-  if (t0.files.every((f) => classifyFile(f) === "config")) categories.add("CONFIG_ONLY");
-  if (t0.files.every((f) => classifyFile(f) === "test")) categories.add("TEST_ONLY");
-  if (t0.files.every((f) => classifyFile(f) === "ci")) categories.add("CI_ONLY");
+  // Build categories from T0 (shared with inferCategoriesFromT0) + hunk analysis.
+  for (const c of t0FileCategories(t0)) categories.add(c);
   if (hasLogicChange) categories.add("LOGIC_CHANGE");
+  // Mixed diffs never satisfy the exclusive `_ONLY` checks above (some files are
+  // code), so their peripheral surfaces would be dropped. In this hunk-level path
+  // (only reached for genuinely mixed diffs), also union each surface by PRESENCE
+  // so e.g. a code+workflow diff pulls ci-guard alongside the LOGIC_CHANGE core
+  // (AC: mixed logic+CI -> core union ci-guard). The pure single-surface path
+  // (inferCategoriesFromT0) keeps exclusive semantics.
+  for (const c of t0PresentSurfaceCategories(t0)) categories.add(c);
 
   // COMMENT_ONLY: hunkCount > 0 (real diff), has changed lines, all are non-logic,
   // and not a rename-only change
@@ -232,18 +235,64 @@ export function analyzeT1(diffOutput, t0) {
  */
 
 /**
- * Infer change categories from T0 analysis when T1 is not run.
+ * Categories derivable from T0 file classification alone (no hunk content).
+ * Shared by analyzeT1 (which adds hunk-derived LOGIC_CHANGE/COMMENT_ONLY on top)
+ * and inferCategoriesFromT0 (the no-T1 path). All checks are length-guarded so an
+ * empty file list yields no category.
  *
  * @param {T0Result} t0
  * @returns {string[]}
  */
-function inferCategoriesFromT0(t0) {
+function t0FileCategories(t0) {
+  if (t0.files.length === 0) return [];
   const categories = [];
   if (t0.renameOnly) categories.push("RENAME_ONLY");
   if (t0.allDocs) categories.push("DOCS_ONLY");
-  if (t0.files.length > 0 && t0.files.every((f) => classifyFile(f) === "config")) categories.push("CONFIG_ONLY");
-  if (t0.files.length > 0 && t0.files.every((f) => classifyFile(f) === "test")) categories.push("TEST_ONLY");
-  if (t0.files.length > 0 && t0.files.every((f) => classifyFile(f) === "ci")) categories.push("CI_ONLY");
+  if (t0.files.every((f) => classifyFile(f) === "config")) categories.push("CONFIG_ONLY");
+  if (t0.files.every((f) => classifyFile(f) === "test")) categories.push("TEST_ONLY");
+  if (t0.files.every((f) => classifyFile(f) === "ci")) categories.push("CI_ONLY");
+  return categories;
+}
+
+/**
+ * Surface categories present in a MIXED diff (at least one file of the surface),
+ * used only by the hunk-level path to union a mixed diff's peripheral lenses on
+ * top of LOGIC_CHANGE. Reuses the same category names / angle mappings as the
+ * exclusive path; presence (not exclusivity) is the correct trigger for a mixed
+ * diff. Renames are handled by the exclusive path, so they are excluded here.
+ *
+ * @param {T0Result} t0
+ * @returns {string[]}
+ */
+function t0PresentSurfaceCategories(t0) {
+  const categories = [];
+  const cats = new Set(t0.files.map(classifyFile));
+  if (cats.has("docs")) categories.push("DOCS_ONLY");
+  if (cats.has("config")) categories.push("CONFIG_ONLY");
+  if (cats.has("test")) categories.push("TEST_ONLY");
+  if (cats.has("ci")) categories.push("CI_ONLY");
+  return categories;
+}
+
+/**
+ * Infer change categories from T0 analysis when T1 (hunk-level) is not run.
+ * Reuses the shared T0 file-category derivation, then adds the pure-code
+ * LOGIC_CHANGE inference that the hunk-level path would otherwise supply.
+ *
+ * @param {T0Result} t0
+ * @returns {string[]}
+ */
+function inferCategoriesFromT0(t0) {
+  const categories = t0FileCategories(t0);
+  // Pure code-only change: a diff whose files all classify as code (and is not a
+  // rename) is a LOGIC_CHANGE. Without this, an all-code diff has a single file
+  // category (so analyzeDiff never runs hunk-level T1) and produces no category,
+  // which resolveDynamicAngles treats as "unclassifiable" → fallback-to-all. That
+  // regressed the primary case: a code-only PR must resolve to the LOGIC_CHANGE
+  // core review subset, not all angles.
+  if (!t0.renameOnly && t0.files.length > 0 && t0.files.every((f) => classifyFile(f) === "code")) {
+    categories.push("LOGIC_CHANGE");
+  }
   return categories;
 }
 
@@ -279,7 +328,14 @@ export function analyzeDiff({ nameStatusOutput, diffOutput }) {
     };
   }
 
-  const ambiguous = t0Ambiguous && (t1.changeCategories.length === 0 || t1.changeCategories.includes("LOGIC_CHANGE"));
+  // `ambiguous` flags one specific case: a diff T0 could not classify (mixed file
+  // categories, so t0Ambiguous) AND whose hunk analysis still produced no
+  // category. It is NOT the only fallback trigger — resolveDynamicAngles also
+  // falls back whenever changeCategories is empty (e.g. a single lone unknown/
+  // asset file yields no category yet is not t0Ambiguous). A mixed diff that
+  // yields a category (e.g. LOGIC_CHANGE) is classified and not ambiguous, so
+  // LOGIC_CHANGE never forces fallback-to-all via this flag.
+  const ambiguous = t0Ambiguous && t1.changeCategories.length === 0;
 
   return { t0, t1, ambiguous };
 }

package/src/claude/hook-decisions.mjs

@@ -11,9 +11,16 @@
 
 import { resolveRunId } from "../loop/run-context.mjs";
 import {
-  isGhPrReadyCommand,
-  extractPrNumberFromGhPrReady,
-  extractRepoFlagFromGhPrReady,
+  commandContainsGhPrReady,
+  commandContainsGhPrMerge,
+  commandContainsGhPrCreate,
+  extractPrNumberFromGhPrReadyAnywhere,
+  extractRepoFlagFromGhPrReadyAnywhere,
+  extractPrNumberFromGhPrMergeAnywhere,
+  extractRepoFlagFromGhPrMergeAnywhere,
+  extractRepoFlagsFromGhPrCreateSegments,
+  commandContainsRawExternalWrite,
+  extractRepoFlagsFromExternalWriteSegments,
   TARGET_REPO_SLUG,
 } from "../loop/bash-command-classify.mjs";
 
@@ -25,6 +32,16 @@ import {
 
 const ALLOW = Object.freeze({ decision: "allow" });
 
+/**
+ * Whether the command string also invokes an evidence-writing script (findings-log ledger or
+ * checkpoint-verdict upsert). Used only to enrich the merge-block message (#1172) — a compound
+ * command combining an evidence write with `gh pr merge` is blocked pre-execution, so the write
+ * never runs; this substring check has no false-negative cost (worst case: the plain message).
+ */
+function commandContainsEvidenceWrite(command) {
+  return command.includes("write-gate-findings-log") || command.includes("upsert-checkpoint-verdict");
+}
+
 /**
  * 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
@@ -33,26 +50,114 @@ const ALLOW = Object.freeze({ decision: "allow" });
 export const DEV_LOOP_AGENT_TYPE = "dev-loop";
 
 /**
- * Decide whether a PreToolUse Bash command must be blocked by the draft-gate boundary.
+ * Decide whether a PreToolUse Bash command must be blocked by a dev-loop gate boundary.
+ *
+ * Three gated commands on the target repo:
+ *   - `gh pr create` — blocked outright; PR creation must flow through the canonical wrapper
+ *     (`scripts/github/create-pr.mjs` / `dev-loops pr create`), which always drafts and
+ *     self-assigns. Closes the hole where raw `gh pr create` opens a ready PR, bypassing draft-first.
+ *   - `gh pr ready` — blocked without clean draft_gate evidence (`pre-pr-ready-gate`).
+ *   - `gh pr merge` — blocked without the full pre-merge gate evidence (`detect-checkpoint-evidence`:
+ *     clean current-head draft_gate + pre_approval_gate). The loop runs this check before merging;
+ *     gating it here closes the hole where a hand-run `gh pr merge` skips the pre-approval gate
+ *     entirely. Everything else passes through.
+ *   - raw `gh issue create` / `gh issue comment` / `gh pr comment` — blocked ONLY when the call
+ *     originates from a SUBAGENT context (`agentType` is a non-null string) and targets the repo.
+ *     Sanctioned external writes flow through node wrappers (gate-verdict comments via
+ *     `upsert-checkpoint-verdict.mjs`, review replies via `reply-resolve*.mjs`, board sync,
+ *     `comment-issue.mjs`), whose Bash command string is `node scripts/…` and never matches these
+ *     raw-`gh` matchers. The MAIN AGENT / operator (agentType null) retains direct `gh issue
+ *     create` — that path is authorized (#1051).
  *
- * 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.
+ * The hook computes `gatePassed`/`gateError` from the gate script appropriate to the command kind.
  *
  * @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 {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
+ *   string inside a subagent, null in the main agent. Scopes the external-write guard.
  * @returns {HookDecision}
  */
-export function decideBashGate({ command, repoSlug = null, gatePassed = false, gateError = null }) {
-  if (typeof command !== "string" || !isGhPrReadyCommand(command)) {
+export function decideBashGate({ command, repoSlug = null, gatePassed = false, gateError = null, agentType = null }) {
+  if (typeof command !== "string") {
+    return ALLOW;
+  }
+  // Subagent-scoped external-write guard: block ad-hoc `gh issue create`/`gh issue comment`/
+  // `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 (#1051).
+  if (typeof agentType === "string" && commandContainsRawExternalWrite(command)) {
+    const cwdTargets = (repoSlug ?? "").toLowerCase() === TARGET_REPO_SLUG.toLowerCase();
+    // 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.
+    const anyWriteInScope = extractRepoFlagsFromExternalWriteSegments(command).some((seg) =>
+      seg.explicitRepo == null
+        ? cwdTargets
+        : seg.explicitRepo.toLowerCase() === TARGET_REPO_SLUG.toLowerCase(),
+    );
+    if (anyWriteInScope) {
+      return {
+        decision: "deny",
+        reason:
+          "Ad-hoc GitHub issue/PR creation and comments from a subagent are blocked. Use the sanctioned " +
+          "node wrappers instead — gate-verdict comments via scripts/github/upsert-checkpoint-verdict.mjs, " +
+          "review-thread replies via scripts/github/reply-resolve*.mjs, board sync, or scripts/github/comment-issue.mjs. " +
+          "Direct `gh issue create` is reserved for the main agent / operator.",
+      };
+    }
+  }
+  // Scan ALL shell segments — the PreToolUse gate blocks pre-emptively, so a gated verb in any
+  // segment (even after `&&` or `;`) must be caught. This differs from the Pi extension's
+  // post-execute `isGhPrReadyCommand`/`isGhPrMergeCommand` which scan only the first segment
+  // (correct there: `false && gh pr ready 42` short-circuits so ready never ran).
+  const isReady = commandContainsGhPrReady(command);
+  const isMerge = commandContainsGhPrMerge(command);
+  const isCreate = commandContainsGhPrCreate(command);
+  if (!isReady && !isMerge && !isCreate) {
     return ALLOW;
   }
 
+  // Raw `gh pr create` is blocked outright on the target repo (no PR number / gate evidence
+  // 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();
+    // 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 (#1047). 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(),
+    );
+    if (anyCreateInScope) {
+      return {
+        decision: "deny",
+        reason:
+          "gh pr create blocked: open PRs via the canonical wrapper `node scripts/github/create-pr.mjs` " +
+          "(a.k.a. `dev-loops pr create`), which always creates a draft and self-assigns. Raw `gh pr create` " +
+          "defaults to ready-for-review and bypasses the draft-first contract (workflow.requireDraftFirst).",
+      };
+    }
+    // The create is out of scope. Only allow outright when there is no ready/merge segment to
+    // evaluate — otherwise fall through so a gated `gh pr ready`/`gh pr merge` in the same
+    // compound command (e.g. `gh pr create --repo other/repo && gh pr merge 5`) is still gated
+    // below rather than short-circuited.
+    if (!isReady && !isMerge) {
+      return ALLOW;
+    }
+  }
+  // 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 = extractRepoFlagFromGhPrReady(command);
+  const explicitRepo = isMerge
+    ? extractRepoFlagFromGhPrMergeAnywhere(command)
+    : extractRepoFlagFromGhPrReadyAnywhere(command);
   if (explicitRepo && explicitRepo.toLowerCase() !== TARGET_REPO_SLUG.toLowerCase()) {
     return ALLOW;
   }
@@ -61,23 +166,41 @@ export function decideBashGate({ command, repoSlug = null, gatePassed = false, g
     return ALLOW;
   }
 
-  const prNumber = extractPrNumberFromGhPrReady(command);
+  const prNumber = isMerge
+    ? extractPrNumberFromGhPrMergeAnywhere(command)
+    : extractPrNumberFromGhPrReadyAnywhere(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.",
+      reason: `${verb} blocked: could not determine the PR number from the command. Include the PR number explicitly.`,
     };
   }
 
   if (gateError) {
+    const which = isMerge ? "pre-merge gate" : "draft-gate";
     return {
       decision: "deny",
-      reason: `gh pr ready blocked: draft-gate evidence check failed (${gateError}).`,
+      reason: `${verb} blocked: ${which} 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" (#1172). 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}.`,