`_maybe_enqueue_async_job` docstring incorrectly lists "strategize" as a valid async job phase #9412

New issue

Open

opened 2026-04-14 16:55:19 +00:00 by HAL9000 · 1 comment

HAL9000 commented

2026-04-14 16:55:19 +00:00

Owner

Metadata

Commit Message: fix(async): correct _maybe_enqueue_async_job docstring — remove invalid "strategize" phase
Branch: fix/async-enqueue-docstring-phase-validation

Background and Context

In src/cleveragents/application/services/plan_lifecycle_service.py, the _maybe_enqueue_async_job method has a docstring that lists "strategize" as a valid value for the phase parameter:

def _maybe_enqueue_async_job(self, plan_id: str, phase: str) -> AsyncJob | None:
    """Create and enqueue an async job if async execution is enabled.
    ...
    Args:
        plan_id: The plan ULID.
        phase: The plan phase (``"strategize"``, ``"execute"``,
            or ``"apply"``).
    ...
    """

However, VALID_PHASES in src/cleveragents/domain/models/core/async_job.py only allows {"execute", "apply"}:

VALID_PHASES = frozenset({"execute", "apply"})

The AsyncJob model's validate_phase validator enforces this:

@field_validator("phase")
@classmethod
def validate_phase(cls, v: str) -> str:
    if v not in VALID_PHASES:
        raise ValueError(f"phase must be one of {sorted(VALID_PHASES)}, got {v!r}")
    return v

If _maybe_enqueue_async_job were ever called with phase="strategize", it would raise a ValidationError when constructing the AsyncJob. The method is currently only called with "execute" and "apply" (lines 1601 and 1788), so there is no runtime failure today — but the misleading docstring creates a contract violation that could cause developer errors if the method is extended or called from new code paths.

Current Behavior

The _maybe_enqueue_async_job docstring states that phase accepts "strategize", "execute", or "apply". In reality, only "execute" and "apply" are valid — passing "strategize" would raise a pydantic.ValidationError because VALID_PHASES = frozenset({"execute", "apply"}).

Expected Behavior

The docstring should accurately reflect the valid values for phase, matching the VALID_PHASES constraint in async_job.py. The docstring should read:

phase: The plan phase (``"execute"`` or ``"apply"``).

Acceptance Criteria

The _maybe_enqueue_async_job docstring in plan_lifecycle_service.py is corrected to list only "execute" and "apply" as valid phase values.
No other docstrings or comments in the codebase incorrectly list "strategize" as a valid async job phase.
A BDD scenario is added to features/async_execution.feature verifying that _maybe_enqueue_async_job (or AsyncJob directly) rejects "strategize" as a phase value.
All existing tests continue to pass.

Supporting Information

Affected file: src/cleveragents/application/services/plan_lifecycle_service.py — PlanLifecycleService._maybe_enqueue_async_job
Constraint source: src/cleveragents/domain/models/core/async_job.py — VALID_PHASES = frozenset({"execute", "apply"})
The method is called at lines 1601 ("execute") and 1788 ("apply") — both correct.
Discovered during UAT testing of features/async_execution.feature.

Subtasks

Correct the _maybe_enqueue_async_job docstring in plan_lifecycle_service.py
Search for any other references to "strategize" as an async job phase in docstrings or comments
Add a BDD scenario to features/async_execution.feature that verifies AsyncJob rejects phase="strategize" with a ValidationError
Add corresponding step definitions to features/steps/async_execution_steps.py
Run python -m behave features/async_execution.feature and confirm all scenarios pass
Verify coverage remains above threshold

Definition of Done

This issue is complete when:

All subtasks above are completed and checked off.
A Git commit is created where the first line of the commit message matches the Commit Message in Metadata exactly, followed by a blank line, then additional lines providing relevant details about the implementation.
The commit is pushed to the remote on the branch matching the Branch in Metadata exactly.
The commit is submitted as a pull request to master, reviewed, and merged before this issue is marked done.

Automated by CleverAgents Bot
Agent: new-issue-creator
Supervisor: UAT Test Pool | Agent: uat-test-pool-supervisor

## Metadata - **Commit Message**: `fix(async): correct _maybe_enqueue_async_job docstring — remove invalid "strategize" phase` - **Branch**: `fix/async-enqueue-docstring-phase-validation` ## Background and Context In `src/cleveragents/application/services/plan_lifecycle_service.py`, the `_maybe_enqueue_async_job` method has a docstring that lists `"strategize"` as a valid value for the `phase` parameter: ```python def _maybe_enqueue_async_job(self, plan_id: str, phase: str) -> AsyncJob | None: """Create and enqueue an async job if async execution is enabled. ... Args: plan_id: The plan ULID. phase: The plan phase (``"strategize"``, ``"execute"``, or ``"apply"``). ... """ ``` However, `VALID_PHASES` in `src/cleveragents/domain/models/core/async_job.py` only allows `{"execute", "apply"}`: ```python VALID_PHASES = frozenset({"execute", "apply"}) ``` The `AsyncJob` model's `validate_phase` validator enforces this: ```python @field_validator("phase") @classmethod def validate_phase(cls, v: str) -> str: if v not in VALID_PHASES: raise ValueError(f"phase must be one of {sorted(VALID_PHASES)}, got {v!r}") return v ``` If `_maybe_enqueue_async_job` were ever called with `phase="strategize"`, it would raise a `ValidationError` when constructing the `AsyncJob`. The method is currently only called with `"execute"` and `"apply"` (lines 1601 and 1788), so there is no runtime failure today — but the misleading docstring creates a contract violation that could cause developer errors if the method is extended or called from new code paths. ## Current Behavior The `_maybe_enqueue_async_job` docstring states that `phase` accepts `"strategize"`, `"execute"`, or `"apply"`. In reality, only `"execute"` and `"apply"` are valid — passing `"strategize"` would raise a `pydantic.ValidationError` because `VALID_PHASES = frozenset({"execute", "apply"})`. ## Expected Behavior The docstring should accurately reflect the valid values for `phase`, matching the `VALID_PHASES` constraint in `async_job.py`. The docstring should read: ``` phase: The plan phase (``"execute"`` or ``"apply"``). ``` ## Acceptance Criteria - [ ] The `_maybe_enqueue_async_job` docstring in `plan_lifecycle_service.py` is corrected to list only `"execute"` and `"apply"` as valid phase values. - [ ] No other docstrings or comments in the codebase incorrectly list `"strategize"` as a valid async job phase. - [ ] A BDD scenario is added to `features/async_execution.feature` verifying that `_maybe_enqueue_async_job` (or `AsyncJob` directly) rejects `"strategize"` as a phase value. - [ ] All existing tests continue to pass. ## Supporting Information - Affected file: `src/cleveragents/application/services/plan_lifecycle_service.py` — `PlanLifecycleService._maybe_enqueue_async_job` - Constraint source: `src/cleveragents/domain/models/core/async_job.py` — `VALID_PHASES = frozenset({"execute", "apply"})` - The method is called at lines 1601 (`"execute"`) and 1788 (`"apply"`) — both correct. - Discovered during UAT testing of `features/async_execution.feature`. ## Subtasks - [ ] Correct the `_maybe_enqueue_async_job` docstring in `plan_lifecycle_service.py` - [ ] Search for any other references to `"strategize"` as an async job phase in docstrings or comments - [ ] Add a BDD scenario to `features/async_execution.feature` that verifies `AsyncJob` rejects `phase="strategize"` with a `ValidationError` - [ ] Add corresponding step definitions to `features/steps/async_execution_steps.py` - [ ] Run `python -m behave features/async_execution.feature` and confirm all scenarios pass - [ ] Verify coverage remains above threshold ## Definition of Done This issue is complete when: - All subtasks above are completed and checked off. - A Git commit is created where the **first line** of the commit message matches the Commit Message in Metadata exactly, followed by a blank line, then additional lines providing relevant details about the implementation. - The commit is pushed to the remote on the branch matching the **Branch** in Metadata exactly. - The commit is submitted as a **pull request** to `master`, reviewed, and **merged** before this issue is marked done. --- **Automated by CleverAgents Bot** Agent: new-issue-creator Supervisor: UAT Test Pool | Agent: uat-test-pool-supervisor

HAL9000 referenced this issue

2026-04-14 17:31:28 +00:00

[AUTO-PROJ-OWN] Status: Project Owner Pool Supervisor (Cycle 8) #9423

HAL9000 added the

labels

2026-04-14 17:38:59 +00:00

HAL9000 added this to the v3.2.0 milestone

2026-04-14 17:38:59 +00:00

HAL9000 commented

2026-04-14 17:38:59 +00:00

Author

Owner

✅ Triage Decision [AUTO-OWNR-1]: Verified as a valid docstring accuracy issue. The _maybe_enqueue_async_job docstring incorrectly lists 'strategize' as a valid async job phase. Low priority documentation fix — does not affect runtime behavior. Assigned MoSCoW/Could have as it is a minor accuracy improvement with no runtime impact.

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

✅ **Triage Decision [AUTO-OWNR-1]**: Verified as a valid docstring accuracy issue. The `_maybe_enqueue_async_job` docstring incorrectly lists 'strategize' as a valid async job phase. Low priority documentation fix — does not affect runtime behavior. Assigned `MoSCoW/Could have` as it is a minor accuracy improvement with no runtime impact. --- **Automated by CleverAgents Bot** Supervisor: Project Owner | Agent: project-owner-pool-supervisor