@dev-loops/core 1.0.3 → 1.0.4-pre.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dev-loops/core",
-  "version": "1.0.3",
+  "version": "1.0.4-pre.1",
   "type": "module",
   "engines": {
     "node": ">=24"

package/src/analysis/change-classifier.mjs

@@ -99,7 +99,7 @@ export const ALWAYS_INCLUDE = new Set(["gate-evidence", "renderer-security", "pr
  *   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 {boolean} fallbackToAll — retained for compatibility; always false
  * @property {string[]} addedAngles — catalog angles added (additive mode only, see #1048)
  * @property {Record<string, string>} addedReasons — why each added angle was added
  */
@@ -108,8 +108,14 @@ export const ALWAYS_INCLUDE = new Set(["gate-evidence", "renderer-security", "pr
  * Resolve which gate angles to run based on detected change categories.
  *
  * 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.
+ * uncertainty still resolves through the same best-effort selection as a
+ * classified diff; it never expands to every configured angle. A LOGIC_CHANGE
+ * diff likewise resolves to its core review subset.
+ *
+ * `configuredAngles` is the caller's candidate pool (mandatory angles have
+ * already been removed), so an uncertain diff may legitimately resolve to an
+ * empty candidate set. The caller combines this with its mandatory floor and
+ * falls back to the static pool if that combined selection would be empty.
  *
  * When `anglePool` is provided (additive mode, see #1048), catalog angles in
  * the pool that the change categories recommend but that are not already in
@@ -117,6 +123,13 @@ export const ALWAYS_INCLUDE = new Set(["gate-evidence", "renderer-security", "pr
  * When `anglePool` is omitted, additive mode is off and `addedAngles` is
  * always empty.
  *
+ * A configured angle that is NOT in CATEGORY_ANGLE_MAP (a consumer-defined
+ * angle) can still be recommended BY change category or file kind when it
+ * declares `categories`/`kinds` via `angleDeclarations`. This is purely
+ * additive: it can only SELECT such an angle when the diff intersects its
+ * declaration; it never drops any angle the catalog map or ALWAYS_INCLUDE
+ * would otherwise recommend.
+ *
  * @param {object} options
  * @param {string[]} options.configuredAngles — all angles configured for this gate
  * @param {string[]} options.changeCategories — from diff analysis
@@ -124,6 +137,11 @@ export const ALWAYS_INCLUDE = new Set(["gate-evidence", "renderer-security", "pr
  * @param {string[]} [options.anglePool] — catalog of angles eligible for additive
  *   selection (caller pre-filters this against excludeAngles); when undefined,
  *   additive selection is disabled
+ * @param {Record<string, {categories?: string[], kinds?: string[]}>} [options.angleDeclarations]
+ *   — per-angle category/file-kind bindings for consumer angles absent from
+ *   CATEGORY_ANGLE_MAP; a match recommends the angle deterministically
+ * @param {string[]} [options.fileKinds] — file kinds present in the diff
+ *   (classifyFile output), used to honor an angle's `kinds` declaration
  * @returns {DynamicAngleResult}
  */
 export function resolveDynamicAngles({
@@ -131,31 +149,9 @@ export function resolveDynamicAngles({
   changeCategories,
   ambiguous = false,
   anglePool,
+  angleDeclarations = {},
+  fileKinds = [],
 }) {
-  // Fallback: ambiguous diff → all angles
-  if (ambiguous) {
-    return {
-      recommendedAngles: [...configuredAngles],
-      skippedAngles: [],
-      reasons: {},
-      fallbackToAll: true,
-      addedAngles: [],
-      addedReasons: {},
-    };
-  }
-
-  // No change categories → all angles (defensive)
-  if (changeCategories.length === 0) {
-    return {
-      recommendedAngles: [...configuredAngles],
-      skippedAngles: [],
-      reasons: {},
-      fallbackToAll: true,
-      addedAngles: [],
-      addedReasons: {},
-    };
-  }
-
   // Build recommended set from category union, tracking the first trigger per angle
   const recommended = new Set();
   const triggers = new Map();
@@ -177,6 +173,27 @@ export function resolveDynamicAngles({
     }
   }
 
+  // Consumer angles bound by declaration: a configured angle absent from
+  // CATEGORY_ANGLE_MAP can name the change-categories / file-kinds that select
+  // it. Recommend it when the diff intersects that declaration, so it need not
+  // be forced `mandatory` to survive dynamic pruning. Additive only: never
+  // removes an angle already recommended above.
+  const changeCatSet = new Set(changeCategories);
+  const fileKindSet = new Set(fileKinds);
+  for (const angle of configuredAngles) {
+    if (recommended.has(angle)) continue;
+    const decl = angleDeclarations[angle];
+    if (!decl) continue;
+    const catHit = (decl.categories ?? []).some((c) => changeCatSet.has(c));
+    const kindHit = (decl.kinds ?? []).some((k) => fileKindSet.has(k));
+    if (catHit || kindHit) {
+      recommended.add(angle);
+      if (!triggers.has(angle)) {
+        triggers.set(angle, catHit ? "declared-category" : "declared-kind");
+      }
+    }
+  }
+
   // Filter to only angles that are configured
   const recommendedAngles = configuredAngles.filter((a) => recommended.has(a));
   const skippedAngles = configuredAngles.filter((a) => !recommended.has(a));
@@ -184,7 +201,11 @@ export function resolveDynamicAngles({
   // Build reasons
   const reasons = {};
   for (const angle of skippedAngles) {
-    reasons[angle] = `Skipped: detected categories (${changeCategories.join(", ") || "none"}) do not trigger this angle`;
+    reasons[angle] = changeCategories.length === 0
+      ? "Skipped: no change category could be established (uncertain classification)"
+      : ambiguous
+        ? `Skipped: analysis remained ambiguous despite detected categories (${changeCategories.join(", ")})`
+        : `Skipped: detected categories (${changeCategories.join(", ")}) do not trigger this angle`;
   }
 
   // Additive: pull in recommended catalog angles not already configured (#1048)

package/src/analysis/diff-analyzer.mjs

@@ -16,6 +16,57 @@
 // closed to a full re-review.
 const DOTFILE_CONFIG_BASENAMES = new Set([".devloops"]);
 
+// Generic classifier tables. Files are classified by principle (broad extension
+// tables + directory/basename conventions), not by a bespoke per-language rule.
+// A new mainstream language is covered by adding its extension here, not by a new
+// branch. Deliberate fail-closed exceptions (`.ruby-version`, `.nvmrc`,
+// stylesheets) are simply absent from every table, so they fall through to
+// "unknown".
+
+// Source extensions across the common languages. A file with one of these is
+// executable/product logic → "code".
+const CODE_EXTENSIONS = new Set([
+  // JS/TS
+  ".mjs", ".cjs", ".js", ".jsx", ".ts", ".mts", ".cts", ".tsx",
+  // Ruby (source + Rails view templates, which embed control flow / XSS surface)
+  ".rb", ".rake", ".erb", ".haml", ".slim", ".jbuilder",
+  // Python
+  ".py", ".pyi",
+  // Go
+  ".go",
+  // Rust
+  ".rs",
+  // Java / Kotlin / Scala
+  ".java", ".kt", ".kts", ".scala", ".sc",
+  // C / C++ / C#
+  ".c", ".h", ".cc", ".cpp", ".cxx", ".hpp", ".hh", ".hxx", ".cs",
+  // PHP / Swift / Elixir / Lua / Dart
+  ".php", ".swift", ".ex", ".exs", ".lua", ".dart",
+  // Shell
+  ".sh", ".bash", ".zsh", ".fish",
+]);
+// Basename-only source files (no discriminating extension).
+const CODE_BASENAMES = new Set(["Rakefile"]);
+
+// Data/config/manifest extensions. `.ru` (rackup) and `.gemspec` are Ruby
+// packaging surface. `.lock` covers every lockfile (Gemfile.lock, Cargo.lock,
+// poetry.lock, yarn.lock, …).
+const CONFIG_EXTENSIONS = new Set([
+  ".yml", ".yaml", ".json", ".toml", ".ini", ".cfg", ".lock", ".ru", ".gemspec",
+]);
+// Manifest basenames without a config extension.
+const CONFIG_BASENAMES = new Set([
+  "Gemfile", "go.mod", "go.sum", "requirements.txt", "pom.xml", "Dockerfile", "Makefile",
+]);
+
+// Prose/documentation extensions.
+const DOCS_EXTENSIONS = new Set([".md", ".markdown", ".rst", ".adoc", ".txt"]);
+
+// Test conventions. A directory segment named any of these, or a basename token
+// (`*_test.*`, `*_spec.*`, `test_*`, `*.test.*`, `*.spec.*`), marks a test file.
+const TEST_DIR_SEGMENTS = new Set(["test", "tests", "spec", "specs", "__tests__"]);
+const TEST_BASENAME_RE = /(\.test\.|\.spec\.|_test\.|_spec\.|^test_)/;
+
 // Prose surface that arms the required `deslop` gate angle.
 // skills/docs/** is excluded via SKILLS_DOCS_EXEMPT_RE: those are normative
 // contracts, not prose.
@@ -135,34 +186,56 @@ export function analyzeT0(nameStatusOutput) {
  */
 export function classifyFile(filePath) {
   const fp = normalizeSep(filePath);
+  const base = fp.split("/").pop();
+  // Extension excludes a leading-dot dotfile (`.nvmrc` → "", not ".nvmrc"), so
+  // runtime-version dotfiles never match an extension table and fall through to
+  // "unknown".
+  const dot = base.lastIndexOf(".");
+  const ext = dot > 0 ? base.slice(dot).toLowerCase() : "";
+
   if (fp.startsWith(".github/")) {
     return "ci";
   }
-  // A known code/config/test extension wins over the docs/ directory-prefix
-  // fallback: a code/config/test file hosted under docs/ is still that surface,
-  // not prose. Extension checks run before the prefix fallbacks below.
+  // Config wins over every later surface: a manifest/data file (even one hosted
+  // under docs/, or a build.gradle.kts that also has a code extension) is config,
+  // not prose or code. `.ruby-version`/`.nvmrc` are absent from all tables and so
+  // stay "unknown" — a runtime bump must re-run ci-guard/determinism, not carry a
+  // stale clean verdict.
   if (
-    fp.endsWith(".yml") || fp.endsWith(".yaml") ||
-    fp.endsWith(".json") || fp === "package.json"
+    CONFIG_EXTENSIONS.has(ext) ||
+    CONFIG_BASENAMES.has(base) ||
+    DOTFILE_CONFIG_BASENAMES.has(base) ||
+    base.startsWith("build.gradle")
   ) {
     return "config";
   }
-  if (DOTFILE_CONFIG_BASENAMES.has(fp.split("/").pop())) {
-    return "config";
+  // Generic test convention, part 1: a basename carrying a test/spec token
+  // (`*_test.*`, `*_spec.*`, `test_*`, `*.test.*`, `*.spec.*`) is a test wherever
+  // it lives — a strong per-file signal that subsumes the old `.test.` and Ruby
+  // `*_spec.rb`/`*_test.rb` rules and wins even under `docs/`.
+  if (TEST_BASENAME_RE.test(base)) {
+    return "test";
   }
-  if (fp.includes(".test.") || fp.startsWith("test/")) {
+  // Generic test convention, part 2: a `test`/`tests`/`spec`/`specs`/`__tests__`
+  // path segment at any depth. Subsumes the old root-anchored `test/`/`spec/`
+  // rules and broadens them to nested suites (`packages/core/test/foo.mjs`).
+  // Excluded under `docs/`: the old rule anchored test dirs at the ROOT, so a
+  // docs-tree prose file (`docs/specs/queue-mode/SPEC.md`) was never a test — the
+  // widened any-depth scan must not reclassify it. This only skips the
+  // DIRECTORY-based classification; a code/config file or a test-token basename
+  // under docs/ is still classified by the extension/basename rules above and
+  // below (`docs/example.mjs` → code, `docs/x.test.mjs` → test).
+  const dirs = fp.split("/").slice(0, -1);
+  if (!fp.startsWith("docs/") && dirs.some((seg) => TEST_DIR_SEGMENTS.has(seg))) {
     return "test";
   }
-  if (
-    fp.endsWith(".mjs") || fp.endsWith(".js") ||
-    fp.endsWith(".ts") || fp.endsWith(".mts")
-  ) {
+  // Broad source table: a file in any covered language is code, not prose, even
+  // under docs/. Stylesheets (`.scss`/`.sass`) are deliberately absent — a
+  // style/asset kind is out of scope.
+  if (CODE_EXTENSIONS.has(ext) || CODE_BASENAMES.has(base)) {
     return "code";
   }
-  if (
-    fp.startsWith("docs/") || fp.endsWith(".md") || fp.endsWith(".markdown") ||
-    fp === "README.md"
-  ) {
+  if (fp.startsWith("docs/") || DOCS_EXTENSIONS.has(ext)) {
     return "docs";
   }
   return "unknown";
@@ -370,6 +443,8 @@ export function analyzeT1(diffOutput, t0) {
  * @property {T0Result} t0
  * @property {T1Result | null} t1
  * @property {boolean} ambiguous — true when heuristics cannot confidently classify
+ * @property {boolean} fullDiffMissing — true when a mixed diff needed hunk-level
+ *   analysis but the full-diff capture was absent/empty (see analyzeDiff)
  */
 
 /**
@@ -423,9 +498,8 @@ function t0PresentSurfaceCategories(t0) {
 function inferCategoriesFromT0(t0) {
   const categories = t0FileCategories(t0);
   // Pure code-only change (all files classify as code, not a rename) is a
-  // LOGIC_CHANGE. Without this an all-code diff yields no category, which
-  // resolveDynamicAngles treats as unclassifiable → fallback-to-all, regressing
-  // the primary case: a code-only PR must resolve to the LOGIC_CHANGE subset.
+  // LOGIC_CHANGE. Without this an all-code diff yields no category and loses
+  // the justified code-review core from best-effort selection.
   if (!t0.renameOnly && t0.files.length > 0 && t0.files.every((f) => classifyFile(f) === "code")) {
     categories.push("LOGIC_CHANGE");
   }
@@ -450,19 +524,31 @@ export function analyzeDiff({ nameStatusOutput, diffOutput }) {
   const t0Ambiguous = !t0.renameOnly && !t0.allDocs && t0.files.length > 1 &&
     new Set(t0.files.map(classifyFile)).size > 1;
 
-  if (t0Ambiguous && diffOutput) {
+  // A full-diff capture is usable evidence only when it carries non-whitespace
+  // content. A whitespace-only capture (e.g. "   \n") must take the SAME
+  // fail-closed path as an absent/empty one: T1 must not run and
+  // `fullDiffMissing` must fire, so a gate needing the full diff cannot read a
+  // hunk-less whitespace capture as complete evidence.
+  const hasDiffText = typeof diffOutput === "string" && diffOutput.trim().length > 0;
+
+  if (t0Ambiguous && hasDiffText) {
     t1 = analyzeT1(diffOutput, t0);
   }
 
   // When t1 is null (unambiguous diff), infer categories from t0
   // so dynamic angle resolution can narrow for config-only / test-only etc.
   if (!t1) {
-    // A genuinely MIXED diff whose T1 never ran (no diffOutput) must NOT get a
-    // T0-only category: non-empty categories set ambiguous=false, so it would
-    // under-select and drop the code-review core. T0-only inference is safe only
-    // for unambiguous diffs; a mixed diff without hunk content is unclassifiable,
-    // so return empty categories and fall back to the full angle set (fail closed).
-    const changeCategories = t0Ambiguous ? [] : inferCategoriesFromT0(t0);
+    // A genuinely MIXED diff whose T1 never ran (no diffOutput) still has
+    // honest T0 surface evidence. Reuse the same surface-presence categories
+    // as the hunk path, and add LOGIC_CHANGE when code is present, so
+    // best-effort selection retains the code-review core without widening to
+    // the full pool.
+    const changeCategories = t0Ambiguous
+      ? [
+          ...t0PresentSurfaceCategories(t0),
+          ...(t0.files.some((f) => classifyFile(f) === "code") ? ["LOGIC_CHANGE"] : []),
+        ]
+      : inferCategoriesFromT0(t0);
     t1 = {
       changeCategories,
       hunkCount: 0,
@@ -478,11 +564,21 @@ export function analyzeDiff({ nameStatusOutput, diffOutput }) {
   }
 
   // `ambiguous` flags one case: a diff T0 could not classify (mixed categories)
-  // AND whose hunk analysis produced no category. It is NOT the only fallback
-  // trigger — resolveDynamicAngles also falls back whenever changeCategories is
-  // empty. 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.
+  // AND its available analysis produced no category. Empty categories resolve
+  // through mandatory-floor best-effort selection, while a hunk-less mixed diff
+  // with T0 surface evidence stays classified and keeps its justified core.
   const ambiguous = t0Ambiguous && t1.changeCategories.length === 0;
 
-  return { t0, t1, ambiguous };
+  // Evidence-availability signal, SEPARATE from `ambiguous` on purpose. A mixed
+  // diff whose hunk-level analysis never ran (no full-diff capture) legitimately
+  // classifies through its honest T0 surfaces for ANGLE SELECTION — that is what
+  // keeps the code-review core in the best-effort subset without widening to the
+  // whole pool. But a fail-closed gate that needs the FULL diff (the size
+  // budget's unwaivable block) must not read that angle-selection fallback as
+  // complete evidence: `ambiguous` is now false for this case, so such a gate
+  // would silently downgrade. Consumers that need the diff itself key off THIS
+  // flag instead of piggybacking on the angle classifier's ambiguity flag.
+  const fullDiffMissing = t0Ambiguous && !hasDiffText;
+
+  return { t0, t1, ambiguous, fullDiffMissing };
 }

package/src/claude/asset-generation.mjs

@@ -21,7 +21,10 @@
  *   async-dispatch concerns. The user entrypoint under Claude is the dev-loop *skill*.)
  * - Skills keep name/description/allowed-tools (space-separated) and preserve `user-invocable`
  *   (Claude honors it 1:1 — `user-invocable: false` hides the skill from the `/` menu). The
- *   Pi-specific `compatibility` text is dropped (no Claude field).
+ *   Pi-specific `compatibility` text is dropped (no Claude field). Whole-file skill exclusion is
+ *   applied by `collectGeneratedAssets` in scripts/claude/generate-claude-assets.mjs before these
+ *   transforms run; this is distinct from `<!-- pi-only -->` blocks, which remove only marked body
+ *   sections.
  */
 
 import { parse as parseYaml } from "yaml";
@@ -295,6 +298,38 @@ export function transformCommand({ source, raw, version = "latest" }) {
   return `${lines.join("\n")}\n${body}`;
 }
 
+/**
+ * Check whether a skill should be excluded from Claude asset generation.
+ * Supports:
+ * - `claude-sync: false`
+ * - `harness: pi` (or `harness: ["pi"]`)
+ * - `pi-only: true`
+ *
+ * @param {Record<string, unknown> | undefined} frontmatter
+ * @returns {boolean}
+ */
+export function isSkillExcludedFromClaude(frontmatter) {
+  if (!frontmatter || typeof frontmatter !== "object") {
+    return false;
+  }
+  const claudeSync = frontmatter["claude-sync"];
+  if (claudeSync === false || (typeof claudeSync === "string" && claudeSync.trim().toLowerCase() === "false")) {
+    return true;
+  }
+  const piOnly = frontmatter["pi-only"];
+  if (piOnly === true || (typeof piOnly === "string" && piOnly.trim().toLowerCase() === "true")) {
+    return true;
+  }
+  const harness = frontmatter.harness;
+  if (typeof harness === "string" && harness.trim().toLowerCase() === "pi") {
+    return true;
+  }
+  if (Array.isArray(harness) && harness.length === 1 && String(harness[0]).trim().toLowerCase() === "pi") {
+    return true;
+  }
+  return false;
+}
+
 /**
  * Transform a canonical `skills/<name>/SKILL.md` into a Claude `.claude/skills/<name>/SKILL.md`.
  * @param {{ source: string, raw: string, version?: string }} input

package/src/claude/hook-decisions.mjs

@@ -32,6 +32,7 @@ import {
   commandContainsCopilotSummonComment,
   commandContainsDetachedWaitTool,
   commandContainsInlineInterpreter,
+  commandContainsCodeVerificationEntrypoint,
 } from "../loop/bash-command-classify.mjs";
 
 /**
@@ -61,6 +62,24 @@ function commandContainsEvidenceWrite(command) {
  */
 export const DEV_LOOP_AGENT_TYPE = "dev-loop";
 
+/**
+ * Normalize a Claude `agent_type` hook-payload value that may be PLUGIN-NAMESPACED
+ * (`<plugin-name>:<agent-name>`, e.g. `dev-loops:dev-loop`) to the bare agent name the coordinator
+ * deciders compare against `DEV_LOOP_AGENT_TYPE`. Returns the substring after the last `:` when
+ * present, else `agentType` unchanged (including `null`/non-string, passed through as-is).
+ *
+ * Applied in the coordinator-scoped deciders (`decideBashGate`, `decideCoordinatorWriteGuard`).
+ * Deliberately NOT applied in `decideWriteGuard` — its main-agent allow-set boundary is covered by
+ * the `DEVLOOPS_RUN_ID` run-id check first, and broadening that decider's comparison is out of
+ * scope for the coordinator→worker delegation boundary.
+ * @param {string|null|undefined} agentType @returns {string|null|undefined}
+ */
+export function normalizeAgentType(agentType) {
+  if (typeof agentType !== "string") return agentType;
+  const idx = agentType.lastIndexOf(":");
+  return idx === -1 ? agentType : agentType.slice(idx + 1);
+}
+
 /**
  * Decide whether a PreToolUse Bash command must be blocked by a dev-loop gate boundary.
  *
@@ -68,8 +87,9 @@ export const DEV_LOOP_AGENT_TYPE = "dev-loop";
  *   - `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.
  *   - `gh pr ready` — blocked without clean draft_gate evidence.
- *   - `gh pr merge` — blocked without full pre-merge gate evidence (clean current-head draft_gate +
- *     pre_approval_gate).
+ *   - `gh pr merge` — blocked outright; use scripts/github/merge-pr.mjs. Its gate evidence check
+ *     requires a clean draft_gate transition record + current-head pre_approval_gate
+ *     (GATE-COMMENT-DRAFT-REQUIREMENTS in skills/docs/gate-review-comment-contract.md).
  *   - raw `gh issue create` / `gh issue comment` / `gh issue edit` / `gh pr comment` — blocked ONLY
  *     from a SUBAGENT context (`agentType` non-null) on the target repo. Sanctioned external writes
  *     flow through node wrappers; the MAIN AGENT / operator (agentType null) retains direct access.
@@ -92,6 +112,9 @@ export const DEV_LOOP_AGENT_TYPE = "dev-loop";
  *   (`resolveHumanMergeOnly`); when true, `gh pr merge` is refused actor-independently
  *   (STOP-HUMAN-MERGE-001), because the main agent is the actor that performs GitHub writes and a
  *   subagent-only deny would enforce nothing.
+ * @param {boolean} [params.enforceCoordinator] - Strict mode for the COORDINATOR-VERIFY-DELEGATION
+ *   boundary, derived by the hook from `DEVLOOPS_COORDINATOR_READONLY=1` — the SAME flag that
+ *   gates `decideCoordinatorWriteGuard`. Default fail-open (mirrors that boundary).
  * @returns {HookDecision}
  */
 export function decideBashGate({
@@ -103,10 +126,30 @@ export function decideBashGate({
   gateError = null,
   agentType = null,
   humanMergeOnly = false,
+  enforceCoordinator = false,
 }) {
   if (typeof command !== "string") {
     return ALLOW;
   }
+
+  // COORDINATOR-VERIFY-DELEGATION: a known code-verification/build entrypoint (bun run
+  // verify/test, vitest, npm test/run test/run build, ...) run inline by the dev-loop COORDINATOR
+  // itself (agent_type "dev-loop"). WORKER subagents (developer/fixer/quality/review) may run these
+  // freely — only the coordinator is scoped out, mirroring `decideCoordinatorWriteGuard`'s
+  // agent_type discriminator. Opt-in via the same `DEVLOOPS_COORDINATOR_READONLY=1` flag as the
+  // write-guard boundary; default fail-open. Not scoped to `inManagedRepo` — this is a local
+  // command-invocation boundary (which binary ran), not a GitHub-repo-targeting one.
+  if (enforceCoordinator && normalizeAgentType(agentType) === DEV_LOOP_AGENT_TYPE && commandContainsCodeVerificationEntrypoint(command)) {
+    return {
+      decision: "deny",
+      reason:
+        "COORDINATOR-VERIFY-DELEGATION: the dev-loop coordinator must not run code-verification/build " +
+        "commands inline. Delegate the verification run to a fresh worker subagent (developer/fixer/" +
+        "quality/review), which reports back a compact pass/fail plus any failing-test names — or, when " +
+        "checking a pushed commit, prefer CI's structured conclusion (`gh pr checks` / " +
+        "scripts/github/detect-checkpoint-evidence.mjs) over a local run. See skills/docs/main-agent-contract.md.",
+    };
+  }
   // Normalize (trim + case-fold) so a divergent slug (surrounding whitespace, casing) does not
   // 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
@@ -130,6 +173,29 @@ export function decideBashGate({
     };
   }
 
+  // COPILOT-FOLLOWUP-WAIT-TOOLS: banned detached/polling wait wrappers. Actor-independent: the
+  // coordinator/main agent — not subagents only — is the actor that leaves backgrounded
+  // `until`/`while … sleep … done` poll loops and bare-`&` backgrounded probe shells orphaned
+  // under the Claude Code harness (no async wake to join them), so the gate must deny its
+  // backgrounding too. Evaluated HERE, before the `gh pr ready`/`merge`/`create` classification,
+  // so a compound command that pairs a lifecycle verb with a backgrounded wait
+  // (`gh pr create --repo other/x && node …/probe-copilot-review.mjs … &`) cannot short-circuit
+  // past it via the create/ready ALLOW paths. The sanctioned wait is always a bounded FOREGROUND
+  // inline probe (`probe-copilot-review.mjs` / `wait-pr-checks.mjs` with an explicit
+  // --timeout/--timeout-ms; `gh run watch`; the watch-cycle CLIs).
+  if (inManagedRepo && commandContainsDetachedWaitTool(command)) {
+    return {
+      decision: "deny",
+      reason:
+        "COPILOT-FOLLOWUP-WAIT-TOOLS: wait only through a bounded FOREGROUND probe (scripts/github/" +
+        "probe-copilot-review.mjs or scripts/github/wait-pr-checks.mjs with an explicit --timeout/" +
+        "--timeout-ms; scripts/loop/detect-copilot-loop-state.mjs one-shot; dev-loops loop watch-cycle; " +
+        "gh run watch) — nohup/disown/tmux/screen detach, while-sleep-poll loops, and bare-`&` " +
+        "backgrounding of a probe/wait script are barred for the coordinator and every subagent (a " +
+        "backgrounded wait orphans under Claude Code, which has no async wake to join it).",
+    };
+  }
+
   // SUBISSUE-NO-ADHOC-BYPASS: ad-hoc `gh api` writes to the target repo's sub-issue endpoints.
   // Actor-independent (no reserved direct path). Gated on the target repo: the absolute slug-embedded
   // form identifies the target repo; the bare relative form (`gh api issues/5/sub_issues`) resolves
@@ -237,20 +303,9 @@ export function decideBashGate({
   }
 
   if (!isReady && !isMerge && !isCreate) {
-    // COPILOT-FOLLOWUP-WAIT-TOOLS: banned detached/polling wait wrappers. Subagent-only — the
-    // 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" && inManagedRepo && commandContainsDetachedWaitTool(command)) {
-      return {
-        decision: "deny",
-        reason:
-          "COPILOT-FOLLOWUP-WAIT-TOOLS: wait only through deterministic tools (scripts/loop/detect-copilot-" +
-          "loop-state.mjs one-shot, dev-loops loop watch-cycle persistent, scripts/github/wait-pr-checks.mjs, " +
-          "gh run watch) — nohup/disown/tmux/screen detach and while-sleep-poll loops are barred for the " +
-          "dev-loop driving agent.",
-      };
-    }
+    // The detached-wait deny (COPILOT-FOLLOWUP-WAIT-TOOLS) is evaluated earlier — actor-independently
+    // and BEFORE this lifecycle-verb classification — so a compound command pairing a lifecycle verb
+    // with a backgrounded wait cannot short-circuit past it through the create/ready ALLOW paths.
     return ALLOW;
   }
 
@@ -291,8 +346,7 @@ export function decideBashGate({
       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.
+  // When both verbs appear in a compound command, the unconditional raw-merge refusal wins.
   const verb = isMerge ? "gh pr merge" : "gh pr ready";
   // 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
@@ -411,6 +465,51 @@ export function decideWriteGuard({ filePath, isRepoMutation, enforce = false, en
   };
 }
 
+/**
+ * Decide whether a PreToolUse Write/Edit must be blocked by the coordinator→worker delegation
+ * boundary — the INVERSE of `decideWriteGuard`, one level down. Under the Claude Code
+ * harness the dev-loop agent itself (Claude `agent_type === "dev-loop"`) acts as a delegating
+ * COORDINATOR: it MUST NOT mutate TRACKED repo files directly — that work is delegated to a fresh
+ * WORKER subagent (`developer`/`fixer`/`quality`/`docs`). `agent_type` is the only discriminator:
+ * `DEVLOOPS_RUN_ID` does not distinguish coordinator from worker (the coordinator mints it and
+ * propagates it to the workers it dispatches), so — unlike `decideWriteGuard` — this decider does
+ * not key on run id at all.
+ *
+ * Denies only when ALL of: strict enforcement is on, the target is a tracked repo mutation, AND
+ * the caller's `agent_type` is the coordinator's (`"dev-loop"`). Every other `agent_type` —
+ * including `null` (the Pi main agent / an interactive Claude session with no subagent context,
+ * which is `decideWriteGuard`'s boundary, not this one) and any worker role — is allowed here.
+ * Strict enforcement is opt-in via `enforce` (the hook derives it from
+ * `DEVLOOPS_COORDINATOR_READONLY=1`); default is fail-open, mirroring `decideWriteGuard`'s
+ * adopt-safe precedent so enabling this boundary does not retroactively break a repo's own
+ * interactive Claude Code dev.
+ *
+ * @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_COORDINATOR_READONLY=1).
+ * @param {string|null} [params.agentType] - Claude `agent_type` from the hook payload, if any.
+ * @returns {HookDecision}
+ */
+export function decideCoordinatorWriteGuard({ filePath, isRepoMutation, enforce = false, agentType = null }) {
+  if (!enforce) {
+    return ALLOW; // strict enforcement not enabled — fail open
+  }
+  if (!isRepoMutation) {
+    return ALLOW; // non-repo or gitignored path (tmp/, the scratchpad, sanctioned ledger paths)
+  }
+  if (normalizeAgentType(agentType) !== DEV_LOOP_AGENT_TYPE) {
+    return ALLOW; // not the coordinator — a worker subagent, or the main agent (the other boundary)
+  }
+  return {
+    decision: "deny",
+    reason:
+      `Coordinator→worker delegation boundary: refusing to mutate repository path "${filePath}" as the ` +
+      "dev-loop coordinator. Delegate this tracked-file edit to a fresh worker subagent (developer/fixer/" +
+      "quality/docs) instead of writing it directly. See skills/docs/main-agent-contract.md.",
+  };
+}
+
 /**
  * Env var that authorizes a deliberate main-checkout mutation while a worktree
  * cycle is active. Reuses the existing default-branch-guard override