gdmcode 0.1.0__py3-none-any.whl

src/config.py

@@ -0,0 +1,762 @@
+"""GdmConfig — loads and validates all configuration.
+
+Legacy session config priority (highest → lowest):
+  1. Environment variables (XAI_API_KEY, GEMINI_API_KEY, OPENAI_API_KEY, GDM_*)
+  2. System keychain (via CredentialStore / keyring)
+  3. ~/.config/gdm/config.toml [api] section
+  4. Built-in defaults
+
+The config object is immutable once created. Re-create to reload.
+
+Application settings (sdk-002) — ConfigLoader with 7-layer precedence:
+  1. Hardcoded defaults
+  2. User config  (~/.config/gdm/config.toml)
+  3. Project config (.gdm/config.toml)
+  4. Team preferences (.gdm/team.toml [preferences])
+  5. Team policy    (.gdm/team.toml [policy])  ← overrides env + CLI
+  6. Environment variables (GDM_* prefix)
+  7. CLI flags
+
+Secrets (api_key, token, password, credential) go to OS keychain — never to TOML.
+"""
+from __future__ import annotations
+
+import logging
+import os
+import re
+import tomllib
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+from pydantic import BaseModel, Field, field_validator
+
+from src._internal.constants import (
+    _CONTEXT_MEMORY_DIR,
+    _DEFAULT_COST_LIMIT_USD,
+    _MAX_AGENT_TURNS,
+)
+from src.exceptions import ConfigError
+from src.models.definitions import Provider
+
+__all__ = ["GdmConfig", "GdmSettings", "ConfigValue", "ConfigLoader", "KEYCHAIN_KEYS", "load_config"]
+
+log = logging.getLogger(__name__)
+
+_GLOBAL_CONFIG_DIR = Path.home() / ".config" / "gdm"
+_GLOBAL_CONFIG_FILE = _GLOBAL_CONFIG_DIR / "config.toml"
+_GLOBAL_INSTRUCTIONS_FILE = _GLOBAL_CONFIG_DIR / "instructions.md"
+
+
+@dataclass(frozen=True)
+class GdmConfig:
+    """Immutable configuration for a gdm session."""
+
+    # Provider + API keys
+    provider: str
+    api_key: str
+    xai_api_key: str | None
+    gemini_api_key: str | None
+    openai_api_key: str | None
+
+    # Project paths
+    project_root: Path
+    context_memory_dir: Path
+    gdm_instructions: str  # contents of .gdm + global instructions, pre-merged
+
+    # Agent behaviour
+    max_turns: int
+    cost_limit_usd: float
+
+    # Spinner customisation (user-appended verbs from config.toml)
+    extra_spinner_verbs: list[str] = field(default_factory=list)
+
+    # Model ID overrides — resolved from env vars + TOML [models] section
+    model_ids: dict[str, str] = field(default_factory=dict)
+
+    # Tool execution settings
+    tools_timeout_secs: int = 30
+
+    # API fallback settings
+    fallback_provider: str | None = None
+    model_id_map: dict[str, str] = field(default_factory=dict)
+
+    # Debug loop settings
+    debug_auto_search_iteration: int = 3   # 0 = disabled
+
+    # Debate model override — "" means use reasoner/debate tier from config
+    debate_model: str = ""
+
+    # Artifact auto-detection (opt-in, off by default to prevent alert fatigue)
+    artifacts_auto_detect: bool = False
+
+    # Whole-codebase mode: load all source files upfront when project fits in context
+    whole_codebase: str = field(default="auto")  # "auto" | "always" | "never"
+
+    # Quiet mode: suppress non-essential startup output (e.g. memory hints)
+    gdm_quiet: bool = False
+
+    # Local provider configurations (Ollama, vLLM) — parsed from [providers.*] TOML
+    local_providers: list = field(default_factory=list)  # list[LocalProviderConfig]
+
+    # Proxy settings — allows geo-restricted regions to route calls via gdm relay.
+    # proxy_token comes from OS keychain / env; never stored in TOML plaintext.
+    proxy_url: str = ""
+    proxy_token: str | None = None
+    proxy_enabled: bool = False
+
+    @property
+    def has_grok(self) -> bool:
+        return bool(self.xai_api_key)
+
+    @property
+    def has_gemini(self) -> bool:
+        return bool(self.gemini_api_key)
+
+    @property
+    def has_codex(self) -> bool:
+        return bool(self.openai_api_key)
+
+
+def load_config(project_root: Path | None = None) -> GdmConfig:
+    """Load and validate configuration from all sources.
+
+    Args:
+        project_root: project directory (defaults to cwd).
+
+    Raises:
+        ConfigError: if no API key is found from any source.
+    """
+    from src.auth import CredentialStore
+
+    root = (project_root or Path.cwd()).resolve()
+    store = CredentialStore()
+    creds = store.load_all()
+
+    # ── 1. API keys: env → keychain (merged in load_all) ────────────────
+    xai_key = creds.xai_api_key
+    gemini_key = creds.gemini_api_key
+    openai_key = creds.openai_api_key
+
+    # ── 2. Global config.toml ─────────────────────────────────────────
+    toml_cfg: dict = {}  # type: ignore[type-arg]
+    if _GLOBAL_CONFIG_FILE.exists():
+        try:
+            toml_cfg = tomllib.loads(_GLOBAL_CONFIG_FILE.read_text(encoding="utf-8"))
+        except Exception as exc:
+            log.warning("Could not parse %s: %s", _GLOBAL_CONFIG_FILE, exc)
+
+    # Keys can also live in config.toml under [api] (lowest priority)
+    api_section = toml_cfg.get("api", {})
+    if not xai_key:
+        xai_key = api_section.get("xai_api_key") or None
+    if not gemini_key:
+        gemini_key = api_section.get("gemini_api_key") or None
+    if not openai_key:
+        openai_key = api_section.get("openai_api_key") or None
+
+    # ── 3. Provider selection ─────────────────────────────────────────
+    preferred = os.environ.get("GDM_PROVIDER") or toml_cfg.get("provider") or None
+
+    provider, api_key = _select_provider(preferred, xai_key, gemini_key, openai_key)
+
+    # ── 4. User instructions (.gdm + global) ─────────────────────────
+    instructions_parts: list[str] = []
+    if _GLOBAL_INSTRUCTIONS_FILE.exists():
+        instructions_parts.append(_GLOBAL_INSTRUCTIONS_FILE.read_text(encoding="utf-8").strip())
+
+    project_gdm = root / ".gdm"
+    _maybe_migrate_gdm_dir(root)  # migrate flat .gdm file to .gdm/ directory
+    if project_gdm.is_dir():
+        instructions_file = project_gdm / "instructions.md"
+        if instructions_file.exists():
+            instructions_parts.append(instructions_file.read_text(encoding="utf-8").strip())
+    elif project_gdm.is_file():
+        instructions_parts.append(project_gdm.read_text(encoding="utf-8").strip())
+
+    gdm_instructions = "\n\n".join(instructions_parts)
+
+    # ── 5. Agent settings ─────────────────────────────────────────────
+    agent_cfg = toml_cfg.get("agent", {})
+    max_turns: int = int(
+        os.environ.get("GDM_MAX_TURNS") or agent_cfg.get("max_turns", _MAX_AGENT_TURNS)
+    )
+    cost_limit: float = float(
+        os.environ.get("GDM_COST_LIMIT") or agent_cfg.get("cost_limit_usd", _DEFAULT_COST_LIMIT_USD)
+    )
+
+    # ── 6. Spinner extra verbs ─────────────────────────────────────────
+    extra_verbs: list[str] = toml_cfg.get("spinner", {}).get("extra_verbs", [])
+
+    # ── 7. Model ID overrides (env vars → TOML [models]) ──────────────
+    model_ids = _load_model_id_overrides(toml_cfg)
+
+    # Apply overrides to module-level ModelDef constants before first use
+    from src.models.definitions import apply_model_id_overrides
+    apply_model_id_overrides(model_ids)
+
+    # ── 8. Debug settings ─────────────────────────────────────────────
+    debug_cfg = toml_cfg.get("debug", {})
+    debug_auto_search_iteration: int = int(
+        os.environ.get("GDM_DEBUG_AUTO_SEARCH_ITERATION")
+        or debug_cfg.get("auto_search_iteration", 3)
+    )
+
+    # ── 9. Tool settings ──────────────────────────────────────────────
+    tools_cfg = toml_cfg.get("tools", {})
+    tools_timeout_secs: int = int(
+        os.environ.get("GDM_TOOLS_TIMEOUT") or tools_cfg.get("timeout_secs", 30)
+    )
+
+    # ── 10. API fallback settings ─────────────────────────────────────
+    fallback_cfg = toml_cfg.get("fallback", {})
+    fallback_provider: str | None = (
+        os.environ.get("GDM_FALLBACK_PROVIDER") or fallback_cfg.get("provider") or None
+    )
+    model_id_map: dict[str, str] = dict(fallback_cfg.get("model_id_map", {}))
+
+    # ── 11. Proxy settings ────────────────────────────────────────────
+    proxy_cfg = toml_cfg.get("proxy", {})
+    proxy_url: str = os.environ.get("GDM_PROXY_URL") or proxy_cfg.get("url") or ""
+    # Token comes from env → keychain only; never stored in TOML plaintext.
+    proxy_token: str | None = creds.proxy_token
+    proxy_enabled: bool = bool(
+        os.environ.get("GDM_PROXY_ENABLED", "").lower() in ("1", "true", "yes")
+        or proxy_cfg.get("enabled", False)
+    )
+
+    return GdmConfig(
+        provider=provider,
+        api_key=api_key,
+        xai_api_key=xai_key,
+        gemini_api_key=gemini_key,
+        openai_api_key=openai_key,
+        project_root=root,
+        context_memory_dir=root / _CONTEXT_MEMORY_DIR,
+        gdm_instructions=gdm_instructions,
+        max_turns=max_turns,
+        cost_limit_usd=cost_limit,
+        extra_spinner_verbs=extra_verbs,
+        model_ids=model_ids,
+        debug_auto_search_iteration=debug_auto_search_iteration,
+        tools_timeout_secs=tools_timeout_secs,
+        fallback_provider=fallback_provider,
+        model_id_map=model_id_map,
+        debate_model=toml_cfg.get("debate", {}).get("model", ""),
+        artifacts_auto_detect=bool(toml_cfg.get("artifacts", {}).get("auto_detect", False)),
+        whole_codebase=toml_cfg.get("context", {}).get("whole_codebase", "auto"),
+        gdm_quiet=bool(
+            os.environ.get("GDM_QUIET", "").lower() in ("1", "true", "yes")
+            or toml_cfg.get("agent", {}).get("quiet", False)
+        ),
+        local_providers=_load_local_providers(toml_cfg),
+        proxy_url=proxy_url,
+        proxy_token=proxy_token,
+        proxy_enabled=proxy_enabled,
+    )
+
+
+def _load_local_providers(toml_cfg: dict) -> list:  # type: ignore[type-arg]
+    """Parse ``[providers.ollama]`` and ``[providers.vllm]`` TOML sections.
+
+    Returns a list of ``LocalProviderConfig`` for each enabled local provider.
+    Providers with ``enabled = false`` (or missing) are skipped.
+    """
+    # Lazy import avoids circular dependency (client.py imports config.py)
+    from src.models.client import LocalProviderConfig
+
+    _DEFAULTS: dict[str, str] = {
+        "ollama": "http://localhost:11434",
+        "vllm": "http://localhost:8000",
+    }
+    providers_cfg = toml_cfg.get("providers", {})
+    result: list = []
+
+    for provider_name in ("ollama", "vllm"):
+        section = providers_cfg.get(provider_name, {})
+        if not section.get("enabled", False):
+            continue
+        result.append(
+            LocalProviderConfig(
+                provider=provider_name,
+                base_url=section.get("base_url", _DEFAULTS[provider_name]),
+                model=section.get("model", ""),
+                local_only=bool(section.get("local_only", True)),
+                allow_cloud_fallback=bool(section.get("allow_cloud_fallback", False)),
+                allow_external=bool(section.get("allow_external", False)),
+            )
+        )
+
+    return result
+
+
+def _load_model_id_overrides(toml_cfg: dict) -> dict[str, str]:  # type: ignore[type-arg]
+    """Build a ``{provider.tier: model_id}`` dict from env vars and TOML.
+
+    Resolution order per key: env var > config.toml > (omitted = use default).
+    """
+    _PROVIDERS = ("grok", "gemini", "codex")
+    _TIERS = ("scout", "coder", "thinker", "reasoner", "debate", "standard")
+    models_section = toml_cfg.get("models", {})
+    result: dict[str, str] = {}
+    for provider in _PROVIDERS:
+        provider_cfg = models_section.get(provider, {})
+        for tier in _TIERS:
+            env_key = f"GDM_MODEL_{provider.upper()}_{tier.upper()}"
+            env_val = os.environ.get(env_key)
+            if env_val:
+                result[f"{provider}.{tier}"] = env_val
+            elif tier in provider_cfg:
+                result[f"{provider}.{tier}"] = str(provider_cfg[tier])
+    return result
+
+
+def _select_provider(    preferred: str | None,
+    xai_key: str | None,
+    gemini_key: str | None,
+    openai_key: str | None,
+) -> tuple[str, str]:
+    """Return (provider_name, api_key) based on preference and available keys.
+
+    Raises ConfigError if no key is available.
+    """
+    # Try the preferred provider first.
+    if preferred:
+        match preferred.lower():
+            case "grok" | "xai" if xai_key:
+                return Provider.GROK, xai_key
+            case "gemini" | "google" if gemini_key:
+                return Provider.GEMINI, gemini_key
+            case "codex" | "openai" if openai_key:
+                return Provider.CODEX, openai_key
+            case _:
+                log.warning("Preferred provider %r has no key — falling back", preferred)
+
+    # Auto-detect: Grok > Gemini > Codex.
+    if xai_key:
+        return Provider.GROK, xai_key
+    if gemini_key:
+        return Provider.GEMINI, gemini_key
+    if openai_key:
+        return Provider.CODEX, openai_key
+
+    raise ConfigError(
+        "No API key found. Set one of:\n"
+        "  export XAI_API_KEY=xai-...       # xAI Grok (recommended)\n"
+        "  export GEMINI_API_KEY=AIza...    # Google Gemini (free tier)\n"
+        "  export OPENAI_API_KEY=sk-...     # OpenAI Codex\n"
+        "Or run: gdm login"
+    )
+
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# Application Settings System (sdk-002)
+# ═══════════════════════════════════════════════════════════════════════════════
+
+# ── Secret keys that NEVER go to TOML ─────────────────────────────────────────
+KEYCHAIN_KEYS: frozenset[str] = frozenset({
+    "xai_api_key", "openai_api_key", "anthropic_api_key",
+    "google_api_key", "github_token",
+})
+
+
+# ── Source-annotated config value ──────────────────────────────────────────────
+@dataclass
+class ConfigValue:
+    """A configuration value annotated with its source layer."""
+
+    value: Any
+    source: str  # e.g. "default", "user:~/.config/gdm/config.toml",
+                 #      "project:.gdm/config.toml", "env:GDM_AUTONOMY_LEVEL",
+                 #      "cli", "team-policy:.gdm/team.toml[policy]"
+
+
+# ── Pydantic application settings model ───────────────────────────────────────
+class GdmSettings(BaseModel):
+    """Immutable application settings loaded by ConfigLoader."""
+
+    model_config = {"frozen": True}
+
+    # [models]
+    primary_model: str = "grok-4-0106"
+    fallback_model: str = "o3-mini"
+
+    # [budget]
+    session_limit_usd: float = Field(default=10.0, ge=0)
+    monthly_limit_usd: float = Field(default=200.0, ge=0)
+
+    # [autonomy]
+    autonomy_level: int = Field(default=2, ge=0, le=5)
+
+    # [audit]
+    retain_days: int = Field(default=90, ge=1)
+
+    # [analytics]
+    consent_required: bool = False
+    roi_estimation: bool = False
+    anonymise: bool = True
+
+    # Enterprise policy fields (written from team.toml [policy])
+    policy_enforced: bool = False
+    allow_git_push: bool = True
+    allow_network: bool = True
+    network_allowlist: list[str] = Field(default_factory=list)
+
+    @field_validator("autonomy_level")
+    @classmethod
+    def autonomy_in_range(cls, v: int) -> int:
+        if not 0 <= v <= 5:
+            raise ValueError(f"autonomy_level must be 0–5, got {v}")
+        return v
+
+
+# ── TOML section → GdmSettings field mapping ──────────────────────────────────
+# Maps TOML dot-notation keys to GdmSettings field names.
+_TOML_KEY_MAP: dict[str, str] = {
+    "models.primary": "primary_model",
+    "models.fallback": "fallback_model",
+    "budget.session_limit_usd": "session_limit_usd",
+    "budget.monthly_limit_usd": "monthly_limit_usd",
+    "autonomy.level": "autonomy_level",
+    "audit.retain_days": "retain_days",
+    "analytics.consent_required": "consent_required",
+    "analytics.roi_estimation": "roi_estimation",
+    "analytics.anonymise": "anonymise",
+}
+# Reverse: GdmSettings field names → TOML dot-notation keys
+_FIELD_TO_TOML: dict[str, str] = {v: k for k, v in _TOML_KEY_MAP.items()}
+
+# Env var names → GdmSettings field names
+_ENV_KEY_MAP: dict[str, str] = {
+    "GDM_MODELS_PRIMARY": "primary_model",
+    "GDM_MODELS_FALLBACK": "fallback_model",
+    "GDM_BUDGET_SESSION_LIMIT_USD": "session_limit_usd",
+    "GDM_BUDGET_MONTHLY_LIMIT_USD": "monthly_limit_usd",
+    "GDM_AUTONOMY_LEVEL": "autonomy_level",
+    "GDM_AUDIT_RETAIN_DAYS": "retain_days",
+    "GDM_ANALYTICS_CONSENT_REQUIRED": "consent_required",
+    "GDM_ANALYTICS_ROI_ESTIMATION": "roi_estimation",
+    "GDM_ANALYTICS_ANONYMISE": "anonymise",
+}
+
+# Policy keys in team.toml [policy] that map to GdmSettings fields
+# "max_autonomy_level" is the policy spelling for "autonomy_level"
+_POLICY_KEY_MAP: dict[str, str] = {
+    "max_autonomy_level": "autonomy_level",
+    "policy_enforced": "policy_enforced",
+    "allow_git_push": "allow_git_push",
+    "allow_network": "allow_network",
+    "network_allowlist": "network_allowlist",
+}
+
+# Integer, float, and bool field sets for env-var coercion
+_INT_FIELDS: frozenset[str] = frozenset({"autonomy_level", "retain_days"})
+_FLOAT_FIELDS: frozenset[str] = frozenset({"session_limit_usd", "monthly_limit_usd"})
+_BOOL_FIELDS: frozenset[str] = frozenset({"consent_required", "roi_estimation", "anonymise"})
+
+
+def _maybe_migrate_gdm_dir(project_root: Path | None = None) -> None:
+    """Migrate legacy .gdm flat-file to .gdm/ directory layout.
+
+    The legacy layout stores ``.gdm`` as a plain text file containing
+    agent instructions.  The new layout uses ``.gdm/`` as a directory
+    that contains ``config.toml``, ``team.toml``, ``instructions.md``, etc.
+    This shim is idempotent — if ``.gdm`` is already a directory (or absent)
+    it does nothing.
+    """
+    root = project_root or Path.cwd()
+    gdm_path = root / ".gdm"
+    if not gdm_path.exists() or gdm_path.is_dir():
+        return
+    # .gdm exists as a file — migrate to a directory
+    legacy_content = gdm_path.read_text(encoding="utf-8", errors="replace")
+    gdm_path.unlink()
+    gdm_path.mkdir(parents=True, exist_ok=True)
+    (gdm_path / "instructions.md").write_text(legacy_content, encoding="utf-8")
+    log.info("Migrated .gdm flat file to .gdm/instructions.md")
+
+
+def _is_secret_key(key: str) -> bool:
+    """Return True if *key* matches a known secret pattern."""
+    if key in KEYCHAIN_KEYS:
+        return True
+    return bool(re.search(r"(api_key|token|secret|password|credential)", key, re.I))
+
+
+def _coerce_env_value(field_name: str, value: str) -> Any:
+    """Coerce an env-var string to the correct Python type for *field_name*."""
+    if field_name in _INT_FIELDS:
+        return int(value)
+    if field_name in _FLOAT_FIELDS:
+        return float(value)
+    if field_name in _BOOL_FIELDS:
+        return value.lower() in ("1", "true", "yes", "on")
+    return value
+
+
+def _flatten_toml(data: dict[str, Any]) -> dict[str, Any]:
+    """Flatten a TOML section dict to GdmSettings field names.
+
+    Handles the standard section layout ([models], [budget], [autonomy], …)
+    *and* flat dicts where keys already match GdmSettings field names
+    (used for team.toml [preferences]).
+    """
+    result: dict[str, Any] = {}
+
+    # [models]
+    models = data.get("models", {})
+    if isinstance(models, dict):
+        if "primary" in models:
+            result["primary_model"] = models["primary"]
+        if "fallback" in models:
+            result["fallback_model"] = models["fallback"]
+
+    # [budget]
+    budget = data.get("budget", {})
+    if isinstance(budget, dict):
+        for k in ("session_limit_usd", "monthly_limit_usd"):
+            if k in budget:
+                result[k] = budget[k]
+
+    # [autonomy]
+    autonomy = data.get("autonomy", {})
+    if isinstance(autonomy, dict) and "level" in autonomy:
+        result["autonomy_level"] = autonomy["level"]
+
+    # [audit]
+    audit = data.get("audit", {})
+    if isinstance(audit, dict) and "retain_days" in audit:
+        result["retain_days"] = audit["retain_days"]
+
+    # [analytics]
+    analytics = data.get("analytics", {})
+    if isinstance(analytics, dict):
+        for k in ("consent_required", "roi_estimation", "anonymise"):
+            if k in analytics:
+                result[k] = analytics[k]
+
+    # Flat keys that directly match GdmSettings field names (team-prefs convenience)
+    for field_name in GdmSettings.model_fields:
+        if field_name in data and field_name not in result:
+            result[field_name] = data[field_name]
+
+    return result
+
+
+class ConfigLoader:
+    """Loads :class:`GdmSettings` from the 7-layer precedence stack.
+
+    Call :meth:`load` to get ``(settings, provenance)`` where *provenance*
+    maps every field name to a :class:`ConfigValue` showing value + origin.
+    """
+
+    def __init__(self, project_root: Path | None = None) -> None:
+        self._project_root = (project_root or Path.cwd()).resolve()
+
+    # ── Public API ──────────────────────────────────────────────────────────
+
+    def load(
+        self, cli_overrides: dict[str, Any] | None = None
+    ) -> tuple[GdmSettings, dict[str, ConfigValue]]:
+        """Return ``(GdmSettings, provenance)`` after merging all layers.
+
+        *cli_overrides* is a dict of ``{field_name: value}`` pairs provided
+        by CLI flags (highest normal priority, overridden by team policy).
+        """
+        user_path = self._user_config_path()
+        project_path = self._project_config_path()
+        team_path = self._team_config_path()
+
+        # Load raw values per source
+        defaults_vals = self._defaults()
+        user_vals = self._load_toml_file(user_path, f"user:{user_path}")
+        project_vals = self._load_toml_file(project_path, f"project:{project_path}")
+        team_prefs_vals = self._load_team_prefs()
+        team_policy_vals = self._load_team_policy()
+        env_vals = self._load_env()
+        cli_vals: dict[str, Any] = cli_overrides or {}
+
+        # Apply layers lowest → highest (each overrides previous)
+        merged: dict[str, ConfigValue] = {}
+
+        for field_name, value in defaults_vals.items():
+            merged[field_name] = ConfigValue(value=value, source="default")
+
+        for field_name, cv in user_vals.items():
+            merged[field_name] = cv
+
+        for field_name, cv in project_vals.items():
+            merged[field_name] = cv
+
+        for field_name, cv in team_prefs_vals.items():
+            merged[field_name] = cv
+
+        # env and cli are applied before policy so policy can override them
+        for field_name, (value, env_key) in env_vals.items():
+            merged[field_name] = ConfigValue(value=value, source=f"env:{env_key}")
+
+        for field_name, value in cli_vals.items():
+            merged[field_name] = ConfigValue(value=value, source="cli")
+
+        # Team policy overrides env + cli (intentional enterprise enforcement)
+        policy_source = f"team-policy:{team_path}[policy]"
+        for field_name, value in team_policy_vals.items():
+            merged[field_name] = ConfigValue(value=value, source=policy_source)
+
+        settings_kwargs = {k: cv.value for k, cv in merged.items()}
+        settings = GdmSettings(**settings_kwargs)
+        return settings, merged
+
+    def write_user(self, key: str, value: Any) -> None:
+        """Write *key* to the user config TOML (or keychain for secrets).
+
+        *key* uses TOML dot notation (e.g. ``"models.primary"``).
+        """
+        if _is_secret_key(key):
+            import keyring  # type: ignore[import-untyped]
+            keyring.set_password("gdm", key, str(value))
+            return
+        path = self._user_config_path()
+        path.parent.mkdir(parents=True, exist_ok=True)
+        self._atomic_write(path, key, value)
+
+    def write_project(self, key: str, value: Any) -> None:
+        """Write *key* to the project config TOML.
+
+        Raises :class:`ValueError` if *key* is a secret — secrets must
+        go to the OS keychain, never to project TOML.
+        """
+        if _is_secret_key(key):
+            raise ValueError(
+                f"{key!r} is a secret — stored in keychain, never in project TOML. "
+                "Use `gdm config set` without --project for secrets."
+            )
+        _maybe_migrate_gdm_dir(self._project_root)
+        path = self._project_config_path()
+        path.parent.mkdir(parents=True, exist_ok=True)
+        self._atomic_write(path, key, value)
+
+    def unset_user(self, key: str) -> None:
+        """Remove *key* from the user config TOML atomically."""
+        path = self._user_config_path()
+        if not path.exists():
+            return
+        existing = tomllib.loads(path.read_text(encoding="utf-8"))
+        keys = key.split(".")
+        node: Any = existing
+        for k in keys[:-1]:
+            if not isinstance(node, dict) or k not in node:
+                return
+            node = node[k]
+        if isinstance(node, dict):
+            node.pop(keys[-1], None)
+        import tomli_w  # type: ignore[import-untyped]
+        tmp = path.with_suffix(".tmp")
+        try:
+            tmp.write_bytes(tomli_w.dumps(existing).encode("utf-8"))
+            tmp.replace(path)
+        except Exception:
+            tmp.unlink(missing_ok=True)
+            raise
+
+    # ── Path helpers ────────────────────────────────────────────────────────
+
+    def _user_config_path(self) -> Path:
+        return _GLOBAL_CONFIG_FILE
+
+    def _project_config_path(self) -> Path:
+        return self._project_root / ".gdm" / "config.toml"
+
+    def _team_config_path(self) -> Path:
+        return self._project_root / ".gdm" / "team.toml"
+
+    # ── Layer loaders ────────────────────────────────────────────────────────
+
+    def _defaults(self) -> dict[str, Any]:
+        return GdmSettings().model_dump()
+
+    def _load_toml_file(
+        self, path: Path, source_label: str
+    ) -> dict[str, ConfigValue]:
+        """Load a TOML config file and return ``{field: ConfigValue}``."""
+        if not path.exists():
+            return {}
+        try:
+            data = tomllib.loads(path.read_text(encoding="utf-8"))
+            flat = _flatten_toml(data)
+            return {k: ConfigValue(value=v, source=source_label) for k, v in flat.items()}
+        except Exception as exc:
+            log.warning("Could not parse %s: %s", path, exc)
+            return {}
+
+    def _load_team_prefs(self) -> dict[str, ConfigValue]:
+        """Load team preferences from team.toml ``[preferences]`` section."""
+        path = self._team_config_path()
+        if not path.exists():
+            return {}
+        try:
+            data = tomllib.loads(path.read_text(encoding="utf-8"))
+            prefs = data.get("preferences", {})
+            flat = _flatten_toml(prefs)
+            source = f"team-prefs:{path}"
+            return {k: ConfigValue(value=v, source=source) for k, v in flat.items()}
+        except Exception as exc:
+            log.warning("Could not parse team.toml [preferences]: %s", exc)
+            return {}
+
+    def _load_team_policy(self) -> dict[str, Any]:
+        """Load team policy from team.toml ``[policy]`` section.
+
+        Returns ``{field_name: value}`` — stored separately from normal
+        ConfigValues so callers can apply policy *after* env + cli.
+        """
+        path = self._team_config_path()
+        if not path.exists():
+            return {}
+        try:
+            data = tomllib.loads(path.read_text(encoding="utf-8"))
+            policy = data.get("policy", {})
+            result: dict[str, Any] = {}
+            for k, v in policy.items():
+                # max_autonomy_level is the policy spelling; maps to autonomy_level
+                target = _POLICY_KEY_MAP.get(k) or (k if k in GdmSettings.model_fields else None)
+                if target:
+                    result[target] = v
+            return result
+        except Exception as exc:
+            log.warning("Could not parse team.toml [policy]: %s", exc)
+            return {}
+
+    def _load_env(self) -> dict[str, tuple[Any, str]]:
+        """Load GDM_* env vars, returning ``{field_name: (value, env_key)}``."""
+        result: dict[str, tuple[Any, str]] = {}
+        for env_key, field_name in _ENV_KEY_MAP.items():
+            val = os.environ.get(env_key)
+            if val is not None:
+                result[field_name] = (_coerce_env_value(field_name, val), env_key)
+        return result
+
+    # ── Atomic TOML write ───────────────────────────────────────────────────
+
+    def _atomic_write(self, path: Path, key: str, value: Any) -> None:
+        """Write *key=value* to a TOML file atomically via tempfile+rename.
+
+        *key* uses dot notation (e.g. ``"models.primary"``).  Partial writes
+        never corrupt the existing file because the rename is atomic on POSIX
+        and best-effort on Windows.
+        """
+        existing = tomllib.loads(path.read_text(encoding="utf-8")) if path.exists() else {}
+        keys = key.split(".")
+        node: Any = existing
+        for k in keys[:-1]:
+            node = node.setdefault(k, {})
+        node[keys[-1]] = value
+        import tomli_w  # type: ignore[import-untyped]
+        tmp = path.with_suffix(".tmp")
+        try:
+            tmp.write_bytes(tomli_w.dumps(existing).encode("utf-8"))
+            tmp.replace(path)  # atomic on POSIX; best-effort on Windows
+        except Exception:
+            tmp.unlink(missing_ok=True)
+            raise
+