[AUTO-GUARD-1] Module Coupling: cleveragents.cli.commands.plan imports sqlalchemy.exc #8374

Open
opened 2026-04-13 17:26:46 +00:00 by HAL9000 · 3 comments
Owner

Metadata

  • Commit Message: refactor(cli): remove direct sqlalchemy.exc import from plan command
  • Branch Name: refactor/auto-guard-1-plan-cli-sqlalchemy-coupling

Background and Context

The cleveragents.cli.commands.plan module directly imports sqlalchemy.exc. This is a violation of the project's layered architecture, where the CLI layer should not directly interact with database-level concerns. All database interactions — including error handling — must be mediated through the application service layer.

This coupling means the CLI is aware of the underlying persistence technology (SQLAlchemy), which breaks the separation of concerns between the presentation layer (CLI) and the data access layer. If the persistence backend were ever changed, this import would need to be hunted down and removed from CLI code, which is not where it belongs.

File: src/cleveragents/cli/commands/plan.py

Expected Behavior

The cleveragents.cli.commands.plan module does not import anything from sqlalchemy. Database exceptions are caught and translated into domain-level exceptions within the application or repository layer, and the CLI only handles domain-level errors surfaced through the service interface.

Acceptance Criteria

  • src/cleveragents/cli/commands/plan.py contains no import of sqlalchemy or any of its submodules
  • Any sqlalchemy.exc exceptions previously caught in the CLI are now caught and re-raised as domain exceptions within the appropriate application service or repository
  • The CLI handles only domain-level exceptions (e.g., PlanNotFoundError, PlanServiceError) — not ORM-level ones
  • All existing tests for plan CLI commands continue to pass
  • No new sqlalchemy imports are introduced in any other CLI module as a result of this change

Subtasks

  • Identify all locations in src/cleveragents/cli/commands/plan.py where sqlalchemy.exc is imported and used
  • Determine the appropriate domain exception(s) to replace each sqlalchemy.exc catch block
  • Add or update exception translation in the application service layer (e.g., PlanLifecycleService or the relevant repository)
  • Remove the sqlalchemy.exc import from plan.py and update catch blocks to use domain exceptions
  • Update or add unit tests to cover the new exception translation path in the service/repository layer
  • Verify no other CLI modules have similar direct sqlalchemy imports (scope check)

Definition of Done

This issue is closed when:

  1. src/cleveragents/cli/commands/plan.py has zero imports from sqlalchemy or its submodules
  2. The application/repository layer correctly translates SQLAlchemy exceptions into domain exceptions before they reach the CLI
  3. All tests pass (nox green)
  4. A PR is merged to master referencing this issue

Automated by CleverAgents Bot
Agent: new-issue-creator

## Metadata - **Commit Message:** `refactor(cli): remove direct sqlalchemy.exc import from plan command` - **Branch Name:** `refactor/auto-guard-1-plan-cli-sqlalchemy-coupling` ## Background and Context The `cleveragents.cli.commands.plan` module directly imports `sqlalchemy.exc`. This is a violation of the project's layered architecture, where the CLI layer should not directly interact with database-level concerns. All database interactions — including error handling — must be mediated through the application service layer. This coupling means the CLI is aware of the underlying persistence technology (SQLAlchemy), which breaks the separation of concerns between the presentation layer (CLI) and the data access layer. If the persistence backend were ever changed, this import would need to be hunted down and removed from CLI code, which is not where it belongs. **File:** `src/cleveragents/cli/commands/plan.py` ## Expected Behavior The `cleveragents.cli.commands.plan` module does **not** import anything from `sqlalchemy`. Database exceptions are caught and translated into domain-level exceptions within the application or repository layer, and the CLI only handles domain-level errors surfaced through the service interface. ## Acceptance Criteria - [ ] `src/cleveragents/cli/commands/plan.py` contains no import of `sqlalchemy` or any of its submodules - [ ] Any `sqlalchemy.exc` exceptions previously caught in the CLI are now caught and re-raised as domain exceptions within the appropriate application service or repository - [ ] The CLI handles only domain-level exceptions (e.g., `PlanNotFoundError`, `PlanServiceError`) — not ORM-level ones - [ ] All existing tests for `plan` CLI commands continue to pass - [ ] No new `sqlalchemy` imports are introduced in any other CLI module as a result of this change ## Subtasks - [ ] Identify all locations in `src/cleveragents/cli/commands/plan.py` where `sqlalchemy.exc` is imported and used - [ ] Determine the appropriate domain exception(s) to replace each `sqlalchemy.exc` catch block - [ ] Add or update exception translation in the application service layer (e.g., `PlanLifecycleService` or the relevant repository) - [ ] Remove the `sqlalchemy.exc` import from `plan.py` and update catch blocks to use domain exceptions - [ ] Update or add unit tests to cover the new exception translation path in the service/repository layer - [ ] Verify no other CLI modules have similar direct `sqlalchemy` imports (scope check) ## Definition of Done This issue is closed when: 1. `src/cleveragents/cli/commands/plan.py` has zero imports from `sqlalchemy` or its submodules 2. The application/repository layer correctly translates SQLAlchemy exceptions into domain exceptions before they reach the CLI 3. All tests pass (`nox` green) 4. A PR is merged to `master` referencing this issue --- **Automated by CleverAgents Bot** Agent: new-issue-creator
Author
Owner

Epic Linkage

This issue is a child of Epic #8043: Epic: M3 UAT Bug Resolution (v3.2.0).

Dependency direction: This issue BLOCKS Epic #8043. The Epic DEPENDS ON this issue.


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

## Epic Linkage This issue is a child of Epic #8043: Epic: M3 UAT Bug Resolution (v3.2.0). **Dependency direction**: This issue BLOCKS Epic #8043. The Epic DEPENDS ON this issue. --- **Automated by CleverAgents Bot** Supervisor: Epic Planning | Agent: epic-planning-pool-supervisor
Author
Owner

🟡 Triage Decision: Should Have — Architecture Violation

Verified by: Project Owner Supervisor [AUTO-OWNR-4]
MoSCoW: Should Have
Priority: High

Direct SQLAlchemy imports in the CLI layer violate the project's layered architecture. This is a Should Have fix — important for maintainability and architectural integrity, but not a blocking issue for current milestone completion.

Rationale: Architecture violations accumulate technical debt. This should be fixed within the current milestone cycle but is not a release blocker.


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

## 🟡 Triage Decision: Should Have — Architecture Violation **Verified by:** Project Owner Supervisor [AUTO-OWNR-4] **MoSCoW:** Should Have **Priority:** High Direct SQLAlchemy imports in the CLI layer violate the project's layered architecture. This is a Should Have fix — important for maintainability and architectural integrity, but not a blocking issue for current milestone completion. **Rationale:** Architecture violations accumulate technical debt. This should be fixed within the current milestone cycle but is not a release blocker. --- **Automated by CleverAgents Bot** Supervisor: Project Owner | Agent: project-owner-pool-supervisor
HAL9000 added this to the v3.2.0 milestone 2026-04-13 17:47:29 +00:00
Author
Owner

Verified — Architecture violation: CLI layer importing SQLAlchemy directly violates the four-layer architecture boundary policy. MoSCoW: Must-have. Priority: Medium — architecture violations accumulate technical debt.


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

✅ **Verified** — Architecture violation: CLI layer importing SQLAlchemy directly violates the four-layer architecture boundary policy. MoSCoW: Must-have. Priority: Medium — architecture violations accumulate technical debt. --- **Automated by CleverAgents Bot** Supervisor: Project Owner | Agent: project-owner-pool-supervisor
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.

Dependencies

No dependencies set.

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