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

package/package.json

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

package/src/analysis/change-classifier.mjs

@@ -117,6 +117,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, ALWAYS_INCLUDE, or the
+ * fallback-to-all path 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 +131,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,6 +143,8 @@ export function resolveDynamicAngles({
   changeCategories,
   ambiguous = false,
   anglePool,
+  angleDeclarations = {},
+  fileKinds = [],
 }) {
   // Fallback: ambiguous diff → all angles
   if (ambiguous) {
@@ -177,6 +191,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));

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";

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

package/src/config/config.mjs

@@ -6,6 +6,7 @@ import { parse as parseYaml } from "yaml";
 import { fileURLToPath } from "node:url";
 import { z } from "zod";
 import { classifyFile } from "../analysis/diff-analyzer.mjs";
+import { ChangeCategory } from "../analysis/change-classifier.mjs";
 import { isDevLoopConfigSourcePath } from "../loop/gate-carry-forward.mjs";
 import { isClaudeHarness } from "../loop/run-context.mjs";
 import { trimmedOrNull } from "../loop/normalize.mjs";
@@ -45,6 +46,12 @@ const BUILTIN_ROLE_TIERS = Object.freeze({
   quality: "low",
   refiner: "high",
   review: "high",
+  // The pre-PR review pass (skills/docs/pre-pr-review-contract.md) runs one
+  // fresh-context general-purpose reviewer before the first push. Default tier
+  // is high (strongest): with zero config that resolves to opus on Claude and
+  // null (inherit) on Pi. Operators opt into a concrete strong model per
+  // harness via models.tiers/roleTiers.
+  "pre-PR-reviewer": "high",
   "dev-loop": "inherit",
 });
 
@@ -113,6 +120,13 @@ const RefinementConfig = z.strictObject({
 // cost saving, never a silently-enforced information cut.
 export const GATE_ANGLE_SCOPES = Object.freeze(["full", "changed-files", "docs-only"]);
 
+// Change-category and file-kind vocabularies a consumer angle can bind to.
+// CHANGE_CATEGORY_NAMES mirrors ChangeCategory; FILE_KIND_NAMES mirrors
+// classifyFile()'s output range. Both feed z.enum so an unknown name is
+// rejected fail-closed at validation instead of silently never matching.
+const CHANGE_CATEGORY_NAMES = Object.freeze(Object.values(ChangeCategory));
+const FILE_KIND_NAMES = Object.freeze(["code", "docs", "config", "test", "ci", "unknown"]);
+
 // One review angle: a bare string is sugar for `{ name }`; the fields are
 // documented on the schema below. mergeConfigLayers merges these arrays BY
 // `name` across config layers, so a later layer can add or disable a single
@@ -132,13 +146,15 @@ const GateAngleEntry = z.preprocess(
     model: z.string().trim().min(1).optional().describe("Concrete model override for this angle (highest precedence)."),
     tier: z.string().trim().min(1).optional().describe("Model tier alias for this angle (used when `model` is absent)."),
     scope: z.enum(GATE_ANGLE_SCOPES).optional().describe("Surface scope this angle needs: full (default), changed-files (diff without the adjacent-code bundle or its changed-files/adjacent-file summary section), or docs-only (doc-file hunks only). Unknown/omitted resolves to full."),
+    categories: z.array(z.enum(CHANGE_CATEGORY_NAMES)).min(1).optional().describe("Change categories (e.g. LOGIC_CHANGE, CONFIG_ONLY, SECURITY_SENSITIVE_SEAM) that dynamically SELECT this consumer angle by diff, so it need not be forced mandatory. Unknown names are rejected fail-closed."),
+    kinds: z.array(z.enum(FILE_KIND_NAMES)).min(1).optional().describe("File kinds (code/config/test/ci/docs/unknown, classifyFile output) that dynamically SELECT this consumer angle by diff. Unknown names are rejected fail-closed."),
   }),
 );
 
 // Diff-class kinds a tier's `match` can name — exactly classifyFile()'s
 // output range (../analysis/diff-analyzer.mjs), so a tier config can never
 // name a kind the classifier could not produce.
-const GateTierMatchKind = z.enum(["code", "docs", "config", "test", "ci", "unknown"]);
+const GateTierMatchKind = z.enum(FILE_KIND_NAMES);
 
 // A tier's match conditions: EVERY changed file's kind must be in `kinds`
 // (when set) AND the change must stay within `maxFiles`/`maxLines` (when
@@ -216,7 +232,7 @@ function formatConfigValue(value) {
 const GATE_KEYS_WITH_BLOCKING_SEVERITIES = /** @type {const} */ (["draft", "preApproval", "spike"]);
 
 const GateConfig = z.strictObject({
-  angles: z.array(GateAngleEntry).optional().describe("Review lenses this gate fans out to. A bare string is sugar for { name }; an object may set mandatory/enabled/persona/prompt/model/tier."),
+  angles: z.array(GateAngleEntry).optional().describe("Review lenses this gate fans out to. A bare string is sugar for { name }; an object may set mandatory/enabled/persona/prompt/model/tier/scope/categories/kinds."),
   dynamic: GateDynamicConfig.optional().describe("Diff-driven dynamic angle selection policy for this gate."),
   required: z.boolean().default(true).describe("Whether this gate must run."),
   requireCi: z.boolean().default(true).describe("Per-gate CI prerequisite (default true): the gate requires green CI on the current head; false opts this gate out of the CI precondition entirely, including a real failure."),
@@ -234,6 +250,13 @@ const GateConfig = z.strictObject({
   // resolveGateConfig applies the built-in fallback (3) after checking both.
   mediumFixWindow: z.number().int().nonnegative().optional().describe("Per-gate medium fix window: an open medium finding stays in the in-gate fix loop through this many rounds of this gate's chain before deferral. high is exempt (never defers). Default 3."),
   worthFixingNowFixWindow: z.number().int().nonnegative().optional().describe("Deprecated alias for mediumFixWindow (pre-rename key name); mediumFixWindow wins when both are set."),
+  // No schema-level `.default()` for the same reason as mediumFixWindow above:
+  // a default would fill this key on every config layer independently and
+  // shadow a layer that sets only this key. resolveGateConfig applies the
+  // built-in fallback ("medium") when the key is absent on the resolved gate.
+  inlineSeverityFloor: z.enum(["medium", "low", "nit"]).optional().describe(
+    "Lowest defect severity still posted as an inline resolvable review thread. Valid values: \"medium\" (default), \"low\", \"nit\" — the floor can never be raised above \"medium\", so medium/high/question always post inline and only low/nit can ever fold. Findings BELOW this floor are folded into a collapsed <details> block in the verdict-marker body instead of posting inline (they create no gate-authored thread); this enforces the \"never suppress medium/high\" non-goal, keeping the folded-summary \"low/nit\" label accurate by construction. A \"question\" always posts inline regardless of this floor (it must keep its resolvable thread to block gate-close until answered). Lower it (e.g. \"low\" or \"nit\") to restore inline posting of lower severities."
+  ),
   // Ordered, first-match-wins diff-class angle tiers (see resolveGateTier).
   // Absent/empty = tiers never apply.
   tiers: z.array(GateTier).min(1).describe("Ordered, first-match-wins diff-class angle tiers for this gate. When the first-matching tier's angle set is inside the gate's angle pool, it replaces dynamic angle reduction for that diff class.").optional(),
@@ -916,13 +939,13 @@ const DEFAULT_REVIEWER_PERSONA = "default-reviewer";
 /**
  * Normalize one raw `gates.<gate>.angles[]` entry (string sugar or object,
  * possibly hand-built and never zod-validated — e.g. a test config object) to
- * `{ name, mandatory?, enabled?, persona?, prompt?, model?, tier?, scope? }`.
+ * `{ name, mandatory?, enabled?, persona?, prompt?, model?, tier?, scope?, categories?, kinds? }`.
  * Returns null for a malformed/empty entry so callers can filter it out. An
  * invalid `scope` (not one of GATE_ANGLE_SCOPES) is dropped rather than
  * kept verbatim — resolveGateAngleScope's fail-open default only ever needs
  * to handle an ABSENT field, never a foreign value.
  * @param {unknown} a
- * @returns {{name: string, mandatory?: boolean, enabled?: boolean, persona?: string, prompt?: string, model?: string, tier?: string, scope?: string}|null}
+ * @returns {{name: string, mandatory?: boolean, enabled?: boolean, persona?: string, prompt?: string, model?: string, tier?: string, scope?: string, categories?: string[], kinds?: string[]}|null}
  */
 function normalizeAngleEntry(a) {
   if (typeof a === "string") {
@@ -940,6 +963,17 @@ function normalizeAngleEntry(a) {
     if (typeof a.model === "string" && a.model.trim().length > 0) entry.model = a.model.trim();
     if (typeof a.tier === "string" && a.tier.trim().length > 0) entry.tier = a.tier.trim();
     if (typeof a.scope === "string" && GATE_ANGLE_SCOPES.includes(a.scope.trim())) entry.scope = a.scope.trim();
+    // Category/file-kind bindings for consumer angles. Enum membership is
+    // enforced by the schema; this hand-built path only keeps non-empty string
+    // entries (bad names simply never match at resolve time).
+    const cats = Array.isArray(a.categories)
+      ? a.categories.filter((c) => typeof c === "string" && c.trim().length > 0).map((c) => c.trim())
+      : [];
+    if (cats.length > 0) entry.categories = cats;
+    const kinds = Array.isArray(a.kinds)
+      ? a.kinds.filter((k) => typeof k === "string" && k.trim().length > 0).map((k) => k.trim())
+      : [];
+    if (kinds.length > 0) entry.kinds = kinds;
     return entry;
   }
   return null;
@@ -949,7 +983,7 @@ function normalizeAngleEntry(a) {
  * Normalize a raw `gates.<gate>.angles` array into full entry objects,
  * dropping malformed entries.
  * @param {unknown} raw
- * @returns {Array<{name: string, mandatory?: boolean, enabled?: boolean, persona?: string, prompt?: string, model?: string, tier?: string, scope?: string}>}
+ * @returns {Array<{name: string, mandatory?: boolean, enabled?: boolean, persona?: string, prompt?: string, model?: string, tier?: string, scope?: string, categories?: string[], kinds?: string[]}>}
  */
 function normalizeAngleEntries(raw) {
   if (!Array.isArray(raw)) return [];
@@ -1771,7 +1805,7 @@ function resolveBlockingSeverities(config, gate) {
  *
  * @param {DevLoopConfig} config
  * @param {"draft"|"preApproval"|"spike"} gate
- * @returns {{ angles: string[]|null, excludeAngles: string[], mandatoryAngles: string[], required: boolean, requireCi: boolean, blockCleanOnFindingSeverities: string[], dynamicAngles: boolean, additiveAngles: boolean, mediumFixWindow: number, tiers: Array<{name: string, match: object, angles: string[]}> }}
+ * @returns {{ angles: string[]|null, excludeAngles: string[], mandatoryAngles: string[], required: boolean, requireCi: boolean, blockCleanOnFindingSeverities: string[], dynamicAngles: boolean, additiveAngles: boolean, mediumFixWindow: number, inlineSeverityFloor: string, tiers: Array<{name: string, match: object, angles: string[]}>, angleCategoryBindings: Record<string, {categories: string[], kinds: string[]}> }}
  * @throws {Error} when ANY gate's (not only the requested one's) PRESENT
  *   `blockCleanOnFindingSeverities` is schema-invalid (non-array, empty, or an
  *   out-of-vocabulary entry). Validated EAGERLY across all three gates on every
@@ -1808,7 +1842,17 @@ export function resolveGateConfig(config, gate) {
     // mediumFixWindow wins; worthFixingNowFixWindow is the deprecated alias,
     // still honored so an unmigrated config keeps its window.
     mediumFixWindow: gateConfig?.mediumFixWindow ?? gateConfig?.worthFixingNowFixWindow ?? 3,
+    inlineSeverityFloor: gateConfig?.inlineSeverityFloor ?? "medium",
     tiers: gateConfig?.tiers ?? [],
+    // Per-angle category/file-kind bindings for enabled entries that declare
+    // them, so dynamic resolution can select a consumer angle by diff instead
+    // of forcing it mandatory. Only entries WITH a declaration appear here;
+    // everything else keeps today's behavior.
+    angleCategoryBindings: Object.fromEntries(
+      entries
+        .filter((e) => e.enabled !== false && (e.categories || e.kinds))
+        .map((e) => [e.name, { categories: e.categories ?? [], kinds: e.kinds ?? [] }]),
+    ),
   };
 }
 
@@ -2668,6 +2712,10 @@ export async function resolveGateAnglesDynamic(config, gate, { diff, hasFullLabe
   });
 
   const categories = [...new Set(analysis.t1?.changeCategories ?? [])];
+  // File kinds present in the diff, to honor a consumer angle's `kinds`
+  // binding. classifyFile is the same classifier the categories above derive
+  // from, so this adds no new classification surface.
+  const fileKinds = [...new Set((analysis.t0?.files ?? []).map(classifyFile))];
 
   // excludeAngles is a hard ceiling: computed once and reused both to cap the
   // additive anglePool and to filter mandatoryAngles below.
@@ -2682,6 +2730,8 @@ export async function resolveGateAnglesDynamic(config, gate, { diff, hasFullLabe
     changeCategories: categories,
     ambiguous: analysis.ambiguous,
     anglePool,
+    angleDeclarations: gateConfig.angleCategoryBindings,
+    fileKinds,
   });
 
   // Merge: mandatory always included (filtered by excludeAngles) + dynamically-selected

package/src/config/extension-defaults.yaml

@@ -133,6 +133,26 @@ gates:
         mandatory: true
         persona: review
         prompt: 'Review the PR description for completeness, contract fitness, and checkbox formatting before this PR is marked ready for review. The PR body is the implementation contract — it must have: - A Summary section explaining what changed and why - A Scope and context section defining the boundary of the change - An Acceptance criteria section with the linked issue acceptance criteria - A Definition of done section - A Non-goals section - A Validation command section describing exactly how to verify the change - The "Closes #N" line must match the linked issue; flag changes that alter or remove the operator-intended close target Checkboxes (`- [ ]` / `- [x]`, or `* [ ]` / `* [x]`) must appear inside genuine Markdown list items. Flag any checkbox marker used outside a list item (including table cells) as a medium finding. Flag any checkbox marker wrapped in backticks (e.g. `` `[x]` ``) as a medium finding. Flag PRs where the body is a single sentence or lacks any of these sections. Do not block on formatting preferences other than checkbox correctness.'
+      - name: holistic
+        mandatory: true
+        persona: review
+        prompt: >-
+          Review the WHOLE change holistically, on its merits, as a senior
+          engineer doing a final read of the entire diff. You are independent and
+          un-briefed: you receive only the spec (acceptance criteria, definition
+          of done, non-goals) and the diff — no author or developer brief and no
+          steering from the reviewed party. Your mandate is broad, not a single
+          named lens. Read the whole change end to end and judge whether, taken
+          together, it correctly and completely does what the spec asks, is
+          internally coherent, and is safe to ship. Concentrate on CROSS-CUTTING
+          problems that no narrow angle owns: mismatches between parts of the
+          change, gaps between the diff and the acceptance criteria, unintended
+          interactions across modules, missing pieces the spec implies, and
+          defects that would otherwise surface later in Copilot review or a
+          consumer repo. Cite concrete file:line evidence for each finding and
+          give a minimal fix. Respect declared non-goals — do not manufacture
+          scope. If the change is coherent and complete against the spec, return
+          clean.
     # #1442 (ADR 0041 prose half): required fail-closed deslop angle for prose
     # deliverables. Runs the A/B-contrast-removal deslop step (ab-contrast-
     # deslop-step.md) — flag surviving binary-contrast constructions so the gate
@@ -221,6 +241,14 @@ gates:
         angles: [srp, soc, ocp, lsp, isp, dip]
       - name: finalization
         angles: [correctness-final, ui-validation]
+      # The holistic reviewer reads the whole diff, so it gets its own
+      # reviewer rather than being auto-chunked with unrelated leftover
+      # angles — one reviewer reviews the whole change holistically.
+      # A consumer repo that overrides gates.fanout.groups replaces this
+      # table wholesale (shallow merge) and must restate this singleton to
+      # keep holistic un-batched.
+      - name: holistic
+        angles: [holistic]
   preApproval:
     angles:
       - name: dry
@@ -294,6 +322,26 @@ gates:
           require a matrix on the PR — the matrix lives on the issue; the PR carries the derived
           checklists. The boundary is explicit: the deterministic block enforces completeness (nothing
           left unchecked/forgotten); you verify each [x] is real and faithfully derived.
+      - name: holistic
+        mandatory: true
+        persona: review
+        prompt: >-
+          Review the WHOLE change holistically, on its merits, as a senior
+          engineer doing a final read of the entire diff. You are independent and
+          un-briefed: you receive only the spec (acceptance criteria, definition
+          of done, non-goals) and the diff — no author or developer brief and no
+          steering from the reviewed party. Your mandate is broad, not a single
+          named lens. Read the whole change end to end and judge whether, taken
+          together, it correctly and completely does what the spec asks, is
+          internally coherent, and is safe to ship. Concentrate on CROSS-CUTTING
+          problems that no narrow angle owns: mismatches between parts of the
+          change, gaps between the diff and the acceptance criteria, unintended
+          interactions across modules, missing pieces the spec implies, and
+          defects that would otherwise surface later in Copilot review or a
+          consumer repo. Cite concrete file:line evidence for each finding and
+          give a minimal fix. Respect declared non-goals — do not manufacture
+          scope. If the change is coherent and complete against the spec, return
+          clean.
       - contradiction-lens
       - correctness-final
       - ui-validation