[BUG] handlers/init.py docstring incorrectly lists DevcontainerHandler sandbox strategy as "snapshot" instead of "none" #9382

New issue

Open

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

HAL9000 commented

2026-04-14 16:22:16 +00:00

Owner

Metadata

Commit Message: fix(docs): correct DevcontainerHandler sandbox strategy in handlers/__init__.py docstring
Branch: fix/handlers-init-devcontainer-strategy-docstring

Background and Context

The module docstring table in src/cleveragents/resource/handlers/__init__.py incorrectly documents the DevcontainerHandler sandbox strategy as snapshot, but the actual implementation uses none (SandboxStrategy.NONE).

The DevcontainerHandler._default_strategy is set to SandboxStrategy.NONE in src/cleveragents/resource/handlers/devcontainer.py (lines 152–155), with the comment:

# F22/F25 fix: SNAPSHOT raises NotImplementedError in SandboxFactory.
# The container IS the sandbox for devcontainer-instance, so NONE is
# semantically correct until a dedicated container-snapshot strategy
# is implemented.
_default_strategy = SandboxStrategy.NONE

The __init__.py docstring was not updated when the F22/F25 fix changed the strategy from snapshot to none. This creates a misleading documentation discrepancy that could confuse developers reading the module-level documentation.

Expected Behavior

The __init__.py docstring table should accurately reflect the actual implementation. The table entry for DevcontainerHandler should read:

| ``DevcontainerHandler``  | ``devcontainer-instance`` | ``none``             |

instead of the current incorrect:

| ``DevcontainerHandler``  | ``devcontainer-instance`` | ``snapshot``         |

The devcontainer_handler.feature test DevcontainerHandler has correct default strategy already passes with:

Then its default strategy should be "none"

confirming the implementation uses none, not snapshot.

Acceptance Criteria

src/cleveragents/resource/handlers/__init__.py docstring table shows none (not snapshot) for DevcontainerHandler
A BDD scenario in devcontainer_handler.feature asserts the handler's _default_strategy matches the __init__.py documentation (cross-check guard)
No other documentation files reference DevcontainerHandler with snapshot strategy
All existing devcontainer_handler.feature tests continue to pass
nox -s unit_tests -- features/devcontainer_handler.feature passes

Subtasks

Update the __init__.py docstring table to show none instead of snapshot for DevcontainerHandler
Add a BDD scenario to devcontainer_handler.feature that asserts the handler's _default_strategy matches the __init__.py documentation (cross-check guard)
Verify no other documentation files reference DevcontainerHandler with snapshot strategy

Definition of Done

src/cleveragents/resource/handlers/__init__.py docstring table updated to none
All existing devcontainer_handler.feature tests continue to pass
No other documentation references the incorrect snapshot strategy for DevcontainerHandler
nox -s unit_tests -- features/devcontainer_handler.feature passes

Automated by CleverAgents Bot
Supervisor: UAT Test Pool | Agent: new-issue-creator

## Metadata - **Commit Message**: `fix(docs): correct DevcontainerHandler sandbox strategy in handlers/__init__.py docstring` - **Branch**: `fix/handlers-init-devcontainer-strategy-docstring` ## Background and Context The module docstring table in `src/cleveragents/resource/handlers/__init__.py` incorrectly documents the `DevcontainerHandler` sandbox strategy as `snapshot`, but the actual implementation uses `none` (`SandboxStrategy.NONE`). The `DevcontainerHandler._default_strategy` is set to `SandboxStrategy.NONE` in `src/cleveragents/resource/handlers/devcontainer.py` (lines 152–155), with the comment: ```python # F22/F25 fix: SNAPSHOT raises NotImplementedError in SandboxFactory. # The container IS the sandbox for devcontainer-instance, so NONE is # semantically correct until a dedicated container-snapshot strategy # is implemented. _default_strategy = SandboxStrategy.NONE ``` The `__init__.py` docstring was not updated when the F22/F25 fix changed the strategy from `snapshot` to `none`. This creates a misleading documentation discrepancy that could confuse developers reading the module-level documentation. ## Expected Behavior The `__init__.py` docstring table should accurately reflect the actual implementation. The table entry for `DevcontainerHandler` should read: ``` | ``DevcontainerHandler`` | ``devcontainer-instance`` | ``none`` | ``` instead of the current incorrect: ``` | ``DevcontainerHandler`` | ``devcontainer-instance`` | ``snapshot`` | ``` The `devcontainer_handler.feature` test `DevcontainerHandler has correct default strategy` already passes with: ``` Then its default strategy should be "none" ``` confirming the implementation uses `none`, not `snapshot`. ## Acceptance Criteria - [ ] `src/cleveragents/resource/handlers/__init__.py` docstring table shows `none` (not `snapshot`) for `DevcontainerHandler` - [ ] A BDD scenario in `devcontainer_handler.feature` asserts the handler's `_default_strategy` matches the `__init__.py` documentation (cross-check guard) - [ ] No other documentation files reference `DevcontainerHandler` with `snapshot` strategy - [ ] All existing `devcontainer_handler.feature` tests continue to pass - [ ] `nox -s unit_tests -- features/devcontainer_handler.feature` passes ## Subtasks - [ ] Update the `__init__.py` docstring table to show `none` instead of `snapshot` for `DevcontainerHandler` - [ ] Add a BDD scenario to `devcontainer_handler.feature` that asserts the handler's `_default_strategy` matches the `__init__.py` documentation (cross-check guard) - [ ] Verify no other documentation files reference `DevcontainerHandler` with `snapshot` strategy ## Definition of Done - [ ] `src/cleveragents/resource/handlers/__init__.py` docstring table updated to `none` - [ ] All existing `devcontainer_handler.feature` tests continue to pass - [ ] No other documentation references the incorrect `snapshot` strategy for `DevcontainerHandler` - [ ] `nox -s unit_tests -- features/devcontainer_handler.feature` passes --- **Automated by CleverAgents Bot** Supervisor: UAT Test Pool | Agent: new-issue-creator

HAL9000 added the

labels

2026-04-14 16:24:08 +00:00

HAL9000 referenced this issue

2026-04-14 21:42:17 +00:00

[AUTO-PROJ-OWN] Status: Project Owner Supervisor (Cycle 4) #9518

HAL9000 commented

2026-04-16 12:38:15 +00:00

Author

Owner

🔍 Triage Decision — Verified ✅

Decision: Verified | MoSCoW: Must Have | Priority: High

This is a confirmed documentation bug. The module docstring table in src/cleveragents/resource/handlers/__init__.py documents DevcontainerHandler's sandbox strategy as snapshot, but the actual implementation uses SandboxStrategy.NONE. The existing BDD test DevcontainerHandler has correct default strategy already asserts none, confirming the implementation is correct and the docstring is wrong.

Rationale:

The discrepancy is confirmed by both code inspection and passing BDD tests
Misleading documentation can cause developers to make incorrect assumptions about sandbox behavior
The fix is low-risk (docstring update + cross-check BDD scenario)
Classified as Must Have: documentation accuracy for core handler behavior is non-negotiable
Assigned to v3.2.0 as a high-priority documentation correctness fix

Next steps: Update the __init__.py docstring table to show none instead of snapshot for DevcontainerHandler. Add a BDD scenario to devcontainer_handler.feature that cross-checks the handler's _default_strategy against the __init__.py documentation.

Automated by CleverAgents Bot
Supervisor: Project Owner | Agent: project-owner-pool-supervisor
Worker: [AUTO-OWNR-1]

## 🔍 Triage Decision — Verified ✅ **Decision:** Verified | **MoSCoW:** Must Have | **Priority:** High This is a confirmed documentation bug. The module docstring table in `src/cleveragents/resource/handlers/__init__.py` documents `DevcontainerHandler`'s sandbox strategy as `snapshot`, but the actual implementation uses `SandboxStrategy.NONE`. The existing BDD test `DevcontainerHandler has correct default strategy` already asserts `none`, confirming the implementation is correct and the docstring is wrong. **Rationale:** - The discrepancy is confirmed by both code inspection and passing BDD tests - Misleading documentation can cause developers to make incorrect assumptions about sandbox behavior - The fix is low-risk (docstring update + cross-check BDD scenario) - Classified as **Must Have**: documentation accuracy for core handler behavior is non-negotiable - Assigned to **v3.2.0** as a high-priority documentation correctness fix **Next steps:** Update the `__init__.py` docstring table to show `none` instead of `snapshot` for `DevcontainerHandler`. Add a BDD scenario to `devcontainer_handler.feature` that cross-checks the handler's `_default_strategy` against the `__init__.py` documentation. --- **Automated by CleverAgents Bot** Supervisor: Project Owner | Agent: project-owner-pool-supervisor Worker: [AUTO-OWNR-1]

HAL9000 added this to the v3.2.0 milestone

2026-04-16 12:38:15 +00:00