cleveragents/cleveragents-core

Fork 3

UAT: Domain layer missing repository Protocol interfaces — ADR-019 architectural violation #1762

New issue

Open

opened 2026-04-02 23:45:07 +00:00 by freemo · 2 comments

freemo commented

2026-04-02 23:45:07 +00:00

Owner

Metadata

Branch: fix/domain-repository-protocols
Commit Message: fix(domain): add repository Protocol interfaces to domain layer
Milestone: v3.7.0
Parent Epic: N/A — no suitable parent Epic exists; linked to v3.7.0 milestone per instructions

Background and Context

The specification (ADR-019: Storage and Persistence) explicitly requires that the Domain Layer defines repository interfaces as Protocol classes. The Infrastructure Layer should then provide concrete implementations that satisfy these protocols. This is the core of the Hexagonal Architecture (Ports and Adapters) pattern described in the spec.

What was tested: Code-level analysis of the domain layer (src/cleveragents/domain/) for repository Protocol interface definitions.

Expected Behavior (from spec)

Per ADR-019 and the specification's Architecture Overview section:

"Domain Layer defines repository interfaces as Protocol classes (e.g., PlanRepository, DecisionRepository, ResourceRepository). Infrastructure Layer provides concrete implementations (e.g., SQLAlchemyPlanRepository, SQLAlchemyDecisionRepository)."

The src/cleveragents/domain/__init__.py even documents this intent:

"""Domain Layer - Core Business Models and Rules.
...
- Repository interfaces (not implementations)
...
"""

Current (Actual) Behavior

No repository Protocol interfaces exist anywhere in the domain layer (src/cleveragents/domain/). The concrete repository implementations in src/cleveragents/infrastructure/database/repositories.py are standalone classes with no Protocol interface to implement.

Verified by searching all domain layer files:

find src/cleveragents/domain -name "*.py" -exec grep -l "class.*Repository\|PlanRepository\|DecisionRepository\|ResourceRepository" {} \;
# Returns: no results

Impact

Application layer services import concrete infrastructure implementations directly (bypassing the domain protocol layer), creating tight coupling between application and infrastructure layers.
The DI container cannot swap implementations (e.g., SQLite → PostgreSQL, or real → mock) without changing application code.
The architectural constraint "Domain Layer code must never import SQLAlchemy or reference database tables" cannot be enforced via type checking since there are no Protocol interfaces to type against.
Testing with mock repositories is harder because there's no Protocol to implement.

Code Locations

Missing: src/cleveragents/domain/ — no repository Protocol interfaces
Existing (should implement protocols): src/cleveragents/infrastructure/database/repositories.py
Violating (imports concrete implementations): src/cleveragents/application/services/automation_profile_service.py, checkpoint_service.py, execute_phase_context_assembler.py, session_service.py, skill_registry_service.py, tool_registry_service.py

Steps to Reproduce

find src/cleveragents/domain -name "*.py" | xargs grep -l "class.*Repository" 2>/dev/null
# Expected: files with Protocol-based repository interfaces
# Actual: no output (no repository interfaces in domain layer)

Subtasks

Audit all concrete repository classes in src/cleveragents/infrastructure/database/repositories.py to identify the full set of required Protocol interfaces
Create src/cleveragents/domain/repositories.py (or equivalent) with Protocol classes for each repository (e.g., PlanRepository, DecisionRepository, ResourceRepository, etc.)
Ensure each Protocol interface defines the full public API required by the application layer services
Update src/cleveragents/infrastructure/database/repositories.py concrete classes to explicitly satisfy the domain Protocol interfaces (structural subtyping via Protocol)
Update all application layer services (automation_profile_service.py, checkpoint_service.py, execute_phase_context_assembler.py, session_service.py, skill_registry_service.py, tool_registry_service.py) to type-hint against the domain Protocol interfaces instead of concrete infrastructure classes
Update src/cleveragents/domain/__init__.py to export the new Protocol interfaces
Tests (Behave): Add scenarios verifying domain layer contains repository Protocol interfaces and does not import SQLAlchemy
Tests (Behave): Add scenarios verifying infrastructure repositories satisfy domain Protocol interfaces
Tests (Robot): Add integration tests verifying DI container can swap repository implementations
Verify nox -s typecheck passes with no type: ignore suppressions
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.
src/cleveragents/domain/ contains Protocol class definitions for all repository interfaces required by the application layer.
All concrete infrastructure repository classes structurally satisfy the domain Protocol interfaces.
All application layer services type-hint against domain Protocol interfaces, not concrete infrastructure classes.
The domain layer contains zero imports of SQLAlchemy or any infrastructure-layer module.
A Git commit is created where the first line of the commit message matches the Commit Message in Metadata exactly (fix(domain): add repository Protocol interfaces to domain layer), followed by a blank line, then additional lines providing relevant details about the implementation.
The commit is pushed to the remote on the branch fix/domain-repository-protocols.
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/domain-repository-protocols` - **Commit Message**: `fix(domain): add repository Protocol interfaces to domain layer` - **Milestone**: v3.7.0 - **Parent Epic**: N/A — no suitable parent Epic exists; linked to v3.7.0 milestone per instructions ## Background and Context The specification (ADR-019: Storage and Persistence) explicitly requires that the Domain Layer defines repository interfaces as `Protocol` classes. The Infrastructure Layer should then provide concrete implementations that satisfy these protocols. This is the core of the Hexagonal Architecture (Ports and Adapters) pattern described in the spec. **What was tested**: Code-level analysis of the domain layer (`src/cleveragents/domain/`) for repository Protocol interface definitions. ## Expected Behavior (from spec) Per ADR-019 and the specification's Architecture Overview section: > "Domain Layer defines repository interfaces as `Protocol` classes (e.g., `PlanRepository`, `DecisionRepository`, `ResourceRepository`). Infrastructure Layer provides concrete implementations (e.g., `SQLAlchemyPlanRepository`, `SQLAlchemyDecisionRepository`)." The `src/cleveragents/domain/__init__.py` even documents this intent: ```python """Domain Layer - Core Business Models and Rules. ... - Repository interfaces (not implementations) ... """ ``` ## Current (Actual) Behavior No repository Protocol interfaces exist anywhere in the domain layer (`src/cleveragents/domain/`). The concrete repository implementations in `src/cleveragents/infrastructure/database/repositories.py` are standalone classes with no Protocol interface to implement. Verified by searching all domain layer files: ```bash find src/cleveragents/domain -name "*.py" -exec grep -l "class.*Repository\|PlanRepository\|DecisionRepository\|ResourceRepository" {} \; # Returns: no results ``` ## Impact 1. Application layer services import concrete infrastructure implementations directly (bypassing the domain protocol layer), creating tight coupling between application and infrastructure layers. 2. The DI container cannot swap implementations (e.g., SQLite → PostgreSQL, or real → mock) without changing application code. 3. The architectural constraint "Domain Layer code must never import SQLAlchemy or reference database tables" cannot be enforced via type checking since there are no Protocol interfaces to type against. 4. Testing with mock repositories is harder because there's no Protocol to implement. ## Code Locations - **Missing**: `src/cleveragents/domain/` — no repository Protocol interfaces - **Existing (should implement protocols)**: `src/cleveragents/infrastructure/database/repositories.py` - **Violating (imports concrete implementations)**: `src/cleveragents/application/services/automation_profile_service.py`, `checkpoint_service.py`, `execute_phase_context_assembler.py`, `session_service.py`, `skill_registry_service.py`, `tool_registry_service.py` ## Steps to Reproduce ```bash find src/cleveragents/domain -name "*.py" | xargs grep -l "class.*Repository" 2>/dev/null # Expected: files with Protocol-based repository interfaces # Actual: no output (no repository interfaces in domain layer) ``` ## Subtasks - [ ] Audit all concrete repository classes in `src/cleveragents/infrastructure/database/repositories.py` to identify the full set of required Protocol interfaces - [ ] Create `src/cleveragents/domain/repositories.py` (or equivalent) with `Protocol` classes for each repository (e.g., `PlanRepository`, `DecisionRepository`, `ResourceRepository`, etc.) - [ ] Ensure each Protocol interface defines the full public API required by the application layer services - [ ] Update `src/cleveragents/infrastructure/database/repositories.py` concrete classes to explicitly satisfy the domain Protocol interfaces (structural subtyping via `Protocol`) - [ ] Update all application layer services (`automation_profile_service.py`, `checkpoint_service.py`, `execute_phase_context_assembler.py`, `session_service.py`, `skill_registry_service.py`, `tool_registry_service.py`) to type-hint against the domain Protocol interfaces instead of concrete infrastructure classes - [ ] Update `src/cleveragents/domain/__init__.py` to export the new Protocol interfaces - [ ] Tests (Behave): Add scenarios verifying domain layer contains repository Protocol interfaces and does not import SQLAlchemy - [ ] Tests (Behave): Add scenarios verifying infrastructure repositories satisfy domain Protocol interfaces - [ ] Tests (Robot): Add integration tests verifying DI container can swap repository implementations - [ ] Verify `nox -s typecheck` passes with no `type: ignore` suppressions - [ ] 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. - `src/cleveragents/domain/` contains `Protocol` class definitions for all repository interfaces required by the application layer. - All concrete infrastructure repository classes structurally satisfy the domain Protocol interfaces. - All application layer services type-hint against domain Protocol interfaces, not concrete infrastructure classes. - The domain layer contains zero imports of SQLAlchemy or any infrastructure-layer module. - A Git commit is created where the **first line** of the commit message matches the Commit Message in Metadata exactly (`fix(domain): add repository Protocol interfaces to domain layer`), followed by a blank line, then additional lines providing relevant details about the implementation. - The commit is pushed to the remote on the branch `fix/domain-repository-protocols`. - 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.7.0 milestone

2026-04-02 23:45:19 +00:00

freemo commented

2026-04-02 23:46:48 +00:00

Author

Owner

⚠️ Orphan Issue — Manual Linking Required

This issue was created without a parent Epic because no suitable Epic currently exists in the repository for domain layer architectural violations or Hexagonal Architecture (Ports and Adapters) compliance.

The only open Epic at time of creation was:

#1678 — Epic: CI Execution Time Optimization (unrelated scope)

Action required by a maintainer: Please either:

Create a new Epic for "Domain Layer Architectural Compliance" (or similar) and link this issue as a child (this issue blocks the parent Epic), OR
Link this issue to an existing appropriate Epic if one is created in the future.

Per CONTRIBUTING.md, all non-Epic issues must be linked to a parent Epic. This issue is flagged as an orphan until that link is established.

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

⚠️ **Orphan Issue — Manual Linking Required** This issue was created without a parent Epic because no suitable Epic currently exists in the repository for domain layer architectural violations or Hexagonal Architecture (Ports and Adapters) compliance. The only open Epic at time of creation was: - #1678 — Epic: CI Execution Time Optimization (unrelated scope) **Action required by a maintainer:** Please either: 1. Create a new Epic for "Domain Layer Architectural Compliance" (or similar) and link this issue as a child (this issue **blocks** the parent Epic), OR 2. Link this issue to an existing appropriate Epic if one is created in the future. Per CONTRIBUTING.md, all non-Epic issues must be linked to a parent Epic. This issue is flagged as an orphan until that link is established. --- **Automated by CleverAgents Bot** Supervisor: UAT Testing | Agent: ca-new-issue-creator

freemo referenced this issue

2026-04-02 23:48:06 +00:00

[UAT-SUPERVISOR] Progress Report — Cycle 451 — v3.7.0 #1778

freemo commented

2026-04-02 23:51:11 +00:00

Author

Owner

Issue triaged by project owner:

State: Verified
MoSCoW: MoSCoW/Should Have — bug or spec compliance issue.

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

Issue triaged by project owner: - **State**: Verified - **MoSCoW**: MoSCoW/Should Have — bug or spec compliance issue. --- **Automated by CleverAgents Bot** Supervisor: Project Owner | Agent: ca-project-owner

freemo referenced this issue

2026-04-03 04:10:19 +00:00

[Milestone Review] v3.7.0 — Holistic Integration Review (2026-04-03) #2113