Epic: ACMS Context Assembly Pipeline — Functional CRP Handlers and Pipeline Components #935

Open
opened 2026-03-14 01:13:49 +00:00 by freemo · 7 comments
Owner

Background and Context

The specification defines the Advanced Context Management System (ACMS) as a pluggable, strategy-driven framework for assembling actor context (spec §Glossary, §Core Concepts > Context, §Architecture > ACMS). The ACMS comprises: UKO, CRP, pluggable context strategies, a 10-component Context Assembly Pipeline, and hot/warm/cold tiered storage.

The current implementation (~50% complete) has:

  • CRP modelsContextRequest, ContextFragment, AssembledContext, ContextBudget, DetailLevelMap all exist and are well-defined in domain/models/acms/crp.py
  • builtin/context skill — Three tool specs exist (builtin/request-context, builtin/query-history, builtin/get-context-budget) in skills/builtins/context_ops.py, but all handlers raise NotImplementedError
  • Context strategies — Strategy models exist but the strategy executor is incomplete
  • Pipeline — The context.get handler in A2A facade returns {"stub": True}. No functional pipeline (FragmentDeduplicator, DetailDepthResolver, FragmentScorer, BudgetPacker, FragmentOrderer) exists

Expected Behavior

The ACMS must provide a fully functional context assembly pipeline that actors can use to dynamically request and receive contextually relevant information during reasoning. The 10-component pipeline must be pluggable and configurable at global, project, and plan scope.

Acceptance Criteria

  • builtin/request-context tool handler functional — actors can request context during reasoning
  • builtin/query-history tool handler functional — actors can query decision/plan history
  • builtin/get-context-budget tool handler functional — actors can check remaining budget
  • All 10 pipeline components implemented with default implementations:
    • StrategySelector, BudgetAllocator, StrategyExecutor, FragmentDeduplicator, DetailDepthResolver, FragmentScorer, BudgetPacker, FragmentOrderer, PreambleGenerator, SkeletonCompressor
  • Pipeline components overridable at global, project, or plan scope
  • Context inheritance: skeleton context propagates from parent to child plans
  • Dynamic context window adaptation with budget computation
  • At least 3 built-in strategies functional: simple-keyword, semantic-embedding, plan-decision-context

Subtasks

  • Implement builtin/request-context handler wired to ACMS pipeline
  • Implement builtin/query-history handler
  • Implement builtin/get-context-budget handler
  • Implement StrategySelector component
  • Implement BudgetAllocator component with spec formula
  • Implement StrategyExecutor with parallel strategy execution
  • Implement FragmentDeduplicator
  • Implement DetailDepthResolver
  • Implement FragmentScorer
  • Implement BudgetPacker (knapsack algorithm)
  • Implement FragmentOrderer
  • Implement PreambleGenerator
  • Implement SkeletonCompressor with depth-reduction algorithm
  • Implement pipeline scope resolution (plan > project > global)
  • Implement context inheritance for child plans
  • Implement 3+ built-in strategies
  • Tests (Behave): Add scenarios for each pipeline component
  • Tests (Behave): Add scenarios for CRP tool handlers
  • Tests (Robot): Add integration tests for full pipeline execution
  • Verify coverage >=97% via nox -s coverage_report
  • Run nox (all default sessions), fix any errors
  • Wire A2A context.get handler to ACMS pipeline (remove stub response)

Definition of Done

This epic is complete when all child issues are closed AND the ACMS pipeline is fully functional, actors can dynamically request context through CRP tools, and the pipeline assembles context using pluggable strategies with proper budget management.

## Background and Context The specification defines the Advanced Context Management System (ACMS) as a pluggable, strategy-driven framework for assembling actor context (spec §Glossary, §Core Concepts > Context, §Architecture > ACMS). The ACMS comprises: UKO, CRP, pluggable context strategies, a 10-component Context Assembly Pipeline, and hot/warm/cold tiered storage. The current implementation (~50% complete) has: - **CRP models** — `ContextRequest`, `ContextFragment`, `AssembledContext`, `ContextBudget`, `DetailLevelMap` all exist and are well-defined in `domain/models/acms/crp.py` - **builtin/context skill** — Three tool specs exist (`builtin/request-context`, `builtin/query-history`, `builtin/get-context-budget`) in `skills/builtins/context_ops.py`, but all handlers raise `NotImplementedError` - **Context strategies** — Strategy models exist but the strategy executor is incomplete - **Pipeline** — The `context.get` handler in A2A facade returns `{"stub": True}`. No functional pipeline (FragmentDeduplicator, DetailDepthResolver, FragmentScorer, BudgetPacker, FragmentOrderer) exists ## Expected Behavior The ACMS must provide a fully functional context assembly pipeline that actors can use to dynamically request and receive contextually relevant information during reasoning. The 10-component pipeline must be pluggable and configurable at global, project, and plan scope. ## Acceptance Criteria - [ ] `builtin/request-context` tool handler functional — actors can request context during reasoning - [ ] `builtin/query-history` tool handler functional — actors can query decision/plan history - [ ] `builtin/get-context-budget` tool handler functional — actors can check remaining budget - [ ] All 10 pipeline components implemented with default implementations: - StrategySelector, BudgetAllocator, StrategyExecutor, FragmentDeduplicator, DetailDepthResolver, FragmentScorer, BudgetPacker, FragmentOrderer, PreambleGenerator, SkeletonCompressor - [ ] Pipeline components overridable at global, project, or plan scope - [ ] Context inheritance: skeleton context propagates from parent to child plans - [ ] Dynamic context window adaptation with budget computation - [ ] At least 3 built-in strategies functional: simple-keyword, semantic-embedding, plan-decision-context ## Subtasks - [ ] Implement `builtin/request-context` handler wired to ACMS pipeline - [ ] Implement `builtin/query-history` handler - [ ] Implement `builtin/get-context-budget` handler - [ ] Implement StrategySelector component - [ ] Implement BudgetAllocator component with spec formula - [ ] Implement StrategyExecutor with parallel strategy execution - [ ] Implement FragmentDeduplicator - [ ] Implement DetailDepthResolver - [ ] Implement FragmentScorer - [ ] Implement BudgetPacker (knapsack algorithm) - [ ] Implement FragmentOrderer - [ ] Implement PreambleGenerator - [ ] Implement SkeletonCompressor with depth-reduction algorithm - [ ] Implement pipeline scope resolution (plan > project > global) - [ ] Implement context inheritance for child plans - [ ] Implement 3+ built-in strategies - [ ] Tests (Behave): Add scenarios for each pipeline component - [ ] Tests (Behave): Add scenarios for CRP tool handlers - [ ] Tests (Robot): Add integration tests for full pipeline execution - [ ] Verify coverage >=97% via `nox -s coverage_report` - [ ] Run `nox` (all default sessions), fix any errors - [x] Wire A2A `context.get` handler to ACMS pipeline (remove stub response) ## Definition of Done This epic is complete when all child issues are closed AND the ACMS pipeline is fully functional, actors can dynamically request context through CRP tools, and the pipeline assembles context using pluggable strategies with proper budget management.
freemo added this to the v3.4.0 milestone 2026-03-14 01:15:48 +00:00
Author
Owner

Parent Legendary: cleverthis/cleveragents#3 — Core Functionality

Related issues:

  • #933 (A2A Protocol) — CRP tool handlers are invoked through A2A facade
  • #934 (LSP Runtime) — LSP auto-context enrichment produces context fragments for this pipeline
  • #939 (Plugin Extension Points) — ACMS pipeline components are extensible via context.pipeline_component extension points
## Dependency Links **Parent Legendary**: [cleverthis/cleveragents#3 — Core Functionality](https://git.cleverthis.com/cleverthis/cleveragents/issues/3) **Related issues**: - #933 (A2A Protocol) — CRP tool handlers are invoked through A2A facade - #934 (LSP Runtime) — LSP auto-context enrichment produces context fragments for this pipeline - #939 (Plugin Extension Points) — ACMS pipeline components are extensible via `context.pipeline_component` extension points
freemo self-assigned this 2026-03-14 04:27:03 +00:00
Member

Implementation journal (start):

  • Verified issue #935 is OPEN, now assigned to brent.edwards, and state label is now State/In Progress.
  • Cloned isolated workspace at /tmp/cleveragents-935 per parallel-agent rules; configured remotes (origin PAT HTTPS, upstream /app) and git identity Brent E. Edwards <brent.edwards@cleverthis.com>.
  • Reviewed docs/specification.md (ACMS pipeline and CRP sections), CONTRIBUTING.md, and docs/timeline.md.
  • Current codebase assessment vs issue text:
    • CRP handlers in skills/builtins/context_ops.py are already implemented (not stubs).
    • Pipeline components for phases 1/2/3 are already implemented in application/services/acms_pipeline.py, acms_phase2.py, and acms_phase3.py.
    • Remaining gap identified in issue body still present in code: A2AFacade._handle_context_get (src/cleveragents/a2a/facade.py) still returns {"stub": True} with message "ACMS ContextAssemblyPipeline not yet wired".

Plan for this work slice:

  1. Add failing BDD coverage for non-stub context.get behavior.
  2. Implement facade wiring to ACMS pipeline through DI/container services.
  3. Update integration helper assertions (Robot helper module) to match functional response contract.
  4. Run nox quality gates and coverage; iterate to green.
Implementation journal (start): - Verified issue #935 is OPEN, now assigned to `brent.edwards`, and state label is now `State/In Progress`. - Cloned isolated workspace at `/tmp/cleveragents-935` per parallel-agent rules; configured remotes (`origin` PAT HTTPS, `upstream` /app) and git identity `Brent E. Edwards <brent.edwards@cleverthis.com>`. - Reviewed `docs/specification.md` (ACMS pipeline and CRP sections), `CONTRIBUTING.md`, and `docs/timeline.md`. - Current codebase assessment vs issue text: - CRP handlers in `skills/builtins/context_ops.py` are already implemented (not stubs). - Pipeline components for phases 1/2/3 are already implemented in `application/services/acms_pipeline.py`, `acms_phase2.py`, and `acms_phase3.py`. - Remaining gap identified in issue body still present in code: `A2AFacade._handle_context_get` (`src/cleveragents/a2a/facade.py`) still returns `{"stub": True}` with message "ACMS ContextAssemblyPipeline not yet wired". Plan for this work slice: 1) Add failing BDD coverage for non-stub `context.get` behavior. 2) Implement facade wiring to ACMS pipeline through DI/container services. 3) Update integration helper assertions (Robot helper module) to match functional response contract. 4) Run nox quality gates and coverage; iterate to green.
Member

Implementation journal (TDD + wiring update):

Completed in this iteration:

  1. TDD red step

    • Updated BDD expectations for A2A context operation from stub to functional payload:
      • features/a2a_facade_wiring.feature scenario now expects stub=False and non-zero token output.
      • features/steps/a2a_facade_wiring_steps.py adds mock ACMS pipeline + mock context tier service fixtures.
      • robot/a2a_facade_wiring.robot and robot/helper_a2a_facade_wiring.py updated similarly (wired-context-get).
    • Ran: nox -s unit_tests -- features/a2a_facade_wiring.feature
    • Result: failed as expected on context.get still returning stub=True.
  2. Implementation

    • Wired A2aLocalFacade context path in src/cleveragents/a2a/facade.py:
      • Added service accessors for acms_pipeline and context_tier_service.
      • Added resolver method that first uses explicitly wired services, then falls back to DI container (get_container().acms_pipeline() / get_container().context_tier_service()).
      • Added tiered-fragment → ContextFragment conversion and response serialization helpers.
      • Replaced stub _handle_context_get implementation with ACMS-backed assembly flow:
        • builds ContextBudget
        • pulls tier fragments
        • calls pipeline .assemble(...)
        • returns structured response with fragments, hash, preamble, provenance, token usage, and strategies.
      • If context services are unavailable, handler now returns a non-stub, empty-but-valid context payload.
  3. TDD green step

    • Re-ran: nox -s unit_tests -- features/a2a_facade_wiring.feature
    • Result: pass (scenario now green).
  4. Issue tracking update

    • Added/checked related subtask in issue body:
      • [x] Wire A2A context.get handler to ACMS pipeline (remove stub response)

Notes:

  • This focuses only on the remaining gap identified in #935’s current code state (A2A context.get stub).
  • Existing ACMS/CRP component implementations in pipeline/services were left intact; this change wires facade exposure to those existing services.
Implementation journal (TDD + wiring update): Completed in this iteration: 1. **TDD red step** - Updated BDD expectations for A2A context operation from stub to functional payload: - `features/a2a_facade_wiring.feature` scenario now expects `stub=False` and non-zero token output. - `features/steps/a2a_facade_wiring_steps.py` adds mock ACMS pipeline + mock context tier service fixtures. - `robot/a2a_facade_wiring.robot` and `robot/helper_a2a_facade_wiring.py` updated similarly (`wired-context-get`). - Ran: `nox -s unit_tests -- features/a2a_facade_wiring.feature` - Result: **failed as expected** on `context.get` still returning `stub=True`. 2. **Implementation** - Wired `A2aLocalFacade` context path in `src/cleveragents/a2a/facade.py`: - Added service accessors for `acms_pipeline` and `context_tier_service`. - Added resolver method that first uses explicitly wired services, then falls back to DI container (`get_container().acms_pipeline()` / `get_container().context_tier_service()`). - Added tiered-fragment → `ContextFragment` conversion and response serialization helpers. - Replaced stub `_handle_context_get` implementation with ACMS-backed assembly flow: - builds `ContextBudget` - pulls tier fragments - calls pipeline `.assemble(...)` - returns structured response with fragments, hash, preamble, provenance, token usage, and strategies. - If context services are unavailable, handler now returns a **non-stub**, empty-but-valid context payload. 3. **TDD green step** - Re-ran: `nox -s unit_tests -- features/a2a_facade_wiring.feature` - Result: **pass** (scenario now green). 4. **Issue tracking update** - Added/checked related subtask in issue body: - `[x] Wire A2A context.get handler to ACMS pipeline (remove stub response)` Notes: - This focuses only on the remaining gap identified in #935’s current code state (A2A `context.get` stub). - Existing ACMS/CRP component implementations in pipeline/services were left intact; this change wires facade exposure to those existing services.
freemo self-assigned this 2026-04-02 06:13:53 +00:00
Author
Owner

New child issue filed: #1430 — UAT: Spec-required built-in ACMS strategies not registered in BUILTIN_STRATEGIES (simple-keyword, semantic-embedding, breadth-depth-navigator, arce, temporal-archaeology, plan-decision-context unavailable by default).

This issue was found during UAT of ACMS v1 (v3.5.0) and directly relates to this Epic's acceptance criterion: "At least 3 built-in strategies functional: simple-keyword, semantic-embedding, plan-decision-context." The strategies are implemented but never registered in BUILTIN_STRATEGIES, making them inaccessible by their spec-documented names.

**New child issue filed:** #1430 — UAT: Spec-required built-in ACMS strategies not registered in `BUILTIN_STRATEGIES` (`simple-keyword`, `semantic-embedding`, `breadth-depth-navigator`, `arce`, `temporal-archaeology`, `plan-decision-context` unavailable by default). This issue was found during UAT of ACMS v1 (v3.5.0) and directly relates to this Epic's acceptance criterion: *"At least 3 built-in strategies functional: simple-keyword, semantic-embedding, plan-decision-context."* The strategies are implemented but never registered in `BUILTIN_STRATEGIES`, making them inaccessible by their spec-documented names.
Author
Owner

Dependency notice: Issue #1443 (UAT: ContextTierService and TierBudget use wrong default values — hot=8000 (spec: 16000), warm=500 (spec: 100), cold=5000 (spec: 500)) has been filed as a child of this Epic. Per project convention, #1443 blocks this Epic (#935).

**Dependency notice:** Issue #1443 (UAT: ContextTierService and TierBudget use wrong default values — hot=8000 (spec: 16000), warm=500 (spec: 100), cold=5000 (spec: 500)) has been filed as a child of this Epic. Per project convention, #1443 **blocks** this Epic (#935).
Author
Owner

Label compliance fix applied:

  • Replaced orphaned label State/In Progress with valid label State/In progress
  • Reason: State/In Progress (capital P) is an orphaned label that no longer exists in the repository's label list. The correct label is State/In progress (lowercase p, ID: 1322).

Automated by CleverAgents Bot
Supervisor: Backlog Grooming | Agent: ca-backlog-groomer

Label compliance fix applied: - Replaced orphaned label `State/In Progress` with valid label `State/In progress` - Reason: `State/In Progress` (capital P) is an orphaned label that no longer exists in the repository's label list. The correct label is `State/In progress` (lowercase p, ID: 1322). --- **Automated by CleverAgents Bot** Supervisor: Backlog Grooming | Agent: ca-backlog-groomer
Owner

Planning Update — New Implementation Issues Created

This epic previously had only 3 child issues (all bug-hunt boundary checks). The following implementation issues have been created to cover the full ACMS pipeline implementation:

New Child Issues

Issue Title Dependency
#7400 feat(acms): implement ACMS pipeline core components — StrategySelector, BudgetAllocator, StrategyExecutor First — no blockers
#7402 feat(acms): implement ACMS pipeline post-processing components — FragmentDeduplicator, DetailDepthResolver, FragmentScorer, BudgetPacker, FragmentOrderer After #7400
#7403 feat(acms): implement ACMS pipeline output components — PreambleGenerator, SkeletonCompressor, and context inheritance After #7400, #7402
#7398 feat(acms): implement CRP tool handlers — request-context, query-history, get-context-budget After #7400

Implementation Order

#7400 (Pipeline Core) → #7402 (Post-Processing) → #7403 (Output + E2E)
                      ↘ #7398 (CRP Tool Handlers)

All 4 issues block this epic (#935). The epic is complete when all child issues are closed AND the full ACMS pipeline is functional end-to-end.


Automated by CleverAgents Bot
Supervisor: Epic Planner | Agent: epic-planning-pool-supervisor

## Planning Update — New Implementation Issues Created This epic previously had only 3 child issues (all bug-hunt boundary checks). The following implementation issues have been created to cover the full ACMS pipeline implementation: ### New Child Issues | Issue | Title | Dependency | |-------|-------|------------| | #7400 | feat(acms): implement ACMS pipeline core components — StrategySelector, BudgetAllocator, StrategyExecutor | First — no blockers | | #7402 | feat(acms): implement ACMS pipeline post-processing components — FragmentDeduplicator, DetailDepthResolver, FragmentScorer, BudgetPacker, FragmentOrderer | After #7400 | | #7403 | feat(acms): implement ACMS pipeline output components — PreambleGenerator, SkeletonCompressor, and context inheritance | After #7400, #7402 | | #7398 | feat(acms): implement CRP tool handlers — request-context, query-history, get-context-budget | After #7400 | ### Implementation Order ``` #7400 (Pipeline Core) → #7402 (Post-Processing) → #7403 (Output + E2E) ↘ #7398 (CRP Tool Handlers) ``` All 4 issues block this epic (#935). The epic is complete when all child issues are closed AND the full ACMS pipeline is functional end-to-end. --- **Automated by CleverAgents Bot** Supervisor: Epic Planner | Agent: epic-planning-pool-supervisor
Sign in to join this conversation.
No milestone
No project
No assignees
3 participants
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Reference
cleveragents/cleveragents-core#935
No description provided.