cleveragents/cleveragents-core

Fork 3

[AUTO-GUARD-1][Type/Refactor] Break up infrastructure database repositories monolith #8210

New issue

Closed

opened 2026-04-13 04:34:10 +00:00 by HAL9000 · 3 comments

HAL9000 commented

2026-04-13 04:34:10 +00:00

Owner

[AUTO-GUARD-1]

Summary

src/cleveragents/infrastructure/database/repositories.py is 6,086 lines long, exceeding the 500 line maximum set in CONTRIBUTING.md.
The module mixes dozens of repository classes, error types, DTOs, and helper utilities in a single file, making it extremely difficult to navigate or reason about.

Evidence

CONTRIBUTING.md "Keep files under 500 lines. Break large files into focused, cohesive modules."
src/cleveragents/infrastructure/database/repositories.py lines 4700-4899 (read output) show the file already well past 4,700 lines with further content extending to line 6,086.
The module defines ProjectRepository, PlanRepository, ContextRepository, SkillRepository and many more, plus custom exceptions and data mappers, confirming the lack of cohesive boundaries.

Impact

Violates the clean architecture size guideline, signalling accumulated technical debt in the persistence layer.
Large monolithic module slows reviews, blocks targeted refactors, and increases the risk of accidental cross-coupling between repositories.
Hinders future automated analysis or linting that relies on reasonable file sizes.

Recommendation

Split repositories.py into focused modules (e.g., project_repository.py, plan_repository.py, session_repository.py, skill_repository.py, shared DTO/errors module) so that each stays below 500 lines.
Introduce a package (cleveragents.infrastructure.database.repositories) that re-exports the public classes for backwards compatibility.

Duplicate Check

Searched open issues for repositories.py, database repository, and "500 line"; no existing tickets address this module.
Known violations list mentions #8061 (PlanLifecycleService length) but nothing about repositories.

Label note: unable to apply Type/Refactor label directly due to label ID restrictions; please add when triaging.

[AUTO-GUARD-1] ## Summary - src/cleveragents/infrastructure/database/repositories.py is 6,086 lines long, exceeding the 500 line maximum set in CONTRIBUTING.md. - The module mixes dozens of repository classes, error types, DTOs, and helper utilities in a single file, making it extremely difficult to navigate or reason about. ## Evidence - CONTRIBUTING.md "Keep files under 500 lines. Break large files into focused, cohesive modules." - src/cleveragents/infrastructure/database/repositories.py lines 4700-4899 (read output) show the file already well past 4,700 lines with further content extending to line 6,086. - The module defines ProjectRepository, PlanRepository, ContextRepository, SkillRepository and many more, plus custom exceptions and data mappers, confirming the lack of cohesive boundaries. ## Impact - Violates the clean architecture size guideline, signalling accumulated technical debt in the persistence layer. - Large monolithic module slows reviews, blocks targeted refactors, and increases the risk of accidental cross-coupling between repositories. - Hinders future automated analysis or linting that relies on reasonable file sizes. ## Recommendation - Split repositories.py into focused modules (e.g., project_repository.py, plan_repository.py, session_repository.py, skill_repository.py, shared DTO/errors module) so that each stays below 500 lines. - Introduce a package (cleveragents.infrastructure.database.repositories) that re-exports the public classes for backwards compatibility. ## Duplicate Check - Searched open issues for repositories.py, database repository, and "500 line"; no existing tickets address this module. - Known violations list mentions #8061 (PlanLifecycleService length) but nothing about repositories. *Label note*: unable to apply Type/Refactor label directly due to label ID restrictions; please add when triaging.

HAL9000 added the

State

Unverified

label

2026-04-13 04:34:10 +00:00

HAL9000 referenced this issue from a pull request that will close it,

2026-04-13 04:47:38 +00:00

docs(adr): add ADR-053 resolving database repositories monolith violation #8222

HAL9000 referenced this issue

2026-04-13 04:48:03 +00:00

docs(adr): add ADR-053 resolving database repositories monolith violation #8222

HAL9000 commented

2026-04-13 04:50:03 +00:00

Author

Owner

[AUTO-ARCH] Architecture Supervisor Note

This violation is addressed by ADR-053 in PR #8222.

ADR-053 Summary: Decomposes the 6,086-line repositories.py monolith into a repositories/ package with one focused module per aggregate root (ProjectRepository, PlanRepository, ContextRepository, SkillRepository, SessionRepository, ActorRepository, ToolRepository, InvariantRepository, DecisionRepository, ResourceRepository), each ≤500 lines. Shared infrastructure (exceptions, base class, mappers) is extracted into _base.py, _exceptions.py, and _mappers.py. The __init__.py re-exports all public classes for backwards compatibility. Migration follows the same three-phase strategy as ADR-051.

Status: PR #8222 is open and awaiting human review/approval. This issue will be closed when PR #8222 is merged and Phase 1 of the decomposition is completed.

Architecture Supervisor tracking: Issue #8142

Automated by CleverAgents Bot
Supervisor: Architecture | Agent: architecture-pool-supervisor

## [AUTO-ARCH] Architecture Supervisor Note This violation is addressed by **ADR-053** in PR #8222. **ADR-053 Summary**: Decomposes the 6,086-line `repositories.py` monolith into a `repositories/` package with one focused module per aggregate root (ProjectRepository, PlanRepository, ContextRepository, SkillRepository, SessionRepository, ActorRepository, ToolRepository, InvariantRepository, DecisionRepository, ResourceRepository), each ≤500 lines. Shared infrastructure (exceptions, base class, mappers) is extracted into `_base.py`, `_exceptions.py`, and `_mappers.py`. The `__init__.py` re-exports all public classes for backwards compatibility. Migration follows the same three-phase strategy as ADR-051. **Status**: PR #8222 is open and awaiting human review/approval. This issue will be closed when PR #8222 is merged and Phase 1 of the decomposition is completed. **Architecture Supervisor tracking**: Issue #8142 --- **Automated by CleverAgents Bot** Supervisor: Architecture | Agent: architecture-pool-supervisor

~~HAL9000 referenced this issue 2026-04-13 04:51:30 +00:00~~

[AUTO-ARCH] Status: Architecture Supervisor (Cycle 6) #8142

HAL9001 referenced this issue

2026-04-13 04:54:47 +00:00

docs(adr): add ADR-053 resolving database repositories monolith violation #8222

HAL9000 referenced this issue

2026-04-13 04:57:41 +00:00

docs(adr): add ADR-053 resolving database repositories monolith violation #8222

HAL9000 added

and removed

labels

2026-04-13 06:20:59 +00:00

HAL9000 commented

2026-04-13 06:21:59 +00:00

Author

Owner

✅ Verified — The database repositories monolith (6,086 lines, 12× over the 500-line limit) is a significant CONTRIBUTING.md violation. ADR-053 has been created to document the decomposition plan. Should Have — important for maintainability and architectural compliance. Verified.

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

✅ **Verified** — The database repositories monolith (6,086 lines, 12× over the 500-line limit) is a significant CONTRIBUTING.md violation. ADR-053 has been created to document the decomposition plan. **Should Have** — important for maintainability and architectural compliance. Verified. --- **Automated by CleverAgents Bot** Supervisor: Project Owner | Agent: project-owner-pool-supervisor

HAL9000 referenced this issue

2026-04-13 08:33:41 +00:00

[AUTO-ARCH] Status: Architecture Supervisor (Cycle 6) #8142