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

package/src/config/config.mjs

@@ -6,8 +6,11 @@ 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";
+import { matchesDiffExcludeGlob } from "../loop/review-dispatch-plan.mjs";
 
 // ============================================================================
 // Sub-schemas
@@ -43,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",
 });
 
@@ -111,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
@@ -130,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
@@ -214,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."),
@@ -232,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(),
@@ -425,6 +450,12 @@ const LocalImplementationConfig = z.strictObject({
     // Composes with (does not replace) refinement.maxCopilotRounds — see
     // resolveEffectiveCopilotRoundCap.
     maxCopilotRounds: z.number().int().nonnegative().default(1).describe("Copilot round cap for light-dispatched PRs; composes as min(this, refinement.maxCopilotRounds)."),
+    // Purely ADDITIVE on top of the hard-coded RISK_PATH_DENYLIST_DEFAULT floor
+    // (resolveGateDispatchMode/touchesRiskPath) — this field can only ADD extra
+    // risk-path globs for a repo, never remove/replace the shipped floor, so a
+    // layer that sets its own lightMode block (as this repo's .devloops already
+    // does for maxFiles/maxLines) can never silently drop the floor.
+    riskPaths: z.array(z.string().trim().min(1)).describe("Repo-specific extra glob patterns that force full fan-out regardless of size, layered ON TOP of the shipped risk-path denylist floor (never replacing it).").optional(),
   }).optional(),
   /**
    * Opt into issue-less PR-first at ANY change scope. Decoupled from lightMode:
@@ -908,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") {
@@ -932,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;
@@ -941,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 [];
@@ -1231,15 +1273,18 @@ function mergeAngleArrays(targetRaw, sourceRaw) {
  * @param {string} filePath
  * @returns {Promise<object|null>}
  */
-async function readConfigFile(filePath) {
-  let raw;
-  try {
-    raw = await readFile(filePath, "utf8");
-  } catch (err) {
-    if (err.code === "ENOENT") return null;
-    throw configError(`Cannot read config file: ${err.message}`, err.code, filePath);
-  }
-
+/**
+ * Parse already-read config text (YAML or JSON, keyed off `filePath`'s
+ * extension) into a plain object. Split out of {@link readConfigFile} so a
+ * caller that already has the raw text from somewhere other than this
+ * checkout's disk (e.g. `loadDevLoopConfig`'s `devloopsOverride`, which reads
+ * a PR head commit's `.devloops` via git) can reuse the exact same parsing
+ * rules instead of re-implementing them.
+ * @param {string} raw
+ * @param {string} filePath - used only for its extension and in error messages
+ * @returns {Record<string, unknown>}
+ */
+function parseConfigContent(raw, filePath) {
   if (raw.trim() === "") {
     throw configError("Config file is empty", "EMPTY_FILE", filePath);
   }
@@ -1274,6 +1319,17 @@ async function readConfigFile(filePath) {
   return parsed;
 }
 
+async function readConfigFile(filePath) {
+  let raw;
+  try {
+    raw = await readFile(filePath, "utf8");
+  } catch (err) {
+    if (err.code === "ENOENT") return null;
+    throw configError(`Cannot read config file: ${err.message}`, err.code, filePath);
+  }
+  return parseConfigContent(raw, filePath);
+}
+
 /**
  * Find a config file by trying one or more base names in order.
  * Each base name prefers YAML (.yaml, then .yml) before JSON.
@@ -1355,6 +1411,24 @@ async function applyLayer(merged, basePaths, layer, warnings, errors, options =
     return merged;
   }
 
+  return applyParsedLayer(merged, filePath, data, layer, warnings, errors);
+}
+
+/**
+ * Validate + merge one already-parsed config layer's data into `merged`.
+ * Split out of {@link applyLayer} so `loadDevLoopConfig`'s `devloopsOverride`
+ * (a PR head commit's `.devloops`, read via git rather than this checkout's
+ * disk) goes through the exact same deprecation normalization, schema
+ * validation, and merge rules as every disk-sourced layer.
+ * @param {Record<string, unknown>} merged
+ * @param {string} filePath - source path/label, used in warnings/errors only
+ * @param {Record<string, unknown>} data - already-parsed layer content
+ * @param {"extensionDefaults"|"defaults"|"devloops"} layer
+ * @param {string[]} warnings
+ * @param {ConfigLoadError[]} errors
+ * @returns {Record<string, unknown>}
+ */
+function applyParsedLayer(merged, filePath, data, layer, warnings, errors) {
   // Deprecated `strategy: "github-first"` alias: normalized to
   // "tracker-first" BEFORE this layer's FileConfigSchema validation (the enum
   // only accepts the canonical value, else the whole layer drops as invalid).
@@ -1434,6 +1508,7 @@ async function applyLayer(merged, basePaths, layer, warnings, errors, options =
  * @typedef {object} LoadOptions
  * @property {string} [repoRoot] - Path to repository root (default: process.cwd())
  * @property {string} [extensionDefaultsBasePath] - Base path (no extension) to extension defaults; overrides the package-relative default
+ * @property {{ raw: string|null, path?: string }} [devloopsOverride] - When present, sources the devloops (primary override) layer from `raw` instead of reading `<repoRoot>/.devloops*` off disk; `raw: null` means "no .devloops at this source" (a legitimate state, distinct from omitting the option entirely, which reads disk as usual)
  */
 
 /**
@@ -1465,26 +1540,52 @@ export async function loadDevLoopConfig(options = {}) {
     warnOnMissing: true,
   });
 
-  // .devloops (primary override) existence: only ENOENT means genuinely absent.
-  // Any other error (EACCES/EISDIR) means it exists but is unreadable, so
-  // select the .devloops path and let applyLayer record the structured error.
-  let primaryExists = false;
-  for (const ext of ["", ".yaml", ".yml", ".json"]) {
-    try {
-      await readFile(devloopsPath + ext, "utf8");
-      primaryExists = true;
-      break;
-    } catch (err) {
-      if (err?.code !== "ENOENT") {
+  // `devloopsOverride` sources the devloops (primary override) layer's
+  // content directly instead of reading this checkout's disk file — used to
+  // resolve config from a different ref (e.g. a PR head commit, read via git)
+  // while extensionDefaults and .pi/dev-loop/defaults still come from
+  // repoRoot on disk. Presence of the key (even `{ raw: null }`,
+  // meaning "no .devloops at that ref") switches modes; omitting the option
+  // entirely preserves today's disk-read behavior.
+  if (options.devloopsOverride !== undefined) {
+    const { raw, path: overridePath = devloopsPath } = options.devloopsOverride ?? {};
+    if (typeof raw === "string") {
+      try {
+        const data = parseConfigContent(raw, overridePath);
+        merged = applyParsedLayer(merged, overridePath, data, "devloops", warnings, errors);
+      } catch (err) {
+        errors.push({
+          path: overridePath,
+          message: `${path.basename(overridePath)}: ${err.message}`,
+          layer: "devloops",
+        });
+      }
+    }
+    // raw == null: no .devloops present at the overridden source — leave
+    // `merged` at extensionDefaults+defaults, mirroring primaryExists: false
+    // below.
+  } else {
+    // .devloops (primary override) existence: only ENOENT means genuinely absent.
+    // Any other error (EACCES/EISDIR) means it exists but is unreadable, so
+    // select the .devloops path and let applyLayer record the structured error.
+    let primaryExists = false;
+    for (const ext of ["", ".yaml", ".yml", ".json"]) {
+      try {
+        await readFile(devloopsPath + ext, "utf8");
         primaryExists = true;
         break;
+      } catch (err) {
+        if (err?.code !== "ENOENT") {
+          primaryExists = true;
+          break;
+        }
+        // ENOENT — genuinely absent, try next extension
       }
-      // ENOENT — genuinely absent, try next extension
     }
-  }
 
-  if (primaryExists) {
-    merged = await applyLayer(merged, devloopsPath, "devloops", warnings, errors);
+    if (primaryExists) {
+      merged = await applyLayer(merged, devloopsPath, "devloops", warnings, errors);
+    }
   }
 
   // Validate final merged config
@@ -1704,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
@@ -1741,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 ?? [] }]),
+    ),
   };
 }
 
@@ -1819,6 +1930,11 @@ export function resolveLightMode(config) {
     maxLines: typeof cfg.maxLines === "number" && Number.isFinite(cfg.maxLines) && cfg.maxLines > 0
       ? cfg.maxLines
       : 200,
+    // Repo-specific ADDITIONS to the risk-path floor (see touchesRiskPath) —
+    // never the floor itself, which is hard-coded and always applied first.
+    riskPaths: Array.isArray(cfg.riskPaths)
+      ? cfg.riskPaths.filter((p) => typeof p === "string" && p.trim().length > 0)
+      : [],
   };
 }
 
@@ -1858,17 +1974,144 @@ export function resolveEffectiveCopilotRoundCap(config, { lightweight = false }
 /** Label that forces full fan-out regardless of change size. */
 export const GATE_FULL_LABEL = "gate:full";
 
+/**
+ * Conservative, hard-coded risk-path denylist floor (GATE-EXEC-PROPORTIONALITY,
+ * gate-review-sub-loop-contract.md): a diff touching any of these trees forces
+ * full fan-out regardless of size. Hard-coded here — never sourced purely from
+ * `.devloops`/extension-defaults layers — so a config layer that replaces its
+ * own `localImplementation.lightMode` block (as this repo's own `.devloops`
+ * already does for maxFiles/maxLines) can only ADD extra globs
+ * (`lightMode.riskPaths`, unioned in by {@link touchesRiskPath}) and can never
+ * drop this floor. Mirrors `DEFAULT_DIFF_EXCLUDE_GLOBS`'s "shipped default
+ * always applied first, caller can only extend it" pattern
+ * (review-dispatch-plan.mjs). Every glob is deliberately OVER-inclusive per the
+ * "ambiguity resolves toward MORE review" rule — a borderline path SHOULD trip
+ * full fan-out, never quietly pass through:
+ *  - gate/review: the dispatch-decision and fan-out/fan-in review-sub-loop
+ *    machinery itself — a change here can move the very floor that decides
+ *    review depth, so it always gets full review.
+ *  - security/auth: any path naming auth/token/secret/credential, plus the
+ *    dedicated security-tooling tree.
+ *  - contract: normative contract docs and the ADR/test surfaces that back
+ *    them.
+ *  - hook: repo/CI hook wiring that runs on every commit or tool call.
+ *  - release: publish/tag machinery, release CI workflows, and package
+ *    publication metadata.
+ * Glob subset (see {@link matchesDiffExcludeGlob}): `**\/` matches
+ * zero-or-more whole path segments, a lone `**` matches any suffix, a single
+ * `*` matches within one path segment only.
+ */
+export const RISK_PATH_DENYLIST_DEFAULT = Object.freeze([
+  // gate / review — the proportionality mechanism's own implementation, plus
+  // any path named gate/review anywhere under scripts/ or packages/core/src/loop.
+  "packages/core/src/config/config.mjs",
+  "packages/core/src/config/extension-defaults.yaml",
+  "scripts/loop/check-size-budget.mjs",
+  "scripts/loop/check-adr-tripwire.mjs",
+  "scripts/loop/resolve-gate-dispatch.mjs",
+  "scripts/loop/detect-change-scope.mjs",
+  "scripts/github/detect-checkpoint-evidence.mjs",
+  "scripts/github/upsert-checkpoint-verdict.mjs",
+  "scripts/github/emit-fanout-dispatch.mjs",
+  "scripts/loop/consolidate-fanin.mjs",
+  "scripts/**/*gate*",
+  "scripts/**/*review*",
+  "packages/core/src/loop/*gate*",
+  "packages/core/src/loop/*gate*/**",
+  "packages/core/src/loop/*review*",
+  "packages/core/src/loop/*review*/**",
+  "skills/docs/gate-review-*",
+  // security / auth
+  "**/*auth*",
+  "**/*token*",
+  "**/*secret*",
+  "**/*credential*",
+  "scripts/security/**",
+  // contract
+  "skills/docs/*-contract.md",
+  "test/contracts/**",
+  "docs/decisions/**",
+  // hook
+  ".claude/hooks/**",
+  ".githooks/**",
+  "scripts/**/*hook*",
+  // release
+  "scripts/release/**",
+  "scripts/**/*release*",
+  "scripts/**/*publish*",
+  ".github/workflows/*release*",
+  ".github/workflows/*publish*",
+  "package.json",
+  "**/package.json",
+]);
+
+/**
+ * Pure risk-path predicate: does ANY changed file match the shipped
+ * {@link RISK_PATH_DENYLIST_DEFAULT} floor or a repo's additive
+ * `localImplementation.lightMode.riskPaths` globs? Fails CLOSED (returns
+ * `true`) when `changedFiles` is not a readable array — absence of evidence is
+ * never triviality.
+ * @param {unknown} changedFiles — repo-relative paths, or anything non-array (ambiguous)
+ * @param {string[]} [extraDenylist] — additive globs from config; never replaces the floor
+ * @returns {boolean}
+ */
+export function touchesRiskPath(changedFiles, extraDenylist = []) {
+  if (!Array.isArray(changedFiles)) return true;
+  const denylist = [...RISK_PATH_DENYLIST_DEFAULT, ...(Array.isArray(extraDenylist) ? extraDenylist : [])];
+  return changedFiles.some((f) => {
+    const posix = String(f).replace(/\\/g, "/");
+    return denylist.some((pattern) => matchesDiffExcludeGlob(posix, pattern));
+  });
+}
+
+/**
+ * Pure predicate: is a check-size-budget.mjs sizeOutcome genuinely T1-clean —
+ * a `pass` outcome AND a finite, non-negative T1-tier slice equal to 0 (the
+ * clean value)? `undefined > 0` and `NaN > 0` both evaluate false, so a bare
+ * `!(t1 > 0)` comparison would read malformed/absent T1 evidence (a missing
+ * `tierLogicLoc`, a non-numeric `t1`) as clean and admit the light path on
+ * unreadable evidence. This requires a genuine NUMBER, never a truthiness
+ * check, so malformed evidence fails CLOSED exactly like a real
+ * size-budget computation error. The ONE shared predicate for this floor
+ * (GATE-EXEC-PROPORTIONALITY): `resolveGateDispatchMode` below and the
+ * size-budget merge gate (scripts/github/detect-checkpoint-evidence.mjs) both
+ * call it, so they never drift onto two independently-maintained floor
+ * implementations — mirroring how {@link touchesRiskPath} is the one shared
+ * risk-path predicate.
+ * @param {{ outcome?: string, tierLogicLoc?: { t1?: number } }|null|undefined} sizeOutcome
+ * @returns {boolean}
+ */
+export function isSizeOutcomeT1Clean(sizeOutcome) {
+  if (sizeOutcome == null || typeof sizeOutcome !== "object") return false;
+  if (sizeOutcome.outcome !== "pass") return false;
+  const t1 = sizeOutcome.tierLogicLoc?.t1;
+  return typeof t1 === "number" && Number.isFinite(t1) && t1 === 0;
+}
+
 /**
  * Decide whether a gate runs as a single-agent inline check or full fan-out,
  * from light-mode config + authoritative PR facts.
  *
  * Precedence (first match wins):
- *   1. `gate:full` label present            → full_fanout
- *   2. light mode disabled / no threshold    → full_fanout
- *   3. scope over threshold (files OR lines) → full_fanout
- *   4. inline finding severity in the gate's blockCleanOnFindingSeverities set
- *                                            → full_fanout (escalated)
- *   5. otherwise                             → inline
+ *   1. `gate:full` label present              → full_fanout
+ *   2. light mode disabled / no threshold      → full_fanout
+ *   3. scope over threshold (files OR lines)   → full_fanout
+ *   4. `changedFiles` unavailable (ambiguous)  → full_fanout
+ *   5. a changed file touches a risk path      → full_fanout
+ *   6. `sizeOutcome` unavailable (ambiguous)    → full_fanout
+ *   7. size-outcome escalate/block             → full_fanout
+ *   8. size-outcome touches the T1 risk tier   → full_fanout
+ *   9. inline finding severity in the gate's blockCleanOnFindingSeverities set
+ *                                              → full_fanout (escalated)
+ *   10. otherwise                              → inline
+ *
+ * Steps 4-8 are the GATE-EXEC-PROPORTIONALITY non-overridable floors
+ * (gate-review-sub-loop-contract.md): they run only once the cheap file/line
+ * cap (step 3) has already passed, so an already-over-cap diff costs the
+ * caller nothing extra. A caller that omits `changedFiles`/`sizeOutcome` for
+ * an otherwise-under-cap diff fails CLOSED (full fan-out) rather than silently
+ * treating missing evidence as trivial — no flag/waiver/prompt can lower these
+ * floors.
  *
  * Pre-check omits `inlineFindingSeverities` (decides whether to run the inline
  * pass at all); escalation passes the inline pass's severities. Absent/partial
@@ -1878,11 +2121,13 @@ export const GATE_FULL_LABEL = "gate:full";
  * @param {"draft"|"preApproval"} gate
  * @param {object} facts
  * @param {{ filesChanged?: number, linesChanged?: number }} [facts.scope] PR scope; absent/partial fields fail safe to full_fanout
+ * @param {string[]} [facts.changedFiles] repo-relative changed-file paths; absent/non-array fails safe to full_fanout
+ * @param {{ outcome?: "pass"|"escalate"|"block", tierLogicLoc?: { t1?: number } }|null} [facts.sizeOutcome] check-size-budget.mjs's computeSizeBudget outcome; absent/null fails safe to full_fanout
  * @param {boolean} [facts.hasFullLabel]           `gate:full` label present on the PR
  * @param {string[]} [facts.inlineFindingSeverities] severities from the inline pass (escalation phase)
- * @returns {{ mode: "inline"|"full_fanout", reason: string, threshold: {maxFiles:number,maxLines:number}|null }}
+ * @returns {{ mode: "inline"|"full_fanout", reason: string, threshold: ({maxFiles:number,maxLines:number,riskPaths:string[]})|null }}
  */
-export function resolveGateDispatchMode(config, gate, { scope, hasFullLabel = false, inlineFindingSeverities } = {}) {
+export function resolveGateDispatchMode(config, gate, { scope, changedFiles, sizeOutcome, hasFullLabel = false, inlineFindingSeverities } = {}) {
   if (hasFullLabel) {
     return { mode: "full_fanout", reason: "gate_full_label", threshold: null };
   }
@@ -1895,6 +2140,31 @@ export function resolveGateDispatchMode(config, gate, { scope, hasFullLabel = fa
   if (filesChanged > threshold.maxFiles || linesChanged > threshold.maxLines) {
     return { mode: "full_fanout", reason: "over_threshold", threshold };
   }
+  if (!Array.isArray(changedFiles)) {
+    return { mode: "full_fanout", reason: "changed_files_unavailable", threshold };
+  }
+  if (touchesRiskPath(changedFiles, threshold.riskPaths)) {
+    return { mode: "full_fanout", reason: "risk_path_touch", threshold };
+  }
+  if (sizeOutcome == null || typeof sizeOutcome !== "object") {
+    return { mode: "full_fanout", reason: "size_outcome_unavailable", threshold };
+  }
+  if (sizeOutcome.outcome !== "pass") {
+    const outcomeLabel = typeof sizeOutcome.outcome === "string" && sizeOutcome.outcome.length > 0 ? sizeOutcome.outcome : "unknown";
+    return { mode: "full_fanout", reason: `size_outcome_${outcomeLabel}`, threshold };
+  }
+  // GATE-EXEC-PROPORTIONALITY: delegate the pass+T1-clean decision to the one
+  // shared predicate (isSizeOutcomeT1Clean, above) so this resolver and the
+  // size-budget merge gate never drift onto two independently-maintained
+  // floor implementations. A malformed/partial T1 value (missing, NaN,
+  // negative, non-numeric) is ambiguity, not triviality, so it fails CLOSED to
+  // `size_outcome_unavailable` exactly like a missing sizeOutcome altogether —
+  // never a naive `t1 > 0` truthiness read.
+  if (!isSizeOutcomeT1Clean(sizeOutcome)) {
+    const t1 = sizeOutcome.tierLogicLoc?.t1;
+    const reason = typeof t1 === "number" && Number.isFinite(t1) && t1 > 0 ? "size_outcome_t1" : "size_outcome_unavailable";
+    return { mode: "full_fanout", reason, threshold };
+  }
   if (Array.isArray(inlineFindingSeverities) && inlineFindingSeverities.length > 0) {
     // Both sides normalize legacy spellings so a "defer" finding still
     // compares against a "low" blocking entry and vice versa.
@@ -1933,15 +2203,31 @@ export function resolveFanoutSequential(config) {
   return s === true;
 }
 
+/**
+ * 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`.
+ */
+export const CLAUDE_MAX_EFFECTIVE_CONCURRENT = 2;
+
 /**
  * Resolve the effective fan-out concurrency (dispatch units per wave): 1 when
- * `gates.fanout.sequential` is set, else `resolveFanoutMaxConcurrent`.
+ * `gates.fanout.sequential` is set, else `resolveFanoutMaxConcurrent`. Under the
+ * Claude harness (`isClaudeHarness(env)`) that value is additionally
+ * clamped to `CLAUDE_MAX_EFFECTIVE_CONCURRENT` so a single-driver Claude
+ * session's per-wave burst (driver + dispatch units) stays within its rate
+ * limit without lowering the shipped cross-harness default (schema/config
+ * surface unchanged) or requiring an operator-imposed throttle. Every other
+ * harness (pi, unknown, no env) returns the configured value unchanged.
  * @param {DevLoopConfig} config
+ * @param {Record<string, string|undefined>} [env] — defaults to `process.env`
  * @returns {number}
  */
-export function resolveFanoutEffectiveConcurrency(config) {
-  if (resolveFanoutSequential(config)) return 1;
-  return resolveFanoutMaxConcurrent(config);
+export function resolveFanoutEffectiveConcurrency(config, env = process.env) {
+  const base = resolveFanoutSequential(config) ? 1 : resolveFanoutMaxConcurrent(config);
+  return isClaudeHarness(env) ? Math.min(base, CLAUDE_MAX_EFFECTIVE_CONCURRENT) : base;
 }
 
 /**
@@ -2196,6 +2482,95 @@ export function resolveGateTier(config, gate, { changedFiles, filesChanged, line
   return { tier: matched.name, angles: [...new Set([...mandatoryAngles, ...matched.angles])], reason: "tier_match" };
 }
 
+/**
+ * The primer-owned deterministic review-proportionality plan
+ * (GATE-EXEC-PROPORTIONALITY, gate-review-sub-loop-contract.md): a single,
+ * pure composition of the existing decision functions so "the plan" (angle
+ * 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
+ * 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).
+ *
+ * @param {DevLoopConfig} config
+ * @param {"draft"|"preApproval"} gate
+ * @param {object} facts
+ * @param {{ filesChanged?: number, linesChanged?: number }} [facts.scope]
+ * @param {string[]} [facts.changedFiles]
+ * @param {{ outcome?: "pass"|"escalate"|"block", tierLogicLoc?: { t1?: number } }|null} [facts.sizeOutcome]
+ * @param {boolean} [facts.hasFullLabel]
+ * @param {string[]} [facts.inlineFindingSeverities]
+ * @returns {{ mode: "inline"|"full_fanout", angles: string[]|null, groups: { name: string, angles: string[] }[], reason: string, floors: { sizeCap: boolean, riskPath: boolean, sizeOutcome: boolean, ambiguity: boolean, unclassifiable: boolean } }}
+ */
+export function resolveReviewProportionality(config, gate, {
+  scope,
+  changedFiles,
+  sizeOutcome,
+  hasFullLabel = false,
+  inlineFindingSeverities,
+} = {}) {
+  const dispatch = resolveGateDispatchMode(config, gate, { scope, changedFiles, sizeOutcome, hasFullLabel, inlineFindingSeverities });
+  const tier = resolveGateTier(config, gate, {
+    changedFiles,
+    filesChanged: scope?.filesChanged,
+    linesChanged: scope?.linesChanged,
+    hasFullLabel,
+  });
+  const floors = Object.freeze({
+    sizeCap: dispatch.reason === "over_threshold",
+    riskPath: dispatch.reason === "risk_path_touch",
+    sizeOutcome: typeof dispatch.reason === "string" && dispatch.reason.startsWith("size_outcome_") && dispatch.reason !== "size_outcome_unavailable",
+    ambiguity: dispatch.reason === "changed_files_unavailable" || dispatch.reason === "size_outcome_unavailable",
+    // resolveGateDispatchMode has no diff-classification awareness of its own
+    // (only resolveGateTier classifies files); an unclassifiable diff is
+    // ambiguity too and must not silently reach inline just because the
+    // 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.
+  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));
+  const groups = resolveFanoutGroups(config, gate, angles ?? [], { fullLabel: hasFullLabel });
+  return Object.freeze({
+    mode,
+    angles,
+    groups,
+    reason,
+    floors,
+  });
+}
+
 /**
  * Resolve gate angles dynamically when `dynamicAngles` is enabled.
  *
@@ -2209,14 +2584,29 @@ export function resolveGateTier(config, gate, { changedFiles, filesChanged, line
  * that tier's angle set (unioned with mandatory) directly and skips the
  * subtractive/additive machinery.
  *
+ * 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
+ * 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.
+ *
  * @param {import("./types.js").DevLoopConfig} config
  * @param {"draft"|"preApproval"} gate
  * @param {object} [options]
  * @param {{ nameStatusOutput: string, diffOutput?: string }} [options.diff]
  * @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)
  * @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 } = {}) {
+export async function resolveGateAnglesDynamic(config, gate, { diff, hasFullLabel = false, checkFloors = false, sizeOutcome, explicitAngles } = {}) {
   // Tier scope facts: changedFiles/filesChanged from T0, linesChanged from T1's
   // real added+deleted count (analyzeDiff's inferred-category path reports a
   // fake 0 for an unambiguous docs-only diff — see analyzeT1/analyzeDiff).
@@ -2235,6 +2625,40 @@ 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)) {
+    return {
+      recommendedAngles: explicitAngles,
+      skippedAngles: [],
+      reasons: {},
+      fallbackToAll: false,
+      dynamicAnglesActive: false,
+      addedAngles: [],
+      addedReasons: {},
+    };
+  }
   const tierResult = resolveGateTier(config, gate, { changedFiles, filesChanged, linesChanged, hasFullLabel });
   if (tierResult.tier) {
     const configuredAngles = resolveGateAngles(config, gate) ?? [];
@@ -2288,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.
@@ -2302,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