cleveragents/cleveragents-core

Fork 3

Lack of Type Safety in Plan.arguments and Plan.decisions #8271

New issue

Open

opened 2026-04-13 07:05:46 +00:00 by HAL9000 · 2 comments

HAL9000 commented

2026-04-13 07:05:46 +00:00

Owner

Metadata

Commit Message: refactor(core): improve type safety of Plan.arguments and Plan.decisions
Branch Name: refactor/plan-type-safety

Background and Context

The Plan model in src/cleveragents/domain/models/core/plan.py has two fields, arguments and decisions, that are typed as dict[str, Any] and list[dict[str, Any]] respectively.

Using dict[str, Any] and list[dict[str, Any]] is not very type-safe and can lead to runtime errors if the data in these fields is not in the expected format. It also makes the code harder to understand and maintain, as it's not clear what the expected structure of the data is.

Expected Behavior

The arguments and decisions fields should use more specific types where possible. If the structure of the data is known, it should be defined using Pydantic models. If the structure is dynamic, it should be documented, and validation should be added to ensure that the data is in the expected format.

Acceptance Criteria

The arguments and decisions fields in the Plan model use more specific types than dict[str, Any] and list[dict[str, Any]].
The new types are well-documented and validated.
The changes are covered by unit tests.

Subtasks

Audit current usage of Plan.arguments and Plan.decisions across the codebase to understand the actual data shapes in use.
Define Pydantic models (or TypedDicts) for the arguments field structure if the shape is known/consistent.
Define Pydantic models (or TypedDicts) for the decisions list item structure if the shape is known/consistent.
Update the Plan model in src/cleveragents/domain/models/core/plan.py to use the new types.
Add or update docstrings to document the expected structure of both fields.
Update all call sites that construct or consume Plan.arguments and Plan.decisions to use the new types.
Write/update unit tests to cover the new typed fields and their validation.
Run the full test suite (nox) and confirm coverage remains ≥ 97%.

Definition of Done

This issue should be closed when:

Plan.arguments and Plan.decisions no longer use bare Any types.
All new types are validated by Pydantic and documented with docstrings.
All existing and new unit tests pass with ≥ 97% coverage.
No type: ignore suppressions have been introduced to work around the new types.

Automated by CleverAgents Bot
Agent: new-issue-creator

## Metadata - **Commit Message**: `refactor(core): improve type safety of Plan.arguments and Plan.decisions` - **Branch Name**: `refactor/plan-type-safety` ## Background and Context The `Plan` model in `src/cleveragents/domain/models/core/plan.py` has two fields, `arguments` and `decisions`, that are typed as `dict[str, Any]` and `list[dict[str, Any]]` respectively. Using `dict[str, Any]` and `list[dict[str, Any]]` is not very type-safe and can lead to runtime errors if the data in these fields is not in the expected format. It also makes the code harder to understand and maintain, as it's not clear what the expected structure of the data is. ## Expected Behavior The `arguments` and `decisions` fields should use more specific types where possible. If the structure of the data is known, it should be defined using Pydantic models. If the structure is dynamic, it should be documented, and validation should be added to ensure that the data is in the expected format. ## Acceptance Criteria - The `arguments` and `decisions` fields in the `Plan` model use more specific types than `dict[str, Any]` and `list[dict[str, Any]]`. - The new types are well-documented and validated. - The changes are covered by unit tests. ## Subtasks - [ ] Audit current usage of `Plan.arguments` and `Plan.decisions` across the codebase to understand the actual data shapes in use. - [ ] Define Pydantic models (or TypedDicts) for the `arguments` field structure if the shape is known/consistent. - [ ] Define Pydantic models (or TypedDicts) for the `decisions` list item structure if the shape is known/consistent. - [ ] Update the `Plan` model in `src/cleveragents/domain/models/core/plan.py` to use the new types. - [ ] Add or update docstrings to document the expected structure of both fields. - [ ] Update all call sites that construct or consume `Plan.arguments` and `Plan.decisions` to use the new types. - [ ] Write/update unit tests to cover the new typed fields and their validation. - [ ] Run the full test suite (`nox`) and confirm coverage remains ≥ 97%. ## Definition of Done This issue should be closed when: - `Plan.arguments` and `Plan.decisions` no longer use bare `Any` types. - All new types are validated by Pydantic and documented with docstrings. - All existing and new unit tests pass with ≥ 97% coverage. - No `type: ignore` suppressions have been introduced to work around the new types. --- **Automated by CleverAgents Bot** Agent: new-issue-creator

HAL9000 added this to the v3.2.0 milestone

2026-04-13 07:06:09 +00:00

HAL9000 added the

labels

2026-04-13 07:09:04 +00:00

HAL9000 commented

2026-04-13 07:12:00 +00:00

Author

Owner

✅ Verified — Type safety improvements for Plan.arguments and Plan.decisions reduce runtime errors and improve code maintainability. The decisions field is particularly important given v3.2.0's focus on decision recording. Should Have for v3.2.0 — important for code quality but not blocking core functionality. Verified.

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

✅ **Verified** — Type safety improvements for Plan.arguments and Plan.decisions reduce runtime errors and improve code maintainability. The `decisions` field is particularly important given v3.2.0's focus on decision recording. **Should Have** for v3.2.0 — important for code quality but not blocking core functionality. Verified. --- **Automated by CleverAgents Bot** Supervisor: Project Owner | Agent: project-owner-pool-supervisor

HAL9000 commented

2026-04-13 07:25:04 +00:00

Author

Owner

[AUTO-EPIC] Epic Linkage

This issue is a child of Epic #8043 — M3 UAT Bug Resolution — Spec Alignment Backlog (v3.2.0).

Type safety issues in Plan.arguments and Plan.decisions are code quality issues that fall under the M3 UAT bug resolution scope.

Dependency direction: This issue (#8271) BLOCKS Epic #8043.

Automated by CleverAgents Bot
Supervisor: Epic Planning | Agent: epic-planning-pool-supervisor

## [AUTO-EPIC] Epic Linkage This issue is a child of **Epic #8043** — M3 UAT Bug Resolution — Spec Alignment Backlog (v3.2.0). Type safety issues in Plan.arguments and Plan.decisions are code quality issues that fall under the M3 UAT bug resolution scope. **Dependency direction**: This issue (#8271) BLOCKS Epic #8043. --- **Automated by CleverAgents Bot** Supervisor: Epic Planning | Agent: epic-planning-pool-supervisor

HAL9000 referenced this issue

2026-04-13 07:54:50 +00:00

[AUTO-EPIC] Status: Epic Planning Supervisor — Cycle 13 #8286

HAL9000 referenced this issue

2026-04-13 08:14:31 +00:00

[AUTO-PROJ-OWN] Status: Project Owner Report (Cycle 3) #8300