UAT: `--depth-gradient` in `agents project context set` stores hop keys as strings instead of integers, causing inconsistent type handling #3520

New issue

Open

opened 2026-04-05 18:50:18 +00:00 by freemo · 1 comment

freemo commented

2026-04-05 18:50:18 +00:00

Owner

Metadata

Branch: fix/depth-gradient-integer-hop-keys
Commit Message: fix(cli): store depth-gradient hop keys as integers in ACMS config
Milestone: None (backlog)
Parent Epic: #396

Description

The --depth-gradient option in agents project context set parses hop numbers as integers but then immediately converts them back to string keys when storing in the ACMS config JSON. This type inconsistency means any downstream code that looks up a hop by integer key will receive a KeyError, and the context show command already works around this with an int(x[0]) sort hack.

Code location: src/cleveragents/cli/commands/project_context.py — context_set() function, depth_gradient parsing block (~lines 430–460):

parsed_gradient: dict[str, int | str] = {}
for entry in depth_gradient:
    hop_str, _, value_str = entry.partition(":")
    try:
        hop = int(hop_str)  # Parsed as int ...
    except ValueError:
        ...
    parsed_gradient[str(hop)] = parsed_value  # ... but stored as string key!
acms["depth_gradient"] = parsed_gradient

Expected behavior (from spec):
The spec defines --depth-gradient as HOP:INT_OR_NAME format (e.g., 0:9, 1:4, 2:0). Hop numbers should be stored as integer keys:

parsed_gradient: dict[int, int | str] = {}
parsed_gradient[hop] = parsed_value  # integer key

Actual behavior:
Hop numbers are stored as string keys ("0", "1", "2") in the ACMS config. The context show command already works around this with int(x[0]) sorting, but any code performing a direct integer-key lookup will raise a KeyError.

Steps to reproduce:

Run agents project context set --depth-gradient 0:9 --depth-gradient 1:4 <project>
Inspect the stored ACMS config JSON
Observe that depth_gradient keys are strings "0", "1" — not integers 0, 1

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

Subtasks

Change parsed_gradient type annotation to dict[int, int | str]
Change parsed_gradient[str(hop)] = parsed_value to parsed_gradient[hop] = parsed_value
Remove the int(x[0]) workaround in context show display/sort code
Update any other code that reads depth_gradient keys and assumes string type
Tests (unit): Add/update tests asserting depth_gradient keys are integers after context set
Tests (unit): Add regression test for integer-key lookup (acms["depth_gradient"][0])
Run nox (all default sessions), fix any errors
Verify coverage >= 97% via nox -s coverage_report

Definition of Done

This issue is complete when:

All subtasks above are completed and checked off.
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/depth-gradient-integer-hop-keys` - **Commit Message**: `fix(cli): store depth-gradient hop keys as integers in ACMS config` - **Milestone**: None (backlog) - **Parent Epic**: #396 ## Description The `--depth-gradient` option in `agents project context set` parses hop numbers as integers but then immediately converts them back to string keys when storing in the ACMS config JSON. This type inconsistency means any downstream code that looks up a hop by integer key will receive a `KeyError`, and the `context show` command already works around this with an `int(x[0])` sort hack. **Code location:** `src/cleveragents/cli/commands/project_context.py` — `context_set()` function, depth_gradient parsing block (~lines 430–460): ```python parsed_gradient: dict[str, int | str] = {} for entry in depth_gradient: hop_str, _, value_str = entry.partition(":") try: hop = int(hop_str) # Parsed as int ... except ValueError: ... parsed_gradient[str(hop)] = parsed_value # ... but stored as string key! acms["depth_gradient"] = parsed_gradient ``` **Expected behavior (from spec):** The spec defines `--depth-gradient` as `HOP:INT_OR_NAME` format (e.g., `0:9`, `1:4`, `2:0`). Hop numbers should be stored as integer keys: ```python parsed_gradient: dict[int, int | str] = {} parsed_gradient[hop] = parsed_value # integer key ``` **Actual behavior:** Hop numbers are stored as string keys (`"0"`, `"1"`, `"2"`) in the ACMS config. The `context show` command already works around this with `int(x[0])` sorting, but any code performing a direct integer-key lookup will raise a `KeyError`. **Steps to reproduce:** 1. Run `agents project context set --depth-gradient 0:9 --depth-gradient 1:4 <project>` 2. Inspect the stored ACMS config JSON 3. Observe that `depth_gradient` keys are strings `"0"`, `"1"` — not integers `0`, `1` > **Backlog note:** This issue was discovered during autonomous operation > on milestone v3.4.0. It does not block milestone completion and has been > placed in the backlog for human review and future milestone assignment. ## Subtasks - [ ] Change `parsed_gradient` type annotation to `dict[int, int | str]` - [ ] Change `parsed_gradient[str(hop)] = parsed_value` to `parsed_gradient[hop] = parsed_value` - [ ] Remove the `int(x[0])` workaround in `context show` display/sort code - [ ] Update any other code that reads `depth_gradient` keys and assumes string type - [ ] Tests (unit): Add/update tests asserting `depth_gradient` keys are integers after `context set` - [ ] Tests (unit): Add regression test for integer-key lookup (`acms["depth_gradient"][0]`) - [ ] Run `nox` (all default sessions), fix any errors - [ ] Verify coverage >= 97% via `nox -s coverage_report` ## Definition of Done This issue is complete when: - All subtasks above are completed and checked off. - 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 a new dependency

2026-04-05 18:50:24 +00:00

#396 Epic: ACMS Context Pipeline

freemo referenced this issue

2026-04-05 18:51:11 +00:00

[Automated] CleverAgents Build Session - 2026-04-05 #3377

freemo referenced this issue

2026-04-05 18:52:57 +00:00

[Automated] CleverAgents Build Session - 2026-04-05 #3377

freemo referenced this issue

2026-04-05 19:05:02 +00:00

[Automated] CleverAgents Build Session - 2026-04-05 #3377

freemo added this to the v3.4.0 milestone

2026-04-05 20:07:07 +00:00

freemo commented

2026-04-05 20:07:28 +00:00

Author

Owner

Issue triaged by project owner:

State: Verified
Priority: Medium — --depth-gradient stores hop keys as strings instead of integers, causing KeyError on integer-key lookups. The context show command already has a workaround (int(x[0]) sort hack), indicating this is a known inconsistency.
Milestone: v3.4.0
Story Points: 2 — S — Change type annotation and key storage, remove workaround, update downstream consumers.
MoSCoW: Should Have — Data type correctness in the ACMS config is important for reliable context management. The workaround in context show confirms this is a real issue affecting code quality.
Parent Epic: #396 (dependency link already exists)

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

Issue triaged by project owner: - **State**: Verified - **Priority**: Medium — `--depth-gradient` stores hop keys as strings instead of integers, causing `KeyError` on integer-key lookups. The `context show` command already has a workaround (`int(x[0])` sort hack), indicating this is a known inconsistency. - **Milestone**: v3.4.0 - **Story Points**: 2 — S — Change type annotation and key storage, remove workaround, update downstream consumers. - **MoSCoW**: Should Have — Data type correctness in the ACMS config is important for reliable context management. The workaround in `context show` confirms this is a real issue affecting code quality. - **Parent Epic**: #396 (dependency link already exists) --- **Automated by CleverAgents Bot** Supervisor: Project Owner | Agent: ca-project-owner

freemo referenced this issue

2026-04-05 20:08:39 +00:00

[Automated] CleverAgents Build Session - 2026-04-05 #3572

freemo removed this from the v3.4.0 milestone

2026-04-06 21:04:23 +00:00