UAT: domain/models/init.py exports only legacy models — spec-required domain entities missing from public API #3417

New issue

Open

opened 2026-04-05 16:36:56 +00:00 by freemo · 0 comments

freemo commented

2026-04-05 16:36:56 +00:00

Owner

Metadata

Branch: fix/domain-models-init-missing-exports
Commit Message: fix(domain): add missing spec-required domain entity exports to domain/models/__init__.py
Milestone: None (backlog — see note below)
Parent Epic: #946

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

Background

The file src/cleveragents/domain/models/__init__.py is the public API surface for the domain models layer. Currently it only exports a small set of legacy models:

# Current exports in domain/models/__init__.py:
from .core import (
    Change, ChangeSet, Context, ContextFile, ContextType, ContextUpdateResult,
    Operation, OperationType, Plan, PlanBuild, PlanResult, PlanStatus,
    Project, ProjectSettings, ProjectStats, SummaryForUpdateContextParams,
)

The spec (docs/specification.md line 43866) identifies the following as the primary domain entities: Plan, Decision, Action, Resource, Actor, Tool, Skill, Session, Invariant, AutomationProfile, Checkpoint, CorrectionAttempt. None of these (except the legacy Plan and Project) are exported from domain/models/__init__.py.

Note: domain/models/core/__init__.py does export all of these correctly. The gap is that domain/models/__init__.py does not re-export them, making the public API surface incomplete.

Missing Exports

The following symbols are present in domain/models/core/__init__.py but absent from domain/models/__init__.py:

Symbol(s)	Source module
`Decision`	`domain/models/core/decision.py`
`Action`, `ActionState`, `ActionArgument`	`domain/models/core/action.py`
`Resource`, `ResourceCapabilities`, `PhysVirt`, `SandboxStrategy`	`domain/models/core/resource.py`
`Actor`	`domain/models/core/actor.py`
`Tool`, `Validation`, `ToolCapability`, `ResourceSlot`	`domain/models/core/tool.py`
`Skill`	`domain/models/core/skill.py`
`Session`, `SessionMessage`, `MessageRole`	`domain/models/core/session.py`
`Invariant`, `InvariantScope`, `InvariantSet`	`domain/models/core/invariant.py`
`AutomationProfile`	`domain/models/core/automation_profile.py`
`SafetyProfile`	`domain/models/core/safety_profile.py`
`Checkpoint`	`domain/models/core/checkpoint.py`
`CorrectionAttempt`	`domain/models/core/correction.py`
`NamespacedProject`, `LinkedResource`	`domain/models/core/project.py`
`LifecyclePlan`	`domain/models/core/plan.py`

Steps to Reproduce

Open src/cleveragents/domain/models/__init__.py
Observe that Decision, Session, Resource, Actor, Invariant, AutomationProfile, SafetyProfile, Action, Tool, Skill, Checkpoint, CorrectionAttempt are not exported
Compare with domain/models/core/__init__.py which exports all of these correctly

Expected: domain/models/__init__.py exports all spec-required primary domain entities
Actual: domain/models/__init__.py only exports legacy Plan, Project, and a few utility models

Impact

External consumers importing from cleveragents.domain.models cannot access the primary domain entities without knowing to import from the deeper cleveragents.domain.models.core path. This violates the principle of a clean public API surface and contradicts the spec's definition of primary domain entities.

Subtasks

Audit domain/models/core/__init__.py to enumerate all currently exported symbols
Update domain/models/__init__.py to re-export all spec-required primary domain entities from domain/models/core
Update __all__ in domain/models/__init__.py to include all newly re-exported symbols
Verify no circular imports are introduced by the new re-exports
Add/update Behave unit test scenarios covering the public API surface of domain/models/__init__.py
Run nox -e typecheck to confirm Pyright passes with no errors
Run nox -e lint to confirm linting passes
Run nox -e unit_tests to confirm all unit tests pass
Run nox -e coverage_report to confirm coverage remains ≥ 97%

Definition of Done

domain/models/__init__.py exports all spec-required primary domain entities listed in the table above
__all__ in domain/models/__init__.py is complete and accurate
No circular imports introduced
Behave unit tests cover the updated public API surface
PR is linked to this issue and to parent Epic #946
All nox stages pass
Coverage >= 97%

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

## Metadata - **Branch**: `fix/domain-models-init-missing-exports` - **Commit Message**: `fix(domain): add missing spec-required domain entity exports to domain/models/__init__.py` - **Milestone**: None (backlog — see note below) - **Parent Epic**: #946 > **Backlog note:** This issue was discovered during autonomous operation > on milestone v3.6.0. It does not block milestone completion and has been > placed in the backlog for human review and future milestone assignment. ## Background The file `src/cleveragents/domain/models/__init__.py` is the public API surface for the domain models layer. Currently it only exports a small set of legacy models: ```python # Current exports in domain/models/__init__.py: from .core import ( Change, ChangeSet, Context, ContextFile, ContextType, ContextUpdateResult, Operation, OperationType, Plan, PlanBuild, PlanResult, PlanStatus, Project, ProjectSettings, ProjectStats, SummaryForUpdateContextParams, ) ``` The spec (`docs/specification.md` line 43866) identifies the following as the primary domain entities: `Plan, Decision, Action, Resource, Actor, Tool, Skill, Session, Invariant, AutomationProfile, Checkpoint, CorrectionAttempt`. None of these (except the legacy `Plan` and `Project`) are exported from `domain/models/__init__.py`. **Note:** `domain/models/core/__init__.py` does export all of these correctly. The gap is that `domain/models/__init__.py` does not re-export them, making the public API surface incomplete. ## Missing Exports The following symbols are present in `domain/models/core/__init__.py` but absent from `domain/models/__init__.py`: | Symbol(s) | Source module | |---|---| | `Decision` | `domain/models/core/decision.py` | | `Action`, `ActionState`, `ActionArgument` | `domain/models/core/action.py` | | `Resource`, `ResourceCapabilities`, `PhysVirt`, `SandboxStrategy` | `domain/models/core/resource.py` | | `Actor` | `domain/models/core/actor.py` | | `Tool`, `Validation`, `ToolCapability`, `ResourceSlot` | `domain/models/core/tool.py` | | `Skill` | `domain/models/core/skill.py` | | `Session`, `SessionMessage`, `MessageRole` | `domain/models/core/session.py` | | `Invariant`, `InvariantScope`, `InvariantSet` | `domain/models/core/invariant.py` | | `AutomationProfile` | `domain/models/core/automation_profile.py` | | `SafetyProfile` | `domain/models/core/safety_profile.py` | | `Checkpoint` | `domain/models/core/checkpoint.py` | | `CorrectionAttempt` | `domain/models/core/correction.py` | | `NamespacedProject`, `LinkedResource` | `domain/models/core/project.py` | | `LifecyclePlan` | `domain/models/core/plan.py` | ## Steps to Reproduce 1. Open `src/cleveragents/domain/models/__init__.py` 2. Observe that `Decision`, `Session`, `Resource`, `Actor`, `Invariant`, `AutomationProfile`, `SafetyProfile`, `Action`, `Tool`, `Skill`, `Checkpoint`, `CorrectionAttempt` are not exported 3. Compare with `domain/models/core/__init__.py` which exports all of these correctly **Expected:** `domain/models/__init__.py` exports all spec-required primary domain entities **Actual:** `domain/models/__init__.py` only exports legacy `Plan`, `Project`, and a few utility models ## Impact External consumers importing from `cleveragents.domain.models` cannot access the primary domain entities without knowing to import from the deeper `cleveragents.domain.models.core` path. This violates the principle of a clean public API surface and contradicts the spec's definition of primary domain entities. ## Subtasks - [ ] Audit `domain/models/core/__init__.py` to enumerate all currently exported symbols - [ ] Update `domain/models/__init__.py` to re-export all spec-required primary domain entities from `domain/models/core` - [ ] Update `__all__` in `domain/models/__init__.py` to include all newly re-exported symbols - [ ] Verify no circular imports are introduced by the new re-exports - [ ] Add/update Behave unit test scenarios covering the public API surface of `domain/models/__init__.py` - [ ] Run `nox -e typecheck` to confirm Pyright passes with no errors - [ ] Run `nox -e lint` to confirm linting passes - [ ] Run `nox -e unit_tests` to confirm all unit tests pass - [ ] Run `nox -e coverage_report` to confirm coverage remains ≥ 97% ## Definition of Done - [ ] `domain/models/__init__.py` exports all spec-required primary domain entities listed in the table above - [ ] `__all__` in `domain/models/__init__.py` is complete and accurate - [ ] No circular imports introduced - [ ] Behave unit tests cover the updated public API surface - [ ] PR is linked to this issue and to parent Epic #946 - [ ] 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 16:37:09 +00:00

#946 Epic: Stub Package Cleanup — Remove Ghost Packages and Empty Stub Modules

freemo referenced this issue

2026-04-05 16:39:14 +00:00

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

freemo referenced this issue

2026-04-05 16:43:07 +00:00

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

freemo referenced this issue

2026-04-05 16:44:25 +00:00

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