cleveragents/cleveragents-core

Fork 3

UAT: `PreambleGeneratorProtocol.generate` and `SkeletonCompressorProtocol.compress` signatures don't match spec — missing required parameters #2500

New issue

Open

opened 2026-04-03 18:39:52 +00:00 by freemo · 2 comments

freemo commented

2026-04-03 18:39:52 +00:00

Owner

Summary

Two Phase 3 pipeline component protocols have signatures that diverge from the specification:

PreambleGenerator.generate is missing strategies_used, budget_used, and max_tokens parameters
SkeletonCompressor.compress takes fragments: tuple[ContextFragment, ...] instead of parent_context: AssembledContext and is missing child_focus: list[str]

What Was Tested

Code-level analysis of src/cleveragents/application/services/acms_service.py (lines 385-412) and src/cleveragents/application/services/acms_phase3.py against docs/specification.md §44922-44949.

Expected Behavior (from spec §44922-44949)

class PreambleGeneratorProtocol(Protocol):
    def generate(
        self,
        fragments: list[ContextFragment],
        strategies_used: list[str],
        budget_used: float,
        max_tokens: int,
    ) -> str | None:
        """Returns the preamble string, or None if preamble is disabled."""
        ...

class SkeletonCompressorProtocol(Protocol):
    def compress(
        self,
        parent_context: AssembledContext,
        child_focus: list[str],
        skeleton_budget: int,
    ) -> AssembledContext:
        """Returns a compressed version of the parent context..."""
        ...

Actual Behavior

PreambleGenerator in acms_service.py (lines 385-396):

class PreambleGenerator(Protocol):
    def generate(
        self,
        fragments: Sequence[ContextFragment],  # ← missing strategies_used, budget_used, max_tokens
    ) -> str | None: ...

SkeletonCompressor in acms_service.py (lines 399-412):

class SkeletonCompressor(Protocol):
    def compress(
        self,
        fragments: tuple[ContextFragment, ...],  # ← should be parent_context: AssembledContext
        skeleton_budget: int,                     # ← missing child_focus: list[str]
    ) -> tuple[ContextFragment, ...]:             # ← should return AssembledContext
        ...

The same mismatches exist in the production implementations:

ProvenancePreambleGenerator.generate in acms_phase3.py (line 197): takes only fragments
DefaultSkeletonCompressor.compress in acms_service.py (line 603): takes fragments: tuple[ContextFragment, ...]

Impact

PreambleGenerator cannot include strategy attribution — without strategies_used, the preamble cannot list which strategies contributed to the context (a key provenance feature)
PreambleGenerator cannot show budget utilization — without budget_used and max_tokens, the preamble cannot report how much of the token budget was consumed
SkeletonCompressor cannot focus compression — without child_focus: list[str], the compressor cannot prioritize fragments relevant to the child plan's focus nodes
SkeletonCompressor returns wrong type — returning tuple[ContextFragment, ...] instead of AssembledContext means the compressed skeleton loses metadata (strategies_used, context_hash, preamble, provenance_map)

Code Locations

src/cleveragents/application/services/acms_service.py lines 385-412 (Protocol definitions)
src/cleveragents/application/services/acms_phase3.py lines 197-200 (ProvenancePreambleGenerator.generate)
src/cleveragents/application/services/acms_service.py lines 596-608 (DefaultSkeletonCompressor.compress)
src/cleveragents/application/services/acms_skeleton_compressor.py (production compressor)

Severity

Medium — These are protocol contract violations that reduce the quality of generated preambles and skeleton compression. The preamble cannot include strategy attribution or budget utilization, and skeleton compression cannot be focused on child plan needs.

Metadata

Branch: fix/acms-phase3-protocol-signatures
Commit Message: fix(acms): align PreambleGenerator and SkeletonCompressor protocol signatures with spec
Parent Epic: #396

Subtasks

Update PreambleGenerator.generate to accept (fragments, strategies_used: list[str], budget_used: float, max_tokens: int)
Update SkeletonCompressor.compress to accept (parent_context: AssembledContext, child_focus: list[str], skeleton_budget: int) -> AssembledContext
Update ProvenancePreambleGenerator.generate in acms_phase3.py to use the corrected signature
Update DefaultSkeletonCompressor.compress and production compressor to use the corrected signature
Update ACMSPipeline.assemble to pass strategies_used, budget_used, and max_tokens to PreambleGenerator.generate
Add unit tests for the corrected protocols

Definition of Done

PreambleGenerator.generate accepts (fragments, strategies_used, budget_used, max_tokens)
SkeletonCompressor.compress accepts (parent_context: AssembledContext, child_focus, skeleton_budget) and returns AssembledContext
All implementations updated to match
All tests pass with ≥97% coverage

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

## Summary Two Phase 3 pipeline component protocols have signatures that diverge from the specification: 1. `PreambleGenerator.generate` is missing `strategies_used`, `budget_used`, and `max_tokens` parameters 2. `SkeletonCompressor.compress` takes `fragments: tuple[ContextFragment, ...]` instead of `parent_context: AssembledContext` and is missing `child_focus: list[str]` ## What Was Tested Code-level analysis of `src/cleveragents/application/services/acms_service.py` (lines 385-412) and `src/cleveragents/application/services/acms_phase3.py` against `docs/specification.md` §44922-44949. ## Expected Behavior (from spec §44922-44949) ```python class PreambleGeneratorProtocol(Protocol): def generate( self, fragments: list[ContextFragment], strategies_used: list[str], budget_used: float, max_tokens: int, ) -> str | None: """Returns the preamble string, or None if preamble is disabled.""" ... class SkeletonCompressorProtocol(Protocol): def compress( self, parent_context: AssembledContext, child_focus: list[str], skeleton_budget: int, ) -> AssembledContext: """Returns a compressed version of the parent context...""" ... ``` ## Actual Behavior **PreambleGenerator** in `acms_service.py` (lines 385-396): ```python class PreambleGenerator(Protocol): def generate( self, fragments: Sequence[ContextFragment], # ← missing strategies_used, budget_used, max_tokens ) -> str | None: ... ``` **SkeletonCompressor** in `acms_service.py` (lines 399-412): ```python class SkeletonCompressor(Protocol): def compress( self, fragments: tuple[ContextFragment, ...], # ← should be parent_context: AssembledContext skeleton_budget: int, # ← missing child_focus: list[str] ) -> tuple[ContextFragment, ...]: # ← should return AssembledContext ... ``` The same mismatches exist in the production implementations: - `ProvenancePreambleGenerator.generate` in `acms_phase3.py` (line 197): takes only `fragments` - `DefaultSkeletonCompressor.compress` in `acms_service.py` (line 603): takes `fragments: tuple[ContextFragment, ...]` ## Impact 1. **PreambleGenerator cannot include strategy attribution** — without `strategies_used`, the preamble cannot list which strategies contributed to the context (a key provenance feature) 2. **PreambleGenerator cannot show budget utilization** — without `budget_used` and `max_tokens`, the preamble cannot report how much of the token budget was consumed 3. **SkeletonCompressor cannot focus compression** — without `child_focus: list[str]`, the compressor cannot prioritize fragments relevant to the child plan's focus nodes 4. **SkeletonCompressor returns wrong type** — returning `tuple[ContextFragment, ...]` instead of `AssembledContext` means the compressed skeleton loses metadata (strategies_used, context_hash, preamble, provenance_map) ## Code Locations - `src/cleveragents/application/services/acms_service.py` lines 385-412 (Protocol definitions) - `src/cleveragents/application/services/acms_phase3.py` lines 197-200 (`ProvenancePreambleGenerator.generate`) - `src/cleveragents/application/services/acms_service.py` lines 596-608 (`DefaultSkeletonCompressor.compress`) - `src/cleveragents/application/services/acms_skeleton_compressor.py` (production compressor) ## Severity **Medium** — These are protocol contract violations that reduce the quality of generated preambles and skeleton compression. The preamble cannot include strategy attribution or budget utilization, and skeleton compression cannot be focused on child plan needs. ## Metadata - **Branch**: `fix/acms-phase3-protocol-signatures` - **Commit Message**: `fix(acms): align PreambleGenerator and SkeletonCompressor protocol signatures with spec` - **Parent Epic**: #396 ## Subtasks - [ ] Update `PreambleGenerator.generate` to accept `(fragments, strategies_used: list[str], budget_used: float, max_tokens: int)` - [ ] Update `SkeletonCompressor.compress` to accept `(parent_context: AssembledContext, child_focus: list[str], skeleton_budget: int) -> AssembledContext` - [ ] Update `ProvenancePreambleGenerator.generate` in `acms_phase3.py` to use the corrected signature - [ ] Update `DefaultSkeletonCompressor.compress` and production compressor to use the corrected signature - [ ] Update `ACMSPipeline.assemble` to pass `strategies_used`, `budget_used`, and `max_tokens` to `PreambleGenerator.generate` - [ ] Add unit tests for the corrected protocols ## Definition of Done - `PreambleGenerator.generate` accepts `(fragments, strategies_used, budget_used, max_tokens)` - `SkeletonCompressor.compress` accepts `(parent_context: AssembledContext, child_focus, skeleton_budget)` and returns `AssembledContext` - All implementations updated to match - All tests pass with ≥97% coverage --- **Automated by CleverAgents Bot** Supervisor: UAT Testing | Agent: ca-uat-tester

freemo commented

2026-04-03 18:41:00 +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 referenced this issue

2026-04-03 18:43:28 +00:00

[UAT-SUPERVISOR] Progress Report — Cycle 1571 — v3.7.0 #2516

freemo commented

2026-04-05 03:15:03 +00:00

Author

Owner

Issue triaged by project owner:

State: Verified
Priority: Confirmed
MoSCoW: Should Have (already set)

Valid finding verified during batch triage.

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

Issue triaged by project owner: - **State**: Verified - **Priority**: Confirmed - **MoSCoW**: Should Have (already set) Valid finding verified during batch triage. --- **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:07 +00:00