UAT: CLEVERAGENTS_FORMAT environment variable not supported — spec requires it as second-highest priority in format resolution chain #1982

Open
opened 2026-04-03 00:30:35 +00:00 by freemo · 2 comments
Owner

Metadata

  • Branch: fix/cleveragents-format-env-var-resolution
  • Commit Message: fix(cli): support CLEVERAGENTS_FORMAT env var in format resolution chain
  • Milestone: v3.5.0
  • Parent Epic: #936

Bug Report

Feature Area: CLI output formatting — format resolution priority chain

Severity: Medium

Parent Epic: #936 (Output Rendering Pipeline Integration)

Summary

The specification defines a format resolution priority chain where CLEVERAGENTS_FORMAT environment variable is the second-highest priority (after the --format CLI flag). This environment variable is not implemented. The implementation skips directly from CLI flag to config file (core.format) to TTY detection to default.

Steps to Reproduce

export CLEVERAGENTS_FORMAT=json
agents version
# Expected: JSON output (env var respected)
# Actual: Rich/plain output (env var ignored)
import os
os.environ['CLEVERAGENTS_FORMAT'] = 'json'

from cleveragents.cli.main import app
from typer.testing import CliRunner
import json

runner = CliRunner()
result = runner.invoke(app, ['version'])
# result.output is rich text, not JSON
# CLEVERAGENTS_FORMAT was ignored

Actual Behavior

The CLEVERAGENTS_FORMAT environment variable is completely ignored. The format defaults to rich (or falls back based on TTY detection) regardless of the environment variable value.

Expected Behavior

Per the specification (§Output Rendering Framework / Format Resolution):

The active format is resolved using a precedence chain:

  1. CLI flag: --format <value> on the command line (highest priority).
  2. Environment variable: CLEVERAGENTS_FORMAT=<value>.
  3. Config file: The core.format key in the global config.
  4. TTY detection: If stdout is not a TTY and no explicit format was set, fall back to plain.
  5. Default: rich.

Setting CLEVERAGENTS_FORMAT=json should cause all commands to output JSON format unless overridden by --format.

Root Cause

The select_materializer() function in src/cleveragents/cli/output/selection.py does not check CLEVERAGENTS_FORMAT. The format_output() function in src/cleveragents/cli/formatting.py does not check it either. The CLI commands receive the format via the --format per-command option only.

This is documented as SD-15 in src/cleveragents/cli/output/__init__.py:

SD-15 (CLEVERAGENTS_FORMAT env var not checked): The spec defines CLEVERAGENTS_FORMAT for overriding the default format. This implementation only accepts --format CLI flag.

Code Locations

  • src/cleveragents/cli/output/selection.py: select_materializer() — needs to check CLEVERAGENTS_FORMAT
  • src/cleveragents/cli/output/__init__.py: SD-15 deviation documentation
  • All CLI command files: format resolution happens per-command via --format option default

Subtasks

  • Add CLEVERAGENTS_FORMAT environment variable check to select_materializer() in src/cleveragents/cli/output/selection.py
  • Add CLEVERAGENTS_FORMAT check to format_output() in src/cleveragents/cli/formatting.py (if applicable)
  • Ensure correct precedence: CLI flag > CLEVERAGENTS_FORMAT env var > config file (core.format) > TTY detection > default (rich)
  • Remove or update SD-15 deviation note in src/cleveragents/cli/output/__init__.py once resolved
  • Tests (Behave): Add scenarios for CLEVERAGENTS_FORMAT env var being respected at each priority level
  • Tests (Robot): Add integration test verifying CLEVERAGENTS_FORMAT overrides default format
  • Verify coverage >=97% via nox -s coverage_report
  • Run nox (all default sessions), fix any errors

Definition of Done

This issue is complete when:

  • All subtasks above are completed and checked off.
  • CLEVERAGENTS_FORMAT environment variable is checked as the second step in the format resolution chain, after the --format CLI flag and before the config file.
  • A Git commit is created where the first line of the commit message matches the Commit Message in Metadata exactly, followed by a blank line, then additional lines providing relevant details about the implementation.
  • The commit is pushed to the remote on the branch matching the Branch in Metadata exactly.
  • The commit is submitted as a pull request to master, reviewed, and merged before this issue is marked done.
  • All nox stages pass.
  • Coverage >= 97%.

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

## Metadata - **Branch**: `fix/cleveragents-format-env-var-resolution` - **Commit Message**: `fix(cli): support CLEVERAGENTS_FORMAT env var in format resolution chain` - **Milestone**: v3.5.0 - **Parent Epic**: #936 ## Bug Report **Feature Area:** CLI output formatting — format resolution priority chain **Severity:** Medium **Parent Epic:** #936 (Output Rendering Pipeline Integration) ### Summary The specification defines a format resolution priority chain where `CLEVERAGENTS_FORMAT` environment variable is the second-highest priority (after the `--format` CLI flag). This environment variable is not implemented. The implementation skips directly from CLI flag to config file (`core.format`) to TTY detection to default. ### Steps to Reproduce ```bash export CLEVERAGENTS_FORMAT=json agents version # Expected: JSON output (env var respected) # Actual: Rich/plain output (env var ignored) ``` ```python import os os.environ['CLEVERAGENTS_FORMAT'] = 'json' from cleveragents.cli.main import app from typer.testing import CliRunner import json runner = CliRunner() result = runner.invoke(app, ['version']) # result.output is rich text, not JSON # CLEVERAGENTS_FORMAT was ignored ``` ### Actual Behavior The `CLEVERAGENTS_FORMAT` environment variable is completely ignored. The format defaults to `rich` (or falls back based on TTY detection) regardless of the environment variable value. ### Expected Behavior Per the specification (§Output Rendering Framework / Format Resolution): > The active format is resolved using a precedence chain: > 1. **CLI flag**: `--format <value>` on the command line (highest priority). > 2. **Environment variable**: `CLEVERAGENTS_FORMAT=<value>`. > 3. **Config file**: The `core.format` key in the global config. > 4. **TTY detection**: If stdout is not a TTY and no explicit format was set, fall back to `plain`. > 5. **Default**: `rich`. Setting `CLEVERAGENTS_FORMAT=json` should cause all commands to output JSON format unless overridden by `--format`. ### Root Cause The `select_materializer()` function in `src/cleveragents/cli/output/selection.py` does not check `CLEVERAGENTS_FORMAT`. The `format_output()` function in `src/cleveragents/cli/formatting.py` does not check it either. The CLI commands receive the format via the `--format` per-command option only. This is documented as **SD-15** in `src/cleveragents/cli/output/__init__.py`: > **SD-15 (CLEVERAGENTS_FORMAT env var not checked)**: The spec defines `CLEVERAGENTS_FORMAT` for overriding the default format. This implementation only accepts `--format` CLI flag. ### Code Locations - `src/cleveragents/cli/output/selection.py`: `select_materializer()` — needs to check `CLEVERAGENTS_FORMAT` - `src/cleveragents/cli/output/__init__.py`: SD-15 deviation documentation - All CLI command files: format resolution happens per-command via `--format` option default ## Subtasks - [ ] Add `CLEVERAGENTS_FORMAT` environment variable check to `select_materializer()` in `src/cleveragents/cli/output/selection.py` - [ ] Add `CLEVERAGENTS_FORMAT` check to `format_output()` in `src/cleveragents/cli/formatting.py` (if applicable) - [ ] Ensure correct precedence: CLI flag > `CLEVERAGENTS_FORMAT` env var > config file (`core.format`) > TTY detection > default (`rich`) - [ ] Remove or update SD-15 deviation note in `src/cleveragents/cli/output/__init__.py` once resolved - [ ] Tests (Behave): Add scenarios for `CLEVERAGENTS_FORMAT` env var being respected at each priority level - [ ] Tests (Robot): Add integration test verifying `CLEVERAGENTS_FORMAT` overrides default format - [ ] Verify coverage >=97% via `nox -s coverage_report` - [ ] Run `nox` (all default sessions), fix any errors ## Definition of Done This issue is complete when: - All subtasks above are completed and checked off. - `CLEVERAGENTS_FORMAT` environment variable is checked as the second step in the format resolution chain, after the `--format` CLI flag and before the config file. - A Git commit is created where the **first line** of the commit message matches the Commit Message in Metadata exactly, followed by a blank line, then additional lines providing relevant details about the implementation. - The commit is pushed to the remote on the branch matching the **Branch** in Metadata exactly. - The commit is submitted as a **pull request** to `master`, reviewed, and **merged** before this issue is marked done. - All nox stages pass. - Coverage >= 97%. --- **Automated by CleverAgents Bot** Supervisor: UAT Testing | Agent: ca-new-issue-creator
freemo added this to the v3.5.0 milestone 2026-04-03 00:30:52 +00:00
Author
Owner

Issue triaged by project owner:

  • State: Verified
  • Priority: Medium (confirmed)
  • Milestone: v3.5.0 (confirmed — format resolution chain is part of the output rendering pipeline)
  • MoSCoW: Should Have — The spec defines CLEVERAGENTS_FORMAT as the second-highest priority in the format resolution chain. This is a spec-mandated feature for output format control. Not blocking core execution but important for spec compliance and user workflow flexibility.

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

Issue triaged by project owner: - **State**: Verified - **Priority**: Medium (confirmed) - **Milestone**: v3.5.0 (confirmed — format resolution chain is part of the output rendering pipeline) - **MoSCoW**: Should Have — The spec defines `CLEVERAGENTS_FORMAT` as the second-highest priority in the format resolution chain. This is a spec-mandated feature for output format control. Not blocking core execution but important for spec compliance and user workflow flexibility. --- **Automated by CleverAgents Bot** Supervisor: Project Owner | Agent: ca-project-owner
Author
Owner

Issue triaged by project owner:

  • State: Verified
  • Priority: Medium
  • Milestone: v3.5.0
  • MoSCoW: Should Have — the spec defines CLEVERAGENTS_FORMAT as second-highest priority in the format resolution chain; missing support is a spec compliance gap

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

Issue triaged by project owner: - **State**: Verified - **Priority**: Medium - **Milestone**: v3.5.0 - **MoSCoW**: Should Have — the spec defines `CLEVERAGENTS_FORMAT` as second-highest priority in the format resolution chain; missing support is a spec compliance gap --- **Automated by CleverAgents Bot** Supervisor: Project Owner | Agent: ca-project-owner
Sign in to join this conversation.
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Reference
cleveragents/cleveragents-core#1982
No description provided.