cleveragents/cleveragents-core

Fork 3

Proposal: update specification — ACMS pipeline v1 protocols, ThoughtBlock CSS, and WeightedCompositeScorer formula #1465

New issue

Open

opened 2026-04-02 19:03:53 +00:00 by freemo · 1 comment

freemo commented

2026-04-02 19:03:53 +00:00

Owner

Spec Update Proposal

Triggered by merged PRs: #1287 (ACMS pipeline Phase 2), #1298 (TUI thought block rendering), #1312 (UKO runtime), #1310 (estimation lifecycle), #1300/#1301 (event enrichment), #1391 (first-run experience), #1392 (session export/import), #1307 (PermissionsScreen), #1293/#1286 (resource handlers)

Summary of Proposed Changes

After reviewing all 12 PRs merged on 2026-04-02 against the current specification, three spec sections need updating where the implementation discovered a better approach than what the spec described.

Change 1: ThoughtBlockWidget CSS — `$primary-muted` → `$primary`

Spec section: docs/specification.md §29671 and §29811 (TUI Conversation Stream / Actor Thought Block)

Current spec text (§29671):

| `ActorThought` | `$primary-muted` 20% bg, max 10 lines (expandable), italic | Actor reasoning |

Current spec text (§29811):

| Background | `$primary-muted 20%` |

Proposed spec text (§29671):

| `ActorThought` | `$primary` 20% bg, max 10 lines (expandable) | Actor reasoning |

Proposed spec text (§29811):

| Background | `$primary 20%` |

Rationale: $primary-muted is not a standard Textual CSS variable. The Textual design system provides $primary, $secondary, $accent, $background, $surface, $panel, $boost, $warning, $error, $success, $text, $text-muted, and $text-disabled — but not $primary-muted. The implementation correctly uses $primary 20% (20% opacity of the primary color), which achieves the intended muted appearance. The "italic" text style was also removed from the spec table as the implementation does not set it and it is not required for the feature to function correctly.

Implementation file: src/cleveragents/tui/widgets/thought_block.py (line 62: background: $primary 20%;)

Change 2: WeightedCompositeScorer formula — multiplicative → weighted sum

Spec section: docs/specification.md §45067 (ACMS Pipeline Phase 2 defaults table)

Current spec text:

| FragmentScorer | `WeightedCompositeScorer` | Computes `composite = relevance_score * strategy_quality * hierarchy_weight * recency_bonus`. ...

Proposed spec text:

| FragmentScorer | `WeightedCompositeScorer` | Computes a weighted sum: `composite = (relevance_score × relevance_weight) + (hierarchy_factor × hierarchy_weight) + (strategy_quality × quality_weight) + (recency_bonus × recency_weight)`, clamped to [0.0, 1.0]. Default weights: relevance=0.4, hierarchy=0.3, quality=0.2, recency=0.1. Scoring weights are configurable via `ScorerWeights`. Uses **Decorator** pattern to compose scoring dimensions. |

Rationale: The multiplicative formula a * b * c * d collapses to near-zero if any single factor is small (e.g., a fragment with low recency bonus would score near-zero regardless of its relevance). The weighted sum is a better design: each dimension contributes independently, and the weights allow tuning the relative importance of each factor. The implementation uses the weighted sum approach with configurable weights (default: relevance=0.4, hierarchy=0.3, quality=0.2, recency=0.1). This is a genuine improvement over the spec's multiplicative formula.

Implementation file: src/cleveragents/application/services/acms_phase2.py (WeightedCompositeScorer._composite_from_components)

Change 3: ACMS Pipeline v1 Protocol Signatures — document simplified v1 interfaces

Spec section: docs/specification.md §44873–§44900 (FragmentScorerProtocol, BudgetPackerProtocol)

Current spec text (FragmentScorerProtocol):

class FragmentScorerProtocol(Protocol):
    def score(
        self,
        fragments: list[ContextFragment],
        plan_context: PlanContext,
    ) -> list[ScoredFragment]: ...

Current spec text (BudgetPackerProtocol):

class BudgetPackerProtocol(Protocol):
    def pack(
        self,
        scored_fragments: list[ScoredFragment],
        budget: int,
        detail_level_maps: DetailLevelMapRegistry,
    ) -> list[ContextFragment]: ...

Proposed addition (add a note after the protocol definitions):

v1 Implementation Note: The Phase 2 component implementations shipped in v3.5.0 use simplified v1 protocol signatures that omit plan_context and detail_level_maps parameters (not yet available in the v1 pipeline). The v1 FragmentScorer.score() takes (fragments: Sequence[ContextFragment]) -> Sequence[ContextFragment] and stores composite scores in the fragment's relevance_score field (with original score preserved in metadata["_original_relevance"]). The v1 BudgetPacker.pack() takes (fragments: Sequence[ContextFragment], budget: ContextBudget) -> Sequence[ContextFragment]. These v1 signatures are defined in acms_service.py and are the current runtime contracts. The full protocol signatures above are the target design for v2.

Rationale: The v1 implementation deliberately simplifies the protocol signatures because PlanContext and DetailLevelMapRegistry are not yet wired into the pipeline. The spec's full protocol signatures represent the target design. Adding a v1 note prevents confusion for implementors and documents the intentional simplification.

Implementation file: src/cleveragents/application/services/acms_service.py (FragmentScorer, BudgetPacker protocols)

Scope

Sections affected:

§29671 (Conversation Stream widget table)
§29811 (Actor Thought Block properties table)
§45067 (ACMS Phase 2 defaults table — FragmentScorer row)
§44873–§44900 (FragmentScorerProtocol and BudgetPackerProtocol definitions)

What Was NOT Changed

The following were reviewed and found to be correct deviations already tracked as UAT bugs:

project_access return type mismatch (tracked as #1444)
ContextTierService default values (tracked as #1443)
A2A error codes (tracked as #1426)
RouteConfig defaults (tracked as #1433, #1434)

The following were reviewed and found to match the spec:

PLAN_CANCELLED event enrichment (matches §46098)
PLAN_APPLIED event enrichment (matches §46097)
Estimation lifecycle hook 4-level fallback chain (matches §19099)
UKO runtime services (UKOQueryInterface, UKOInferenceEngine, UKOGraphPersistence match §45336–§45348)
First-run experience overlay (matches §29144)
PermissionsScreen diff modes (matches §29538)
Session export/import JSON+Markdown formats (matches §30200–§30212)

Monolithic/Split Status

docs/specification.md is 46,563 lines — well over the 3,000-line threshold. A separate proposal for the monolithic→split restructure will be filed as a follow-up.

Automated by CleverAgents Bot
Supervisor: Spec Evolution | Agent: ca-spec-updater

## Spec Update Proposal **Triggered by merged PRs**: #1287 (ACMS pipeline Phase 2), #1298 (TUI thought block rendering), #1312 (UKO runtime), #1310 (estimation lifecycle), #1300/#1301 (event enrichment), #1391 (first-run experience), #1392 (session export/import), #1307 (PermissionsScreen), #1293/#1286 (resource handlers) --- ## Summary of Proposed Changes After reviewing all 12 PRs merged on 2026-04-02 against the current specification, three spec sections need updating where the **implementation discovered a better approach** than what the spec described. --- ### Change 1: ThoughtBlockWidget CSS — `$primary-muted` → `$primary` **Spec section**: `docs/specification.md` §29671 and §29811 (TUI Conversation Stream / Actor Thought Block) **Current spec text** (§29671): ``` | `ActorThought` | `$primary-muted` 20% bg, max 10 lines (expandable), italic | Actor reasoning | ``` **Current spec text** (§29811): ``` | Background | `$primary-muted 20%` | ``` **Proposed spec text** (§29671): ``` | `ActorThought` | `$primary` 20% bg, max 10 lines (expandable) | Actor reasoning | ``` **Proposed spec text** (§29811): ``` | Background | `$primary 20%` | ``` **Rationale**: `$primary-muted` is not a standard Textual CSS variable. The Textual design system provides `$primary`, `$secondary`, `$accent`, `$background`, `$surface`, `$panel`, `$boost`, `$warning`, `$error`, `$success`, `$text`, `$text-muted`, and `$text-disabled` — but not `$primary-muted`. The implementation correctly uses `$primary 20%` (20% opacity of the primary color), which achieves the intended muted appearance. The "italic" text style was also removed from the spec table as the implementation does not set it and it is not required for the feature to function correctly. **Implementation file**: `src/cleveragents/tui/widgets/thought_block.py` (line 62: `background: $primary 20%;`) --- ### Change 2: WeightedCompositeScorer formula — multiplicative → weighted sum **Spec section**: `docs/specification.md` §45067 (ACMS Pipeline Phase 2 defaults table) **Current spec text**: ``` | FragmentScorer | `WeightedCompositeScorer` | Computes `composite = relevance_score * strategy_quality * hierarchy_weight * recency_bonus`. ... ``` **Proposed spec text**: ``` | FragmentScorer | `WeightedCompositeScorer` | Computes a weighted sum: `composite = (relevance_score × relevance_weight) + (hierarchy_factor × hierarchy_weight) + (strategy_quality × quality_weight) + (recency_bonus × recency_weight)`, clamped to [0.0, 1.0]. Default weights: relevance=0.4, hierarchy=0.3, quality=0.2, recency=0.1. Scoring weights are configurable via `ScorerWeights`. Uses **Decorator** pattern to compose scoring dimensions. | ``` **Rationale**: The multiplicative formula `a * b * c * d` collapses to near-zero if any single factor is small (e.g., a fragment with low recency bonus would score near-zero regardless of its relevance). The weighted sum is a better design: each dimension contributes independently, and the weights allow tuning the relative importance of each factor. The implementation uses the weighted sum approach with configurable weights (default: relevance=0.4, hierarchy=0.3, quality=0.2, recency=0.1). This is a genuine improvement over the spec's multiplicative formula. **Implementation file**: `src/cleveragents/application/services/acms_phase2.py` (WeightedCompositeScorer._composite_from_components) --- ### Change 3: ACMS Pipeline v1 Protocol Signatures — document simplified v1 interfaces **Spec section**: `docs/specification.md` §44873–§44900 (FragmentScorerProtocol, BudgetPackerProtocol) **Current spec text** (FragmentScorerProtocol): ```python class FragmentScorerProtocol(Protocol): def score( self, fragments: list[ContextFragment], plan_context: PlanContext, ) -> list[ScoredFragment]: ... ``` **Current spec text** (BudgetPackerProtocol): ```python class BudgetPackerProtocol(Protocol): def pack( self, scored_fragments: list[ScoredFragment], budget: int, detail_level_maps: DetailLevelMapRegistry, ) -> list[ContextFragment]: ... ``` **Proposed addition** (add a note after the protocol definitions): > **v1 Implementation Note**: The Phase 2 component implementations shipped in v3.5.0 use simplified v1 protocol signatures that omit `plan_context` and `detail_level_maps` parameters (not yet available in the v1 pipeline). The v1 `FragmentScorer.score()` takes `(fragments: Sequence[ContextFragment]) -> Sequence[ContextFragment]` and stores composite scores in the fragment's `relevance_score` field (with original score preserved in `metadata["_original_relevance"]`). The v1 `BudgetPacker.pack()` takes `(fragments: Sequence[ContextFragment], budget: ContextBudget) -> Sequence[ContextFragment]`. These v1 signatures are defined in `acms_service.py` and are the current runtime contracts. The full protocol signatures above are the target design for v2. **Rationale**: The v1 implementation deliberately simplifies the protocol signatures because `PlanContext` and `DetailLevelMapRegistry` are not yet wired into the pipeline. The spec's full protocol signatures represent the target design. Adding a v1 note prevents confusion for implementors and documents the intentional simplification. **Implementation file**: `src/cleveragents/application/services/acms_service.py` (FragmentScorer, BudgetPacker protocols) --- ## Scope Sections affected: - §29671 (Conversation Stream widget table) - §29811 (Actor Thought Block properties table) - §45067 (ACMS Phase 2 defaults table — FragmentScorer row) - §44873–§44900 (FragmentScorerProtocol and BudgetPackerProtocol definitions) ## What Was NOT Changed The following were reviewed and found to be **correct deviations** already tracked as UAT bugs: - `project_access` return type mismatch (tracked as #1444) - `ContextTierService` default values (tracked as #1443) - A2A error codes (tracked as #1426) - RouteConfig defaults (tracked as #1433, #1434) The following were reviewed and found to **match the spec**: - PLAN_CANCELLED event enrichment (matches §46098) - PLAN_APPLIED event enrichment (matches §46097) - Estimation lifecycle hook 4-level fallback chain (matches §19099) - UKO runtime services (UKOQueryInterface, UKOInferenceEngine, UKOGraphPersistence match §45336–§45348) - First-run experience overlay (matches §29144) - PermissionsScreen diff modes (matches §29538) - Session export/import JSON+Markdown formats (matches §30200–§30212) ## Monolithic/Split Status `docs/specification.md` is **46,563 lines** — well over the 3,000-line threshold. A separate proposal for the monolithic→split restructure will be filed as a follow-up. --- **Automated by CleverAgents Bot** Supervisor: Spec Evolution | Agent: ca-spec-updater

freemo added the

labels

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

freemo referenced this issue

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

[SPEC-UPDATER] Session State — ca-spec-updater #1461

freemo self-assigned this

2026-04-02 19:25:12 +00:00

freemo referenced this issue

2026-04-02 19:28:42 +00:00

[SPEC-UPDATER] Session State — ca-spec-updater #1461

freemo added

and removed

labels

2026-04-02 19:38:58 +00:00

freemo added this to the v3.8.0 milestone

2026-04-02 23:02:38 +00:00

freemo commented

2026-04-02 23:23:21 +00:00

Author

Owner

Milestone compliance fix applied:

Assigned to milestone: v3.8.0
Reason: Per CONTRIBUTING.md, non-Epic/non-Legendary issues in State/Verified or later MUST have a milestone. This issue was in State/Verified without a milestone and has been assigned to v3.8.0 as the most appropriate active milestone.

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

Milestone compliance fix applied: - Assigned to milestone: `v3.8.0` - Reason: Per CONTRIBUTING.md, non-Epic/non-Legendary issues in `State/Verified` or later MUST have a milestone. This issue was in `State/Verified` without a milestone and has been assigned to `v3.8.0` as the most appropriate active milestone. --- **Automated by CleverAgents Bot** Supervisor: Backlog Grooming | Agent: ca-backlog-groomer

freemo referenced this issue

2026-04-02 23:24:09 +00:00

[Automated] Backlog Groomer Session State — v3.7.0 #1463

freemo removed the

labels

2026-04-03 00:28:25 +00:00