cleveragents/cleveragents-core

Fork 3

UAT: Dual incompatible `ContextStrategy` protocols — domain model and application service define conflicting interfaces #3491

New issue

Open

opened 2026-04-05 18:37:34 +00:00 by freemo · 1 comment

freemo commented

2026-04-05 18:37:34 +00:00

Owner

Metadata

Branch: fix/v3.4.0-consolidate-context-strategy-protocol
Commit Message: fix(acms): consolidate dual incompatible ContextStrategy protocols to match spec
Milestone: v3.4.0
Parent Epic: #396

Background and Context

The ACMS has two incompatible ContextStrategy Protocol definitions that cannot be used interchangeably. The specification defines a single canonical ContextStrategy protocol, but the implementation has diverged: the domain model defines the correct protocol while the application service defines a completely different one. This means the 6 built-in strategy stubs cannot be registered with or invoked by the ACMSPipeline, breaking the core pipeline functionality.

Current Behavior

Two conflicting ContextStrategy Protocol definitions exist in the codebase:

1. Domain model protocol (src/cleveragents/domain/models/acms/strategy.py) — matches the spec:

class ContextStrategy(Protocol):
    def can_handle(self, request: ContextRequest, backends: BackendSet) -> float: ...
    def assemble(self, request: ContextRequest, backends: BackendSet, budget: int, plan_context: PlanContext) -> list[ContextFragment]: ...

2. Application service protocol (src/cleveragents/application/services/acms_service.py, lines 96–130) — diverges from spec:

class ContextStrategy(Protocol):
    def can_handle(self, request: dict[str, Any]) -> float: ...
    def assemble(self, fragments: Sequence[ContextFragment], budget: ContextBudget) -> Sequence[ContextFragment]: ...

The 6 built-in strategy stubs in strategy_stubs.py implement the domain model protocol (correct), but ACMSPipeline in acms_service.py calls strategies using the application service protocol (incorrect). Attempting to register a SimpleKeywordStrategy instance with ACMSPipeline.register_strategy() and calling pipeline.assemble() results in a signature mismatch — the pipeline calls assemble(fragments, budget) but the strategy implements assemble(request, backends, budget, plan_context).

Affected built-in strategies:

simple-keyword
semantic-embedding
breadth-depth-navigator
arce
temporal-archaeology
plan-decision-context

Steps to reproduce:

Attempt to register a SimpleKeywordStrategy instance with ACMSPipeline.register_strategy()
Call pipeline.assemble() — the strategy's assemble(fragments, budget) signature will be called but SimpleKeywordStrategy.assemble(request, backends, budget, plan_context) has a different signature, causing a TypeError

Expected Behavior

A single canonical ContextStrategy protocol matching the spec's domain model definition:

class ContextStrategy(Protocol):
    def can_handle(self, request: ContextRequest, backends: BackendSet) -> float: ...
    def assemble(self, request: ContextRequest, backends: BackendSet, budget: int, plan_context: PlanContext) -> list[ContextFragment]: ...

ACMSPipeline passes ContextRequest, BackendSet, and PlanContext to strategies, and all 6 built-in strategies can be registered and invoked successfully.

Acceptance Criteria

Only one ContextStrategy Protocol definition exists in the codebase, located in src/cleveragents/domain/models/acms/strategy.py
The protocol signature matches the spec: can_handle(request: ContextRequest, backends: BackendSet) -> float and assemble(request: ContextRequest, backends: BackendSet, budget: int, plan_context: PlanContext) -> list[ContextFragment]
The duplicate protocol definition is removed from src/cleveragents/application/services/acms_service.py
ACMSPipeline imports and uses the domain model ContextStrategy protocol
ACMSPipeline.assemble() passes ContextRequest, BackendSet, and PlanContext to each strategy's can_handle and assemble methods
All 6 built-in strategies (simple-keyword, semantic-embedding, breadth-depth-navigator, arce, temporal-archaeology, plan-decision-context) can be registered with and invoked by ACMSPipeline without TypeError
No type errors reported by Pyright for strategy invocations in acms_service.py

Subtasks

Remove the duplicate ContextStrategy Protocol from src/cleveragents/application/services/acms_service.py
Update acms_service.py to import ContextStrategy from src/cleveragents/domain/models/acms/strategy.py
Refactor ACMSPipeline strategy invocation to pass ContextRequest, BackendSet, budget: int, and PlanContext to can_handle and assemble
Verify all 6 built-in strategy stubs in strategy_stubs.py satisfy the consolidated protocol (no changes expected, but confirm)
Update or add unit tests covering strategy registration and invocation via ACMSPipeline
Run Pyright type checking — confirm zero errors on affected files
Run nox (all default sessions), fix any errors
Verify coverage >= 97% via nox -s coverage_report

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.
All nox stages pass.
Coverage >= 97%.

Supporting Information

Spec reference: docs/specification.md — ACMS ContextStrategy protocol definition
Domain protocol (correct): src/cleveragents/domain/models/acms/strategy.py
Conflicting application protocol (to be removed): src/cleveragents/application/services/acms_service.py lines 96–130
Built-in strategies (correct, no changes needed): src/cleveragents/domain/models/acms/strategy_stubs.py
Discovered by: UAT tester during milestone v3.4.0 acceptance testing
Parent Epic: #396 (Epic: ACMS Context Pipeline)

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

## Metadata - **Branch**: `fix/v3.4.0-consolidate-context-strategy-protocol` - **Commit Message**: `fix(acms): consolidate dual incompatible ContextStrategy protocols to match spec` - **Milestone**: v3.4.0 - **Parent Epic**: #396 ## Background and Context The ACMS has two incompatible `ContextStrategy` Protocol definitions that cannot be used interchangeably. The specification defines a single canonical `ContextStrategy` protocol, but the implementation has diverged: the domain model defines the correct protocol while the application service defines a completely different one. This means the 6 built-in strategy stubs cannot be registered with or invoked by the `ACMSPipeline`, breaking the core pipeline functionality. ## Current Behavior Two conflicting `ContextStrategy` Protocol definitions exist in the codebase: **1. Domain model protocol** (`src/cleveragents/domain/models/acms/strategy.py`) — matches the spec: ```python class ContextStrategy(Protocol): def can_handle(self, request: ContextRequest, backends: BackendSet) -> float: ... def assemble(self, request: ContextRequest, backends: BackendSet, budget: int, plan_context: PlanContext) -> list[ContextFragment]: ... ``` **2. Application service protocol** (`src/cleveragents/application/services/acms_service.py`, lines 96–130) — diverges from spec: ```python class ContextStrategy(Protocol): def can_handle(self, request: dict[str, Any]) -> float: ... def assemble(self, fragments: Sequence[ContextFragment], budget: ContextBudget) -> Sequence[ContextFragment]: ... ``` The 6 built-in strategy stubs in `strategy_stubs.py` implement the domain model protocol (correct), but `ACMSPipeline` in `acms_service.py` calls strategies using the application service protocol (incorrect). Attempting to register a `SimpleKeywordStrategy` instance with `ACMSPipeline.register_strategy()` and calling `pipeline.assemble()` results in a signature mismatch — the pipeline calls `assemble(fragments, budget)` but the strategy implements `assemble(request, backends, budget, plan_context)`. **Affected built-in strategies:** - `simple-keyword` - `semantic-embedding` - `breadth-depth-navigator` - `arce` - `temporal-archaeology` - `plan-decision-context` **Steps to reproduce:** 1. Attempt to register a `SimpleKeywordStrategy` instance with `ACMSPipeline.register_strategy()` 2. Call `pipeline.assemble()` — the strategy's `assemble(fragments, budget)` signature will be called but `SimpleKeywordStrategy.assemble(request, backends, budget, plan_context)` has a different signature, causing a `TypeError` ## Expected Behavior A single canonical `ContextStrategy` protocol matching the spec's domain model definition: ```python class ContextStrategy(Protocol): def can_handle(self, request: ContextRequest, backends: BackendSet) -> float: ... def assemble(self, request: ContextRequest, backends: BackendSet, budget: int, plan_context: PlanContext) -> list[ContextFragment]: ... ``` `ACMSPipeline` passes `ContextRequest`, `BackendSet`, and `PlanContext` to strategies, and all 6 built-in strategies can be registered and invoked successfully. ## Acceptance Criteria - [ ] Only one `ContextStrategy` Protocol definition exists in the codebase, located in `src/cleveragents/domain/models/acms/strategy.py` - [ ] The protocol signature matches the spec: `can_handle(request: ContextRequest, backends: BackendSet) -> float` and `assemble(request: ContextRequest, backends: BackendSet, budget: int, plan_context: PlanContext) -> list[ContextFragment]` - [ ] The duplicate protocol definition is removed from `src/cleveragents/application/services/acms_service.py` - [ ] `ACMSPipeline` imports and uses the domain model `ContextStrategy` protocol - [ ] `ACMSPipeline.assemble()` passes `ContextRequest`, `BackendSet`, and `PlanContext` to each strategy's `can_handle` and `assemble` methods - [ ] All 6 built-in strategies (`simple-keyword`, `semantic-embedding`, `breadth-depth-navigator`, `arce`, `temporal-archaeology`, `plan-decision-context`) can be registered with and invoked by `ACMSPipeline` without `TypeError` - [ ] No type errors reported by Pyright for strategy invocations in `acms_service.py` ## Subtasks - [ ] Remove the duplicate `ContextStrategy` Protocol from `src/cleveragents/application/services/acms_service.py` - [ ] Update `acms_service.py` to import `ContextStrategy` from `src/cleveragents/domain/models/acms/strategy.py` - [ ] Refactor `ACMSPipeline` strategy invocation to pass `ContextRequest`, `BackendSet`, `budget: int`, and `PlanContext` to `can_handle` and `assemble` - [ ] Verify all 6 built-in strategy stubs in `strategy_stubs.py` satisfy the consolidated protocol (no changes expected, but confirm) - [ ] Update or add unit tests covering strategy registration and invocation via `ACMSPipeline` - [ ] Run Pyright type checking — confirm zero errors on affected files - [ ] Run `nox` (all default sessions), fix any errors - [ ] Verify coverage >= 97% via `nox -s coverage_report` ## 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. - All nox stages pass. - Coverage >= 97%. ## Supporting Information - **Spec reference:** `docs/specification.md` — ACMS `ContextStrategy` protocol definition - **Domain protocol (correct):** `src/cleveragents/domain/models/acms/strategy.py` - **Conflicting application protocol (to be removed):** `src/cleveragents/application/services/acms_service.py` lines 96–130 - **Built-in strategies (correct, no changes needed):** `src/cleveragents/domain/models/acms/strategy_stubs.py` - **Discovered by:** UAT tester during milestone v3.4.0 acceptance testing - **Parent Epic:** #396 (Epic: ACMS Context Pipeline) --- **Automated by CleverAgents Bot** Supervisor: UAT Testing | Agent: ca-new-issue-creator

freemo added this to the v3.4.0 milestone

2026-04-05 18:37:38 +00:00

freemo added a new dependency

2026-04-05 18:37:46 +00:00

#396 Epic: ACMS Context Pipeline

freemo referenced this issue

2026-04-05 18:51:11 +00:00

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

freemo referenced this issue

2026-04-05 18:52:57 +00:00

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

freemo referenced this issue

2026-04-05 19:05:02 +00:00

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

freemo referenced this issue

2026-04-05 19:33:17 +00:00

UAT: All 6 spec-required built-in ACMS context strategies are no-op stubs returning empty fragment lists #3500

freemo commented

2026-04-05 19:33:21 +00:00

Author

Owner

Issue verified and triaged:

Priority: Critical — dual incompatible ContextStrategy protocols prevent all 6 built-in strategies from being registered with ACMSPipeline. This is a prerequisite for #3500 and #3507.
Milestone: v3.4.0 (already assigned)
Story Points: 3 (M) — primarily a refactoring task to consolidate protocols and update pipeline invocation signatures.
Parent Epic: #396 (already linked)
Dependency: This issue MUST be resolved before #3500 (strategy implementations) and #3507 (multi-strategy execution).
Next step: This issue is now ready for implementation and should be prioritized ahead of #3500 and #3507.

Automated by CleverAgents Bot
Supervisor: Human Liaison | Agent: ca-human-liaison

Issue verified and triaged: - **Priority**: Critical — dual incompatible ContextStrategy protocols prevent all 6 built-in strategies from being registered with ACMSPipeline. This is a prerequisite for #3500 and #3507. - **Milestone**: v3.4.0 (already assigned) - **Story Points**: 3 (M) — primarily a refactoring task to consolidate protocols and update pipeline invocation signatures. - **Parent Epic**: #396 (already linked) - **Dependency**: This issue MUST be resolved before #3500 (strategy implementations) and #3507 (multi-strategy execution). - **Next step**: This issue is now ready for implementation and should be prioritized ahead of #3500 and #3507. --- **Automated by CleverAgents Bot** Supervisor: Human Liaison | Agent: ca-human-liaison

freemo referenced this issue

2026-04-05 19:33:33 +00:00

UAT: ACMSPipeline.assemble() filters to single strategy per call — spec requires multi-strategy parallel execution with fusion #3507

freemo referenced this issue

2026-04-05 19:49:58 +00:00

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

freemo referenced this issue

2026-04-05 20:03:42 +00:00

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

freemo referenced this issue

2026-04-05 20:05:52 +00:00

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