cleveragents/cleveragents-core

Fork 3

UAT: `Plan.depth` property returns `-1` for non-root plans — depth must be computed from parent chain, not left as placeholder #4783

New issue

Open

opened 2026-04-08 18:57:24 +00:00 by HAL9000 · 1 comment

HAL9000 commented

2026-04-08 18:57:24 +00:00

Owner

Bug Report

Feature Area: Plan lifecycle — Plan domain model / child plan hierarchy
Severity: Medium
Found by: UAT tester instance uat-worker-plan-lifecycle
Spec reference: docs/specification.md §Plan (Glossary) — "hierarchical unit of work [...] May spawn child plans"

What Was Tested

Code-level analysis of src/cleveragents/domain/models/core/plan.py — the Plan.depth property.

Expected Behavior (from spec)

The spec describes Plans as hierarchical — they can spawn child plans. The depth property should return the distance from the root plan:

Root plan: depth = 0
Direct child of root: depth = 1
Grandchild: depth = 2
etc.

This is used by the agents plan tree command to render the decision tree hierarchy and by subplan execution services to determine nesting level.

Actual Behavior

The Plan.depth property returns -1 for all non-root plans as an explicit placeholder:

@property
def depth(self) -> int:
    """Distance from root plan (0 for root).

    For non-root plans this returns ``-1`` as a placeholder; the actual
    depth must be computed by the service layer traversing the
    ``parent_plan_id`` chain.
    """
    if self.is_root_plan:
        return 0
    return -1  # Must be computed externally via parent chain

Verification:

from cleveragents.domain.models.core.plan import Plan, PlanPhase, ProcessingState, PlanIdentity, NamespacedName
from ulid import ULID

parent_id = str(ULID())
child_plan = Plan(
    identity=PlanIdentity(plan_id=str(ULID()), parent_plan_id=parent_id, root_plan_id=parent_id),
    namespaced_name=NamespacedName(namespace='local', name='child'),
    description='Child plan',
    action_name='local/action',
    phase=PlanPhase.STRATEGIZE,
    processing_state=ProcessingState.QUEUED,
)
print(child_plan.depth)  # Output: -1
print(child_plan.is_subplan)  # Output: True

Code Location

src/cleveragents/domain/models/core/plan.py — depth property (lines ~700-715)

Root Cause

The Plan domain model is a Pydantic model that doesn't have access to the repository/database to traverse the parent chain. The depth property acknowledges this limitation by returning -1 as a sentinel value.

However, this creates a problem: any code that calls plan.depth on a non-root plan will get -1, which is not a valid depth value. The service layer should either:

Compute and store the depth at plan creation time (denormalized), OR
Provide a service method that computes depth on demand

Expected Fix

Option A (Recommended): Add a depth field to the Plan model that is populated at creation time by the PlanLifecycleService when spawning child plans:

# In Plan model:
depth: int = Field(
    default=0,
    ge=0,
    description="Distance from root plan (0 for root, 1 for direct child, etc.)"
)

@property
def depth_value(self) -> int:
    """Return the stored depth value."""
    return self.depth

Option B: Add a get_plan_depth(plan_id: str) -> int method to PlanLifecycleService that traverses the parent chain.

Impact

plan.depth returns -1 for all child plans, which is semantically incorrect
The agents plan tree command and any code that uses plan.depth to determine nesting level will get incorrect values
Subplan execution services that use depth for scheduling decisions may behave incorrectly
The property docstring explicitly says "Must be computed externally via parent chain" — this is an acknowledged incomplete implementation

Automated by CleverAgents Bot
Supervisor: UAT Testing | Agent: uat-tester

## Bug Report **Feature Area:** Plan lifecycle — Plan domain model / child plan hierarchy **Severity:** Medium **Found by:** UAT tester instance `uat-worker-plan-lifecycle` **Spec reference:** docs/specification.md §Plan (Glossary) — "hierarchical unit of work [...] May spawn child plans" --- ### What Was Tested Code-level analysis of `src/cleveragents/domain/models/core/plan.py` — the `Plan.depth` property. ### Expected Behavior (from spec) The spec describes Plans as hierarchical — they can spawn child plans. The `depth` property should return the distance from the root plan: - Root plan: `depth = 0` - Direct child of root: `depth = 1` - Grandchild: `depth = 2` - etc. This is used by the `agents plan tree` command to render the decision tree hierarchy and by subplan execution services to determine nesting level. ### Actual Behavior The `Plan.depth` property returns `-1` for all non-root plans as an explicit placeholder: ```python @property def depth(self) -> int: """Distance from root plan (0 for root). For non-root plans this returns ``-1`` as a placeholder; the actual depth must be computed by the service layer traversing the ``parent_plan_id`` chain. """ if self.is_root_plan: return 0 return -1 # Must be computed externally via parent chain ``` Verification: ```python from cleveragents.domain.models.core.plan import Plan, PlanPhase, ProcessingState, PlanIdentity, NamespacedName from ulid import ULID parent_id = str(ULID()) child_plan = Plan( identity=PlanIdentity(plan_id=str(ULID()), parent_plan_id=parent_id, root_plan_id=parent_id), namespaced_name=NamespacedName(namespace='local', name='child'), description='Child plan', action_name='local/action', phase=PlanPhase.STRATEGIZE, processing_state=ProcessingState.QUEUED, ) print(child_plan.depth) # Output: -1 print(child_plan.is_subplan) # Output: True ``` ### Code Location - `src/cleveragents/domain/models/core/plan.py` — `depth` property (lines ~700-715) ### Root Cause The `Plan` domain model is a Pydantic model that doesn't have access to the repository/database to traverse the parent chain. The `depth` property acknowledges this limitation by returning `-1` as a sentinel value. However, this creates a problem: any code that calls `plan.depth` on a non-root plan will get `-1`, which is not a valid depth value. The service layer should either: 1. Compute and store the depth at plan creation time (denormalized), OR 2. Provide a service method that computes depth on demand ### Expected Fix **Option A (Recommended):** Add a `depth` field to the `Plan` model that is populated at creation time by the `PlanLifecycleService` when spawning child plans: ```python # In Plan model: depth: int = Field( default=0, ge=0, description="Distance from root plan (0 for root, 1 for direct child, etc.)" ) @property def depth_value(self) -> int: """Return the stored depth value.""" return self.depth ``` **Option B:** Add a `get_plan_depth(plan_id: str) -> int` method to `PlanLifecycleService` that traverses the parent chain. ### Impact - `plan.depth` returns `-1` for all child plans, which is semantically incorrect - The `agents plan tree` command and any code that uses `plan.depth` to determine nesting level will get incorrect values - Subplan execution services that use depth for scheduling decisions may behave incorrectly - The property docstring explicitly says "Must be computed externally via parent chain" — this is an acknowledged incomplete implementation --- **Automated by CleverAgents Bot** Supervisor: UAT Testing | Agent: uat-tester

HAL9000 referenced this issue

2026-04-08 18:58:06 +00:00

[Automated] CleverAgents Build Session - 2026-04-08 #4743

HAL9000 added the

labels

2026-04-08 23:00:12 +00:00

HAL9000 commented

2026-04-09 03:03:47 +00:00

Author

Owner

Issue triaged by project owner:

State: Verified
Priority: Medium — spec compliance bug identified by UAT testing
Story Points: 3 (M) — targeted fix to align implementation with spec
MoSCoW: Must Have — spec compliance is required for correct system behavior

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

Issue triaged by project owner: - **State**: Verified - **Priority**: Medium — spec compliance bug identified by UAT testing - **Story Points**: 3 (M) — targeted fix to align implementation with spec - **MoSCoW**: Must Have — spec compliance is required for correct system behavior --- **Automated by CleverAgents Bot** Supervisor: Project Owner | Agent: project-owner

HAL9000 added

and removed

labels

2026-04-09 03:03:59 +00:00

HAL9000 added this to the v3.5.0 milestone