BUG-HUNT: [spec-alignment] Configuration settings are not loaded from the specified config.toml file #3710

New issue

Open

opened 2026-04-05 22:16:00 +00:00 by freemo · 1 comment

freemo commented

2026-04-05 22:16:00 +00:00

Owner

Metadata

Branch: fix/config-settings-load-from-toml-file
Commit Message: fix(config): load settings from ~/.cleveragents/config.toml per spec precedence chain
Milestone: v3.7.0
Parent Epic: #397

Bug Report: [spec-alignment] — Configuration settings are not loaded from the specified config.toml file

Severity Assessment

Impact: Critical. The application does not respect user configuration files (config.toml), making it impossible for users to configure the system as designed. The application silently ignores the primary configuration method outlined in the specification.
Likelihood: High. Any user attempting to configure the application using the documented config.toml file will encounter this issue.
Priority: Critical

Location

File: src/cleveragents/config/settings.py
Function/Class: Settings(BaseSettings)
Lines: 26-734

Description

The project specification explicitly states that the primary configuration file is ~/.cleveragents/config.toml and that configuration is resolved through a precedence chain that includes this file.

However, the Settings class in settings.py is implemented using pydantic-settings and is configured to only load settings from environment variables (e.g., env_prefix="cleveragents_"). There is no logic to locate, parse, or load values from the specified TOML configuration file.

As a result, the application completely ignores the documented configuration file, and settings can only be provided via environment variables. This is a direct contradiction of the system's design specification.

Evidence

The Settings class definition only configures environment variable loading:

class Settings(BaseSettings):
    """Application runtime configuration backed by environment variables."""

    model_config = SettingsConfigDict(
        env_prefix="cleveragents_", case_sensitive=False, extra="ignore"
    )
    # ...

There is no code that references or loads a config.toml file.

Expected Behavior

The application should load settings from ~/.cleveragents/config.toml as part of the configuration hierarchy, as documented in docs/specification.md. Environment variables should override the values from the file, but the file should be the primary source for user configuration.

Actual Behavior

The application only reads configuration from environment variables. The config.toml file is never read, and any settings within it are silently ignored.

Suggested Fix

Modify the Settings class to use Pydantic's support for TOML file loading. This likely involves adding a settings_source to the SettingsConfigDict or manually loading the TOML file and passing its values to the Settings constructor. The loading mechanism must respect the precedence order defined in the specification.

Subtasks

Write a failing Behave scenario that reproduces the bug (TDD — must be merged before fix)
Implement a custom settings_customise_sources() on Settings to inject a TOML file source
Resolve ~/.cleveragents/config.toml (or CLEVERAGENTS_CONFIG_PATH override) as the TOML source path
Ensure correct precedence: env vars > config.toml > defaults
Add type annotations and pass nox -e typecheck
Update or add Robot Framework integration test verifying config.toml values are loaded
Verify nox passes with coverage >= 97%

Definition of Done

A Behave scenario exists that fails before the fix and passes after
Settings loads values from ~/.cleveragents/config.toml when the file is present
Environment variables correctly override values from config.toml
The fix does not break any existing tests
All nox stages pass
Coverage >= 97%

Automated by CleverAgents Bot
Supervisor: Bug Hunting | Agent: ca-new-issue-creator

## Metadata - **Branch**: `fix/config-settings-load-from-toml-file` - **Commit Message**: `fix(config): load settings from ~/.cleveragents/config.toml per spec precedence chain` - **Milestone**: v3.7.0 - **Parent Epic**: #397 ## Bug Report: [spec-alignment] — Configuration settings are not loaded from the specified config.toml file ### Severity Assessment - **Impact**: Critical. The application does not respect user configuration files (`config.toml`), making it impossible for users to configure the system as designed. The application silently ignores the primary configuration method outlined in the specification. - **Likelihood**: High. Any user attempting to configure the application using the documented `config.toml` file will encounter this issue. - **Priority**: Critical ### Location - **File**: `src/cleveragents/config/settings.py` - **Function/Class**: `Settings(BaseSettings)` - **Lines**: 26-734 ### Description The project specification explicitly states that the primary configuration file is `~/.cleveragents/config.toml` and that configuration is resolved through a precedence chain that includes this file. However, the `Settings` class in `settings.py` is implemented using `pydantic-settings` and is configured to *only* load settings from environment variables (e.g., `env_prefix="cleveragents_"`). There is no logic to locate, parse, or load values from the specified TOML configuration file. As a result, the application completely ignores the documented configuration file, and settings can only be provided via environment variables. This is a direct contradiction of the system's design specification. ### Evidence The `Settings` class definition only configures environment variable loading: ```python class Settings(BaseSettings): """Application runtime configuration backed by environment variables.""" model_config = SettingsConfigDict( env_prefix="cleveragents_", case_sensitive=False, extra="ignore" ) # ... ``` There is no code that references or loads a `config.toml` file. ### Expected Behavior The application should load settings from `~/.cleveragents/config.toml` as part of the configuration hierarchy, as documented in `docs/specification.md`. Environment variables should override the values from the file, but the file should be the primary source for user configuration. ### Actual Behavior The application *only* reads configuration from environment variables. The `config.toml` file is never read, and any settings within it are silently ignored. ### Suggested Fix Modify the `Settings` class to use Pydantic's support for TOML file loading. This likely involves adding a `settings_source` to the `SettingsConfigDict` or manually loading the TOML file and passing its values to the `Settings` constructor. The loading mechanism must respect the precedence order defined in the specification. ### Category spec-alignment ## Subtasks - [ ] Write a failing Behave scenario that reproduces the bug (TDD — must be merged before fix) - [ ] Implement a custom `settings_customise_sources()` on `Settings` to inject a TOML file source - [ ] Resolve `~/.cleveragents/config.toml` (or `CLEVERAGENTS_CONFIG_PATH` override) as the TOML source path - [ ] Ensure correct precedence: env vars > config.toml > defaults - [ ] Add type annotations and pass `nox -e typecheck` - [ ] Update or add Robot Framework integration test verifying config.toml values are loaded - [ ] Verify `nox` passes with coverage >= 97% ## Definition of Done - [ ] A Behave scenario exists that fails before the fix and passes after - [ ] `Settings` loads values from `~/.cleveragents/config.toml` when the file is present - [ ] Environment variables correctly override values from `config.toml` - [ ] The fix does not break any existing tests - [ ] All nox stages pass - [ ] Coverage >= 97% --- **Automated by CleverAgents Bot** Supervisor: Bug Hunting | Agent: ca-new-issue-creator

freemo added this to the v3.7.0 milestone

2026-04-05 22:16:16 +00:00

freemo added a new dependency

2026-04-05 22:16:22 +00:00

#397 Epic: Server & Autonomy Infrastructure

freemo commented

2026-04-05 22:22:30 +00:00

Author

Owner

Issue triaged by project owner:

State: Verified
Priority: Critical — The application completely ignores ~/.cleveragents/config.toml, the primary user configuration mechanism. Settings can only be provided via environment variables. This makes the entire config system non-functional for end users.
Milestone: v3.7.0 (already assigned)
Story Points: 5 — L — Requires implementing a custom settings_customise_sources() on the Pydantic Settings class to inject a TOML file source, with correct precedence (env vars > config.toml > defaults). Moderate complexity.
MoSCoW: Must Have — The spec explicitly defines ~/.cleveragents/config.toml as the primary configuration file. Without this, users cannot configure the application as designed. This is a fundamental spec compliance failure.
Parent Epic: #397

Automated by CleverAgents Bot
Supervisor: Project Owner | Agent: ca-project-owner

Issue triaged by project owner: - **State**: Verified - **Priority**: Critical — The application completely ignores `~/.cleveragents/config.toml`, the primary user configuration mechanism. Settings can only be provided via environment variables. This makes the entire config system non-functional for end users. - **Milestone**: v3.7.0 (already assigned) - **Story Points**: 5 — L — Requires implementing a custom `settings_customise_sources()` on the Pydantic Settings class to inject a TOML file source, with correct precedence (env vars > config.toml > defaults). Moderate complexity. - **MoSCoW**: Must Have — The spec explicitly defines `~/.cleveragents/config.toml` as the primary configuration file. Without this, users cannot configure the application as designed. This is a fundamental spec compliance failure. - **Parent Epic**: #397 --- **Automated by CleverAgents Bot** Supervisor: Project Owner | Agent: ca-project-owner

freemo referenced this issue

2026-04-05 22:22:42 +00:00

[Automated] CleverAgents Build Session - 2026-04-05 (Resumed) #3654

freemo referenced this issue

2026-04-05 22:31:32 +00:00

[Automated] CleverAgents Build Session - 2026-04-05 (Resumed) #3654

freemo removed this from the v3.7.0 milestone

2026-04-06 23:31:20 +00:00