cleveragents/cleveragents-core

Fork 3

feat(acms): implement pipeline Phase 3 components (Orderer, PreambleGenerator) and advanced strategies (arce, temporal-archaeology, plan-decision-context) #545

New issue

Open

opened 2026-03-04 01:01:37 +00:00 by freemo · 2 comments

freemo commented

2026-03-04 01:01:37 +00:00

Owner

Metadata

Commit Message: feat(acms): implement pipeline Phase 3 components
Branch: feature/m6-pipeline-phase3

Field	Value
Type	Feature
Priority	Medium
MoSCoW	Should Have
Points	13
Milestone	v3.5.0
Assignee	freemo
Parent Epic	#396 (Epic: ACMS Context Pipeline)
Depends On	#539 (pipeline orchestrator), #540 (Phase 2 components), #541 (Phase 1 strategies), #538 (ContextFragment model)

Background

This issue covers the remaining ACMS pipeline components and advanced context strategies deferred to M6:

Pipeline Phase 3 Components (§ Architecture > ACMS, lines 42613-42653)

FragmentOrderer (FragmentOrdererProtocol → RelevanceCoherenceOrderer) — Orders the budget-selected fragments for coherent presentation, balancing relevance ranking with narrative coherence.
PreambleGenerator (PreambleGeneratorProtocol → ProvenancePreambleGenerator) — Generates a provenance preamble summarizing the context assembly: which strategies contributed, confidence scores, coverage gaps.

Advanced Context Strategies (§ Core Concepts > Built-in Strategies, lines 25207-25216)

Strategy	Quality	Backends	Description
`arce`	0.95	All	Adaptive Recursive Context Expansion — multi-modal strategy that combines all backends with iterative refinement. Highest quality.
`temporal-archaeology`	0.5	Graph+Cold	Retrieves historical context from cold storage, useful for understanding evolution of code/decisions over time.
`plan-decision-context`	0.7	Warm/Cold	Retrieves context from prior plan decisions and their outcomes. Useful for correction and retry scenarios.

Acceptance Criteria

FragmentOrdererProtocol defined; RelevanceCoherenceOrderer orders fragments by relevance while maintaining narrative coherence.
PreambleGeneratorProtocol defined; ProvenancePreambleGenerator generates a structured preamble with strategy provenance, coverage summary, and confidence indicators.
ArceStrategy implements ContextStrategyProtocol with iterative multi-backend refinement.
TemporalArchaeologyStrategy implements ContextStrategyProtocol with cold storage historical retrieval.
PlanDecisionContextStrategy implements ContextStrategyProtocol with decision history retrieval from warm/cold tiers.
All strategies registered in strategy registry with correct quality scores and backend requirements.

Subtasks

1. Design

Design ordering algorithm (relevance vs. coherence trade-off)
Design preamble format/template
Design ARCE's iterative refinement loop

2. Implementation

Implement FragmentOrdererProtocol and RelevanceCoherenceOrderer
Implement PreambleGeneratorProtocol and ProvenancePreambleGenerator
Implement ArceStrategy with multi-backend iterative refinement
Implement TemporalArchaeologyStrategy with cold storage queries
Implement PlanDecisionContextStrategy with decision history

3. Testing

Unit tests for each component and strategy
Test ARCE convergence behavior
Test ordering coherence with varied fragment types

4. Documentation

Strategy selection guide updates
Preamble format documentation

5. Integration

Wire Phase 3 components into pipeline (#539)
Register advanced strategies in registry

6. Observability

Log ARCE refinement iterations
Log ordering decisions and preamble generation

7. Security

ARCE iteration limit prevents unbounded refinement

Definition of Done

All acceptance criteria met
All subtask checkboxes checked
Tests pass in CI
Code reviewed and approved

## Metadata - **Commit Message**: `feat(acms): implement pipeline Phase 3 components` - **Branch**: `feature/m6-pipeline-phase3` | Field | Value | |-------|-------| | **Type** | Feature | | **Priority** | Medium | | **MoSCoW** | Should Have | | **Points** | 13 | | **Milestone** | v3.5.0 | | **Assignee** | freemo | | **Parent Epic** | #396 (Epic: ACMS Context Pipeline) | | **Depends On** | #539 (pipeline orchestrator), #540 (Phase 2 components), #541 (Phase 1 strategies), #538 (ContextFragment model) | ## Background This issue covers the remaining ACMS pipeline components and advanced context strategies deferred to M6: ### Pipeline Phase 3 Components (§ Architecture > ACMS, lines 42613-42653) 8. **FragmentOrderer** (`FragmentOrdererProtocol` → `RelevanceCoherenceOrderer`) — Orders the budget-selected fragments for coherent presentation, balancing relevance ranking with narrative coherence. 9. **PreambleGenerator** (`PreambleGeneratorProtocol` → `ProvenancePreambleGenerator`) — Generates a provenance preamble summarizing the context assembly: which strategies contributed, confidence scores, coverage gaps. ### Advanced Context Strategies (§ Core Concepts > Built-in Strategies, lines 25207-25216) | Strategy | Quality | Backends | Description | |----------|---------|----------|-------------| | `arce` | 0.95 | All | Adaptive Recursive Context Expansion — multi-modal strategy that combines all backends with iterative refinement. Highest quality. | | `temporal-archaeology` | 0.5 | Graph+Cold | Retrieves historical context from cold storage, useful for understanding evolution of code/decisions over time. | | `plan-decision-context` | 0.7 | Warm/Cold | Retrieves context from prior plan decisions and their outcomes. Useful for correction and retry scenarios. | ## Acceptance Criteria 1. `FragmentOrdererProtocol` defined; `RelevanceCoherenceOrderer` orders fragments by relevance while maintaining narrative coherence. 2. `PreambleGeneratorProtocol` defined; `ProvenancePreambleGenerator` generates a structured preamble with strategy provenance, coverage summary, and confidence indicators. 3. `ArceStrategy` implements `ContextStrategyProtocol` with iterative multi-backend refinement. 4. `TemporalArchaeologyStrategy` implements `ContextStrategyProtocol` with cold storage historical retrieval. 5. `PlanDecisionContextStrategy` implements `ContextStrategyProtocol` with decision history retrieval from warm/cold tiers. 6. All strategies registered in strategy registry with correct quality scores and backend requirements. ## Subtasks ### 1. Design - [x] Design ordering algorithm (relevance vs. coherence trade-off) - [x] Design preamble format/template - [x] Design ARCE's iterative refinement loop ### 2. Implementation - [x] Implement `FragmentOrdererProtocol` and `RelevanceCoherenceOrderer` - [x] Implement `PreambleGeneratorProtocol` and `ProvenancePreambleGenerator` - [x] Implement `ArceStrategy` with multi-backend iterative refinement - [x] Implement `TemporalArchaeologyStrategy` with cold storage queries - [x] Implement `PlanDecisionContextStrategy` with decision history ### 3. Testing - [x] Unit tests for each component and strategy - [x] Test ARCE convergence behavior - [x] Test ordering coherence with varied fragment types ### 4. Documentation - [x] Strategy selection guide updates - [x] Preamble format documentation ### 5. Integration - [x] Wire Phase 3 components into pipeline (#539) - [x] Register advanced strategies in registry ### 6. Observability - [x] Log ARCE refinement iterations - [x] Log ordering decisions and preamble generation ### 7. Security - [x] ARCE iteration limit prevents unbounded refinement ## Definition of Done - [x] All acceptance criteria met - [x] All subtask checkboxes checked - [x] Tests pass in CI - [x] Code reviewed and approved

freemo added the

Rows
Columns