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

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, resolveDynamicAngles } 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
@@ -168,9 +184,9 @@ const GateTier = z.strictObject({
 });
 
 const GateDynamicConfig = z.strictObject({
-  // Diff-driven dynamic angle PRUNING, ON by default. mandatory:true
-  // angles stay a hard always-run floor; fallbackToAll degrades to the full
-  // static pool when classification is ambiguous.
+  // Diff-driven dynamic angle PRUNING, ON by default. mandatory:true angles
+  // stay a hard always-run floor. fallbackToAll is retained in resolver output
+  // for compatibility but is always false; uncertainty never widens the set.
   subtractive: z.boolean().default(true).describe("Enable diff-driven dynamic angle PRUNING for this gate (ON by default; set false to restore the full static angle pool). Was gates.<gate>.dynamicAngles."),
   // Additive counterpart to the subtractive path: when true, the
   // context-builder may also ADD catalog angles (from resolveAnglePool) that
@@ -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 ?? [] }]),
+    ),
   };
 }
 
@@ -2161,12 +2205,15 @@ export function resolveFanoutSequential(config) {
 
 /**
  * Claude-harness-scoped cap on effective fan-out concurrency (per ADR
- * docs/decisions/0069-claude-harness-fanout-concurrency-clamp.md). The
- * shipped cross-harness `gates.fanout.maxConcurrent` default (4) plus the
- * driver's own call still 429s a single-driver Claude session; other
- * harnesses (pi, unknown) are unaffected — see `resolveFanoutEffectiveConcurrency`.
+ * docs/decisions/0069-claude-harness-fanout-concurrency-clamp.md, amended by
+ * docs/decisions/0083-raise-claude-fanout-concurrency-cap-to-4.md). The
+ * `GATE-EXEC-DISPATCH-RETRY-BACKOFF` retry/backoff policy turns a single 429
+ * into latency instead of a failed drive, so this cap only bounds the
+ * steady-state per-wave burst (driver + dispatch units) for a single-driver
+ * Claude session; other harnesses (pi, unknown) are unaffected — see
+ * `resolveFanoutEffectiveConcurrency`.
  */
-export const CLAUDE_MAX_EFFECTIVE_CONCURRENT = 2;
+export const CLAUDE_MAX_EFFECTIVE_CONCURRENT = 4;
 
 /**
  * Resolve the effective fan-out concurrency (dispatch units per wave): 1 when
@@ -2438,6 +2485,51 @@ export function resolveGateTier(config, gate, { changedFiles, filesChanged, line
   return { tier: matched.name, angles: [...new Set([...mandatoryAngles, ...matched.angles])], reason: "tier_match" };
 }
 
+/**
+ * Best-effort angle selection for a diff no diff-class tier matched (an
+ * unclassifiable file, a dev-loop config-source delta, or no tier configured).
+ * Uncertainty selects the mandatory floor plus the lenses the diff still
+ * justifies — the always-include lens and any consumer angle whose declared
+ * category/kind binding intersects the diff. It is never the whole pool,
+ * except for the degenerate gate whose pool holds neither a mandatory nor an
+ * always-include angle: an empty best-effort selection falls back to the static
+ * pool (fail-closed — more angles, not fewer) rather than returning nothing.
+ *
+ * `dynamic.subtractive: false` is the documented opt-out ("restore the full
+ * static angle pool"); this returns the static pool unchanged, mirroring
+ * resolveGateAnglesDynamic's `!gateConfig.dynamicAngles` branch so the composer
+ * and the resolver agree for the same diff.
+ *
+ * This composer has no diff TEXT (only the changed-file list), so it can bind
+ * on file kinds but not on hunk-derived change categories. Except for the
+ * `gate:full` path, it is therefore a lower bound: the round's authoritative
+ * angle set is resolved by resolveGateAnglesDynamic, which can add lenses bound
+ * to real change categories. On `gate:full`, the composer deliberately returns
+ * the full static pool and is instead a superset of the dynamic resolver.
+ */
+function selectFloorPlusJustifiedAngles(config, gate, changedFiles) {
+  const gateConfig = resolveGateConfig(config, gate);
+  // Documented opt-out: `dynamic.subtractive: false` restores the full static
+  // pool. Mirror resolveGateAnglesDynamic's `!gateConfig.dynamicAngles` branch
+  // so the composer and the resolver never disagree under an explicit operator
+  // config (both are callers of the same selection contract).
+  if (!gateConfig.dynamicAngles) return resolveGateAngles(config, gate) ?? [];
+  const { mandatoryAngles } = resolveGateAngleContract(config, gate);
+  const pool = resolveGateAngles(config, gate) ?? [];
+  const candidatePool = pool.filter((a) => !mandatoryAngles.includes(a));
+  const validChangedFiles = (Array.isArray(changedFiles) ? changedFiles : [])
+    .filter((f) => typeof f === "string" && f.trim().length > 0);
+  const fileKinds = [...new Set(validChangedFiles.map((f) => classifyFile(f)))];
+  const { recommendedAngles } = resolveDynamicAngles({
+    configuredAngles: candidatePool,
+    changeCategories: [],
+    fileKinds,
+    angleDeclarations: gateConfig.angleCategoryBindings,
+  });
+  const selected = [...new Set([...mandatoryAngles, ...recommendedAngles])];
+  return selected.length > 0 ? selected : pool;
+}
+
 /**
  * The primer-owned deterministic review-proportionality plan
  * (GATE-EXEC-PROPORTIONALITY, gate-review-sub-loop-contract.md): a single,
@@ -2445,25 +2537,25 @@ export function resolveGateTier(config, gate, { changedFiles, filesChanged, line
  * set + execution mode + grouping) is one testable, persistable object.
  * Delegates entirely to {@link resolveGateDispatchMode} (mode, including the
  * non-overridable size-cap/risk-path/size-outcome/ambiguity floors),
- * {@link resolveGateTier} (angle set AND diff-classification), and
- * {@link resolveFanoutGroups} (dispatch-unit grouping). No git I/O, no logic
+ * {@link resolveGateTier} (angle set AND diff-classification),
+ * {@link resolveDynamicAngles} (no-tier best-effort selection), and {@link
+ * resolveFanoutGroups} (dispatch-unit grouping). No git I/O, no logic
  * of its own beyond the floor-vs-tier precedence below: this is the ONE place
  * the primer (emit) and the merge gate (re-verify) compose mode + angles +
  * grouping, so they can never drift onto two different floor implementations.
  *
- * Floor-vs-tier precedence: a fired RISK-signal floor — the risk-path
- * denylist (`risk_path_touch`), a non-clean/ambiguous size-budget outcome
- * (`size_outcome_*`, `size_outcome_unavailable`), missing changed-file
- * evidence (`changed_files_unavailable`), or an unclassifiable diff
- * (`resolveGateTier`'s `unclassifiable_file`) — ALWAYS forces `full_fanout`
- * with the FULL untriered angle pool, never a matched tier's reduced set. The
- * hard size cap (`over_threshold`) differs: it ALWAYS forces `full_fanout`
- * MODE (distinct-reviewer-per-angle, never the light single-combined path)
- * but does NOT force the full untriered pool — a merely-over-cap-but-tier-
- * classifiable diff keeps its diff-class-tier-reduced angle set (the
- * pre-existing, orthogonal mechanism), untouched for a `gate:full`-labelled
- * PR (resolveGateTier self-bypasses) or a repo with light mode disabled
- * (`light_mode_disabled` is not a floor).
+ * Floor-vs-tier precedence: every fired floor affects DISPATCH only. A
+ * RISK-signal floor — the risk-path denylist (`risk_path_touch`), a non-clean/
+ * ambiguous size-budget outcome (`size_outcome_*`,
+ * `size_outcome_unavailable`), missing changed-file evidence
+ * (`changed_files_unavailable`), or an unclassifiable diff
+ * (`resolveGateTier`'s `unclassifiable_file`) — ALWAYS forces `full_fanout`,
+ * as does the hard size cap (`over_threshold`). The angle SET remains the
+ * matched tier or, when no tier matched, the mandatory floor plus the lenses
+ * justified by the changed-file kinds. It never widens to the full untriered
+ * pool merely because a floor fired. A `gate:full` label (which self-bypasses
+ * tier matching) and disabled light mode continue to govern dispatch mode
+ * independently; `light_mode_disabled` is not a floor.
  *
  * @param {DevLoopConfig} config
  * @param {"draft"|"preApproval"} gate
@@ -2500,23 +2592,24 @@ export function resolveReviewProportionality(config, gate, {
     // dispatch-mode facts alone looked trivial.
     unclassifiable: tier.reason === "unclassifiable_file",
   });
-  // sizeCap (over_threshold) is deliberately EXCLUDED from the forced-full-
-  // pool set: it predates this change's risk/ambiguity floors and pre-existing
-  // behavior (the diff-class-tier mechanism) keeps a merely-over-the-tiny-
-  // inline-cap-but-still-tier-classifiable diff on its reduced tier set — see
-  // resolveGateTier's "small non-risky diff outside the inline cap but
-  // matching a tier" contract. Only a genuine RISK signal (a risk-path touch,
-  // a non-clean/ambiguous size-budget outcome, or an unclassifiable diff)
-  // forces the full untriered pool.
+  // sizeCap (over_threshold) is deliberately EXCLUDED from the risk-signal
+  // floor set: it predates the risk/ambiguity floors. Every floor affects the
+  // dispatch mode only; angle selection remains tiered or best-effort.
   const dispatchFloorFired = floors.riskPath || floors.sizeOutcome || floors.ambiguity;
   const floored = dispatchFloorFired || floors.unclassifiable;
   const mode = floored ? "full_fanout" : dispatch.mode;
   const reason = floored && !dispatchFloorFired ? "unclassifiable_diff" : dispatch.reason;
   // The mandatory-angle floor is present either way: a tier match already
-  // unions mandatoryAngles in (resolveGateTier), and the no-tier fallback
-  // (resolveGateAngles) does the same union — see AC-4 "mandatory angles
-  // combined, never dropped".
-  const angles = floored ? resolveGateAngles(config, gate) : (tier.angles ?? resolveGateAngles(config, gate));
+  // unions mandatoryAngles in (resolveGateTier), and the no-tier best-effort
+  // selection does the same union — see AC-4 "mandatory angles combined,
+  // never dropped". A `gate:full` label is the explicit "run everything"
+  // escape hatch (ADR 0048): it keeps forcing the full configured pool, which
+  // is also what resolveGateTier's gate_full_label bypass left in place before
+  // best-effort selection existed.
+  const staticAngles = resolveGateAngles(config, gate);
+  const angles = hasFullLabel
+    ? staticAngles
+    : (tier.angles ?? (staticAngles === null ? null : selectFloorPlusJustifiedAngles(config, gate, changedFiles)));
   const groups = resolveFanoutGroups(config, gate, angles ?? [], { fullLabel: hasFullLabel });
   return Object.freeze({
     mode,
@@ -2531,9 +2624,10 @@ export function resolveReviewProportionality(config, gate, {
  * Resolve gate angles dynamically when `dynamicAngles` is enabled.
  *
  * Diff analysis (../analysis/*) filters the configured angle list to angles
- * relevant to the change set. When `dynamic.subtractive: false` or no
- * diff is given, returns the full configured list. When `additiveAngles` is on,
- * catalog angles from resolveAnglePool may also be added, with
+ * relevant to the change set. When `dynamic.subtractive: false`, returns the
+ * full configured list. Without a diff, ordinary callers keep that static pool
+ * while floor-aware callers use mandatory-floor best-effort selection. When
+ * `additiveAngles` is on, catalog angles from resolveAnglePool may also be added, with
  * `excludeAngles` a hard ceiling.
  *
  * Diff-class tiers (resolveGateTier) are consulted FIRST: a tier match returns
@@ -2542,15 +2636,14 @@ export function resolveReviewProportionality(config, gate, {
  *
  * GATE-EXEC-PROPORTIONALITY floor-awareness (opt-in via `checkFloors`): when
  * the caller supplies `checkFloors: true` (and, when available, `sizeOutcome`
- * from check-size-budget.mjs), this delegates to {@link
+ * from check-size-budget.mjs), this delegates floor determination to {@link
  * resolveReviewProportionality} — the SAME composer resolve-gate-dispatch.mjs
- * uses — over the SAME diff-derived changed-file/scope facts, so a diff whose
- * dispatch decision is floored (risk-path touch, a non-clean/ambiguous
- * size-budget outcome, or an unclassifiable diff) NEVER keeps a tier's
- * reduced (or dynamically-pruned) angle set here: it gets the full untriered
- * pool, exactly like the primer's own dispatch-decision step. Omitted
- * (default), this resolves exactly as before — a caller that does not have
- * size-budget evidence to hand is unaffected.
+ * uses — over the SAME diff-derived changed-file/scope facts. A fired floor
+ * forces `full_fanout` DISPATCH and refuses an explicit override, but the angle
+ * SET is always the tier-or-dynamic best-effort selection below; uncertainty
+ * never widens it to the full untriered pool. Omitted (default), this resolves
+ * exactly as before — a caller that does not have size-budget evidence to hand
+ * is unaffected.
  *
  * @param {import("./types.js").DevLoopConfig} config
  * @param {"draft"|"preApproval"} gate
@@ -2559,7 +2652,7 @@ export function resolveReviewProportionality(config, gate, {
  * @param {boolean} [options.hasFullLabel] — `gate:full` label present on the PR (bypasses tier resolution)
  * @param {boolean} [options.checkFloors] — opt into the GATE-EXEC-PROPORTIONALITY floor check above
  * @param {{ outcome?: "pass"|"escalate"|"block", tierLogicLoc?: { t1?: number } }|null} [options.sizeOutcome] — only consulted when `checkFloors` is true
- * @param {string[]} [options.explicitAngles] — caller-supplied verbatim override (e.g. CLI `--angles`); wins over tier/dynamic resolution but NEVER over a fired floor above (a fired floor's full pool, mandatory angles included via resolveGateAngles, is returned instead)
+ * @param {string[]} [options.explicitAngles] — caller-supplied verbatim override (e.g. CLI `--angles`); wins over tier/dynamic resolution but NEVER over a fired floor above (a fired floor refuses the override and continues to tier/dynamic best-effort selection)
  * @returns {{ recommendedAngles: string[] | null, skippedAngles: string[], reasons: Record<string,string>, fallbackToAll: boolean, dynamicAnglesActive: boolean, addedAngles: string[], addedReasons: Record<string,string> }}
  */
 export async function resolveGateAnglesDynamic(config, gate, { diff, hasFullLabel = false, checkFloors = false, sizeOutcome, explicitAngles } = {}) {
@@ -2581,30 +2674,20 @@ export async function resolveGateAnglesDynamic(config, gate, { diff, hasFullLabe
       linesChanged = lineStats.added + lineStats.deleted;
     }
   }
-  if (checkFloors) {
-    const plan = resolveReviewProportionality(config, gate, {
-      scope: { filesChanged, linesChanged },
-      changedFiles,
-      sizeOutcome,
-      hasFullLabel,
-    });
-    if (plan.floors.riskPath || plan.floors.sizeOutcome || plan.floors.ambiguity || plan.floors.unclassifiable) {
-      return {
-        recommendedAngles: plan.angles ?? [],
-        skippedAngles: [],
-        reasons: {},
-        fallbackToAll: false,
-        dynamicAnglesActive: false,
-        addedAngles: [],
-        addedReasons: {},
-      };
-    }
-  }
-  // A fired floor above always wins (its full pool already includes the
-  // mandatory floor via resolveGateAngles) — an explicit --angles override is
-  // only honored once no floor fired, matching its documented "verbatim,
-  // dynamic resolution bypassed" contract.
-  if (Array.isArray(explicitAngles)) {
+  const plan = checkFloors
+    ? resolveReviewProportionality(config, gate, {
+        scope: { filesChanged, linesChanged },
+        changedFiles,
+        sizeOutcome,
+        hasFullLabel,
+      })
+    : null;
+  const floorFired = plan !== null && (
+    plan.floors.riskPath || plan.floors.sizeOutcome || plan.floors.ambiguity || plan.floors.unclassifiable
+  );
+  // A fired floor refuses an explicit --angles override. Selection falls
+  // through to the same tier/dynamic best-effort path as every other diff.
+  if (Array.isArray(explicitAngles) && !floorFired) {
     return {
       recommendedAngles: explicitAngles,
       skippedAngles: [],
@@ -2644,12 +2727,24 @@ export async function resolveGateAnglesDynamic(config, gate, { diff, hasFullLabe
   }
 
   if (!gateConfig.dynamicAngles || !diff) {
+    // No diff to select on (a thin briefing) or dynamic resolution explicitly
+    // disabled by config. An explicitly disabled resolver keeps its static pool
+    // — that is the config asking for every angle. When dynamic resolution is
+    // enabled, a floor-aware caller that simply has no diff still gets the
+    // composer's mandatory-floor-plus-justified set rather than the whole pool,
+    // so absence of evidence never widens the angle set either.
+    const bestEffortWithoutDiff = Boolean(!diff && plan && gateConfig.dynamicAngles);
+    const recommendedAngles = bestEffortWithoutDiff ? (plan.angles ?? staticAngles) : staticAngles;
+    const recommended = new Set(recommendedAngles);
+    const skippedAngles = staticAngles.filter((a) => !recommended.has(a));
     return {
-      recommendedAngles: staticAngles,
-      skippedAngles: [],
-      reasons: {},
+      recommendedAngles,
+      skippedAngles,
+      reasons: Object.fromEntries(
+        skippedAngles.map((a) => [a, "Skipped: no diff is available to select on; the mandatory floor plus justified lenses were selected instead"]),
+      ),
       fallbackToAll: false,
-      dynamicAnglesActive: false,
+      dynamicAnglesActive: bestEffortWithoutDiff,
       addedAngles: [],
       addedReasons: {},
     };
@@ -2668,6 +2763,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.
@@ -2676,12 +2775,13 @@ export async function resolveGateAnglesDynamic(config, gate, { diff, hasFullLabe
     ? resolveAnglePool(config).filter(a => !excluded.has(a))
     : undefined;
 
-  const { resolveDynamicAngles: resolve } = await import("../analysis/change-classifier.mjs");
-  const dynamicResult = resolve({
+  const dynamicResult = resolveDynamicAngles({
     configuredAngles: candidatePool,
     changeCategories: categories,
     ambiguous: analysis.ambiguous,
     anglePool,
+    angleDeclarations: gateConfig.angleCategoryBindings,
+    fileKinds,
   });
 
   // Merge: mandatory always included (filtered by excludeAngles) + dynamically-selected
@@ -2696,12 +2796,24 @@ export async function resolveGateAnglesDynamic(config, gate, { diff, hasFullLabe
     Object.entries(dynamicResult.addedReasons ?? {}).filter(([a]) => !mandatory.has(a))
   );
 
-  const recommendedAngles = [...new Set([...filteredMandatory, ...dynamicResult.recommendedAngles, ...addedAngles])];
+  const mergedAngles = [...new Set([...filteredMandatory, ...dynamicResult.recommendedAngles, ...addedAngles])];
+
+  // Degenerate-pool fail-closed: a gate whose configured pool holds neither a
+  // mandatory nor an always-include angle (e.g. `angles: ["kiss"]`) can legally
+  // resolve to zero angles for an unclassifiable diff. Never resolve zero
+  // angles — fall back to the static pool (already excludeAngles-filtered),
+  // mirroring selectFloorPlusJustifiedAngles and the composer, so the resolver
+  // and the composer agree for the identical input. The whole pool is selected,
+  // so nothing is skipped and no angle carries a skip reason.
+  const degenerateFallback = mergedAngles.length === 0;
+  const recommendedAngles = degenerateFallback ? [...staticAngles] : mergedAngles;
+  const skippedAngles = degenerateFallback ? [] : dynamicResult.skippedAngles;
+  const reasons = degenerateFallback ? {} : dynamicResult.reasons;
 
   return {
     recommendedAngles,
-    skippedAngles: dynamicResult.skippedAngles,
-    reasons: dynamicResult.reasons,
+    skippedAngles,
+    reasons,
     fallbackToAll: dynamicResult.fallbackToAll,
     dynamicAnglesActive: true,
     addedAngles,

package/src/config/extension-defaults.yaml

@@ -126,13 +126,39 @@ gates:
             implementation bugs, logic errors, contract violations, or security
             issues
           - Unresolved review threads that raise implementation concerns Flag any unresolved comment that identifies a concrete implementation problem as a blocking finding (severity: high or medium). Do not flag: - Resolved threads - Style nits, formatting suggestions, or cosmetic feedback - Comments from non-collaborators or bots - Outdated comments that were already addressed in a later commit If no unresolved implementation concerns exist, return clean.
-      - contradiction-lens
-      - code-conformance
-      - semantic-drift
+      - name: contradiction-lens
+        persona: review
+        prompt: "Apply STYLE-CONTRADICTION-LENS when the repo defines it (dev-loops: skills/docs/contract-style-guide.md): check every added or changed normative rule (MUST/SHOULD/MAY) against the repo's rule registry for opposing modality or a weaker restatement. Also flag statements in the diff, the PR body, touched contracts, or accepted decision records (for example docs/decisions/) that contradict each other. Cite both sides of each contradiction with file:line."
+      - name: code-conformance
+        persona: review
+        prompt: Review this change for conformance to existing repo code conventions and patterns. Compare naming, module layout, and helper reuse against neighboring code in the same package. Flag ad hoc patterns that diverge from an established convention without a stated reason.
+      - name: semantic-drift
+        persona: review
+        prompt: Review this change for semantic drift between code and its documented behavior. Compare the diff's actual logic against the intent stated in touched docs, contracts, and comments. Flag a documented behavior that no longer matches what the code does, or code whose behavior no longer matches what a touched doc or contract claims.
       - name: pr-description
         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 +247,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,9 +328,35 @@ 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.
-      - contradiction-lens
-      - correctness-final
-      - ui-validation
+      - 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.
+      - name: contradiction-lens
+        persona: review
+        prompt: "Apply STYLE-CONTRADICTION-LENS when the repo defines it (dev-loops: skills/docs/contract-style-guide.md): check every added or changed normative rule (MUST/SHOULD/MAY) against the repo's rule registry for opposing modality or a weaker restatement. Also flag statements in the diff, the PR body, touched contracts, or accepted decision records (for example docs/decisions/) that contradict each other. Cite both sides of each contradiction with file:line."
+      - name: correctness-final
+        persona: review
+        prompt: Perform a final correctness pass on the current head. Flag residual logic errors, contract violations, and behavior mismatches introduced or left unfixed since the draft gate.
+      - name: ui-validation
+        persona: review
+        prompt: "Review this change against the repo's UI validation contract when it defines one (dev-loops: skills/docs/ui-validation-contract.md and skills/docs/ui-e2e-scoping-step.md). When the changed-file set matches the UI e2e scoping globs, verify passing UI e2e coverage exists and that each touched rendered artifact is registered; an unregistered new artifact is a blocking finding. Return clean when no changed path matches or the repo defines no UI validation contract."
     required: true
   # Relaxed spike gate profile (#965). A spike's deliverable is a findings doc,
   # not production code, so it is intentionally lighter than the production