UAT: `ContextStrategy` protocol `can_handle` and `assemble` signatures don't match spec — missing `BackendSet` and `PlanContext` parameters #2485

New issue

Open

opened 2026-04-03 18:37:57 +00:00 by freemo · 1 comment

freemo commented

2026-04-03 18:37:57 +00:00

Owner

Summary

The ContextStrategy protocol defined in acms_service.py has fundamentally different method signatures from what the specification requires. This means any custom strategy written to the spec will be incompatible with the pipeline, and the pipeline itself cannot pass the correct data to strategies.

What Was Tested

Code-level analysis of src/cleveragents/application/services/acms_service.py (the ContextStrategy Protocol) and src/cleveragents/application/services/context_strategies.py (built-in strategy implementations) against docs/specification.md §25506-25529.

Expected Behavior (from spec §25506-25529)

class ContextStrategy(Protocol):
    def can_handle(self, request: ContextRequest, backends: BackendSet) -> float:
        """Returns 0.0-1.0 confidence that this strategy can usefully
        contribute to this request."""
        ...

    def assemble(self, request: ContextRequest, backends: BackendSet,
                 budget: int, plan_context: PlanContext) -> list[ContextFragment]:
        """Execute the strategy. Must respect the budget."""
        ...

The spec requires:

can_handle(request: ContextRequest, backends: BackendSet) -> float
assemble(request: ContextRequest, backends: BackendSet, budget: int, plan_context: PlanContext) -> list[ContextFragment]

Actual Behavior

In src/cleveragents/application/services/acms_service.py (lines 111-125):

class ContextStrategy(Protocol):
    def can_handle(self, request: dict[str, Any]) -> float:
        ...

    def assemble(
        self,
        fragments: Sequence[ContextFragment],
        budget: ContextBudget,
    ) -> Sequence[ContextFragment]:
        ...

All built-in strategies in context_strategies.py and acms_advanced_strategies.py implement this wrong signature.

Key differences:

can_handle takes dict[str, Any] instead of ContextRequest + BackendSet
assemble takes pre-fetched fragments + ContextBudget instead of request + BackendSet + budget: int + PlanContext
The strategy never receives the ContextRequest in assemble, so it cannot use query, focus URIs, UKO types, temporal scope, or priority from the request
The strategy never receives BackendSet, so it cannot check backend availability or route to the correct backend
The strategy never receives PlanContext, so plan-hierarchy-aware strategies like plan-decision-context cannot traverse ancestor decisions

Code Locations

src/cleveragents/application/services/acms_service.py lines 95-125 (Protocol definition)
src/cleveragents/application/services/context_strategies.py lines 80-90, 174-190, 270-285 (built-in implementations)
src/cleveragents/application/services/acms_advanced_strategies.py lines 111-120, 272-280, 368-375 (advanced implementations)
src/cleveragents/domain/models/acms/strategy.py lines 194-244 (domain-layer Protocol — this one IS correct per spec)

Note: The domain-layer ContextStrategy in strategy.py has the correct spec-aligned signature, but the application-layer Protocol in acms_service.py diverges from it. The pipeline uses the application-layer Protocol.

Steps to Reproduce

Read docs/specification.md §25506-25529 for the spec-required signatures
Read src/cleveragents/application/services/acms_service.py lines 95-125
Observe the signature mismatch

Severity

High — This is a fundamental protocol contract violation. Custom strategies written to the spec cannot be registered with the pipeline. The pipeline cannot pass ContextRequest, BackendSet, or PlanContext to strategies, making the ACMS unable to perform request-aware, backend-aware, or plan-hierarchy-aware context assembly.

Metadata

Branch: fix/acms-context-strategy-protocol-signatures
Commit Message: fix(acms): align ContextStrategy protocol signatures with spec
Parent Epic: #396

Subtasks

Update ContextStrategy Protocol in acms_service.py to match spec signatures
Update all built-in strategies (SimpleKeywordStrategy, SemanticEmbeddingStrategy, BreadthDepthNavigatorStrategy, ArceStrategy, TemporalArchaeologyStrategy, PlanDecisionContextStrategy) to use the correct signatures
Update DefaultStrategyExecutor.execute to pass request, backends, and plan_context to strategies
Add unit tests for the corrected protocol

Definition of Done

ContextStrategy.can_handle accepts (request: ContextRequest, backends: BackendSet) -> float
ContextStrategy.assemble accepts (request: ContextRequest, backends: BackendSet, budget: int, plan_context: PlanContext) -> list[ContextFragment]
All built-in strategies implement the corrected signatures
All tests pass with ≥97% coverage

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

## Summary The `ContextStrategy` protocol defined in `acms_service.py` has fundamentally different method signatures from what the specification requires. This means any custom strategy written to the spec will be incompatible with the pipeline, and the pipeline itself cannot pass the correct data to strategies. ## What Was Tested Code-level analysis of `src/cleveragents/application/services/acms_service.py` (the `ContextStrategy` Protocol) and `src/cleveragents/application/services/context_strategies.py` (built-in strategy implementations) against `docs/specification.md` §25506-25529. ## Expected Behavior (from spec §25506-25529) ```python class ContextStrategy(Protocol): def can_handle(self, request: ContextRequest, backends: BackendSet) -> float: """Returns 0.0-1.0 confidence that this strategy can usefully contribute to this request.""" ... def assemble(self, request: ContextRequest, backends: BackendSet, budget: int, plan_context: PlanContext) -> list[ContextFragment]: """Execute the strategy. Must respect the budget.""" ... ``` The spec requires: - `can_handle(request: ContextRequest, backends: BackendSet) -> float` - `assemble(request: ContextRequest, backends: BackendSet, budget: int, plan_context: PlanContext) -> list[ContextFragment]` ## Actual Behavior In `src/cleveragents/application/services/acms_service.py` (lines 111-125): ```python class ContextStrategy(Protocol): def can_handle(self, request: dict[str, Any]) -> float: ... def assemble( self, fragments: Sequence[ContextFragment], budget: ContextBudget, ) -> Sequence[ContextFragment]: ... ``` All built-in strategies in `context_strategies.py` and `acms_advanced_strategies.py` implement this wrong signature. **Key differences:** 1. `can_handle` takes `dict[str, Any]` instead of `ContextRequest` + `BackendSet` 2. `assemble` takes pre-fetched `fragments` + `ContextBudget` instead of `request` + `BackendSet` + `budget: int` + `PlanContext` 3. The strategy never receives the `ContextRequest` in `assemble`, so it cannot use query, focus URIs, UKO types, temporal scope, or priority from the request 4. The strategy never receives `BackendSet`, so it cannot check backend availability or route to the correct backend 5. The strategy never receives `PlanContext`, so plan-hierarchy-aware strategies like `plan-decision-context` cannot traverse ancestor decisions ## Code Locations - `src/cleveragents/application/services/acms_service.py` lines 95-125 (Protocol definition) - `src/cleveragents/application/services/context_strategies.py` lines 80-90, 174-190, 270-285 (built-in implementations) - `src/cleveragents/application/services/acms_advanced_strategies.py` lines 111-120, 272-280, 368-375 (advanced implementations) - `src/cleveragents/domain/models/acms/strategy.py` lines 194-244 (domain-layer Protocol — this one IS correct per spec) Note: The domain-layer `ContextStrategy` in `strategy.py` has the correct spec-aligned signature, but the application-layer Protocol in `acms_service.py` diverges from it. The pipeline uses the application-layer Protocol. ## Steps to Reproduce 1. Read `docs/specification.md` §25506-25529 for the spec-required signatures 2. Read `src/cleveragents/application/services/acms_service.py` lines 95-125 3. Observe the signature mismatch ## Severity **High** — This is a fundamental protocol contract violation. Custom strategies written to the spec cannot be registered with the pipeline. The pipeline cannot pass `ContextRequest`, `BackendSet`, or `PlanContext` to strategies, making the ACMS unable to perform request-aware, backend-aware, or plan-hierarchy-aware context assembly. ## Metadata - **Branch**: `fix/acms-context-strategy-protocol-signatures` - **Commit Message**: `fix(acms): align ContextStrategy protocol signatures with spec` - **Parent Epic**: #396 ## Subtasks - [ ] Update `ContextStrategy` Protocol in `acms_service.py` to match spec signatures - [ ] Update all built-in strategies (`SimpleKeywordStrategy`, `SemanticEmbeddingStrategy`, `BreadthDepthNavigatorStrategy`, `ArceStrategy`, `TemporalArchaeologyStrategy`, `PlanDecisionContextStrategy`) to use the correct signatures - [ ] Update `DefaultStrategyExecutor.execute` to pass `request`, `backends`, and `plan_context` to strategies - [ ] Add unit tests for the corrected protocol ## Definition of Done - `ContextStrategy.can_handle` accepts `(request: ContextRequest, backends: BackendSet) -> float` - `ContextStrategy.assemble` accepts `(request: ContextRequest, backends: BackendSet, budget: int, plan_context: PlanContext) -> list[ContextFragment]` - All built-in strategies implement the corrected signatures - All tests pass with ≥97% coverage --- **Automated by CleverAgents Bot** Supervisor: UAT Testing | Agent: ca-uat-tester

freemo commented

2026-04-03 18:40:59 +00:00

Author

Owner

Issue triaged by project owner:

State: Verified
MoSCoW: Should Have — Spec compliance or quality improvement that should be included in the milestone.

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

Issue triaged by project owner: - **State**: Verified - **MoSCoW**: Should Have — Spec compliance or quality improvement that should be included in the milestone. --- **Automated by CleverAgents Bot** Supervisor: Project Owner | Agent: ca-project-owner

freemo added this to the v3.7.0 milestone

2026-04-05 05:07:08 +00:00

freemo removed this from the v3.7.0 milestone

2026-04-07 00:50:04 +00:00