cleveragents/cleveragents-core

Fork 3

fix(config): correct "five-level" to "six-level" in config_service.py and config.py docstrings #3847

New issue

Open

opened 2026-04-06 06:55:52 +00:00 by freemo · 1 comment

freemo commented

2026-04-06 06:55:52 +00:00

Owner

Metadata

Branch: fix/config-docstring-five-to-six-level-precedence
Commit Message: fix(config): correct "five-level" to "six-level" in config_service and config CLI docstrings
Milestone: (none — backlog)
Parent Epic: (pending — see orphan note below)

Description

The module docstring for src/cleveragents/application/services/config_service.py states the system implements a "five-level precedence chain", but the actual implementation has six levels (adding a LOCAL scope between ENV_VAR and PROJECT). This creates a misleading developer experience and incorrect documentation.

Expected Behaviour

The module docstring should accurately describe the six-level precedence chain:

CLI flag > env var > local (config.local.toml) > project (config.toml) > global > default

Actual Behaviour

The module docstring currently says:

"""Config service with multi-level resolution chain and typed key registry.

Provides a resolution layer on top of ``Settings`` (pydantic-settings) that
manages TOML file persistence and implements a five-level precedence chain:

    CLI flag  >  environment variable  >  project-scoped  >  global config  >  default

This is incorrect — it omits the local scope and says "five-level" when there are actually six levels.

Evidence

The ConfigLevel enum has 6 values:

class ConfigLevel(Enum):
    CLI_FLAG = "cli_flag"
    ENV_VAR  = "env_var"
    LOCAL    = "local"       # <-- This is the 6th level
    PROJECT  = "project"
    GLOBAL   = "global"
    DEFAULT  = "default"

The resolve() method docstring already correctly states "six-level":

Precedence (highest → lowest)::
    CLI flag > env var > local (config.local.toml)
             > project (config.toml) > global > default

Affected Locations

File	Location	Incorrect Text
`src/cleveragents/application/services/config_service.py`	Module docstring (lines 1–9)	`"five-level precedence chain"` / omits `local` scope
`src/cleveragents/cli/commands/config.py`	Module docstring	`"implements the five-level precedence chain"`
`src/cleveragents/cli/commands/config.py`	`config_get()` docstring	`"Use --verbose to display the full five-level resolution chain."`

Impact

Developers reading the module docstring will have an incorrect understanding of the resolution chain.
The --verbose flag in agents config get is described as showing a "five-level" chain but actually shows six levels.
Inconsistency between module-level and method-level documentation erodes trust in the docs.

Subtasks

Update config_service.py module docstring: replace "five-level" with "six-level" and add local (config.local.toml) to the chain diagram
Update config.py module docstring: replace "five-level" with "six-level"
Update config_get() docstring in config.py: replace "five-level" with "six-level"
Verify no other docstrings or comments in the codebase reference "five-level" for this chain
Run nox -e lint and nox -e typecheck to confirm no regressions

Definition of Done

All three docstring locations updated to say "six-level" with the correct chain diagram
No remaining references to "five-level" precedence chain in the codebase
nox -e lint passes
nox -e typecheck passes
All nox stages pass
Coverage >= 97%

Backlog note: This issue was discovered during autonomous operation
on milestone v3.6.0. It does not block milestone completion and has been
placed in the backlog for human review and future milestone assignment.

Automated by CleverAgents Bot
Supervisor: UAT Testing | Agent: ca-uat-tester

## Metadata - **Branch**: `fix/config-docstring-five-to-six-level-precedence` - **Commit Message**: `fix(config): correct "five-level" to "six-level" in config_service and config CLI docstrings` - **Milestone**: *(none — backlog)* - **Parent Epic**: *(pending — see orphan note below)* ## Description The module docstring for `src/cleveragents/application/services/config_service.py` states the system implements a **"five-level precedence chain"**, but the actual implementation has **six levels** (adding a `LOCAL` scope between `ENV_VAR` and `PROJECT`). This creates a misleading developer experience and incorrect documentation. ### Expected Behaviour The module docstring should accurately describe the six-level precedence chain: ``` CLI flag > env var > local (config.local.toml) > project (config.toml) > global > default ``` ### Actual Behaviour The module docstring currently says: ```python """Config service with multi-level resolution chain and typed key registry. Provides a resolution layer on top of ``Settings`` (pydantic-settings) that manages TOML file persistence and implements a five-level precedence chain: CLI flag > environment variable > project-scoped > global config > default ``` This is incorrect — it omits the `local` scope and says "five-level" when there are actually six levels. ### Evidence The `ConfigLevel` enum has 6 values: ```python class ConfigLevel(Enum): CLI_FLAG = "cli_flag" ENV_VAR = "env_var" LOCAL = "local" # <-- This is the 6th level PROJECT = "project" GLOBAL = "global" DEFAULT = "default" ``` The `resolve()` method docstring already correctly states "six-level": ``` Precedence (highest → lowest):: CLI flag > env var > local (config.local.toml) > project (config.toml) > global > default ``` ### Affected Locations | File | Location | Incorrect Text | |------|----------|----------------| | `src/cleveragents/application/services/config_service.py` | Module docstring (lines 1–9) | `"five-level precedence chain"` / omits `local` scope | | `src/cleveragents/cli/commands/config.py` | Module docstring | `"implements the five-level precedence chain"` | | `src/cleveragents/cli/commands/config.py` | `config_get()` docstring | `"Use --verbose to display the full five-level resolution chain."` | ### Impact - Developers reading the module docstring will have an incorrect understanding of the resolution chain. - The `--verbose` flag in `agents config get` is described as showing a "five-level" chain but actually shows six levels. - Inconsistency between module-level and method-level documentation erodes trust in the docs. ## Subtasks - [ ] Update `config_service.py` module docstring: replace `"five-level"` with `"six-level"` and add `local (config.local.toml)` to the chain diagram - [ ] Update `config.py` module docstring: replace `"five-level"` with `"six-level"` - [ ] Update `config_get()` docstring in `config.py`: replace `"five-level"` with `"six-level"` - [ ] Verify no other docstrings or comments in the codebase reference `"five-level"` for this chain - [ ] Run `nox -e lint` and `nox -e typecheck` to confirm no regressions ## Definition of Done - [ ] All three docstring locations updated to say `"six-level"` with the correct chain diagram - [ ] No remaining references to `"five-level"` precedence chain in the codebase - [ ] `nox -e lint` passes - [ ] `nox -e typecheck` passes - [ ] All nox stages pass - [ ] Coverage >= 97% > **Backlog note:** This issue was discovered during autonomous operation > on milestone v3.6.0. It does not block milestone completion and has been > placed in the backlog for human review and future milestone assignment. --- **Automated by CleverAgents Bot** Supervisor: UAT Testing | Agent: ca-uat-tester

freemo commented

2026-04-06 06:56:28 +00:00

Author

Owner

⚠️ Orphan Issue — Manual Epic Linking Required

This issue was created by an automated agent and no suitable parent Epic was found at creation time. A scan of all open Type/Epic issues found no Epic specifically covering config service documentation accuracy or docstring correctness.

Action required by a human maintainer: Please link this issue to the appropriate parent Epic using Forgejo's dependency system (this issue should block the parent Epic). Candidate epics to consider:

If a "Config Service" or "Documentation Quality" epic exists or is created, link there.
Otherwise, consider creating a new Epic for config-layer documentation correctness.

Until linked, this issue is technically an orphan per CONTRIBUTING.md policy.

Automated by CleverAgents Bot
Supervisor: UAT Testing | Agent: ca-new-issue-creator

⚠️ **Orphan Issue — Manual Epic Linking Required** This issue was created by an automated agent and no suitable parent Epic was found at creation time. A scan of all open `Type/Epic` issues found no Epic specifically covering config service documentation accuracy or docstring correctness. **Action required by a human maintainer:** Please link this issue to the appropriate parent Epic using Forgejo's dependency system (this issue should **block** the parent Epic). Candidate epics to consider: - If a "Config Service" or "Documentation Quality" epic exists or is created, link there. - Otherwise, consider creating a new Epic for config-layer documentation correctness. Until linked, this issue is technically an orphan per CONTRIBUTING.md policy. --- **Automated by CleverAgents Bot** Supervisor: UAT Testing | Agent: ca-new-issue-creator

freemo added the

Points

label

2026-04-06 06:56:48 +00:00

freemo referenced this issue

2026-04-06 06:58:39 +00:00

[Automated] CleverAgents Build Session - 2026-04-06 #3775

freemo referenced this issue

2026-04-06 07:00:43 +00:00

[Automated] CleverAgents Build Session - 2026-04-06 #3775

freemo referenced this issue

2026-04-06 07:04:26 +00:00