@dev-loops/core 1.0.0-rc.2 → 1.0.0-rc.4

package/src/config/config.mjs

@@ -1,8 +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
@@ -12,13 +16,20 @@ import { z } from "zod";
 // callers need a stable value even when they construct config objects directly.
 // ============================================================================
 
-const StrategyConfig = z.strictObject({
-  default: z.enum(["local-first", "github-first"]).describe("Default work-intake strategy: local-first starts from a repo plan file, github-first from a tracked issue."),
-});
-
-const InputSourceConfig = z.strictObject({
-  default: z.enum(["tracker", "phase-docs"]).describe("Where local-first work reads its spec: the tracker issue body, or repo phase docs."),
-});
+// `strategy` and `inputSource` are single-value families (their only child was
+// a `default` wrapper) — flattened to a bare enum at the family key itself.
+//
+// `tracker-first` renames the former `github-first` (issue #1408, the
+// tracker-agnostic seam: provider-neutral naming now that GitHub is one
+// tracker provider among a stable seam, not the only one). `github-first` is
+// still ACCEPTED as a deprecated alias — normalized to `tracker-first` with a
+// load-time warning in `loadDevLoopConfig` (see the alias-normalization pass
+// below `mergeConfigLayers`) — but this schema only validates the canonical
+// value, so the alias must be normalized on the raw merged object BEFORE it
+// reaches this parse.
+const StrategyConfig = z.enum(["local-first", "tracker-first"]).describe("Work-intake strategy: local-first starts from a repo plan file, tracker-first from a tracked issue (\"github-first\" is a deprecated accepted alias).");
+
+const InputSourceConfig = z.enum(["tracker", "phase-docs"]).describe("Where local-first work reads its spec: the tracker issue body, or repo phase docs.");
 
 // Built-in tier aliases shipped with zero config. A tier alias maps a
 // harness-neutral name (low/high) to a concrete per-harness model id; `null`
@@ -92,37 +103,217 @@ const ModelsConfigBase = z.strictObject({
 
 const ModelsConfig = ModelsConfigBase.superRefine(refineRoleTiers);
 
+// A round with at most this many comments (after this many rounds) counts as
+// low-signal and stops further Copilot rounds early — folded from the three
+// flat `stopOnLowSignal`/`lowSignalRoundThreshold`/`lowSignalMaxComments` keys
+// into one sub-object (they are one feature).
+const LowSignalConfig = z.strictObject({
+  enabled: z.boolean().default(false).describe("Stop Copilot rounds early once they stop producing signal."),
+  roundThreshold: z.number().int().nonnegative().default(3).describe("Rounds counted toward the low-signal stop decision."),
+  maxComments: z.number().int().nonnegative().default(2).describe("A round with at most this many comments counts as low-signal."),
+});
+
 const RefinementConfig = z.strictObject({
   fanOut: z.number().int().min(1).max(10).describe("Parallel reviewers per refinement round."),
   mode: z.enum(["parallel", "sequential"]).describe("Whether refinement reviewers run in parallel or one after another."),
   maxCopilotRounds: z.number().int().nonnegative().default(5).describe("Automated Copilot review rounds before converging; 0 disables Copilot review."),
-  stopOnLowSignal: z.boolean().default(false).describe("Stop Copilot rounds early once they stop producing signal."),
-  lowSignalRoundThreshold: z.number().int().nonnegative().default(3).describe("Rounds counted toward the low-signal stop decision."),
-  lowSignalMaxComments: z.number().int().nonnegative().default(2).describe("A round with at most this many comments counts as low-signal."),
+  lowSignal: LowSignalConfig.optional().describe("Early-stop policy for low-signal Copilot rounds."),
   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), `persona`/`prompt`/`model`/
+// `tier` (was the top-level `personas` map + angle-keyed
+// `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
+// single angle without restating the whole list.
+// A bare string is sugar for { name }; preprocessing the string→object wrap
+// BEFORE validation (rather than a z.union of the two shapes) means every
+// malformed angle entry validates against this ONE object schema, so a bad
+// field (e.g. `mandatory: "yes"`) reports its own actionable path/message
+// (`gates.draft.angles.1.mandatory: ...`) instead of zod's opaque
+// invalid_union "Invalid input" that swallows which branch failed why.
+const GateAngleEntry = z.preprocess(
+  (v) => (typeof v === "string" ? { name: v } : v),
+  z.strictObject({
+    name: z.string().trim().min(1),
+    mandatory: z.boolean().optional().describe("Always run this angle, regardless of diff-based dynamic selection."),
+    enabled: z.boolean().optional().describe("Set false to drop this angle from the resolved list (a later config layer disabling a base angle)."),
+    persona: z.string().trim().min(1).optional().describe("Reviewer persona for this angle."),
+    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({
+  // 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
+  // config's own configured angles) — that change-category heuristics
+  // recommend but that are not already in this gate's configured pool.
+  // Default false preserves the subtractive-only behavior exactly.
+  additive: z.boolean().default(false).describe("Allow diff-driven addition of catalog angles beyond this gate's configured pool (was gates.<gate>.additiveAngles)."),
+});
+
+// One unified gate schema for draft/preApproval/spike (D2): the spike gate
+// profile ships `required: false, requireCi: false` and a small docs-first
+// angle set; `blockCleanOnFindingSeverities` and `dynamic.additive` are
+// accepted but INERT for spike (a findings-doc deliverable has no "clean
+// verdict" escalation path and no additive dynamic pool) rather than being
+// split into a second schema.
 const GateConfig = z.strictObject({
-  angles: z.array(z.string().trim().min(1)).describe("Review lenses this gate fans out to.").optional(),
-  excludeAngles: z.array(z.string().trim().min(1)).default([]).describe("Angles removed from the resolved angle list."),
-  mandatoryAngles: z.array(z.string().trim().min(1)).default([]).describe("Angles that always run, regardless of diff-based dynamic selection."),
+  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."),
+  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."),
-  dynamicAngles: z.boolean().default(false).describe("Enable diff-driven dynamic angle resolution for this gate."),
-  // Additive counterpart to the subtractive dynamicAngles 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 config's own configured angles) — that change-category
-  // heuristics recommend but that are not already in this gate's configured
-  // pool. Default false preserves today's subtractive-only behavior exactly.
-  additiveAngles: z.boolean().default(false).describe("Allow diff-driven addition of catalog angles beyond this gate's configured pool."),
+    .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,
@@ -141,43 +332,60 @@ const GatesConfig = z.strictObject({
   // fan-out/fan-in review sub-loop (executionMode === "fanout_fanin" plus a
   // durable findings-log ledger), not an inline single-agent run. Default
   // true (opt-out): a clean gate verdict requires fan-out/fan-in evidence
-  // unless explicitly disabled. See docs/gate-review-sub-loop-contract.md.
+  // unless explicitly disabled. See skills/docs/gate-review-sub-loop-contract.md.
   requireFanoutEvidence: z.boolean().default(true),
   // Fail-closed enforcement that a fanout_fanin gate verdict carries recorded,
   // internally-consistent fan-out *provenance* (distinct reviewer count +
   // per-angle dispatch). This RAISES THE BAR against a single agent self-producing
   // every artifact but does NOT prove independence — provenance is self-reported,
   // so it remains forgeable; un-forgeable recording is the Pi-harness bridge (see
-  // the honest caveat in docs/gate-review-sub-loop-contract.md). Layered ON TOP of
+  // the honest caveat in skills/docs/gate-review-sub-loop-contract.md). Layered ON TOP of
   // requireFanoutEvidence — only takes effect when fan-out evidence enforcement
   // 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
-  // docs/gate-review-sub-loop-contract.md.
-  postFindingsComments: z.boolean().default(true),
+  // 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.
+  // 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>.additiveAngles, #1048). When absent, resolveAnglePool()
+  // (gates.<gate>.dynamic.additive, #1048). GLOBAL, not per-gate (D1): one
+  // repo-wide catalog for additive selection. When absent, resolveAnglePool()
   // falls back to the union of the built-in persona registry's angle names
   // and every angle configured across this config's own draft/preApproval/
-  // spike gates (angles + mandatoryAngles).
+  // spike gates.
   anglePool: z.array(z.string().trim().min(1)).optional(),
   // Fail-closed enforcement that a fanout_fanin gate's recorded per-angle
-  // provenance names only angles in the gate's configured pool (angles +
-  // mandatoryAngles) — ad-hoc/foreign angle labels are rejected rather than
-  // silently accepted. Default true (reject); set false to warn instead of
-  // fail. See resolveRejectForeignAngles / docs/gate-review-sub-loop-contract.md.
+  // provenance names only angles in the gate's configured pool — ad-hoc/foreign
+  // angle labels are rejected rather than silently accepted. Default true
+  // (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({
+  // ponytail: secondary cleanup #6 (stopAt kebab values vs camelCase gate
+  // keys) is DEFERRED — "draft-pr"/"pre-approval" are checkpoint/state-machine
+  // vocabulary shared far beyond config (lifecycle-state.mjs, hook-decisions.mjs,
+  // the handoff-envelope contract, skills/docs/reviewer-loop-state-graph.md, and ~20
+  // more files), not a config-local spelling. Renaming here would mean
+  // renaming that shared vocabulary, a materially larger change than this
+  // config-schema RFC's scope.
   stopAt: z.array(
     z.enum(["refinement", "draft-pr", "pre-approval", "merge"])
   ).describe("Checkpoints that require operator confirmation before the loop proceeds (default: [\"merge\"])."),
@@ -194,8 +402,12 @@ const AutonomyConfig = z.strictObject({
  * reviewer/assignee. Opt-in (default off). Pairs with autonomy.humanMergeOnly.
  * `candidatesFrom` selects which sources the resolver queries; `assignees` is a
  * static highest-priority candidate list. Absent/empty = disabled no-op.
+ *
+ * Lifted directly onto `approval` (its only child) rather than nested under
+ * `approval.humanHandoff` — `approval` had exactly one sub-key, so the wrapper
+ * added a level without adding meaning.
  */
-const HumanHandoffConfig = z.strictObject({
+const ApprovalConfig = z.strictObject({
   enabled: z.boolean().default(false),
   candidatesFrom: z
     .array(z.enum(["codeowners", "recent-committers"]))
@@ -203,15 +415,24 @@ const HumanHandoffConfig = z.strictObject({
   assignees: z.array(z.string().trim().min(1)).optional(),
 });
 
-const ApprovalConfig = z.strictObject({
-  humanHandoff: HumanHandoffConfig.optional(),
-});
-
 const WorkflowConfig = z.strictObject({
   asyncStartMode: z.enum(["required", "allowed"]).default("required").describe("Whether the async start contract is required or merely allowed."),
+  // ponytail: workflow.asyncStartMode -> asyncStartRequired (secondary cleanup
+  // #5) is DEFERRED — that string is echoed verbatim into the persisted
+  // handoff-envelope contract field (validated, rendered, and cross-checked by
+  // workflow-handoff-contract.test.mjs / the inspect-run viewer), so renaming
+  // 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."),
   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
+  // auto-detecting the default branch" (see resolveBaseBranch), never a static
+  // "main". Bare branch name; consumers add the `origin/` remote-ref prefix
+  // where one is needed (worktree creation) and pass the bare name where one
+  // is not (gh/PR base).
+  baseBranch: z.string().trim().min(1).describe("Repo-level base/integration branch override (bare name, e.g. \"main\" or \"spike/foo\"). When set, worktree creation and PR targeting use it instead of the auto-detected default branch. Unset = auto-detect (origin/HEAD, else main/master).").optional(),
 });
 
 const LocalImplementationConfig = z.strictObject({
@@ -230,32 +451,80 @@ const LocalImplementationConfig = z.strictObject({
    * change scope. Decoupled from lightMode: gate dispatch still resolves
    * inline vs full_fanout from scope on its own, so over-threshold issue-less
    * PRs get the full fan-out and the full-PR Copilot round cap.
+   *
+   * Flattened to a bare boolean — `enabled` was its only child key.
    */
-  issueless: z.strictObject({
-    enabled: z.boolean().describe("Opt into issue-less PR-first dispatch at any change scope; gate dispatch still resolves inline vs full fan-out from scope on its own."),
-  }).optional(),
+  issueless: z.boolean().describe("Opt into issue-less PR-first dispatch at any change scope; gate dispatch still resolves inline vs full fan-out from scope on its own.").optional(),
 });
 
+// GitHub Projects board identifier: exactly one of number/title (two parallel
+// keys folded into one selector object). `ownerKey` names the config key in
+// the refine failure message — each usage site gets its own accurate
+// message rather than a shared one that could name the wrong key.
+function boardRefConfig(ownerKey) {
+  return z
+    .strictObject({
+      number: z.number().int().positive().describe("GitHub Projects board number.").optional(),
+      title: z.string().trim().min(1).describe("GitHub Projects board title.").optional(),
+    })
+    .refine((v) => typeof v.number === "number" || typeof v.title === "string", {
+      message: `${ownerKey} must set number or title`,
+    });
+}
+
+const QueueBoardConfig = boardRefConfig("queue.board");
+
 /** Queue mode config */
 const QueueConfig = z.strictObject({
   maxParallel: z.number().int().min(1).max(10).default(3).describe("Maximum queue items worked in parallel."),
   maxAutoFiledIssues: z.number().int().min(0).max(100).default(10).describe("Cap on auto-filed issues per run."),
   reDispatchMaxRetries: z.number().int().min(0).max(10).default(1).describe("Retries when re-dispatching a failed queue item."),
-  projectNumber: z.number().int().positive().describe("GitHub Projects board number (explicit opt-in to Projects-based queue ordering).").optional(),
-  boardTitle: z.string().trim().min(1).describe("GitHub Projects board title (explicit opt-in to Projects-based queue ordering).").optional(),
+  // Deprecated: superseded by `tracker.board` (issue #1408, the tracker-agnostic
+  // seam). Kept accepted for back-compat — see resolveTrackerBoard, which reads
+  // `tracker.board` first and falls back to this field with a load-time warning.
+  board: QueueBoardConfig.describe("Deprecated: use tracker.board instead. GitHub Projects board identifier.").optional(),
   archiveOlderThanDays: z.number().int().positive().describe("Archive done board items older than this many days.").optional(),
 });
 
+/**
+ * Tracker config (issue #1408, the tracker-agnostic seam). `provider` is a
+ * free-form registry key (not a zod enum): an unknown provider fails closed
+ * at `resolveTrackerAdapter` call time, not at config-parse time — the
+ * seam/resolver must not preclude a consumer registering an external
+ * provider post-1.0 (`plugin`, reserved, not implemented in this pass).
+ * `board` supersedes the deprecated `queue.board` (see resolveTrackerBoard).
+ *
+ * No generic `fieldMappings` (logical-column -> provider-status) key here:
+ * the github provider's logical-column -> Status mapping IS the existing,
+ * already-load-bearing `queue.statusColumns` (read by `loadStateColumnMap` in
+ * `../loop/queue-board-sync.mjs`; `next_up` is the fail-closed pickup column
+ * `resolve-active-board-item.mjs` reads). Adding a second, inert mapping key
+ * here would collide with that live one rather than replace it. A future
+ * external provider defines its OWN logical -> status mapping (its shape is
+ * provider-specific) when one is actually implemented — YAGNI to generalize
+ * this now for a provider that does not exist yet.
+ */
+const TrackerConfig = z.strictObject({
+  provider: z.string().trim().min(1).describe("Tracker provider registry key. Built-in: \"github\" (default).").optional(),
+  plugin: z.string().trim().min(1).describe("Reserved: module specifier for an external tracker provider plugin (post-1.0, not implemented in this pass).").optional(),
+  board: boardRefConfig("tracker.board").describe("Tracker board identifier; supersedes the deprecated queue.board.").optional(),
+});
+
 /**
  * Worktree lifecycle config (#909): which gitignored files/dirs to provision
  * into a fresh worktree from the main checkout. Entries are repo-relative
- * literal paths OR glob patterns. `copyOnInit` → `fs.cp` (isolated per
- * worktree); `linkOnInit` → absolute symlink into the main checkout (read-only
- * data). Both optional; empty/absent is a valid no-op.
+ * literal paths OR glob patterns, each tagged with its mode (was two parallel
+ * `copyOnInit`/`linkOnInit` arrays encoding the mode via which array it lived
+ * in). `copy` → `fs.cp` (isolated per worktree); `link` → absolute symlink
+ * into the main checkout (read-only data). Empty/absent is a valid no-op.
  */
+const WorktreeEntry = z.strictObject({
+  path: z.string().trim().min(1).describe("Repo-relative path or glob."),
+  mode: z.enum(["copy", "link"]).describe("copy = fs.cp into the worktree (isolated, mutable); link = absolute symlink to the main checkout (shared, read-only)."),
+});
+
 const WorktreeConfig = z.strictObject({
-  copyOnInit: z.array(z.string().trim().min(1)).describe("Repo-relative paths/globs copied into a fresh worktree (isolated per worktree — use for mutable files).").optional(),
-  linkOnInit: z.array(z.string().trim().min(1)).describe("Repo-relative paths/globs symlinked to the main checkout (shared — read-only data only).").optional(),
+  entries: z.array(WorktreeEntry).optional().describe("Gitignored paths/globs provisioned into a fresh worktree."),
 });
 
 /**
@@ -453,16 +722,6 @@ const UiReviewConfig = z.strictObject({
 /** Internal path whitelist for internal-only PR detection — flat array of regex strings */
 const InternalPatternsConfig = z.array(z.string().trim().min(1)).min(1);
 
-const PersonaEntry = z.strictObject({
-  persona: z.string().min(1),
-  // Optional in the merged/full schema so consumer overrides can replace
-  // only persona/defaultModel without having to restate the inherited prompt.
-  prompt: z.string().min(1).optional().describe("Short focused instruction for the reviewer agent — what to look for and how to judge this angle"),
-  defaultModel: z.string().trim().min(1).nullable().default(null),
-});
-
-const PersonasConfig = z.record(z.string().min(1), PersonaEntry);
-
 // Partial nested gate entries for file-level config (allows overriding only
 // requireCi/required/angles without restating the whole gate object).
 const FileGatesConfig = z.strictObject({
@@ -474,17 +733,22 @@ 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(),
-  anglePool: z.array(z.string().trim().min(1)).describe("Explicit global lens catalog for additive angle selection.").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(),
 });
 
-// Partial persona entries for file-level config (allows omitting fields)
-const FilePersonasConfig = z.record(z.string().min(1), PersonaEntry.partial());
-
 // ============================================================================
 // Full schema — families are optional (BUILT_IN_DEFAULTS provides fallback)
+//
+// The `tracker:` config block is intentionally reserved here; a future
+// tracker-seam change adds it on top of this restructured schema. Not added
+// in this pass — this is the config-shape redesign only — but resolvers in
+// this module take the effective config as a plain parameter (no
+// global/singleton reads), so a later tracker adapter (and any multi-tracker
+// layer on top of it) stays additive.
 // ============================================================================
 
 /**
@@ -503,13 +767,10 @@ export const DevLoopConfigSchema = z.strictObject({
   workflow: WorkflowConfig.optional(),
   localImplementation: LocalImplementationConfig.optional(),
   queue: QueueConfig.optional(),
-  personas: PersonasConfig.optional(),
+  tracker: TrackerConfig.optional(),
   internalPathPatterns: InternalPatternsConfig.optional(),
   worktree: WorktreeConfig.optional(),
   uiReview: UiReviewConfig.optional(),
-  // Deprecated (removed in #1088): tolerated so consumer .devloops files that
-  // still carry a localPlanning block keep parsing. Accepted, never read.
-  localPlanning: z.unknown().optional(),
 });
 
 // ============================================================================
@@ -518,18 +779,16 @@ export const DevLoopConfigSchema = z.strictObject({
 
 export const BUILT_IN_DEFAULTS = Object.freeze({
   version: 1,
-  strategy: Object.freeze({ default: "local-first" }),
-  inputSource: Object.freeze({ default: "tracker" }),
+  strategy: "local-first",
+  inputSource: "tracker",
   models: Object.freeze({}),
-  refinement: Object.freeze({ fanOut: 3, mode: "parallel", maxCopilotRounds: 5, stopOnLowSignal: false, lowSignalRoundThreshold: 3, lowSignalMaxComments: 2 }),
+  refinement: Object.freeze({ fanOut: 3, mode: "parallel", maxCopilotRounds: 5, lowSignal: Object.freeze({ enabled: false, roundThreshold: 3, maxComments: 2 }) }),
   gates: Object.freeze({}),
   autonomy: Object.freeze({ stopAt: Object.freeze(["merge"]), humanMergeOnly: false }),
   approval: Object.freeze({
-    humanHandoff: Object.freeze({
-      enabled: false,
-      candidatesFrom: Object.freeze([]),
-      assignees: Object.freeze([]),
-    }),
+    enabled: false,
+    candidatesFrom: Object.freeze([]),
+    assignees: Object.freeze([]),
   }),
   workflow: Object.freeze({
     asyncStartMode: "required",
@@ -539,17 +798,22 @@ export const BUILT_IN_DEFAULTS = Object.freeze({
   }),
   localImplementation: Object.freeze({
     lightMode: Object.freeze({ enabled: false, maxFiles: 3, maxLines: 200, maxCopilotRounds: 1 }),
-    issueless: Object.freeze({ enabled: false }),
+    issueless: false,
   }),
   queue: Object.freeze({
     maxParallel: 3,
     maxAutoFiledIssues: 10,
     reDispatchMaxRetries: 1,
-    // projectNumber and boardTitle are intentionally absent from defaults
-    // — setting either is an explicit operator opt-in for Projects-based
-    // queue ordering.
+    // queue.board is intentionally absent from defaults — setting it is an
+    // explicit operator opt-in for Projects-based queue ordering.
+  }),
+  tracker: Object.freeze({
+    provider: "github",
+    // tracker.board is intentionally absent from defaults — setting it is an
+    // explicit operator opt-in (mirrors queue.board). The logical-column ->
+    // Status mapping is queue.statusColumns (see TrackerConfig above), not a
+    // tracker-owned default.
   }),
-  personas: Object.freeze({}),
   internalPathPatterns: Object.freeze([
     "^scripts/",
     "^docs/",
@@ -558,7 +822,7 @@ export const BUILT_IN_DEFAULTS = Object.freeze({
     "^\\.github/",
     "^test/",
   ]),
-  worktree: Object.freeze({ copyOnInit: Object.freeze([]), linkOnInit: Object.freeze([]) }),
+  worktree: Object.freeze({ entries: Object.freeze([]) }),
 });
 
 // ============================================================================
@@ -567,9 +831,9 @@ export const BUILT_IN_DEFAULTS = Object.freeze({
 
 export const FileConfigSchema = z.strictObject({
   version: z.literal(1).describe("Config format version; always 1."),
-  strategy: StrategyConfig.partial().describe("Work-intake strategy defaults.").optional(),
-  inputSource: InputSourceConfig.partial().describe("Spec source for local-first work.").optional(),
-  models: ModelsConfigBase.partial().superRefine(refineRoleTiers).describe("Model routing: conductor override, per-role/angle overrides, tier aliases, and role→tier policy.").optional(),
+  strategy: StrategyConfig.optional().describe("Work-intake strategy default."),
+  inputSource: InputSourceConfig.optional().describe("Spec source for local-first work."),
+  models: ModelsConfigBase.partial().superRefine(refineRoleTiers).describe("Model routing: conductor override, per-role overrides, tier aliases, and role→tier policy.").optional(),
   refinement: RefinementConfig.partial().describe("Refinement fan-out and Copilot review-round behavior.").optional(),
   gates: FileGatesConfig.describe("Gate review configuration: per-gate angle sets plus fan-out enforcement knobs.").optional(),
   autonomy: AutonomyConfig.partial().describe("How far the loop proceeds without operator confirmation.").optional(),
@@ -577,28 +841,27 @@ export const FileConfigSchema = z.strictObject({
   workflow: WorkflowConfig.partial().describe("Workflow posture: draft-first, retrospectives, dev mode, async start.").optional(),
   localImplementation: LocalImplementationConfig.partial().describe("Local implementation dispatch (light mode for small scoped changes).").optional(),
   queue: QueueConfig.partial().describe("Queue mode: parallelism, auto-filing caps, and Projects board opt-in.").optional(),
-  personas: FilePersonasConfig.describe("Gate-angle → reviewer persona registry overrides (angle name → persona, prompt, default model).").optional(),
+  tracker: TrackerConfig.partial().describe("Tracker seam config: provider (default \"github\") and board. The github provider's logical-column->Status mapping is the existing queue.statusColumns; a future external provider defines its own.").optional(),
   internalPathPatterns: InternalPatternsConfig.describe("Regex whitelist for internal-only PR detection.").optional(),
   worktree: WorktreeConfig.partial().describe("Worktree provisioning: gitignored files/dirs copied or symlinked into fresh worktrees.").optional(),
   uiReview: UiReviewConfig.partial().describe("UI-review route recipes: per-project run/boot, dev-login, driven flows, and caps.").optional(),
-  // Deprecated (removed in #1088): tolerated so consumer .devloops files that
-  // still carry a localPlanning block keep parsing. Accepted, never read.
-  localPlanning: z.unknown().optional(),
+  // 1.0 hard break (no dual-form): the deprecated `localPlanning` key (removed
+  // behavior in #1088, tolerated-but-unread since) is dropped from the 1.0
+  // schema entirely — an unknown key now fails closed like any other typo,
+  // rather than silently parsing and doing nothing.
 });
 
 // ============================================================================
-// Built-in persona registry — fallback when config.personas is absent
+// Built-in persona registry — fallback for gate-review angle → reviewer
+// persona resolution.
 //
-// Maps gate-review angle names to reviewer personas. Only the persona name
-// is defined here; prompts and per-angle model defaults live in the config
-// (.pi/dev-loop/defaults.yaml personas section).
-//
-// Consumers can extend or override these by adding personas entries to
-// their .pi/dev-loop/defaults.* or settings.* config files (with legacy overrides.* fallback). Config-resolved
-// personas take priority over this built-in registry.
+// Maps gate-review angle names to reviewer personas. Only the persona name is
+// defined here; prompts and per-angle model overrides live on the angle's own
+// config entry (gates.<gate>.angles[].persona/.prompt/.model/.tier) when a
+// consumer wants to override this registry — see resolveReviewerRole.
 //
 // Angle names come from the gate-angle config (gates.draft.angles /
-// gates.preApproval.angles in .pi/dev-loop/defaults.yaml).
+// gates.preApproval.angles in extension-defaults.yaml).
 // ============================================================================
 
 const BUILTIN_PERSONAS = Object.freeze({
@@ -641,17 +904,142 @@ const DEFAULT_REVIEWER_PERSONA = "default-reviewer";
  * @property {boolean} fallback - True when no specialized persona was found
  */
 
+/**
+ * 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? }`.
+ * 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}
+ */
+function normalizeAngleEntry(a) {
+  if (typeof a === "string") {
+    const name = a.trim();
+    return name.length > 0 ? { name } : null;
+  }
+  if (a && typeof a === "object" && !Array.isArray(a)) {
+    const name = typeof a.name === "string" ? a.name.trim() : "";
+    if (name.length === 0) return null;
+    const entry = { name };
+    if (a.mandatory === true) entry.mandatory = true;
+    if (a.enabled === false) entry.enabled = false;
+    if (typeof a.persona === "string" && a.persona.trim().length > 0) entry.persona = a.persona.trim();
+    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;
+}
+
+/**
+ * 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}>}
+ */
+function normalizeAngleEntries(raw) {
+  if (!Array.isArray(raw)) return [];
+  const out = [];
+  for (const a of raw) {
+    const entry = normalizeAngleEntry(a);
+    if (entry) out.push(entry);
+  }
+  return out;
+}
+
+/**
+ * Find a named angle's configured entry, searching this config's own gates in
+ * a fixed priority order (draft, preApproval, spike). Angle persona/prompt/
+ * model/tier now live on the gate's own angle entry (D3/D4 — folded from the
+ * removed top-level `personas` map and angle-keyed `models.roles`/
+ * `models.roleTiers`), so a lookup by name alone (no gate context, matching
+ * `resolveReviewerRole`/`resolveRoleModel`'s existing signatures) checks each
+ * gate in turn and returns the first match. The shipped default config never
+ * gives the same angle name divergent overrides across gates, so this is
+ * unambiguous in practice.
+ *
+ * A DISABLED entry (`enabled: false`) is skipped, never returned: the same
+ * angle name can be a real, enabled angle with its own persona/prompt on one
+ * gate while merely disabled (a bare `enabled:false` placeholder, no override
+ * fields) on another — e.g. a gate that inherited the name via merge-by-name
+ * (D3) and dropped it. Returning that placeholder would shadow the other
+ * gate's real override. Both callers of this function (resolveReviewerRole,
+ * resolveRoleModel's angle path) only ever look up a name already present in
+ * SOME gate's enabled, resolved angle list (`resolveGateAngles`), so a name
+ * disabled everywhere and enabled nowhere is never actually queried — there
+ * is no "return the disabled entry as a last resort" case to serve.
+ * @param {DevLoopConfig} config
+ * @param {string} name
+ * @returns {{name: string, mandatory?: boolean, enabled?: boolean, persona?: string, prompt?: string, model?: string, tier?: string}|null}
+ */
+function findAngleEntry(config, name) {
+  for (const gate of ["draft", "preApproval", "spike"]) {
+    const entries = normalizeAngleEntries(config?.gates?.[gate]?.angles);
+    const found = entries.find((e) => e.name === name && e.enabled !== false);
+    if (found) return found;
+  }
+  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
+ * a partial config override (e.g. `{ pi: "..." }`) preserves the untouched
+ * built-in harness key rather than erasing the whole `{claude,pi}` mapping.
+ * @param {DevLoopConfig} config
+ * @param {string|undefined} tierAlias
+ * @param {"claude"|"pi"} harness
+ * @returns {string|null}
+ */
+function resolveTierMapping(config, tierAlias, harness) {
+  if (!tierAlias || tierAlias === "inherit") return null;
+  const builtinMapping = BUILTIN_TIERS[tierAlias];
+  const configMapping = config?.models?.tiers?.[tierAlias];
+  if (!builtinMapping && !configMapping) return null;
+  const mapping = { ...builtinMapping, ...configMapping };
+  const model = mapping[harness];
+  return typeof model === "string" && model.trim().length > 0 ? model.trim() : null;
+}
+
 /**
  * Resolve a gate angle name to a reviewer persona and model.
  *
  * Resolution order:
- * 1. Look up angle in config.personas[angle] (consumer overrides)
+ * 1. Look up the angle's own configured entry across this config's gates
+ *    (`gates.<gate>.angles[].persona`/`.prompt`/`.model` — consumer overrides,
+ *    see {@link findAngleEntry})
  * 2. If not found in config, look up in BUILTIN_PERSONAS
- * 3. If found in either, apply model override from config.models.roles[angle] if present
+ * 3. If found in either, apply the entry's `model` override if present
  * 4. If not found anywhere, fall back to default reviewer with angle as focus lens,
- *    still applying any model override from config
+ *    still applying any `model` override from the entry
  *
- * @param {object} config - DevLoopConfig (or partial with personas, models.roles)
+ * @param {object} config - DevLoopConfig (or a partial with gates)
  * @param {string|null|undefined} angle - Gate angle / lens name
  * @returns {RoleResolutionResult}
  */
@@ -666,17 +1054,16 @@ export function resolveReviewerRole(config, angle) {
     };
   }
 
-  // Resolution: config.personas > BUILTIN_PERSONAS > default-reviewer
-  const configPersona = config?.personas?.[angle] ?? null;
+  const entry = findAngleEntry(config, angle);
   const builtinPersona = BUILTIN_PERSONAS[angle] ?? null;
-  const persona = configPersona ?? builtinPersona;
-  const modelOverride = config?.models?.roles?.[angle] || null;
+  const personaName = entry?.persona ?? builtinPersona?.persona ?? null;
+  const modelOverride = entry?.model ?? null;
 
-  if (persona) {
+  if (personaName) {
     return {
-      persona: persona.persona,
-      model: modelOverride || persona.defaultModel || null,
-      prompt: persona.prompt || null,
+      persona: personaName,
+      model: modelOverride || builtinPersona?.defaultModel || null,
+      prompt: entry?.prompt ?? null,
       fallback: false,
     };
   }
@@ -695,19 +1082,20 @@ export function resolveReviewerRole(config, angle) {
  * `null` (inherit → pass no model override).
  *
  * Precedence:
- *   1. `models.roles[role]` — concrete per-role/angle override (highest).
- *   2. Tier alias, mapped through `models.tiers[tier][harness]` (or built-in
- *      tiers); `inherit`/absent/null → `null`. The alias depends on `kind`:
- *      - `kind: "angle"` (gate review dispatch): an explicit
- *        `models.roleTiers[role]` override, else the `review` tier. A gate
- *        review runs at review quality even when the angle's name collides with
- *        a routine role — e.g. the `docs` angle resolves via the `review` tier
- *        (high), not the `docs` writer role's low tier. (Its persona/agent still
- *        comes from `resolveReviewerRole`; only the tier is forced to review.)
- *      - `kind: "role"`/absent (routine subagent): `models.roleTiers[role]` (or
- *        the built-in role tier), else — when the name is not a named role — the
- *        tier for its review persona (so a non-colliding gate angle passed
- *        without `kind` still resolves high via `review`).
+ *   1. `kind: "angle"` (gate review dispatch): the angle's own configured
+ *      `model` (concrete, found via {@link findAngleEntry}), else its `tier`,
+ *      else the built-in `review` tier — a gate review runs at review quality
+ *      even when the angle's name collides with a routine role, e.g. the
+ *      `docs` angle resolves via the `review` tier (high), not the `docs`
+ *      writer role's low tier. (Its persona/agent still comes from
+ *      `resolveReviewerRole`; only the tier is forced to review.)
+ *   2. `kind: "role"`/absent (routine subagent): `models.roles[role]`
+ *      (concrete, highest precedence), else `models.roleTiers[role]` (or the
+ *      built-in role tier) mapped through `models.tiers[tier][harness]` (or
+ *      built-in tiers); `inherit`/absent/null → `null`. When the name is not a
+ *      named role, falls back to the tier for its review persona (so a
+ *      non-colliding gate angle passed without `kind` still resolves high via
+ *      `review`).
  *
  * Callers dispatching a gate review angle whose name may collide with a routine
  * role (only `docs` today) MUST pass `kind: "angle"` to avoid the silent
@@ -724,40 +1112,31 @@ export function resolveReviewerRole(config, angle) {
 export function resolveRoleModel(config, { role, harness, kind } = {}) {
   if (!role || (harness !== "claude" && harness !== "pi")) return null;
 
-  // 1. Concrete per-role/angle override wins outright (over any tier).
+  if (kind === "angle") {
+    const entry = findAngleEntry(config, role);
+    if (typeof entry?.model === "string" && entry.model.length > 0) return entry.model;
+    const tierAlias = entry?.tier ?? BUILTIN_ROLE_TIERS.review;
+    return resolveTierMapping(config, tierAlias, harness);
+  }
+
+  // 1. Concrete per-role override wins outright (over any tier). Role-keyed
+  // only — angle-keyed concrete overrides moved to the gate's angle entry
+  // (kind: "angle", above).
   const concrete = config?.models?.roles?.[role];
   if (typeof concrete === "string" && concrete.trim().length > 0) {
     return concrete.trim();
   }
 
-  // 2. Resolve a tier alias for this role/angle.
+  // 2. Resolve a tier alias for this role.
   const roleTiers = { ...BUILTIN_ROLE_TIERS, ...(config?.models?.roleTiers ?? {}) };
-  let tierAlias;
-  if (kind === "angle") {
-    // Gate review angle: an explicit per-angle override wins, else the review
-    // tier — a gate review is review-quality regardless of a coincidental
-    // routine-role persona name (the `docs` angle must not inherit `docs`→low).
-    tierAlias = config?.models?.roleTiers?.[role] ?? roleTiers.review;
-  } else {
-    tierAlias = roleTiers[role];
-    if (tierAlias === undefined) {
-      // Not a named role — treat as a gate angle and inherit its review
-      // persona's tier (critical angles resolve high via the `review` persona).
-      const { persona } = resolveReviewerRole(config, role);
-      tierAlias = roleTiers[persona];
-    }
+  let tierAlias = roleTiers[role];
+  if (tierAlias === undefined) {
+    // Not a named role — treat as a gate angle and inherit its review
+    // persona's tier (critical angles resolve high via the `review` persona).
+    const { persona } = resolveReviewerRole(config, role);
+    tierAlias = roleTiers[persona];
   }
-  if (!tierAlias || tierAlias === "inherit") return null;
-
-  // Deep-merge the alias mapping so a partial override (e.g. `{ pi: "..." }`,
-  // which the schema allows) preserves the untouched built-in harness key rather
-  // than erasing the whole {claude,pi} mapping and resolving null for that harness.
-  const builtinMapping = BUILTIN_TIERS[tierAlias];
-  const configMapping = config?.models?.tiers?.[tierAlias];
-  if (!builtinMapping && !configMapping) return null;
-  const mapping = { ...builtinMapping, ...configMapping };
-  const model = mapping[harness];
-  return typeof model === "string" && model.trim().length > 0 ? model.trim() : null;
+  return resolveTierMapping(config, tierAlias, harness);
 }
 
 // ============================================================================
@@ -789,11 +1168,16 @@ function resolveExtensionDefaultsPath(options = {}) {
 
 // ============================================================================
 
+/** True for a non-null, non-array plain object. */
+function isPlainObject(v) {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+
 /**
  * Merge two config objects. Keys in `source` override keys in `target`.
  * Family objects merge at one level, except `gates`, which merges one extra
  * nested gate-object level so settings can override `draft.requireCi` without
- * restating the shipped draft angles.
+ * restating the shipped draft angles (see {@link mergeGatesFamily}).
  * @param {Record<string, unknown>} target
  * @param {Record<string, unknown>} source
  * @returns {Record<string, unknown>}
@@ -801,17 +1185,9 @@ function resolveExtensionDefaultsPath(options = {}) {
 function mergeConfigLayers(target, source) {
   const result = { ...target };
   for (const key of Object.keys(source)) {
-    if (
-      key !== "version" &&
-      typeof source[key] === "object" &&
-      source[key] !== null &&
-      !Array.isArray(source[key]) &&
-      typeof result[key] === "object" &&
-      result[key] !== null &&
-      !Array.isArray(result[key])
-    ) {
+    if (key !== "version" && isPlainObject(source[key]) && isPlainObject(result[key])) {
       result[key] = key === "gates"
-        ? mergeNestedObject(result[key], source[key])
+        ? mergeGatesFamily(result[key], source[key])
         : { ...(result[key] || {}), ...(source[key] || {}) };
     } else {
       result[key] = source[key];
@@ -820,27 +1196,70 @@ function mergeConfigLayers(target, source) {
   return result;
 }
 
-function mergeNestedObject(target, source) {
-  const result = { ...(target || {}) };
+const MERGE_BY_NAME_GATE_KEYS = Object.freeze(["draft", "preApproval", "spike"]);
 
+/** Merge the `gates` family: draft/preApproval/spike get the gate-object merge
+ * ({@link mergeGateObject}, angle-array-by-name aware); every other `gates.*`
+ * key (`anglePool`, `requireFanoutEvidence`, ...) merges shallowly as before. */
+function mergeGatesFamily(target, source) {
+  const result = { ...(target || {}) };
   for (const key of Object.keys(source || {})) {
-    if (
-      typeof source[key] === "object" &&
-      source[key] !== null &&
-      !Array.isArray(source[key]) &&
-      typeof result[key] === "object" &&
-      result[key] !== null &&
-      !Array.isArray(result[key])
-    ) {
+    if (MERGE_BY_NAME_GATE_KEYS.includes(key) && isPlainObject(source[key]) && isPlainObject(result[key])) {
+      result[key] = mergeGateObject(result[key], source[key]);
+    } else if (isPlainObject(source[key]) && isPlainObject(result[key])) {
       result[key] = { ...(result[key] || {}), ...(source[key] || {}) };
     } else {
       result[key] = source[key];
     }
   }
+  return result;
+}
 
+/**
+ * Merge one gate object (draft/preApproval/spike) across config layers.
+ * `angles` merges BY NAME (D3): a later layer can add a new angle, or override
+ * an existing angle's flags (including `enabled: false` to drop it), without
+ * restating the whole array. `dynamic` merges shallowly (its two booleans).
+ * Every other key (`required`, `requireCi`, `blockCleanOnFindingSeverities`)
+ * is replaced wholesale, same as any scalar/array config value.
+ */
+function mergeGateObject(target, source) {
+  const result = { ...(target || {}) };
+  for (const key of Object.keys(source || {})) {
+    if (key === "angles") {
+      result.angles = mergeAngleArrays(result.angles, source.angles);
+    } else if (key === "dynamic" && isPlainObject(source.dynamic) && isPlainObject(result.dynamic)) {
+      result.dynamic = { ...(result.dynamic || {}), ...(source.dynamic || {}) };
+    } else {
+      result[key] = source[key];
+    }
+  }
   return result;
 }
 
+/**
+ * Merge two `gates.<gate>.angles` arrays BY `name` (D3): entries in `target`
+ * keep their position; a `source` entry with a name already in `target`
+ * overrides that entry's fields (shallow — e.g. `{ enabled: false }` drops it
+ * without touching its `persona`/`prompt`); a `source` entry with a new name
+ * is appended. This is what lets a later config layer add or disable a single
+ * angle without restating the whole upstream list.
+ * @param {unknown} targetRaw
+ * @param {unknown} sourceRaw
+ * @returns {Array<{name: string}>}
+ */
+function mergeAngleArrays(targetRaw, sourceRaw) {
+  const targetEntries = normalizeAngleEntries(targetRaw);
+  const sourceEntries = normalizeAngleEntries(sourceRaw);
+  if (targetEntries.length === 0) return sourceEntries;
+  const byName = new Map(targetEntries.map((e) => [e.name, e]));
+  for (const entry of sourceEntries) {
+    const existing = byName.get(entry.name);
+    byName.set(entry.name, existing ? { ...existing, ...entry } : entry);
+  }
+  return [...byName.values()];
+}
+
 /**
  * Try to read and parse a config file (YAML preferred, JSON fallback).
  * Detects format from file extension: .yaml/.yml → YAML, .json → JSON.
@@ -975,7 +1394,41 @@ async function applyLayer(merged, basePaths, layer, warnings, errors, options =
     return merged;
   }
 
-  // Validate the file's structure before merging
+  // Deprecated `strategy: "github-first"` alias (issue #1408, the
+  // tracker-agnostic seam): normalized to "tracker-first" BEFORE this layer's
+  // own FileConfigSchema validation, since the schema enum only accepts the
+  // canonical value and would otherwise drop the whole layer as invalid.
+  if (data.strategy === "github-first") {
+    warnings.push(
+      `strategy: "github-first" is a deprecated alias for "tracker-first" (issue #1408). ` +
+      `Update ${path.basename(filePath)} to use "tracker-first"; the alias will be removed in a future version.`
+    );
+    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`
+  // is returned unchanged) rather than merging the rest of the file's valid
+  // keys — a single typo'd angle field is exactly as disruptive as a
+  // completely broken file. `errors[].message` now names the offending
+  // path/field (see GateAngleEntry's preprocess-not-union shape), so the
+  // failure is at least actionable; the whole-layer-skip granularity itself
+  // is an existing, separate concern.
   const validation = FileConfigSchema.safeParse(data);
   if (!validation.success) {
     errors.push({
@@ -1119,6 +1572,20 @@ export async function loadDevLoopConfig(options = {}) {
     }
   }
 
+  // Deprecated `queue.board` -> `tracker.board` alias (issue #1408, the
+  // tracker-agnostic seam). Runs on the fully-merged object (unlike the
+  // `strategy: "github-first"` alias above, this only affects cross-layer
+  // MERGE PRECEDENCE, not per-layer schema validity — queue.board is still a
+  // valid FileConfigSchema shape on its own — so normalizing once here, after
+  // every layer has merged, is sufficient).
+  if (isPlainObject(merged.queue?.board) && !isPlainObject(merged.tracker?.board)) {
+    warnings.push(
+      `queue.board is a deprecated alias for tracker.board (issue #1408). ` +
+      `Update .devloops to set tracker.board instead; the alias will be removed in a future version.`
+    );
+    merged = { ...merged, tracker: { ...(merged.tracker ?? {}), board: merged.queue.board } };
+  }
+
   // Validate final merged config
   const result = DevLoopConfigSchema.safeParse(merged);
   if (!result.success) {
@@ -1265,15 +1732,15 @@ export function resolveRefinementConfig(config, key) {
   }
 
   if (key === "stopOnLowSignal") {
-    return config?.refinement?.stopOnLowSignal ?? DEFAULT_REFINEMENT_CONFIG.stopOnLowSignal;
+    return config?.refinement?.lowSignal?.enabled ?? DEFAULT_REFINEMENT_CONFIG.lowSignal.enabled;
   }
 
   if (key === "lowSignalRoundThreshold") {
-    return config?.refinement?.lowSignalRoundThreshold ?? DEFAULT_REFINEMENT_CONFIG.lowSignalRoundThreshold;
+    return config?.refinement?.lowSignal?.roundThreshold ?? DEFAULT_REFINEMENT_CONFIG.lowSignal.roundThreshold;
   }
 
   if (key === "lowSignalMaxComments") {
-    return config?.refinement?.lowSignalMaxComments ?? DEFAULT_REFINEMENT_CONFIG.lowSignalMaxComments;
+    return config?.refinement?.lowSignal?.maxComments ?? DEFAULT_REFINEMENT_CONFIG.lowSignal.maxComments;
   }
 
   throw new Error(`Unknown refinement config key: ${key}`);
@@ -1316,29 +1783,46 @@ export function resolveRefinement(config) {
  * config omits them (caller falls back to skill-defined defaults). Boolean gate
  * flags always resolve to stable defaults.
  *
+ * The returned shape is the STABLE, resolved view every other angle resolver
+ * and consumer builds on — `mandatoryAngles`/`excludeAngles`/`dynamicAngles`/
+ * `additiveAngles` are derived here from the unified `gates.<gate>.angles`
+ * array (`mandatory: true` / `enabled: false` per-entry, D3) and the
+ * `gates.<gate>.dynamic` sub-object, so downstream consumers keep reading the
+ * same field names the pre-1.0 flat config keys used. (`extraAngles` no
+ * longer exists as a concept: D3's merge-by-name lets a later config layer add
+ * a plain, non-mandatory angle to `angles` directly, without restating the
+ * list — the exact ergonomic `extraAngles` used to provide.)
+ *
  * @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];
+  const entries = normalizeAngleEntries(gateConfig?.angles);
+  // An explicitly-empty (or all-garbage/malformed) array is a real configured
+  // "no angles" — distinct from the key being absent entirely, which callers
+  // read as "fall back to skill-defined defaults" (angles: null).
+  const hasAngles = Array.isArray(gateConfig?.angles);
   return {
-    angles: gateConfig?.angles && Array.isArray(gateConfig.angles)
-      ? gateConfig.angles.map(a => (typeof a === "string" ? a.trim() : "")).filter(a => a.length > 0)
-      : null,
-    excludeAngles: gateConfig?.excludeAngles && Array.isArray(gateConfig.excludeAngles)
-      ? gateConfig.excludeAngles.map(a => (typeof a === "string" ? a.trim() : "")).filter(a => a.length > 0)
-      : [],
-    mandatoryAngles: gateConfig?.mandatoryAngles && Array.isArray(gateConfig.mandatoryAngles)
-      ? gateConfig.mandatoryAngles.map(a => (typeof a === "string" ? a.trim() : "")).filter(a => a.length > 0)
-      : [],
+    angles: hasAngles ? entries.filter((e) => e.enabled !== false).map((e) => e.name) : null,
+    excludeAngles: entries.filter((e) => e.enabled === false).map((e) => e.name),
+    mandatoryAngles: entries.filter((e) => e.enabled !== false && e.mandatory === true).map((e) => e.name),
     required: gateConfig?.required ?? true,
     requireCi: gateConfig?.requireCi ?? true,
-    dynamicAngles: gateConfig?.dynamicAngles ?? false,
-    additiveAngles: gateConfig?.additiveAngles ?? 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 ?? [],
   };
 }
 
@@ -1351,7 +1835,7 @@ export function resolveGateConfig(config, gate) {
  * a durable findings-log ledger exists for that gate + head SHA. Using a
  * `!== false` test (rather than `=== true`) keeps the opt-out semantics robust
  * for programmatically-built config objects that bypass schema defaulting. See
- * docs/gate-review-sub-loop-contract.md.
+ * skills/docs/gate-review-sub-loop-contract.md.
  *
  * @param {DevLoopConfig} config
  * @returns {boolean}
@@ -1361,11 +1845,12 @@ 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
- * docs/gate-review-sub-loop-contract.md).
+ * 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;
 
@@ -1377,7 +1862,7 @@ export const FANOUT_PROVENANCE_MIN_REVIEWERS = 2;
  * `=== true` test so behavior is byte-identical to today unless a repo
  * explicitly opts in via `gates.requireFanoutProvenance: true`. Layered on top
  * of fan-out evidence enforcement (see buildFanoutEnforcement). See
- * docs/gate-review-sub-loop-contract.md.
+ * skills/docs/gate-review-sub-loop-contract.md.
  *
  * @param {DevLoopConfig} config
  * @returns {boolean}
@@ -1398,21 +1883,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
- * 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;
 }
 
 /**
@@ -1440,14 +1925,14 @@ export function resolveLightMode(config) {
 /**
  * Resolve the issue-less PR-first any-scope opt-in (#1349).
  *
- * True only when `localImplementation.issueless.enabled` is exactly `true`;
- * absent, false, or malformed values resolve to false (fail closed).
+ * True only when `localImplementation.issueless` is exactly `true`; absent,
+ * false, or malformed values resolve to false (fail closed).
  *
  * @param {DevLoopConfig} config
  * @returns {boolean}
  */
 export function resolveIssuelessEnabled(config) {
-  return config?.localImplementation?.issueless?.enabled === true;
+  return config?.localImplementation?.issueless === true;
 }
 
 /**
@@ -1523,21 +2008,197 @@ 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.
  *
- * Merges mandatoryAngles with the configured candidate angles, filters
- * through excludeAngles, and deduplicates. Returns null only when both
- * angles and mandatoryAngles are absent/empty for the given gate (caller
- * falls back to skill-defined defaults).
+ * Unions the mandatory angle names (entries with `mandatory: true`) with the
+ * gate's full configured angle list, then removes disabled entries
+ * (`enabled: false`): `mandatoryAngles ∪ angles − disabled`, deduplicated (a
+ * mandatory angle also present in `angles` is a no-op — it appears exactly
+ * once and keeps its mandatory status). Returns null only when the gate has
+ * no configured `angles` at all (caller falls back to skill-defined
+ * defaults); an explicitly-empty `angles: []` returns `[]`.
  *
  * @param {DevLoopConfig} config
  * @param {"draft"|"preApproval"} gate
@@ -1546,6 +2207,11 @@ export function resolveGateDispatchMode(config, gate, { scope, hasFullLabel = fa
 export function resolveGateAngles(config, gate) {
   const gateConfig = resolveGateConfig(config, gate);
   if (gateConfig.angles === null && gateConfig.mandatoryAngles.length === 0) return null;
+  // gateConfig.angles is already exclude-filtered (resolveGateConfig drops
+  // enabled:false entries); the excludeAngles filter below is a defensive
+  // no-op that keeps this correct even for a hand-built config object that
+  // sets excludeAngles/angles independently rather than through the
+  // gates.<gate>.angles[].enabled shape.
   const excluded = new Set(gateConfig.excludeAngles);
   const merged = [...new Set([...gateConfig.mandatoryAngles, ...(gateConfig.angles ?? [])])];
   return merged.filter(a => !excluded.has(a));
@@ -1607,14 +2273,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
@@ -1622,13 +2353,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) {
@@ -1732,24 +2505,105 @@ export function resolveWorkflowConfig(config, key) {
   throw new Error(`Unknown workflow config key: ${key}`);
 }
 
+/** Best-effort `git` probe: stdout trimmed on success, `null` on any failure
+ * (missing repo, missing ref, git not on PATH, etc.) — never throws. */
+function tryGit(args, cwd) {
+  try {
+    return execFileSync("git", args, { cwd, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] }).trim();
+  } catch {
+    return null;
+  }
+}
+
+// Last-resort literal when git auto-detection cannot resolve anything (e.g. no
+// git repo at cwd) — matches the branch name every prior hardcoded "main"/
+// "origin/main" call site already assumed.
+const AUTO_DETECT_BASE_BRANCH_FALLBACK = "main";
+
+/**
+ * Auto-detect the repo's default branch (bare name) at `cwd`: prefer the
+ * remote's advertised default (`origin/HEAD`, works for any branch name), else
+ * probe `main`/`master` as a remote-tracking or local ref, else fall back to
+ * the literal "main". Every probe is best-effort; a missing/unreadable repo
+ * degrades to the literal fallback rather than throwing.
+ * @param {string} cwd
+ * @returns {string}
+ */
+function autoDetectDefaultBranch(cwd) {
+  const originHead = tryGit(["rev-parse", "--abbrev-ref", "origin/HEAD"], cwd);
+  if (originHead && originHead.startsWith("origin/")) {
+    return originHead.slice("origin/".length);
+  }
+  for (const candidate of ["main", "master"]) {
+    if (tryGit(["rev-parse", "--verify", "--quiet", `refs/remotes/origin/${candidate}`], cwd) !== null) return candidate;
+    if (tryGit(["rev-parse", "--verify", "--quiet", `refs/heads/${candidate}`], cwd) !== null) return candidate;
+  }
+  return AUTO_DETECT_BASE_BRANCH_FALLBACK;
+}
+
+/**
+ * Resolve the effective base/integration branch (bare name — never
+ * `origin/`-prefixed) for worktree creation, PR targeting, and merge-base
+ * scope measurement (#1368).
+ *
+ * `workflow.baseBranch` (a non-empty trimmed string) is the authoritative
+ * override; unset, malformed, or empty is treated identically to unset and
+ * falls back to the existing auto-detect: the remote's advertised default
+ * branch (`origin/HEAD`), else `main`/`master`, else the literal "main".
+ * Never throws.
+ *
+ * Callers own the `origin/` prefix: worktree creation prepends it (a remote
+ * ref), gh/PR base flags pass the bare name straight through.
+ *
+ * @param {DevLoopConfig|null|undefined} config
+ * @param {{ cwd?: string }} [options]
+ * @returns {string} bare branch name
+ */
+export function resolveBaseBranch(config, { cwd = process.cwd() } = {}) {
+  const configured = config?.workflow?.baseBranch;
+  if (typeof configured === "string" && configured.trim().length > 0) {
+    // A prefix-only value (e.g. "origin/", "refs/heads/") normalizes to empty —
+    // treat that as unset and fall through to auto-detect, never return "".
+    const bare = normalizeToBareBranch(configured.trim());
+    if (bare.length > 0) return bare;
+  }
+  return autoDetectDefaultBranch(cwd);
+}
+
+/**
+ * Reduce a configured base value to a BARE branch name. Callers prepend
+ * `origin/` for remote refs, so a configured `origin/main` /
+ * `refs/remotes/origin/main` / `refs/heads/main` must be stripped to `main`
+ * first — otherwise the worktree base double-prefixes to `origin/origin/main`.
+ * A branch name that merely contains a slash (e.g. `spike/vite`) is left intact.
+ */
+export function normalizeToBareBranch(value) {
+  return value
+    .replace(/^refs\/remotes\/origin\//, "")
+    .replace(/^refs\/heads\//, "")
+    .replace(/^origin\//, "");
+}
+
 /**
  * Resolve the worktree lifecycle config from the merged dev-loop config.
  *
- * Returns `{ copyOnInit, linkOnInit }` with empty-array defaults when the
- * config omits the `worktree` section or either list. Entries are trimmed,
- * repo-relative literal paths or glob patterns expanded against the main
- * checkout at provision time. See scripts/loop/provision-worktree.mjs.
+ * Returns `{ copyOnInit, linkOnInit }` (split by each entry's `mode`) with
+ * empty-array defaults when the config omits `worktree.entries` or it is
+ * empty. Entries are trimmed, repo-relative literal paths or glob patterns
+ * expanded against the main checkout at provision time. See
+ * scripts/loop/provision-worktree.mjs.
  *
  * @param {DevLoopConfig} config
  * @returns {{ copyOnInit: string[], linkOnInit: string[] }}
  */
 export function resolveWorktreeConfig(config) {
-  const wt = config?.worktree;
-  const list = (v) =>
-    Array.isArray(v)
-      ? v.map((s) => (typeof s === "string" ? s.trim() : "")).filter((s) => s.length > 0)
-      : [];
-  return { copyOnInit: list(wt?.copyOnInit), linkOnInit: list(wt?.linkOnInit) };
+  const entries = Array.isArray(config?.worktree?.entries) ? config.worktree.entries : [];
+  const pathsForMode = (mode) =>
+    entries
+      .filter((e) => e && typeof e === "object" && e.mode === mode)
+      .map((e) => (typeof e.path === "string" ? e.path.trim() : ""))
+      .filter((p) => p.length > 0);
+  return { copyOnInit: pathsForMode("copy"), linkOnInit: pathsForMode("link") };
 }
 
 /**
@@ -1864,16 +2718,16 @@ export function resolveUiReviewDriveRecipe(config) {
  * Resolve the human-handoff config from the merged dev-loop config (#920).
  *
  * Returns a normalized `{ enabled, candidatesFrom, assignees }`. Defaults to
- * disabled with empty arrays when the `approval.humanHandoff` section is absent.
- * When disabled (default), this is a no-op: callers must not source candidates
- * or assign anyone. Pairs with `autonomy.humanMergeOnly`: when human-merge is
+ * disabled with empty arrays when the `approval` section is absent. When
+ * disabled (default), this is a no-op: callers must not source candidates or
+ * assign anyone. Pairs with `autonomy.humanMergeOnly`: when human-merge is
  * enforced, this names who should take the merge.
  *
  * @param {DevLoopConfig} config
  * @returns {{ enabled: boolean, candidatesFrom: ("codeowners"|"recent-committers")[], assignees: string[] }}
  */
 export function resolveHumanHandoffConfig(config) {
-  const hh = config?.approval?.humanHandoff;
+  const hh = config?.approval;
   const enabled = hh?.enabled === true;
   const list = (v) =>
     Array.isArray(v)
@@ -1894,3 +2748,34 @@ export function resolveHumanHandoffConfig(config) {
     assignees: enabled ? assignees : [],
   };
 }
+
+/**
+ * Resolve the tracker provider registry key (issue #1408). Defaults to
+ * `"github"` — the only built-in provider in v1 — when unset. Callers pass
+ * this to `resolveTrackerAdapter` (`@dev-loops/core/tracker`).
+ *
+ * @param {DevLoopConfig} config
+ * @returns {string}
+ */
+export function resolveTrackerProvider(config) {
+  const raw = config?.tracker?.provider;
+  return typeof raw === "string" && raw.trim().length > 0 ? raw.trim() : "github";
+}
+
+/**
+ * Resolve the effective tracker board identifier. `tracker.board` is
+ * canonical; `queue.board` is a DEPRECATED alias, already normalized onto
+ * `tracker.board` by `loadDevLoopConfig` (with a load-time warning) for any
+ * config that went through the loader. This resolver also accepts a
+ * hand-built config object that sets `queue.board` directly (bypassing the
+ * loader, e.g. in a test) and falls back to it — with no warning, since only
+ * the loader surfaces warnings.
+ *
+ * @param {DevLoopConfig} config
+ * @returns {{ number?: number, title?: string } | null}
+ */
+export function resolveTrackerBoard(config) {
+  if (isPlainObject(config?.tracker?.board)) return config.tracker.board;
+  if (isPlainObject(config?.queue?.board)) return config.queue.board;
+  return null;
+}