@dev-loops/core 1.0.0-rc.3 → 1.0.0-rc.5

package/src/config/config.mjs

@@ -1,9 +1,12 @@
 import { readFile } from "node:fs/promises";
+import { normalizeSeverity } from "../loop/gate-fanin.mjs";
 import { execFileSync } from "node:child_process";
 import path from "node:path";
 import { parse as parseYaml } from "yaml";
 import { fileURLToPath } from "node:url";
 import { z } from "zod";
+import { classifyFile } from "../analysis/diff-analyzer.mjs";
+import { isDevLoopConfigSourcePath } from "../loop/gate-carry-forward.mjs";
 
 // ============================================================================
 // Sub-schemas
@@ -118,12 +121,24 @@ const RefinementConfig = z.strictObject({
   roles: z.array(z.string().trim().min(1)).describe("Review lenses the refinement fan-out dispatches.").optional(),
 });
 
+// Per-angle surface scope: how much of the gate-context bundle an angle
+// actually needs. "full" (default) is today's omniscient briefing;
+// "changed-files" drops the adjacent-code bundle AND the invariant prefix's
+// "Changed files + adjacent-code summary" section (the diff itself still
+// carries every changed file); "docs-only" narrows further to doc-file
+// hunks only. Resolution (resolveGateAngleScope) fails open to "full" for an
+// unknown/missing value — a narrow scope is an opt-in cost saving, never a
+// silently-enforced information cut.
+export const GATE_ANGLE_SCOPES = Object.freeze(["full", "changed-files", "docs-only"]);
+
 // One review angle: a bare string is sugar for `{ name }`. An object may also
 // set `mandatory` (always runs, survives dynamic pruning — was
 // gates.<gate>.mandatoryAngles), `enabled: false` (drops it from the resolved
-// list — was gates.<gate>.excludeAngles, D3), and `persona`/`prompt`/`model`/
+// list — was gates.<gate>.excludeAngles, D3), `persona`/`prompt`/`model`/
 // `tier` (was the top-level `personas` map + angle-keyed
-// `models.roles`/`models.roleTiers`, D4: model > tier > built-in precedence).
+// `models.roles`/`models.roleTiers`, D4: model > tier > built-in precedence),
+// and `scope` (AC3: the surface briefing variant this angle needs — see
+// GATE_ANGLE_SCOPES).
 // This is the ONE identity for a gate-review angle (was five separate places
 // — see the config-schema RFC). `mergeConfigLayers` merges these arrays BY
 // `name` across config layers (D3), so a later layer can add or disable a
@@ -144,11 +159,51 @@ const GateAngleEntry = z.preprocess(
     prompt: z.string().min(1).optional().describe("Short focused instruction for the reviewer agent — what to look for and how to judge this angle."),
     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."),
   }),
 );
 
+// 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"]);
+
+// 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
+// set). At least one condition is required — a bare `{}` would match every
+// diff unconditionally, which is never the intent of an explicit tier entry.
+const GateTierMatch = z
+  .strictObject({
+    kinds: z.array(GateTierMatchKind).min(1).describe("Changed-file kinds this tier matches; every changed file's classifyFile() kind must be in this set.").optional(),
+    maxFiles: z.number().int().min(1).describe("Match only when the change touches at most this many files.").optional(),
+    maxLines: z.number().int().min(1).describe("Match only when the change stays within this many changed lines.").optional(),
+  })
+  .superRefine((match, ctx) => {
+    if (match.kinds === undefined && match.maxFiles === undefined && match.maxLines === undefined) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message: "match must set at least one of kinds, maxFiles, maxLines",
+      });
+    }
+  });
+
+// One diff-class angle tier: a fixed angle set applied instead of dynamic
+// subtractive/additive reduction when `match` holds. See resolveGateTier.
+const GateTier = z.strictObject({
+  name: z.string().trim().min(1).describe("Tier name; surfaces as the tier:<name> resolution reason."),
+  match: GateTierMatch.describe("Diff-class conditions that select this tier."),
+  angles: z.array(z.string().trim().min(1)).min(1).describe("Angle set this tier resolves to when matched; unioned with the gate's mandatory angles."),
+});
+
 const GateDynamicConfig = z.strictObject({
-  subtractive: z.boolean().default(false).describe("Enable diff-driven dynamic angle PRUNING for this gate (was gates.<gate>.dynamicAngles)."),
+  // Diff-driven dynamic angle selection is ON by default (#1579): a fresh
+  // install narrows the angle pool to what the diff-classifier recommends.
+  // mandatory:true angles stay a hard always-run floor; fallbackToAll fires
+  // when classification is ambiguous, degrading to the full static pool. Set
+  // subtractive:false to restore the full static angle pool (the gate:full label
+  // only forces per-angle dispatch of the still-pruned set, not the full pool —
+  // combine both for the original full static fan-out).
+  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 (#1048): when true, the
   // context-builder may also ADD catalog angles — from resolveAnglePool()
   // (gates.anglePool, or else the union of the persona registry and this
@@ -169,13 +224,96 @@ const GateConfig = z.strictObject({
   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."),
+  // Defect severities only (high/medium/low, plus their pre-rename spellings)
+  // — "question"/"nit" are non-defect categories that never block a clean
+  // verdict by severity: a question's own answered/never-deferred contract
+  // and a nit's immediate-defer disposition already decide its fate, so
+  // admitting either here would let a config block on a severity the
+  // disposition pass simultaneously auto-resolves.
   blockCleanOnFindingSeverities: z
-    .array(z.enum(["must-fix", "worth-fixing-now", "defer"]))
+    .array(z.enum(["high", "medium", "low", "must-fix", "worth-fixing-now", "nice-to-have", "defer"]))
     .min(1)
-    .default(["must-fix"])
-    .describe("Finding severities that block a clean gate verdict."),
+    .default(["high"])
+    .describe("Defect finding severities that block a clean gate verdict (high/medium/low only — \"question\"/\"nit\" are non-defect categories and never block by severity). \"must-fix\" is the deprecated legacy spelling of \"high\", \"worth-fixing-now\" of \"medium\", and \"nice-to-have\"/\"defer\" of \"low\"; consumers normalize them."),
+  // Per-gate medium fix window (#1581): an open medium finding stays in the
+  // in-gate fix loop through this many rounds of THIS gate's chain and is
+  // deferred (replied-to + resolved) from the next round on. Defaults to 3
+  // (the built-in MEDIUM_FIX_WINDOW fallback in
+  // scripts/github/_gate-finding-surface.mjs). high is exempt: it never
+  // defers and forces per-gate continuation until the gate round cap escalates.
+  // No schema-level `.default()`: resolveGateConfig applies the built-in
+  // fallback (3) only after checking BOTH this key and the deprecated
+  // `worthFixingNowFixWindow` alias. A schema-level default would fill this
+  // key on every config LAYER independently (each layer is parsed through
+  // this schema on its own before merging), permanently shadowing a layer
+  // that sets only the deprecated alias.
+  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."),
+  // Deprecated alias for `mediumFixWindow` (pre-rename key); accepted on read
+  // and normalized in resolveGateConfig so an unmigrated config still behaves
+  // identically. `mediumFixWindow` wins when both are set.
+  worthFixingNowFixWindow: z.number().int().nonnegative().optional().describe("Deprecated alias for mediumFixWindow (pre-rename key name); mediumFixWindow wins when both are set."),
+  // Ordered, first-match-wins diff-class angle tiers (see resolveGateTier).
+  // Absent/empty = tiers never apply, so a gate that never sets this key keeps
+  // today's dynamic-subtractive/additive/full-pool resolution unchanged.
+  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(),
+});
+
+// One named group of angles dispatched together onto a single reviewer under
+// grouped fan-out (AC6). `name` is recorded as the shared reviewer's
+// provenance `group` (see resolveFanoutGroups / fanoutReviewerPairingError).
+const FanoutGroup = z.strictObject({
+  name: z.string().trim().min(1).describe("Group name; recorded as the shared reviewer's provenance `group` when this group dispatches."),
+  angles: z.array(z.string().trim().min(1)).min(1).describe("Angle names batched onto one reviewer when this group resolves."),
 });
 
+// Angle-dispatch fan-out policy (AC6 + #1601 two-knob dispatch bounds). The
+// grouped default batches related angles from a static table onto one
+// reviewer per group, cutting the fixed per-reviewer briefing cost when
+// several angles read the same surface; `per-angle` keeps the original
+// one-reviewer-per-angle fan-out (bypasses configured groups). `gate:full` no
+// longer restores per-angle dispatch (ADR 0047 superseded by 0048): it forces
+// the full angle set upstream (resolveGateTier) and dispatches GROUPED here.
+// Two orthogonal bounds (issue #1601):
+//   maxAnglesPerGroup (N, default 3, min 1) — after configured-groups
+//     matching, leftover ungrouped angles auto-chunk into dispatch units of
+//     ≤N instead of singletons. mode: per-angle bypasses the table entirely
+//   maxConcurrent (M, default 4, min 1) — the conductor dispatches at most M
+//     dispatch units per wave (scheduleFanoutWaves via scheduleParallelWaves).
+// An angle resolved for a round but not named in any configured group joins
+// the auto-chunked leftover pool — `groups` need only list the angles worth
+// batching explicitly.
+const FanoutConfig = z.strictObject({
+  mode: z.enum(["grouped", "per-angle"]).default("grouped").describe("Angle dispatch mode: grouped batches related angles onto one reviewer each (default); per-angle bypasses the configured-groups table and emits one singleton unit per angle (the original full-scrutiny shape). per-angle is equivalent to maxAnglesPerGroup: 1 in dispatch unit size ONLY when no configured multi-angle group matches a resolved angle; otherwise per-angle bypasses configured groups while maxAnglesPerGroup: 1 honors them (matched first, never split)."),
+  groups: z.array(FanoutGroup).optional().describe("Static named angle groups consulted in grouped mode. An angle absent from every group joins the auto-chunked leftover pool (chunked into units of ≤maxAnglesPerGroup)."),
+  maxAnglesPerGroup: z.number().int().min(1).default(3).describe("Max angles per auto-chunked dispatch unit for leftover ungrouped angles (default 3, min 1). Configured groups are matched first and never split by this knob; mode: per-angle bypasses the table entirely (one singleton per angle)."),
+  maxConcurrent: z.number().int().min(1).default(4).describe("Max dispatch units (groups) the conductor dispatches concurrently per wave (default 4, min 1). The wave plan is emitted by write-gate-context.mjs via scheduleFanoutWaves (scheduleParallelWaves)."),
+});
+
+/**
+ * Two `gates.fanout.groups` entries sharing one `name` would resolve to two
+ * dispatch units with the same reviewer-sentinel scope (resolveFanoutGroups
+ * keys the scope by group name) — reject at config-validation time rather
+ * than let it degrade silently at dispatch time. Applied via `.superRefine`
+ * where `FanoutConfig` is used (zod v4 rejects `.partial()` on a schema that
+ * already carries a refinement), not on `FanoutConfig` itself.
+ * @param {{ groups?: Array<{ name: string }> }} val
+ * @param {import("zod").RefinementCtx} ctx
+ */
+function rejectDuplicateFanoutGroupNames(val, ctx) {
+  if (!Array.isArray(val.groups)) return;
+  const seen = new Set();
+  for (const [index, group] of val.groups.entries()) {
+    if (seen.has(group.name)) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        path: ["groups", index, "name"],
+        message: `duplicate gates.fanout.groups name "${group.name}"`,
+      });
+    }
+    seen.add(group.name);
+  }
+}
+
 const GatesConfig = z.strictObject({
   draft: GateConfig.optional(),
   // `requireCi` is honored on both gates: default true keeps CI a precondition,
@@ -206,16 +344,22 @@ const GatesConfig = z.strictObject({
   // is active. Default false (opt-in): closing this loophole is additive and
   // does not change behavior for existing ledgers that carry no provenance.
   requireFanoutProvenance: z.boolean().default(false),
-  // Cap on how many scoped `review` reviewers the gate fan-out spawns in
-  // parallel. When the resolved angle set exceeds this cap, the overflow runs
-  // in sequential batches and the degradation is recorded in the gate evidence.
-  maxFanoutReviewers: z.number().int().min(1).max(64).default(8),
-  // Post the consolidated gate fan-out findings as a visible, marker-tagged PR
-  // comment so they are auditable and Copilot/humans are aware of them. Default
-  // true (opt-out). The disposition ledger is written regardless; this flag only
-  // suppresses the PR comment when explicitly false. See
+  // SUPERSEDED by gates.fanout.maxConcurrent (#1601, ADR 0048): the conductor
+  // now dispatches wave-by-wave at most M dispatch units per wave via
+  // scheduleFanoutWaves (the wave plan emitted by write-gate-context.mjs), so
+  // maxFanoutReviewers no longer governs fan-out dispatch. Kept for back-compat
+  // (zero non-test callers in the dispatch path); a consumer setting it gets
+  // no dispatch effect. See gates.fanout.maxConcurrent for the active cap.
+  maxFanoutReviewers: z.number().int().min(1).max(64).default(8).describe("SUPERSEDED by gates.fanout.maxConcurrent (#1601, ADR 0048): no longer governs fan-out dispatch — the conductor dispatches wave-by-wave at most gates.fanout.maxConcurrent (M) dispatch units per wave via scheduleFanoutWaves (the wave plan emitted by write-gate-context.mjs). Kept for back-compat; setting it has no dispatch effect."),
+  // #1462 GATE-EXEC-PRIME is MANDATORY (not a flag): every gate fan-out primes the
+  // byte-identical briefing prefix before the reviewers read it — see
   // skills/docs/gate-review-sub-loop-contract.md.
-  postFindingsComments: z.boolean().default(true),
+  // Post the consolidated gate fan-out findings as a SECOND visible,
+  // marker-tagged PR comment. Default false (opt-in): the round's verdict
+  // review already carries every finding (GATE-COMMENT-SINGLE-SURFACE), so this
+  // comment renders each finding's text a second time. The disposition ledger
+  // is written regardless. See skills/docs/gate-review-sub-loop-contract.md.
+  postFindingsComments: z.boolean().default(false),
   // Explicit global lens catalog override for additive angle selection
   // (gates.<gate>.dynamic.additive, #1048). GLOBAL, not per-gate (D1): one
   // repo-wide catalog for additive selection. When absent, resolveAnglePool()
@@ -229,6 +373,9 @@ const GatesConfig = z.strictObject({
   // (reject); set false to warn instead of fail. See resolveRejectForeignAngles
   // / skills/docs/gate-review-sub-loop-contract.md.
   rejectForeignAngles: z.boolean().default(true),
+  // Grouped vs per-angle fan-out dispatch policy + static grouping table
+  // (AC6). GLOBAL, not per-gate — see resolveFanoutGroups.
+  fanout: FanoutConfig.superRefine(rejectDuplicateFanoutGroupNames).optional(),
 });
 
 const AutonomyConfig = z.strictObject({
@@ -277,7 +424,7 @@ const WorkflowConfig = z.strictObject({
   // it here would also mean renaming a shipped artifact contract, not just a
   // config key. Out of scope for this config-shape RFC; revisit as its own
   // change against skills/docs/gate-review-comment-contract.md + the envelope schema.
-  requireRetrospective: z.boolean().describe("Require a retrospective checkpoint before a loop completes."),
+  requireRetrospective: z.boolean().describe("Require a retrospective checkpoint for the previous qualifying async completion before the next dev-loop start/resume."),
   requireDraftFirst: z.boolean().describe("Open pull requests as drafts and promote via the draft gate."),
   devModeDefault: z.boolean().describe("Default new loops to dev mode."),
   // No default here and absent from BUILT_IN_DEFAULTS — unset means "keep
@@ -586,10 +733,11 @@ const FileGatesConfig = z.strictObject({
   spike: GateConfig.partial().describe("Relaxed spike gate profile; applies only to spike-mode work.").optional(),
   requireFanoutEvidence: z.boolean().describe("Require fan-out/fan-in review evidence on gate verdicts; inline single-agent verdicts are rejected except under the strict light-mode exception (under-threshold scope, no gate:full label, recorded inline reason).").optional(),
   requireFanoutProvenance: z.boolean().describe("Additionally require recorded, internally-consistent fan-out provenance (distinct reviewer count + per-angle dispatch).").optional(),
-  maxFanoutReviewers: z.number().int().min(1).max(64).describe("Cap on parallel gate fan-out reviewers; overflow runs in sequential batches.").optional(),
-  postFindingsComments: z.boolean().describe("Post consolidated gate findings as a marker-tagged PR comment (default true).").optional(),
+  maxFanoutReviewers: z.number().int().min(1).max(64).describe("SUPERSEDED by gates.fanout.maxConcurrent (#1601, ADR 0048): no longer governs fan-out dispatch — the conductor dispatches wave-by-wave at most gates.fanout.maxConcurrent (M) dispatch units per wave via scheduleFanoutWaves (the wave plan emitted by write-gate-context.mjs). Kept for back-compat; setting it has no dispatch effect.").optional(),
+  postFindingsComments: z.boolean().describe("Also post consolidated gate findings as a second marker-tagged PR comment, duplicating the verdict review's own findings (default false).").optional(),
   anglePool: z.array(z.string().trim().min(1)).describe("Explicit global lens catalog for additive angle selection (global, not per-gate).").optional(),
   rejectForeignAngles: z.boolean().describe("Reject fan-out provenance naming angles outside the gate's configured pool (default true).").optional(),
+  fanout: FanoutConfig.partial().superRefine(rejectDuplicateFanoutGroupNames).describe("Grouped vs per-angle fan-out dispatch policy + static grouping table (global, not per-gate).").optional(),
 });
 
 // ============================================================================
@@ -759,10 +907,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? }`. Returns
- * null for a malformed/empty entry so callers can filter it out.
+ * `{ name, mandatory?, enabled?, persona?, prompt?, model?, tier?, scope? }`.
+ * 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}|null}
+ * @returns {{name: string, mandatory?: boolean, enabled?: boolean, persona?: string, prompt?: string, model?: string, tier?: string, scope?: string}|null}
  */
 function normalizeAngleEntry(a) {
   if (typeof a === "string") {
@@ -779,6 +930,7 @@ function normalizeAngleEntry(a) {
     if (typeof a.prompt === "string" && a.prompt.length > 0) entry.prompt = a.prompt;
     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();
     return entry;
   }
   return null;
@@ -788,7 +940,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}>}
+ * @returns {Array<{name: string, mandatory?: boolean, enabled?: boolean, persona?: string, prompt?: string, model?: string, tier?: string, scope?: string}>}
  */
 function normalizeAngleEntries(raw) {
   if (!Array.isArray(raw)) return [];
@@ -834,6 +986,27 @@ function findAngleEntry(config, name) {
   return null;
 }
 
+/**
+ * Resolve a gate angle's declared surface scope (AC3, #1572): "full"
+ * (default), "changed-files", or "docs-only" — see GATE_ANGLE_SCOPES. Unlike
+ * {@link findAngleEntry} (which searches every gate in a fixed priority
+ * order because persona/prompt resolution has no gate context), this looks up
+ * the entry within the ONE named gate — an angle's scope is meaningful only
+ * for the specific gate pass building its briefing. Fails open to "full" for
+ * an angle with no configured entry, a disabled entry, or an
+ * unknown/malformed `scope` value: a narrow scope is an opt-in cost saving,
+ * never a silently-enforced information cut.
+ * @param {DevLoopConfig} config
+ * @param {"draft"|"preApproval"|"spike"} gate
+ * @param {string} name
+ * @returns {"full"|"changed-files"|"docs-only"}
+ */
+export function resolveGateAngleScope(config, gate, name) {
+  const entries = normalizeAngleEntries(config?.gates?.[gate]?.angles);
+  const found = entries.find((e) => e.name === name && e.enabled !== false);
+  return found?.scope ?? "full";
+}
+
 /**
  * Resolve a tier alias to its per-harness concrete model, or `null`
  * (`inherit`/unmapped/absent → no override). Deep-merges the alias mapping so
@@ -1233,6 +1406,20 @@ async function applyLayer(merged, basePaths, layer, warnings, errors, options =
     data = { ...data, strategy: "tracker-first" };
   }
 
+  // Removed `gates.primeSharedPrefix` (#1462): GATE-EXEC-PRIME cache priming is
+  // now mandatory, not a knob. The schema is strictObject, so a stale key would
+  // otherwise drop the WHOLE gates layer as invalid. Strip it before validation
+  // with a deprecation warning — old configs keep loading; priming happens
+  // unconditionally regardless of the removed value.
+  if (data?.gates && Object.prototype.hasOwnProperty.call(data.gates, "primeSharedPrefix")) {
+    warnings.push(
+      `gates.primeSharedPrefix is removed (#1462): cache priming is now mandatory, not configurable. ` +
+      `Remove it from ${path.basename(filePath)}; the key is ignored.`
+    );
+    const { primeSharedPrefix: _removed, ...gatesRest } = data.gates;
+    data = { ...data, gates: gatesRest };
+  }
+
   // Validate the file's structure before merging. Pre-existing behavior
   // (unrelated to the #1404 angle-entry redesign): a schema violation ANYWHERE
   // in this layer's file drops the WHOLE layer (errors is populated, `merged`
@@ -1244,6 +1431,35 @@ async function applyLayer(merged, basePaths, layer, warnings, errors, options =
   // is an existing, separate concern.
   const validation = FileConfigSchema.safeParse(data);
   if (!validation.success) {
+    // Surface a visible WARNING (not just the structured error) so the
+    // whole-layer drop is never silent (#1578): many consumers destructure
+    // only `config` (or `config` + `warnings`) and never read `errors`, so a
+    // schema-rejected layer would vanish without a trace. Naming the
+    // offending keys here lets a stale raw-key config (e.g.
+    // gates.<gate>.mandatoryAngles/excludeAngles) point at the canonical
+    // angle-entry migration path.
+    const offendingKeys = validation.error.issues
+      .flatMap((i) => {
+        if (i.code === "unrecognized_keys" && Array.isArray(i.keys) && i.keys.length) {
+          const prefix = i.path.length ? `${i.path.join(".")}.` : "";
+          return i.keys.map((k) => `${prefix}${k}`);
+        }
+        return i.path.length ? [i.path.join(".")] : [];
+      });
+    // Gate the raw-key migration hint: only append it when the offending
+    // keys actually include the pre-redesign mandatoryAngles/excludeAngles
+    // names, so an unrelated schema failure (e.g. a type error) does not get
+    // misleading raw-key migration guidance. (#1578)
+    const hasRawGateKey = offendingKeys.some((k) => /mandatoryAngles|excludeAngles/.test(k));
+    const migrationHint = hasRawGateKey
+      ? ` Migrate raw gates.<gate>.mandatoryAngles/excludeAngles to the canonical angle-entry shape ` +
+        `(gates.<gate>.angles with { name, mandatory: true } / { name, enabled: false }).`
+      : ` Fix or remove the offending key(s) to restore this config layer.`;
+    warnings.push(
+      `${path.basename(filePath)}: config layer rejected by schema — the whole layer was dropped, so this layer's overrides are not applied (previously merged layers remain in effect). ` +
+      `Offending key(s): ${offendingKeys.length ? offendingKeys.join(", ") : "(unknown)"}.` +
+      migrationHint
+    );
     errors.push({
       path: filePath,
       message: `${path.basename(filePath)}: Schema validation failed: ${validation.error.issues.map(i => `${i.path.join(".")}: ${i.message}`).join("; ")}`,
@@ -1608,7 +1824,7 @@ export function resolveRefinement(config) {
  *
  * @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 }}
+ * @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[]}> }}
  */
 export function resolveGateConfig(config, gate) {
   const gateConfig = config?.gates?.[gate];
@@ -1623,11 +1839,19 @@ export function resolveGateConfig(config, gate) {
     mandatoryAngles: entries.filter((e) => e.enabled !== false && e.mandatory === true).map((e) => e.name),
     required: gateConfig?.required ?? true,
     requireCi: gateConfig?.requireCi ?? true,
-    dynamicAngles: gateConfig?.dynamic?.subtractive ?? false,
+    dynamicAngles: gateConfig?.dynamic?.subtractive ?? true,
     additiveAngles: gateConfig?.dynamic?.additive ?? false,
+    // Normalized + deduped at the resolve boundary so every consumer (envelope,
+    // verdict poster, fan-in, viewer) sees canonical spellings only; a
+    // half-migrated ["must-fix","low","defer"] collapses to two entries.
     blockCleanOnFindingSeverities: gateConfig?.blockCleanOnFindingSeverities && Array.isArray(gateConfig.blockCleanOnFindingSeverities)
-      ? [...gateConfig.blockCleanOnFindingSeverities]
-      : ["must-fix"],
+      ? [...new Set(gateConfig.blockCleanOnFindingSeverities.map((s) => normalizeSeverity(s)))]
+      : ["high"],
+    // `mediumFixWindow` wins; `worthFixingNowFixWindow` is the deprecated
+    // pre-rename key, still honored so an unmigrated config keeps its
+    // configured window rather than silently reverting to the default.
+    mediumFixWindow: gateConfig?.mediumFixWindow ?? gateConfig?.worthFixingNowFixWindow ?? 3,
+    tiers: gateConfig?.tiers ?? [],
   };
 }
 
@@ -1650,10 +1874,11 @@ export function resolveRequireFanoutEvidence(config) {
 }
 
 /**
- * Minimum distinct reviewer count for a fanout_fanin ledger to satisfy
- * requireFanoutProvenance. A floor of 2 is the smallest count that is not a
- * single agent; it raises the bar but does not prove independence (provenance
- * is self-reported — see the honest caveat in
+ * ABSOLUTE minimum distinct reviewer count for a fanout_fanin ledger to
+ * satisfy requireFanoutProvenance; the effective read-time floor scales to
+ * max(this, the ledger's fresh-angle count). A floor of 2 is the smallest
+ * count that is not a single agent; it raises the bar but does not prove
+ * independence (provenance is self-reported — see the honest caveat in
  * skills/docs/gate-review-sub-loop-contract.md).
  */
 export const FANOUT_PROVENANCE_MIN_REVIEWERS = 2;
@@ -1687,21 +1912,21 @@ export function resolveRejectForeignAngles(config) {
 }
 
 /**
- * Resolve whether the consolidated gate fan-out findings should be posted as a
- * visible, marker-tagged PR comment.
+ * Resolve whether the consolidated gate fan-out findings should ALSO be posted
+ * as a second visible, marker-tagged PR comment.
  *
- * Returns true (post the comment) unless `gates.postFindingsComments` is
- * explicitly set to false. Using a `!== false` test (rather than `=== true`)
- * keeps the opt-out semantics robust for programmatically-built config objects
- * that bypass schema defaulting. The disposition ledger is written regardless;
- * this flag only suppresses the auditable PR comment. See
- * skills/docs/gate-review-sub-loop-contract.md.
+ * Returns false unless `gates.postFindingsComments` is explicitly set to true.
+ * The round's verdict review is already the findings surface
+ * (`GATE-COMMENT-SINGLE-SURFACE`), so this comment is opt-in duplication; the
+ * `=== true` test keeps that opt-in semantics for programmatically-built config
+ * objects that bypass schema defaulting. The disposition ledger is written
+ * regardless. See skills/docs/gate-review-sub-loop-contract.md.
  *
  * @param {DevLoopConfig} config
  * @returns {boolean}
  */
 export function resolveGatePostFindingsComments(config) {
-  return config?.gates?.postFindingsComments !== false;
+  return config?.gates?.postFindingsComments === true;
 }
 
 /**
@@ -1812,14 +2037,187 @@ export function resolveGateDispatchMode(config, gate, { scope, hasFullLabel = fa
     return { mode: "full_fanout", reason: "over_threshold", threshold };
   }
   if (Array.isArray(inlineFindingSeverities) && inlineFindingSeverities.length > 0) {
-    const blocking = new Set(resolveGateConfig(config, gate).blockCleanOnFindingSeverities);
-    if (inlineFindingSeverities.some((s) => blocking.has(s))) {
+    // Both sides normalize legacy spellings so a "defer" finding still
+    // compares against a "low" blocking entry and vice versa.
+    const blocking = new Set(resolveGateConfig(config, gate).blockCleanOnFindingSeverities.map((s) => normalizeSeverity(s)));
+    if (inlineFindingSeverities.some((s) => blocking.has(normalizeSeverity(s)))) {
       return { mode: "full_fanout", reason: "escalated", threshold };
     }
   }
   return { mode: "inline", reason: "under_threshold", threshold };
 }
 
+/**
+ * Default auto-chunk size for ungrouped angles (issue #1601). Mirrors the
+ * zod default on `gates.fanout.maxAnglesPerGroup`.
+ */
+export const DEFAULT_MAX_ANGLES_PER_GROUP = 3;
+
+/**
+ * Default concurrent-dispatch-unit cap per wave (issue #1601). Mirrors the
+ * zod default on `gates.fanout.maxConcurrent`; consumed by
+ * `scheduleFanoutWaves` (@dev-loops/core/loop/gate-fanin).
+ */
+export const DEFAULT_FANOUT_MAX_CONCURRENT = 4;
+
+/**
+ * Resolve `gates.fanout.maxAnglesPerGroup` (issue #1601, default 3, min 1).
+ * The number of ungrouped angles auto-chunked into one dispatch unit.
+ * Defensive, independent of zod: a non-integer or sub-1 value falls back to
+ * the built-in default so a malformed raw merged config (which zod may have
+ * rejected at load time while still returning it) never crashes Phase 2.
+ * @param {DevLoopConfig} config
+ * @returns {number}
+ */
+export function resolveMaxAnglesPerGroup(config) {
+  const n = config?.gates?.fanout?.maxAnglesPerGroup;
+  if (typeof n !== "number" || !Number.isInteger(n) || n < 1) return DEFAULT_MAX_ANGLES_PER_GROUP;
+  return n;
+}
+
+/**
+ * Resolve `gates.fanout.maxConcurrent` (issue #1601, default 4, min 1). The
+ * max dispatch units (groups) the conductor dispatches concurrently per wave.
+ * Defensive, independent of zod (same rationale as resolveMaxAnglesPerGroup).
+ * @param {DevLoopConfig} config
+ * @returns {number}
+ */
+export function resolveFanoutMaxConcurrent(config) {
+  const m = config?.gates?.fanout?.maxConcurrent;
+  if (typeof m !== "number" || !Number.isInteger(m) || m < 1) return DEFAULT_FANOUT_MAX_CONCURRENT;
+  return m;
+}
+
+/**
+ * Resolve grouped fan-out dispatch (AC6 + #1601 two-knob dispatch bounds):
+ * map a round's resolved review angles onto the dispatch units it actually
+ * dispatches.
+ *
+ * Dispatch shape precedence (first match wins):
+ *   1. `gates.fanout.mode === "per-angle"` → bypasses configured groups; one
+ *      singleton unit per angle (the original one-reviewer-per-angle fan-out;
+ *      NOT equivalent to maxAnglesPerGroup: 1 when configured groups match)
+ *   2. otherwise (default `grouped`) → configured `gates.fanout.groups` are
+ *      matched first (unchanged), then the leftover ungrouped angles are
+ *      auto-chunked into dispatch units of ≤ `maxAnglesPerGroup` (default 3)
+ *      instead of singletons.
+ *
+ * `gate:full` (`options.fullLabel`) NO LONGER restores per-angle dispatch
+ * (ADR 0047 superseded by 0048): `gate:full` keeps forcing the full angle set
+ * UPSTREAM (resolveGateTier returns `gate_full_label`, so resolveGateAnglesDynamic
+ * skips diff-class tier reduction) and dispatches GROUPED here. The `fullLabel`
+ * parameter is retained on the signature (callers thread it) but no longer
+ * changes the dispatch shape — it is a no-op here, kept only to avoid a breaking
+ * API change to the exported resolver; its angle-set effect lives upstream.
+ *
+ * A configured group is included only when at least one of its angles is in
+ * `resolvedAngles` this round — an unmatched group is dropped, never emitted
+ * empty. Configured groups are NEVER split by `maxAnglesPerGroup` (the knob
+ * chunks only the leftover ungrouped pool). Each reviewer still writes ONE
+ * artifact per angle at the existing per-angle paths; grouping only changes how
+ * many reviewers are dispatched, not the artifact shape (see
+ * skills/docs/gate-review-sub-loop-contract.md).
+ *
+ * Auto-chunk unit names are deterministic and stable (issue #1601): a
+ * single-angle leftover chunk is named by its angle (collisions with an emitted
+ * group name disambiguated to `angle:<name>`, preserving the pre-#1601
+ * singleton convention); a multi-angle chunk is named `group:<a>+<b>+<c>` from
+ * its deterministically-ordered members. Unit names key reviewer-sentinel
+ * scopes and provenance `group`, so they must be unique — a chunk whose base
+ * name still collides gets a `#2`/`#3`/… suffix.
+ *
+ * Defensive, independent of zod: `loadDevLoopConfig` returns the raw merged
+ * config even when schema validation fails (on ANY layer, not necessarily
+ * `gates.fanout` itself), so a malformed `gates.fanout.groups` entry can
+ * reach here. A non-object entry, a non-array/blank `angles`, or a
+ * blank/duplicate `name` is dropped (its angles fall through to the leftover
+ * auto-chunk pool) rather than thrown — mirroring the sibling
+ * `normalizeAngleEntries` convention: this resolver degrades to a smaller
+ * grouping table, never crashes the conductor's Phase 2 planning.
+ * `resolvedAngles` is deduplicated up front so a duplicated entry (e.g. a
+ * hand-built `--angles` list) never mints two dispatch units sharing one name.
+ *
+ * @param {DevLoopConfig} config
+ * @param {"draft"|"preApproval"|"spike"} gate unused today — fan-out grouping
+ *   is a global policy (`gates.fanout`), not per-gate; accepted for symmetry
+ *   with the other `resolveGate*(config, gate, ...)` resolvers.
+ * @param {string[]} resolvedAngles this round's resolved angle names
+ * @param {{ fullLabel?: boolean }} [options] — retained for API stability;
+ *   no longer changes the dispatch shape (see `gate:full` note above).
+ * @returns {{ name: string, angles: string[] }[]}
+ */
+export function resolveFanoutGroups(config, gate, resolvedAngles, { fullLabel = false } = {}) {
+  const angles = Array.isArray(resolvedAngles)
+    ? [...new Set(resolvedAngles.filter((a) => typeof a === "string" && a.trim().length > 0).map((a) => a.trim()))]
+    : [];
+  const perAngleGroups = () => angles.map((name) => ({ name, angles: [name] }));
+  // per-angle: bypass configured groups and emit one singleton unit per
+  // angle (the original one-reviewer-per-angle fan-out). gate:full no longer
+  // takes this branch (ADR 0047 superseded by 0048): fullLabel is a no-op here.
+  const fanout = config?.gates?.fanout ?? {};
+  if (fanout.mode === "per-angle") return perAngleGroups();
+  const angleSet = new Set(angles);
+  const rawGroups = Array.isArray(fanout.groups) ? fanout.groups : [];
+  const configuredGroups = [];
+  const seenGroupNames = new Set();
+  for (const group of rawGroups) {
+    if (!group || typeof group !== "object" || Array.isArray(group)) continue;
+    const name = typeof group.name === "string" ? group.name.trim() : "";
+    if (name.length === 0 || seenGroupNames.has(name)) continue;
+    const groupAngles = Array.isArray(group.angles)
+      ? [...new Set(group.angles.filter((a) => typeof a === "string" && a.trim().length > 0).map((a) => a.trim()))]
+      : [];
+    if (groupAngles.length === 0) continue;
+    seenGroupNames.add(name);
+    configuredGroups.push({ name, angles: groupAngles });
+  }
+  const grouped = new Set();
+  const result = [];
+  for (const group of configuredGroups) {
+    const members = group.angles.filter((a) => angleSet.has(a) && !grouped.has(a));
+    if (members.length === 0) continue;
+    for (const a of members) grouped.add(a);
+    result.push({ name: group.name, angles: members });
+  }
+  // Issue #1601: leftover ungrouped angles auto-chunk into dispatch units of
+  // ≤ maxAnglesPerGroup (default 3) instead of singletons. Configured groups
+  // are matched first and never split by this knob (only the leftover pool is
+  // chunked). Deterministic order (input order) + stable unit names.
+  const usedNames = new Set(result.map((g) => g.name));
+  const leftover = angles.filter((name) => !grouped.has(name));
+  const maxAnglesPerGroup = resolveMaxAnglesPerGroup(config);
+  for (let i = 0; i < leftover.length; i += maxAnglesPerGroup) {
+    const chunk = leftover.slice(i, i + maxAnglesPerGroup);
+    const unitName = stableAutoChunkUnitName(chunk, usedNames);
+    usedNames.add(unitName);
+    result.push({ name: unitName, angles: chunk });
+  }
+  return result;
+}
+
+/**
+ * Deterministic, stable dispatch-unit name for an auto-chunked leftover
+ * unit (issue #1601). A single-angle chunk keeps the pre-#1601 singleton
+ * convention (the angle name, disambiguated to `angle:<name>` on collision
+ * with an emitted group name); a multi-angle chunk is named
+ * `group:<a>+<b>+<c>` from its deterministically-ordered members, with a
+ * `#N` suffix when even that base collides. Pure.
+ * @param {string[]} chunk — non-empty, deterministically ordered
+ * @param {Set<string>} usedNames — already-emitted unit names (mutated by caller)
+ * @returns {string}
+ */
+function stableAutoChunkUnitName(chunk, usedNames) {
+  if (chunk.length === 1) {
+    const name = chunk[0];
+    return usedNames.has(name) ? `angle:${name}` : name;
+  }
+  const base = `group:${chunk.join("+")}`;
+  if (!usedNames.has(base)) return base;
+  let k = 2;
+  while (usedNames.has(`${base}#${k}`)) k++;
+  return `${base}#${k}`;
+}
+
 /**
  * Resolve review angles for a specific gate from the merged dev-loop config.
  *
@@ -1904,14 +2302,79 @@ export function resolveGateAngleContract(config, gate) {
   return { mandatoryAngles, pool };
 }
 
+/**
+ * Resolve the diff-class angle tier for a gate from its configured, ordered
+ * `gates.<gate>.tiers` list (first-match-wins). Pure and synchronous — the
+ * single source of truth for tier selection, consulted at the top of
+ * `resolveGateAnglesDynamic` before any dynamic subtractive/additive
+ * reduction runs.
+ *
+ * FAIL CLOSED at every uncertain step: the `gate:full` label, no tiers
+ * configured, an unavailable/malformed scope, a changed dev-loop
+ * config-source file (`isDevLoopConfigSourcePath`), or an unclassifiable
+ * changed file (`classifyFile` returns "unknown") all resolve to `tier: null`
+ * rather than a guess. A matched tier's angle set is additionally validated
+ * against the gate's angle pool (`resolveGateAngleContract`) — ANY tier angle
+ * outside a non-null pool voids the whole match (no partial intersection): a
+ * typo'd tier angle is caught here, not by silently dropping reviewers at
+ * gate time.
+ *
+ * @param {DevLoopConfig} config
+ * @param {"draft"|"preApproval"|"spike"} gate
+ * @param {object} facts
+ * @param {string[]} [facts.changedFiles] — repo-relative changed file paths for this diff
+ * @param {number} [facts.filesChanged] — count of changed files
+ * @param {number} [facts.linesChanged] — count of changed lines (added + deleted)
+ * @param {boolean} [facts.hasFullLabel] — `gate:full` label present on the PR
+ * @returns {{ tier: string|null, angles: string[]|null, reason: string }}
+ */
+export function resolveGateTier(config, gate, { changedFiles, filesChanged, linesChanged, hasFullLabel = false } = {}) {
+  if (hasFullLabel) {
+    return { tier: null, angles: null, reason: "gate_full_label" };
+  }
+  const tiers = resolveGateConfig(config, gate).tiers;
+  if (tiers.length === 0) {
+    return { tier: null, angles: null, reason: "no_tiers_configured" };
+  }
+  if (
+    !Array.isArray(changedFiles) || changedFiles.length === 0 ||
+    !Number.isFinite(filesChanged) || !Number.isFinite(linesChanged)
+  ) {
+    return { tier: null, angles: null, reason: "scope_unavailable" };
+  }
+  if (changedFiles.some((f) => isDevLoopConfigSourcePath(f))) {
+    return { tier: null, angles: null, reason: "config_source_delta" };
+  }
+  const kinds = changedFiles.map((f) => classifyFile(f));
+  if (kinds.some((k) => k === "unknown")) {
+    return { tier: null, angles: null, reason: "unclassifiable_file" };
+  }
+  const matched = tiers.find((t) => {
+    const match = t.match ?? {};
+    if (Array.isArray(match.kinds) && !kinds.every((k) => match.kinds.includes(k))) return false;
+    if (typeof match.maxFiles === "number" && filesChanged > match.maxFiles) return false;
+    if (typeof match.maxLines === "number" && linesChanged > match.maxLines) return false;
+    return true;
+  });
+  if (!matched) {
+    return { tier: null, angles: null, reason: "no_tier_match" };
+  }
+  const { mandatoryAngles, pool } = resolveGateAngleContract(config, gate);
+  if (pool !== null && matched.angles.some((a) => !pool.includes(a))) {
+    return { tier: null, angles: null, reason: "angle_outside_pool" };
+  }
+  return { tier: matched.name, angles: [...new Set([...mandatoryAngles, ...matched.angles])], reason: "tier_match" };
+}
+
 /**
  * Resolve gate angles dynamically when `dynamicAngles` is enabled in config.
  *
  * Uses diff analysis helpers (from ../analysis/*) to filter the
  * configured angle list down to only angles relevant to the change set.
  *
- * When `dynamicAngles` is disabled (default), returns the full configured
- * angle list (same as `resolveGateAngles`).
+ * When `dynamicAngles` is disabled (opt-out via `dynamic.subtractive: false`,
+ * see #1579), returns the full configured angle list (same as
+ * `resolveGateAngles`); no diff also falls back to the full static pool.
  *
  * When `additiveAngles` is also enabled (default off, see #1048), catalog
  * angles from `resolveAnglePool()` (`gates.anglePool`, or else the union of
@@ -1919,13 +2382,55 @@ export function resolveGateAngleContract(config, gate) {
  * by change-category heuristics but absent from the gate's configured pool
  * may also be added; `excludeAngles` remains a hard ceiling on additions.
  *
+ * Diff-class angle tiers (`gates.<gate>.tiers`, see `resolveGateTier`) are
+ * consulted FIRST, ahead of any subtractive/additive reduction below: when the
+ * diff's changed-file scope matches a configured tier, that tier's angle set
+ * (unioned with mandatory angles) is returned directly and the
+ * subtractive/additive machinery below is skipped entirely. No tier match
+ * (including "no tiers configured") falls through to the existing behavior
+ * unchanged.
+ *
  * @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)
  * @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 } = {}) {
+export async function resolveGateAnglesDynamic(config, gate, { diff, hasFullLabel = false } = {}) {
+  // Tier scope facts: changedFiles/filesChanged from T0 (file-level), linesChanged
+  // from T1 (hunk-level) reused for its real added+deleted line count rather than
+  // T0's/analyzeDiff's own inferred-category path, which reports a fake 0 line
+  // count for an unambiguous (e.g. docs-only) diff — see analyzeT1/analyzeDiff.
+  let changedFiles;
+  let filesChanged;
+  let linesChanged;
+  if (diff) {
+    const { analyzeT0, analyzeT1 } = await import("../analysis/diff-analyzer.mjs");
+    const t0 = analyzeT0(diff.nameStatusOutput);
+    changedFiles = t0.files;
+    filesChanged = changedFiles.length;
+    if (diff.diffOutput) {
+      const lineStats = analyzeT1(diff.diffOutput, t0).lineStats;
+      linesChanged = lineStats.added + lineStats.deleted;
+    }
+  }
+  const tierResult = resolveGateTier(config, gate, { changedFiles, filesChanged, linesChanged, hasFullLabel });
+  if (tierResult.tier) {
+    const configuredAngles = resolveGateAngles(config, gate) ?? [];
+    const tierAngleSet = new Set(tierResult.angles);
+    const skippedAngles = configuredAngles.filter((a) => !tierAngleSet.has(a));
+    return {
+      recommendedAngles: tierResult.angles,
+      skippedAngles,
+      reasons: Object.fromEntries(skippedAngles.map((a) => [a, `tier:${tierResult.tier}`])),
+      fallbackToAll: false,
+      dynamicAnglesActive: true,
+      addedAngles: [],
+      addedReasons: {},
+    };
+  }
+
   const gateConfig = resolveGateConfig(config, gate);
   const staticAngles = resolveGateAngles(config, gate);
   if (staticAngles === null) {