@dev-loops/core 0.1.0

package/src/config/config.mjs

@@ -0,0 +1,965 @@
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { parse as parseYaml } from "yaml";
+import { z } from "zod";
+
+// ============================================================================
+// Sub-schemas
+//
+// BUILT_IN_DEFAULTS remains the canonical shipped default surface for loader
+// fallbacks. Select field-level defaults may still exist where merged-schema
+// callers need a stable value even when they construct config objects directly.
+// ============================================================================
+
+const StrategyConfig = z.strictObject({
+  default: z.enum(["local-first", "github-first"]),
+});
+
+const InputSourceConfig = z.strictObject({
+  default: z.enum(["tracker", "phase-docs"]),
+});
+
+const ModelsConfig = z.strictObject({
+  conductor: z.string().trim().min(1).optional(),
+  roles: z.record(z.string(), z.string().trim().min(1)).optional(),
+});
+
+const RefinementConfig = z.strictObject({
+  fanOut: z.number().int().min(1).max(10),
+  mode: z.enum(["parallel", "sequential"]),
+  maxCopilotRounds: z.number().int().positive().default(5),
+  stopOnLowSignal: z.boolean().default(false),
+  lowSignalRoundThreshold: z.number().int().nonnegative().default(3),
+  lowSignalMaxComments: z.number().int().nonnegative().default(2),
+  roles: z.array(z.string().trim().min(1)).optional(),
+});
+
+const GateConfig = z.strictObject({
+  angles: z.array(z.string().trim().min(1)).optional(),
+  excludeAngles: z.array(z.string().trim().min(1)).default([]),
+  mandatoryAngles: z.array(z.string().trim().min(1)).default([]),
+  required: z.boolean().default(true),
+  requireCi: z.boolean().default(true),
+  blockCleanOnFindingSeverities: z
+    .array(z.enum(["must-fix", "worth-fixing-now", "defer"]))
+    .min(1)
+    .default(["must-fix"]),
+  dynamicAngles: z.boolean().default(false),
+});
+
+const GatesConfig = z.strictObject({
+  draft: GateConfig.optional(),
+  // `requireCi` is only behaviorally configurable for the draft gate.
+  // preApproval always requires CI even if config repeats `requireCi`.
+  preApproval: GateConfig.optional(),
+});
+
+const AutonomyConfig = z.strictObject({
+  stopAt: z.array(
+    z.enum(["refinement", "draft-pr", "pre-approval", "merge"])
+  ),
+});
+
+const WorkflowConfig = z.strictObject({
+  asyncStartMode: z.enum(["required", "allowed"]).default("required"),
+  requireRetrospective: z.boolean(),
+  requireRetrospectiveGate: z.boolean().default(false),
+  requireDraftFirst: z.boolean(),
+  devModeDefault: z.boolean(),
+});
+
+const LocalImplementationConfig = z.strictObject({
+  /** Opt into light mode for small scoped changes */
+  lightMode: z.strictObject({
+    enabled: z.boolean(),
+    maxFiles: z.number().int().min(1),
+    maxLines: z.number().int().min(1),
+  }).optional(),
+});
+
+/** Queue mode config */
+const QueueConfig = z.strictObject({
+  maxParallel: z.number().int().min(1).max(10).default(3),
+  maxAutoFiledIssues: z.number().int().min(0).max(100).default(10),
+  reDispatchMaxRetries: z.number().int().min(0).max(10).default(1),
+  projectNumber: z.number().int().positive().optional(),
+  boardTitle: z.string().trim().min(1).optional(),
+});
+
+/** 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 FileGateConfig = GateConfig.partial();
+const FileGatesConfig = z.strictObject({
+  draft: FileGateConfig.optional(),
+  preApproval: FileGateConfig.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)
+// ============================================================================
+
+/**
+ * @typedef {z.infer<typeof DevLoopConfigSchema>} DevLoopConfig
+ */
+
+export const DevLoopConfigSchema = z.strictObject({
+  version: z.literal(1),
+  strategy: StrategyConfig.optional(),
+  inputSource: InputSourceConfig.optional(),
+  models: ModelsConfig.optional(),
+  refinement: RefinementConfig.optional(),
+  gates: GatesConfig.optional(),
+  autonomy: AutonomyConfig.optional(),
+  workflow: WorkflowConfig.optional(),
+  localImplementation: LocalImplementationConfig.optional(),
+  queue: QueueConfig.optional(),
+  personas: PersonasConfig.optional(),
+  internalPathPatterns: InternalPatternsConfig.optional(),
+});
+
+// ============================================================================
+// Built-in defaults — frozen canonical single source of truth
+// ============================================================================
+
+export const BUILT_IN_DEFAULTS = Object.freeze({
+  version: 1,
+  strategy: Object.freeze({ default: "github-first" }),
+  inputSource: Object.freeze({ default: "tracker" }),
+  models: Object.freeze({}),
+  refinement: Object.freeze({ fanOut: 3, mode: "parallel", maxCopilotRounds: 5, stopOnLowSignal: false, lowSignalRoundThreshold: 3, lowSignalMaxComments: 2 }),
+  gates: Object.freeze({}),
+  autonomy: Object.freeze({ stopAt: Object.freeze(["merge"]) }),
+  workflow: Object.freeze({
+    asyncStartMode: "required",
+    requireRetrospective: false,
+    requireRetrospectiveGate: false,
+    requireDraftFirst: false,
+    devModeDefault: false,
+  }),
+  localImplementation: Object.freeze({
+    lightMode: Object.freeze({ enabled: false, maxFiles: 3, maxLines: 200 }),
+  }),
+  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.
+  }),
+  personas: Object.freeze({}),
+  internalPathPatterns: Object.freeze([
+    "^scripts/",
+    "^docs/",
+    "^skills/docs/",
+    "^\\.pi/",
+    "^\\.github/",
+    "^test/",
+  ]),
+});
+
+// ============================================================================
+// File-level validation schema — allows partial family objects
+// ============================================================================
+
+export const FileConfigSchema = z.strictObject({
+  version: z.literal(1),
+  strategy: StrategyConfig.partial().optional(),
+  inputSource: InputSourceConfig.partial().optional(),
+  models: ModelsConfig.partial().optional(),
+  refinement: RefinementConfig.partial().optional(),
+  gates: FileGatesConfig.optional(),
+  autonomy: AutonomyConfig.partial().optional(),
+  workflow: WorkflowConfig.partial().optional(),
+  localImplementation: LocalImplementationConfig.partial().optional(),
+  queue: QueueConfig.partial().optional(),
+  personas: FilePersonasConfig.optional(),
+  internalPathPatterns: InternalPatternsConfig.optional(),
+});
+
+// ============================================================================
+// Built-in persona registry — fallback when config.personas is absent
+//
+// 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.
+//
+// Angle names come from the gate-angle config (gates.draft.angles /
+// gates.preApproval.angles in .pi/dev-loop/defaults.yaml).
+// ============================================================================
+
+const BUILTIN_PERSONAS = Object.freeze({
+  scope:       { persona: "review", defaultModel: null },
+  coverage:    { persona: "review", defaultModel: null },
+  correctness: { persona: "review", defaultModel: null },
+  docs:        { persona: "docs", defaultModel: null },
+  deep:        { persona: "review", defaultModel: null },
+  dry:         { persona: "review", defaultModel: null },
+  kiss:        { persona: "review", defaultModel: null },
+  srp:         { persona: "review", defaultModel: null },
+  ocp:         { persona: "review", defaultModel: null },
+  lsp:         { persona: "review", defaultModel: null },
+  isp:         { persona: "review", defaultModel: null },
+  dip:         { persona: "review", defaultModel: null },
+  soc:         { persona: "review", defaultModel: null },
+  yagni:       { persona: "review", defaultModel: null },
+  "contract-surface":  { persona: "review", defaultModel: null },
+  "input-validation":  { persona: "review", defaultModel: null },
+  "packaging-runtime": { persona: "review", defaultModel: null },
+  "state-concurrency": { persona: "review", defaultModel: null },
+  "renderer-security": { persona: "review", defaultModel: null },
+  determinism:          { persona: "review", defaultModel: null },
+});
+
+const DEFAULT_REVIEWER_PERSONA = "default-reviewer";
+
+// ============================================================================
+// Role resolution
+// ============================================================================
+
+/**
+ * @typedef {object} RoleResolutionResult
+ * @property {string} persona - Agent persona name to use
+ * @property {string|null} model - Effective model (null = use persona default)
+ * @property {string|null} prompt - Focused review instruction for this angle (null when fallback)
+ * @property {boolean} fallback - True when no specialized persona was found
+ */
+
+/**
+ * Resolve a gate angle name to a reviewer persona and model.
+ *
+ * Resolution order:
+ * 1. Look up angle in config.personas[angle] (consumer overrides)
+ * 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
+ * 4. If not found anywhere, fall back to default reviewer with angle as focus lens,
+ *    still applying any model override from config
+ *
+ * @param {object} config - DevLoopConfig (or partial with personas, models.roles)
+ * @param {string|null|undefined} angle - Gate angle / lens name
+ * @returns {RoleResolutionResult}
+ */
+export function resolveReviewerRole(config, angle) {
+  // Null/undefined/empty angle → fallback
+  if (angle == null || angle === "") {
+    return {
+      persona: DEFAULT_REVIEWER_PERSONA,
+      model: null,
+      prompt: null,
+      fallback: true,
+    };
+  }
+
+  // Resolution: config.personas > BUILTIN_PERSONAS > default-reviewer
+  const configPersona = config?.personas?.[angle] ?? null;
+  const builtinPersona = BUILTIN_PERSONAS[angle] ?? null;
+  const persona = configPersona ?? builtinPersona;
+  const modelOverride = config?.models?.roles?.[angle] || null;
+
+  if (persona) {
+    return {
+      persona: persona.persona,
+      model: modelOverride || persona.defaultModel || null,
+      prompt: persona.prompt || null,
+      fallback: false,
+    };
+  }
+
+  // Unknown angle — fall back to default reviewer, but still apply model override
+  return {
+    persona: DEFAULT_REVIEWER_PERSONA,
+    model: modelOverride || null,
+    prompt: null,
+    fallback: true,
+  };
+}
+
+// ============================================================================
+// Error types
+// ============================================================================
+
+/**
+ * @typedef {object} ConfigLoadError
+ * @property {string} path - Human-readable file path or layer name
+ * @property {string} message - Error description
+ * @property {"defaults"|"settings"|"merged"} layer - Which config layer failed
+ */
+
+// ============================================================================
+// Helpers
+// ============================================================================
+
+/**
+ * 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.
+ * @param {Record<string, unknown>} target
+ * @param {Record<string, unknown>} source
+ * @returns {Record<string, unknown>}
+ */
+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])
+    ) {
+      result[key] = key === "gates"
+        ? mergeNestedObject(result[key], source[key])
+        : { ...(result[key] || {}), ...(source[key] || {}) };
+    } else {
+      result[key] = source[key];
+    }
+  }
+  return result;
+}
+
+function mergeNestedObject(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])
+    ) {
+      result[key] = { ...(result[key] || {}), ...(source[key] || {}) };
+    } else {
+      result[key] = source[key];
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Try to read and parse a config file (YAML preferred, JSON fallback).
+ * Detects format from file extension: .yaml/.yml → YAML, .json → JSON.
+ * Returns the parsed object or null if the file doesn't exist.
+ * Throws on read errors other than ENOENT.
+ * @param {string} filePath
+ * @returns {Promise<object|null>}
+ */
+async function readConfigFile(filePath) {
+  let raw;
+  try {
+    raw = await readFile(filePath, "utf8");
+  } catch (err) {
+    if (err.code === "ENOENT") return null;
+    throw configError(`Cannot read config file: ${err.message}`, err.code, filePath);
+  }
+
+  if (raw.trim() === "") {
+    throw configError("Config file is empty", "EMPTY_FILE", filePath);
+  }
+
+  const hasExt = filePath.endsWith(".yaml") || filePath.endsWith(".yml") || filePath.endsWith(".json");
+  const isYaml = filePath.endsWith(".yaml") || filePath.endsWith(".yml");
+  let parsed;
+  if (hasExt) {
+    try {
+      parsed = isYaml ? parseYaml(raw) : JSON.parse(raw);
+    } catch (err) {
+      const format = isYaml ? "YAML" : "JSON";
+      throw configError(`Invalid ${format} in config file: ${err.message}`, `INVALID_${format.toUpperCase()}`, filePath);
+    }
+  } else {
+    // Bare file (no recognized extension) — try YAML first, fallback JSON
+    try {
+      parsed = parseYaml(raw);
+    } catch {
+      try {
+        parsed = JSON.parse(raw);
+      } catch (err) {
+        throw configError(`Invalid config file (tried YAML and JSON): ${err.message}`, "INVALID_BARE_FILE", filePath);
+      }
+    }
+  }
+
+  if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw configError("Config file must be an object", "NOT_AN_OBJECT", filePath);
+  }
+
+  return parsed;
+}
+
+/**
+ * Find a config file by trying one or more base names in order.
+ * Each base name prefers YAML (.yaml, then .yml) before JSON.
+ * @param {string|string[]} basePaths - Path(s) without extension (e.g. .../defaults)
+ * @returns {Promise<{ path: string, data: object|null }>}
+ */
+async function findConfigFile(basePaths) {
+  const candidates = Array.isArray(basePaths) ? basePaths : [basePaths];
+
+  for (const basePath of candidates) {
+    // Try bare path first (e.g., .devloops without extension).
+    // Success returns immediately.
+    // ENOENT: file genuinely absent — try extension variants.
+    // Other errors (EISDIR, EACCES): file exists but is unreadable —
+    // try extension variants as fallback, but surface the original
+    // error if no extension variant exists.
+    let bareData = null;
+    let bareError = null;
+    try {
+      bareData = await readConfigFile(basePath);
+    } catch (err) {
+      bareError = err;
+    }
+    if (bareData !== null) return { path: basePath, data: bareData };
+
+    for (const ext of [".yaml", ".yml", ".json"]) {
+      const filePath = basePath + ext;
+      const data = await readConfigFile(filePath);
+      if (data !== null) return { path: filePath, data };
+    }
+
+    // No extension variant found either — if the bare path exists but is
+    // unreadable, surface that error rather than silently falling back.
+    if (bareError) throw bareError;
+  }
+
+  return { path: candidates[0] + ".yaml", data: null };
+}
+
+/**
+ * @param {string} message
+ * @param {string} code
+ * @param {string} filePath
+ * @returns {Error & { code: string, path: string }}
+ */
+function configError(message, code, filePath) {
+  return Object.assign(new Error(message), { code, path: filePath });
+}
+
+/**
+ * Try to load and merge one config layer (defaults or settings).
+ * @param {Record<string, unknown>} merged - Current merged config
+ * @param {string|string[]} basePaths - Config file base path(s) without extension
+ * @param {"defaults"|"settings"} layer - Layer name
+ * @param {string[]} warnings
+ * @param {ConfigLoadError[]} errors
+ * @param {{ warnOnMissing?: boolean }} [options]
+ * @returns {Promise<Record<string, unknown>>}
+ */
+async function applyLayer(merged, basePaths, layer, warnings, errors, options = {}) {
+  let filePath, data = null;
+  try {
+    const found = await findConfigFile(basePaths);
+    filePath = found.path;
+    data = found.data;
+  } catch (err) {
+    const preferredBasePath = Array.isArray(basePaths) ? basePaths[0] : basePaths;
+    const errorPath = err.path ?? preferredBasePath + ".yaml";
+    errors.push({
+      path: errorPath,
+      message: `${path.basename(errorPath)}: ${err.message}`,
+      layer,
+    });
+    return merged;
+  }
+
+  if (data === null) {
+    if (options.warnOnMissing) {
+      warnings.push(`Committed ${layer} config not found (tried .yaml, .yml, and .json), using built-in defaults`);
+    }
+    return merged;
+  }
+
+  // Validate the file's structure before merging
+  const validation = FileConfigSchema.safeParse(data);
+  if (!validation.success) {
+    errors.push({
+      path: filePath,
+      message: `${path.basename(filePath)}: Schema validation failed: ${validation.error.issues.map(i => `${i.path.join(".")}: ${i.message}`).join("; ")}`,
+      layer,
+    });
+    return merged;
+  }
+
+  return mergeConfigLayers(merged, data);
+}
+
+// ============================================================================
+// Loader
+// ============================================================================
+
+/**
+ * @typedef {object} LoadResult
+ * @property {DevLoopConfig} config
+ * @property {string[]} warnings
+ * @property {ConfigLoadError[]} errors
+ */
+
+/**
+ * @typedef {object} LoadOptions
+ * @property {string} [repoRoot] - Path to repository root (default: process.cwd())
+ */
+
+/**
+ * Load the dev-loop configuration with full precedence:
+ *   settings.(yaml|yml|json) > legacy overrides.(yaml|yml|json) > defaults.(yaml|yml|json) > built-in defaults
+ *
+ * Never throws for config-related problems.
+ * Returns built-in defaults even when all files are missing or broken.
+ *
+ * @param {LoadOptions} [options]
+ * @returns {Promise<LoadResult>}
+ */
+export async function loadDevLoopConfig(options = {}) {
+  const repoRoot = options.repoRoot ?? process.cwd();
+  const configDir = path.join(repoRoot, ".pi", "dev-loop");
+  const defaultsPath = path.join(configDir, "defaults");
+  const devloopsPath = path.join(repoRoot, ".devloops");
+  const settingsPaths = [path.join(configDir, "settings"), path.join(configDir, "overrides")];
+
+  /** @type {string[]} */
+  const warnings = [];
+  /** @type {ConfigLoadError[]} */
+  const errors = [];
+
+  let merged = { ...BUILT_IN_DEFAULTS };
+
+  merged = await applyLayer(merged, defaultsPath, "defaults", warnings, errors, {
+    warnOnMissing: true,
+  });
+
+  // Check if .devloops exists (primary consumer override)
+  // Only ENOENT means the file is genuinely absent; any other error
+  // (EACCES, EISDIR, etc.) means the file exists but is unreadable,
+  // so we must select the .devloops path so applyLayer can record the
+  // structured error.
+  let primaryExists = false;
+  for (const ext of ["", ".yaml", ".yml", ".json"]) {
+    try {
+      await readFile(devloopsPath + ext, "utf8");
+      primaryExists = true;
+      break;
+    } catch (err) {
+      if (err?.code !== "ENOENT") {
+        primaryExists = true;
+        break;
+      }
+      // ENOENT — genuinely absent, try next extension
+    }
+  }
+
+  if (primaryExists) {
+    // .devloops is the primary override — apply it
+    merged = await applyLayer(merged, devloopsPath, "settings", warnings, errors);
+
+    // Warn if legacy files still exist alongside .devloops (but don't load them —
+    // .devloops is authoritative; legacy must not override it)
+    let legacyAlongside = false;
+    for (const legacyPath of settingsPaths) {
+      for (const ext of [".yaml", ".yml", ".json"]) {
+        try {
+          await readFile(legacyPath + ext, "utf8");
+          legacyAlongside = true;
+          break;
+        } catch (err) {
+          if (err?.code !== "ENOENT") {
+            // File exists but is unreadable — treat as "found" so the
+            // deprecation warning fires (applyLayer is not called for legacy
+            // paths when .devloops is present, so the flag only controls the warning).
+            legacyAlongside = true;
+            break;
+          }
+        }
+      }
+      if (legacyAlongside) break;
+    }
+    if (legacyAlongside) {
+      warnings.push(
+        `Deprecated config path(s) found under .pi/dev-loop/settings.* or .pi/dev-loop/overrides.*. ` +
+        `Migrate to .devloops (or .devloops.yaml/.devloops.yml/.devloops.json) at repo root. ` +
+        `Legacy paths will be removed in a future version.`
+      );
+    }
+  } else {
+    // No .devloops — fall back to legacy .pi/dev-loop/settings.* or overrides.* (deprecated)
+    let legacyFound = false;
+    for (const legacyPath of settingsPaths) {
+      for (const ext of [".yaml", ".yml", ".json"]) {
+        try {
+          await readFile(legacyPath + ext, "utf8");
+          legacyFound = true;
+          break;
+        } catch (err) {
+          if (err?.code !== "ENOENT") {
+            // File exists but is unreadable — treat as "found" so the
+            // deprecation warning fires and applyLayer can surface the error
+            // (legacy applyLayer runs in this branch).
+            legacyFound = true;
+            break;
+          }
+        }
+      }
+      if (legacyFound) break;
+    }
+    if (legacyFound) {
+      warnings.push(
+        `Deprecated config path(s) found under .pi/dev-loop/settings.* or .pi/dev-loop/overrides.*. ` +
+        `Migrate to .devloops (or .devloops.yaml/.devloops.yml/.devloops.json) at repo root. ` +
+        `Legacy paths will be removed in a future version.`
+      );
+      merged = await applyLayer(merged, settingsPaths, "settings", warnings, errors);
+    }
+  }
+
+  // Validate final merged config
+  const result = DevLoopConfigSchema.safeParse(merged);
+  if (!result.success) {
+    errors.push({
+      path: "<merged>",
+      message: `Config validation failed: ${result.error.issues.map(i => `${i.path.join(".")}: ${i.message}`).join("; ")}`,
+      layer: "merged",
+    });
+    // Return merged as-is — caller gets validation errors but still has config with all layers applied
+    return { config: /** @type {*} */ (merged), warnings, errors };
+  }
+
+  return { config: result.data, warnings, errors };
+}
+
+/**
+ * Resolve the conductor model from the merged dev-loop config.
+ *
+ * Returns the configured model string if present, or null when the config
+ * does not specify a conductor model override (caller falls back to its
+ * own built-in default).
+ *
+ * Accepts the validated DevLoopConfig from {@link loadDevLoopConfig}.
+ *
+ * @param {DevLoopConfig} config
+ * @returns {string|null}
+ */
+export function resolveConductorModel(config) {
+  const raw = config?.models?.conductor;
+  if (typeof raw === "string" && raw.trim().length > 0) {
+    return raw.trim();
+  }
+  return null;
+}
+
+/**
+ * Resolve the autonomy stop-at list from the merged dev-loop config.
+ *
+ * Returns the set of gates that require operator confirmation. Gates not in
+ * the returned list may proceed automatically once their review conditions
+ * are satisfied.
+ *
+ * Defaults to `["merge"]` when the config does not specify `autonomy.stopAt`
+ * (the conservative built-in posture: everything auto-continues until merge).
+ *
+ * Accepts the validated DevLoopConfig from {@link loadDevLoopConfig}.
+ *
+ * @param {DevLoopConfig} config
+ * @returns {string[]}
+ */
+export function resolveAutonomyStopAt(config) {
+  if (config?.autonomy?.stopAt && Array.isArray(config.autonomy.stopAt)) {
+    return [...config.autonomy.stopAt];
+  }
+  return ["merge"];
+}
+
+const DEFAULT_REFINEMENT_CONFIG = BUILT_IN_DEFAULTS.refinement;
+const DEFAULT_WORKFLOW_CONFIG = BUILT_IN_DEFAULTS.workflow;
+
+/**
+ * Resolve one refinement configuration value from the merged dev-loop config.
+ *
+ * Returns the configured value when present, or the built-in default for the
+ * requested key.
+ *
+ * @param {DevLoopConfig} config
+ * @param {"fanOut"|"mode"|"roles"|"maxCopilotRounds"|"stopOnLowSignal"|"lowSignalRoundThreshold"|"lowSignalMaxComments"} key
+ * @returns {number|"parallel"|"sequential"|string[]|boolean|null}
+ */
+export function resolveRefinementConfig(config, key) {
+  if (key === "roles") {
+    return config?.refinement?.roles && Array.isArray(config.refinement.roles)
+      ? [...config.refinement.roles]
+      : null;
+  }
+
+  if (key === "fanOut") {
+    return config?.refinement?.fanOut ?? DEFAULT_REFINEMENT_CONFIG.fanOut;
+  }
+
+  if (key === "mode") {
+    return config?.refinement?.mode ?? DEFAULT_REFINEMENT_CONFIG.mode;
+  }
+
+  if (key === "maxCopilotRounds") {
+    return config?.refinement?.maxCopilotRounds ?? DEFAULT_REFINEMENT_CONFIG.maxCopilotRounds;
+  }
+
+  if (key === "stopOnLowSignal") {
+    return config?.refinement?.stopOnLowSignal ?? DEFAULT_REFINEMENT_CONFIG.stopOnLowSignal;
+  }
+
+  if (key === "lowSignalRoundThreshold") {
+    return config?.refinement?.lowSignalRoundThreshold ?? DEFAULT_REFINEMENT_CONFIG.lowSignalRoundThreshold;
+  }
+
+  if (key === "lowSignalMaxComments") {
+    return config?.refinement?.lowSignalMaxComments ?? DEFAULT_REFINEMENT_CONFIG.lowSignalMaxComments;
+  }
+
+  throw new Error(`Unknown refinement config key: ${key}`);
+}
+
+/**
+ * Resolve the refinement configuration from the merged dev-loop config.
+ *
+ * Returns `{ fanOut, mode, roles, maxCopilotRounds, stopOnLowSignal, lowSignalRoundThreshold, lowSignalMaxComments }` with sensible built-in
+ * defaults (`fanOut: 3`, `mode: "parallel"`, `roles: null`,
+ * `maxCopilotRounds: 5`, `stopOnLowSignal: false`, `lowSignalRoundThreshold: 3`,
+ * `lowSignalMaxComments: 2`).
+ *
+ * Accepts the validated DevLoopConfig from {@link loadDevLoopConfig}.
+ *
+ * @param {DevLoopConfig} config
+ * @returns {{ fanOut: number, mode: "parallel"|"sequential", roles: string[]|null, maxCopilotRounds: number, stopOnLowSignal: boolean, lowSignalRoundThreshold: number, lowSignalMaxComments: number }}
+ */
+export function resolveRefinement(config) {
+  const fanOut = /** @type {number} */ (resolveRefinementConfig(config, "fanOut"));
+  const mode = /** @type {"parallel"|"sequential"} */ (resolveRefinementConfig(config, "mode"));
+  const roles = /** @type {string[]|null} */ (resolveRefinementConfig(config, "roles"));
+  const maxCopilotRounds = /** @type {number} */ (resolveRefinementConfig(config, "maxCopilotRounds"));
+  const stopOnLowSignal = /** @type {boolean} */ (resolveRefinementConfig(config, "stopOnLowSignal"));
+  const lowSignalRoundThreshold = /** @type {number} */ (resolveRefinementConfig(config, "lowSignalRoundThreshold"));
+  const lowSignalMaxComments = /** @type {number} */ (resolveRefinementConfig(config, "lowSignalMaxComments"));
+  return { fanOut, mode, roles, maxCopilotRounds, stopOnLowSignal, lowSignalRoundThreshold, lowSignalMaxComments };
+}
+
+/**
+ * Resolve one gate configuration object from the merged dev-loop config.
+ *
+ * Returns the configured gate angles when present, or null for angles when the
+ * config omits them (caller falls back to skill-defined defaults). Boolean gate
+ * flags always resolve to stable defaults.
+ *
+ * @param {DevLoopConfig} config
+ * @param {"draft"|"preApproval"} gate
+ * @returns {{ angles: string[]|null, excludeAngles: string[], mandatoryAngles: string[], required: boolean, requireCi: boolean, blockCleanOnFindingSeverities: string[], dynamicAngles: boolean }}
+ */
+export function resolveGateConfig(config, gate) {
+  const gateConfig = config?.gates?.[gate];
+  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)
+      : [],
+    required: gateConfig?.required ?? true,
+    requireCi: gateConfig?.requireCi ?? true,
+    dynamicAngles: gateConfig?.dynamicAngles ?? false,
+    blockCleanOnFindingSeverities: gateConfig?.blockCleanOnFindingSeverities && Array.isArray(gateConfig.blockCleanOnFindingSeverities)
+      ? [...gateConfig.blockCleanOnFindingSeverities]
+      : ["must-fix"],
+  };
+}
+
+/**
+ * Resolve local implementation light mode config.
+ *
+ * Returns null when light mode is disabled (config absent or enabled=false).
+ * Returns { maxFiles, maxLines } when enabled.
+ *
+ * @param {DevLoopConfig} config
+ * @returns {{ maxFiles: number, maxLines: number } | null}
+ */
+export function resolveLightMode(config) {
+  const cfg = config?.localImplementation?.lightMode;
+  if (!cfg || cfg.enabled === false) return null;
+  return {
+    maxFiles: typeof cfg.maxFiles === "number" && Number.isFinite(cfg.maxFiles) && cfg.maxFiles > 0
+      ? cfg.maxFiles
+      : 3,
+    maxLines: typeof cfg.maxLines === "number" && Number.isFinite(cfg.maxLines) && cfg.maxLines > 0
+      ? cfg.maxLines
+      : 200,
+  };
+}
+
+/**
+ * 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).
+ *
+ * @param {DevLoopConfig} config
+ * @param {"draft"|"preApproval"} gate
+ * @returns {string[]|null}
+ */
+export function resolveGateAngles(config, gate) {
+  const gateConfig = resolveGateConfig(config, gate);
+  if (gateConfig.angles === null && gateConfig.mandatoryAngles.length === 0) return null;
+  const excluded = new Set(gateConfig.excludeAngles);
+  const merged = [...new Set([...gateConfig.mandatoryAngles, ...(gateConfig.angles ?? [])])];
+  return merged.filter(a => !excluded.has(a));
+}
+
+/**
+ * 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`).
+ *
+ * @param {import("./types.js").DevLoopConfig} config
+ * @param {"draft"|"preApproval"} gate
+ * @param {object} [options]
+ * @param {{ nameStatusOutput: string, diffOutput?: string }} [options.diff]
+ * @returns {{ recommendedAngles: string[] | null, skippedAngles: string[], reasons: Record<string,string>, fallbackToAll: boolean, dynamicAnglesActive: boolean }}
+ */
+export async function resolveGateAnglesDynamic(config, gate, { diff } = {}) {
+  const gateConfig = resolveGateConfig(config, gate);
+  const staticAngles = resolveGateAngles(config, gate);
+  if (staticAngles === null) {
+    return { recommendedAngles: null, skippedAngles: [], reasons: {}, fallbackToAll: false, dynamicAnglesActive: false };
+  }
+
+  if (!gateConfig.dynamicAngles || !diff) {
+    return {
+      recommendedAngles: staticAngles,
+      skippedAngles: [],
+      reasons: {},
+      fallbackToAll: false,
+      dynamicAnglesActive: false,
+    };
+  }
+
+  // Split into mandatory (always run) and candidate pool (dynamic selection)
+  // staticAngles is already filtered by excludeAngles via resolveGateAngles
+  const mandatory = new Set(gateConfig.mandatoryAngles);
+  const candidatePool = staticAngles.filter(a => !mandatory.has(a));
+
+  // Dynamic resolution
+  const { analyzeDiff } = await import("../analysis/diff-analyzer.mjs");
+  const analysis = analyzeDiff({
+    nameStatusOutput: diff.nameStatusOutput,
+    diffOutput: diff.diffOutput,
+  });
+
+  const categories = [...new Set(analysis.t1?.changeCategories ?? [])];
+
+  const { resolveDynamicAngles: resolve } = await import("../analysis/change-classifier.mjs");
+  const dynamicResult = resolve({
+    configuredAngles: candidatePool,
+    changeCategories: categories,
+    ambiguous: analysis.ambiguous,
+  });
+
+  // Merge: mandatory always included (filtered by excludeAngles) + dynamically-selected candidates
+  const excluded = new Set(gateConfig.excludeAngles);
+  const filteredMandatory = gateConfig.mandatoryAngles.filter(a => !excluded.has(a));
+  const recommendedAngles = [...new Set([...filteredMandatory, ...dynamicResult.recommendedAngles])];
+
+  return {
+    recommendedAngles,
+    skippedAngles: dynamicResult.skippedAngles,
+    reasons: dynamicResult.reasons,
+    fallbackToAll: dynamicResult.fallbackToAll,
+    dynamicAnglesActive: true,
+  };
+}
+
+/**
+ * Resolve one workflow configuration value from the merged dev-loop config.
+ *
+ * Returns the configured workflow value when present, or the built-in default
+ * for the requested key.
+ *
+ * @param {DevLoopConfig} config
+ * @param {"asyncStartMode"|"requireRetrospective"|"requireRetrospectiveGate"|"requireDraftFirst"|"devModeDefault"} key
+ * @returns {string|boolean}
+ */
+export function resolveWorkflowConfig(config, key) {
+  if (key === "asyncStartMode") {
+    return config?.workflow?.asyncStartMode ?? DEFAULT_WORKFLOW_CONFIG.asyncStartMode;
+  }
+
+  if (key === "requireRetrospective") {
+    return config?.workflow?.requireRetrospective ?? DEFAULT_WORKFLOW_CONFIG.requireRetrospective;
+  }
+
+  if (key === "requireRetrospectiveGate") {
+    return config?.workflow?.requireRetrospectiveGate ?? DEFAULT_WORKFLOW_CONFIG.requireRetrospectiveGate;
+  }
+
+  if (key === "requireDraftFirst") {
+    return config?.workflow?.requireDraftFirst ?? DEFAULT_WORKFLOW_CONFIG.requireDraftFirst;
+  }
+
+  if (key === "devModeDefault") {
+    return config?.workflow?.devModeDefault ?? DEFAULT_WORKFLOW_CONFIG.devModeDefault;
+  }
+
+  throw new Error(`Unknown workflow config key: ${key}`);
+}
+
+const DEFAULT_INTERNAL_PATH_PATTERNS = BUILT_IN_DEFAULTS.internalPathPatterns;
+
+/**
+ * Resolve the internal path patterns from the merged dev-loop config.
+ *
+ * Returns an array of regex pattern strings used by detect-internal-only-pr.mjs
+ * to classify files as internal tooling (vs consumer-facing). When the config
+ * omits this section, returns the built-in shipped defaults.
+ *
+ * Consumers can override these in .devloops at repo root.
+ *
+ * @param {DevLoopConfig} config
+ * @returns {string[]}
+ */
+export function resolveInternalPathPatterns(config) {
+  if (
+    config?.internalPathPatterns &&
+    Array.isArray(config.internalPathPatterns) &&
+    config.internalPathPatterns.length > 0
+  ) {
+    return [...config.internalPathPatterns];
+  }
+  return [...DEFAULT_INTERNAL_PATH_PATTERNS];
+}