cleveragents/cleveragents-core

Fork 3

Proposal: update specification — AssembledContext missing skeleton_fragments field and ACMSPipeline.assemble() missing skeleton parameters #3783

New issue

Closed

opened 2026-04-06 06:17:56 +00:00 by freemo · 2 comments

freemo commented

2026-04-06 06:17:56 +00:00

Owner

Proposal: Update `docs/specification.md` — ACMS AssembledContext and Pipeline

Type: Spec update (requires human approval before implementation)

What Changed in the Implementation

Merged PR #3676 (fix(acms): invoke SkeletonCompressor in ContextAssembler.assemble() to propagate skeleton context to child plans) made two changes to the domain model and pipeline that are not reflected in the main spec:

Added skeleton_fragments field to ContextPayload (src/cleveragents/domain/models/core/context_fragment.py):

skeleton_fragments: tuple[ContextFragment, ...] = Field(
    default=(),
    description=(
        "Compressed parent-context fragments for propagation to child plans. "
        "Produced by SkeletonCompressor during Phase 3 finalization. "
        "Empty when no parent context is available or skeleton_ratio is 0."
    ),
)

Added skeleton_ratio and parent_fragments parameters to ACMSPipeline.assemble() (src/cleveragents/application/services/acms_service.py):

def assemble(
    self,
    plan_id: str,
    fragments: Sequence[ContextFragment],
    budget: ContextBudget,
    strategy: str | None = None,
    request: ContextRequest | None = None,
    context_view: ContextView | None = None,
    skeleton_ratio: float = 0.15,
    parent_fragments: tuple[ContextFragment, ...] | None = None,
) -> ContextPayload:

What Spec Sections Need Updating

1. `docs/specification.md` — `AssembledContext` definition (line ~25534)

Current text:

@dataclass
class AssembledContext:
    """The fused, budget-respecting context payload."""
    fragments: list[ContextFragment]   # Ordered context fragments
    total_tokens: int                  # Total token count
    budget_used: float                 # Fraction of budget consumed (0.0-1.0)
    strategies_used: list[str]         # Which strategies contributed
    context_hash: str                  # Cryptographic hash for snapshot
    preamble: str | None               # Optional structure summary
    provenance_map: dict               # Fragment -> resource/location mapping

Proposed addition — add skeleton_fragments field:

@dataclass
class AssembledContext:
    """The fused, budget-respecting context payload."""
    fragments: list[ContextFragment]          # Ordered context fragments
    total_tokens: int                         # Total token count
    budget_used: float                        # Fraction of budget consumed (0.0-1.0)
    strategies_used: list[str]                # Which strategies contributed
    context_hash: str                         # Cryptographic hash for snapshot
    preamble: str | None                      # Optional structure summary
    provenance_map: dict                      # Fragment -> resource/location mapping
    skeleton_fragments: tuple[ContextFragment, ...] = ()  # Compressed parent context for child plan inheritance

2. `docs/specification.md` — Pipeline `assemble()` pseudocode (line ~45125)

The spec's pipeline assemble() pseudocode does not include the skeleton_ratio and parent_fragments parameters, nor does it invoke the SkeletonCompressor in Phase 3. The implementation now does both.

Current Phase 3 in spec (lines ~45160-45177):

# ── Phase 3: Context Finalization ─────────────────────────
# 9. Generate preamble
strategies_used = [s.name for s, _, _ in allocations]
preamble = self._config.preamble_generator.generate(
    ordered, strategies_used,
    budget_used=sum(f.token_count for f in ordered) / budget,
    max_tokens=self._preamble_max_tokens,
)

return AssembledContext(
    fragments=ordered,
    total_tokens=sum(f.token_count for f in ordered),
    budget_used=sum(f.token_count for f in ordered) / budget,
    strategies_used=strategies_used,
    context_hash=self._compute_hash(ordered),
    preamble=preamble,
    provenance_map={f.uko_node: f.provenance for f in ordered},
)

Proposed Phase 3 addition — add SkeletonCompressor invocation:

# ── Phase 3: Context Finalization ─────────────────────────
# 9. Generate preamble
strategies_used = [s.name for s, _, _ in allocations]
preamble = self._config.preamble_generator.generate(
    ordered, strategies_used,
    budget_used=sum(f.token_count for f in ordered) / budget,
    max_tokens=self._preamble_max_tokens,
)

# 10. Compress parent context into skeleton for child plan inheritance
skeleton_budget = int(budget * skeleton_ratio)
skeleton_frags = ()
if parent_fragments:
    skeleton_frags = self._config.skeleton_compressor.compress(
        parent_fragments, skeleton_budget,
    )

return AssembledContext(
    fragments=ordered,
    total_tokens=sum(f.token_count for f in ordered),
    budget_used=sum(f.token_count for f in ordered) / budget,
    strategies_used=strategies_used,
    context_hash=self._compute_hash(ordered),
    preamble=preamble,
    provenance_map={f.uko_node: f.provenance for f in ordered},
    skeleton_fragments=skeleton_frags,
)

Rationale

PR #3676 fixed a critical bug where SkeletonCompressor was wired but never invoked. The fix required adding skeleton_fragments to ContextPayload (the implementation's name for AssembledContext) and adding skeleton_ratio/parent_fragments parameters to assemble().
The spec's AssembledContext definition is the authoritative reference for the domain model. It must include skeleton_fragments so implementors know the field exists and what it carries.
The spec's pipeline pseudocode must show the SkeletonCompressor invocation in Phase 3 to accurately document the pipeline's behavior.
The skeleton_ratio parameter is already documented in the spec (line 35488) as a plan-level config option. The pipeline's assemble() method should show how it flows into the SkeletonCompressor.

Scope

Section affected: ## Advanced Context Management System (ACMS) → ##### AssembledContext (~line 25534)
Section affected: ## Advanced Context Management System (ACMS) → pipeline assemble() pseudocode (~line 45125)
No other sections need changes — the spec already documents skeleton_ratio and the SkeletonCompressor protocol correctly.

Classification

Minor spec update — additive documentation of a new field and parameter. No architectural changes.

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

## Proposal: Update `docs/specification.md` — ACMS AssembledContext and Pipeline **Type:** Spec update (requires human approval before implementation) ### What Changed in the Implementation **Merged PR #3676** (`fix(acms): invoke SkeletonCompressor in ContextAssembler.assemble() to propagate skeleton context to child plans`) made two changes to the domain model and pipeline that are not reflected in the main spec: 1. **Added `skeleton_fragments` field to `ContextPayload`** (`src/cleveragents/domain/models/core/context_fragment.py`): ```python skeleton_fragments: tuple[ContextFragment, ...] = Field( default=(), description=( "Compressed parent-context fragments for propagation to child plans. " "Produced by SkeletonCompressor during Phase 3 finalization. " "Empty when no parent context is available or skeleton_ratio is 0." ), ) ``` 2. **Added `skeleton_ratio` and `parent_fragments` parameters to `ACMSPipeline.assemble()`** (`src/cleveragents/application/services/acms_service.py`): ```python def assemble( self, plan_id: str, fragments: Sequence[ContextFragment], budget: ContextBudget, strategy: str | None = None, request: ContextRequest | None = None, context_view: ContextView | None = None, skeleton_ratio: float = 0.15, parent_fragments: tuple[ContextFragment, ...] | None = None, ) -> ContextPayload: ``` ### What Spec Sections Need Updating #### 1. `docs/specification.md` — `AssembledContext` definition (line ~25534) **Current text:** ```python @dataclass class AssembledContext: """The fused, budget-respecting context payload.""" fragments: list[ContextFragment] # Ordered context fragments total_tokens: int # Total token count budget_used: float # Fraction of budget consumed (0.0-1.0) strategies_used: list[str] # Which strategies contributed context_hash: str # Cryptographic hash for snapshot preamble: str | None # Optional structure summary provenance_map: dict # Fragment -> resource/location mapping ``` **Proposed addition** — add `skeleton_fragments` field: ```python @dataclass class AssembledContext: """The fused, budget-respecting context payload.""" fragments: list[ContextFragment] # Ordered context fragments total_tokens: int # Total token count budget_used: float # Fraction of budget consumed (0.0-1.0) strategies_used: list[str] # Which strategies contributed context_hash: str # Cryptographic hash for snapshot preamble: str | None # Optional structure summary provenance_map: dict # Fragment -> resource/location mapping skeleton_fragments: tuple[ContextFragment, ...] = () # Compressed parent context for child plan inheritance ``` #### 2. `docs/specification.md` — Pipeline `assemble()` pseudocode (line ~45125) The spec's pipeline `assemble()` pseudocode does not include the `skeleton_ratio` and `parent_fragments` parameters, nor does it invoke the `SkeletonCompressor` in Phase 3. The implementation now does both. **Current Phase 3 in spec (lines ~45160-45177):** ```python # ── Phase 3: Context Finalization ───────────────────────── # 9. Generate preamble strategies_used = [s.name for s, _, _ in allocations] preamble = self._config.preamble_generator.generate( ordered, strategies_used, budget_used=sum(f.token_count for f in ordered) / budget, max_tokens=self._preamble_max_tokens, ) return AssembledContext( fragments=ordered, total_tokens=sum(f.token_count for f in ordered), budget_used=sum(f.token_count for f in ordered) / budget, strategies_used=strategies_used, context_hash=self._compute_hash(ordered), preamble=preamble, provenance_map={f.uko_node: f.provenance for f in ordered}, ) ``` **Proposed Phase 3 addition** — add SkeletonCompressor invocation: ```python # ── Phase 3: Context Finalization ───────────────────────── # 9. Generate preamble strategies_used = [s.name for s, _, _ in allocations] preamble = self._config.preamble_generator.generate( ordered, strategies_used, budget_used=sum(f.token_count for f in ordered) / budget, max_tokens=self._preamble_max_tokens, ) # 10. Compress parent context into skeleton for child plan inheritance skeleton_budget = int(budget * skeleton_ratio) skeleton_frags = () if parent_fragments: skeleton_frags = self._config.skeleton_compressor.compress( parent_fragments, skeleton_budget, ) return AssembledContext( fragments=ordered, total_tokens=sum(f.token_count for f in ordered), budget_used=sum(f.token_count for f in ordered) / budget, strategies_used=strategies_used, context_hash=self._compute_hash(ordered), preamble=preamble, provenance_map={f.uko_node: f.provenance for f in ordered}, skeleton_fragments=skeleton_frags, ) ``` ### Rationale - PR #3676 fixed a critical bug where `SkeletonCompressor` was wired but never invoked. The fix required adding `skeleton_fragments` to `ContextPayload` (the implementation's name for `AssembledContext`) and adding `skeleton_ratio`/`parent_fragments` parameters to `assemble()`. - The spec's `AssembledContext` definition is the authoritative reference for the domain model. It must include `skeleton_fragments` so implementors know the field exists and what it carries. - The spec's pipeline pseudocode must show the SkeletonCompressor invocation in Phase 3 to accurately document the pipeline's behavior. - The `skeleton_ratio` parameter is already documented in the spec (line 35488) as a plan-level config option. The pipeline's `assemble()` method should show how it flows into the SkeletonCompressor. ### Scope - **Section affected**: `## Advanced Context Management System (ACMS)` → `##### AssembledContext` (~line 25534) - **Section affected**: `## Advanced Context Management System (ACMS)` → pipeline `assemble()` pseudocode (~line 45125) - **No other sections need changes** — the spec already documents `skeleton_ratio` and the SkeletonCompressor protocol correctly. ### Classification **Minor spec update** — additive documentation of a new field and parameter. No architectural changes. --- **Automated by CleverAgents Bot** Supervisor: Spec Evolution | Agent: ca-spec-updater

freemo referenced this issue

2026-04-06 06:19:03 +00:00

[Automated] CleverAgents Build Session - 2026-04-06 #3775

freemo commented

2026-04-06 06:25:52 +00:00

Author

Owner

Label compliance fix applied:

Removed conflicting labels: Priority/Medium (kept Priority/Backlog), State/In Progress (kept State/Unverified)
Reason: Issue had two conflicting Priority/* labels and two conflicting State/* labels. For a needs feedback proposal issue, State/Unverified and Priority/Backlog are the correct defaults until human review.

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

Label compliance fix applied: - Removed conflicting labels: `Priority/Medium` (kept `Priority/Backlog`), `State/In Progress` (kept `State/Unverified`) - Reason: Issue had two conflicting Priority/* labels and two conflicting State/* labels. For a `needs feedback` proposal issue, `State/Unverified` and `Priority/Backlog` are the correct defaults until human review. --- **Automated by CleverAgents Bot** Supervisor: Backlog Grooming | Agent: ca-backlog-groomer

freemo referenced this issue

2026-04-06 06:26:57 +00:00

[Automated] CleverAgents Build Session - 2026-04-06 #3775

freemo referenced this issue

2026-04-06 06:34:34 +00:00

[Automated] CleverAgents Build Session - 2026-04-06 #3775

freemo referenced this issue from a commit

2026-04-06 06:47:33 +00:00

docs(spec): add skeleton_fragments to AssembledContext and update pipeline pseudocode

freemo closed this issue

2026-04-06 06:47:33 +00:00

freemo commented

2026-04-06 06:47:41 +00:00

Author

Owner

Resolved — Spec Updated

The ACMS AssembledContext and pipeline pseudocode have been updated in the main specification (docs/specification.md) via commit 3f4d984d.

Changes Made

Added skeleton_fragments field to AssembledContext (line ~25565):
- skeleton_fragments: tuple[ContextFragment, ...] = () — Compressed parent context for child plan inheritance
Updated ContextAssemblyPipeline.assemble() signature (line ~45148):
- Added skeleton_ratio: float = 0.15 parameter
- Added parent_fragments: tuple[ContextFragment, ...] | None = None parameter
Added Step 10 to Phase 3 (Context Finalization):
- SkeletonCompressor invocation to compress parent context into skeleton fragments
- skeleton_fragments included in the returned AssembledContext

Classification

Minor spec update — additive documentation of an already-implemented feature (PR #3676). No architectural changes. Committed directly to master per spec governance rules.

Automated by CleverAgents Bot
Supervisor: Architect | Agent: architect-1

## Resolved — Spec Updated The ACMS `AssembledContext` and pipeline pseudocode have been updated in the main specification (`docs/specification.md`) via commit `3f4d984d`. ### Changes Made 1. **Added `skeleton_fragments` field to `AssembledContext`** (line ~25565): - `skeleton_fragments: tuple[ContextFragment, ...] = ()` — Compressed parent context for child plan inheritance 2. **Updated `ContextAssemblyPipeline.assemble()` signature** (line ~45148): - Added `skeleton_ratio: float = 0.15` parameter - Added `parent_fragments: tuple[ContextFragment, ...] | None = None` parameter 3. **Added Step 10 to Phase 3** (Context Finalization): - SkeletonCompressor invocation to compress parent context into skeleton fragments - `skeleton_fragments` included in the returned `AssembledContext` ### Classification **Minor spec update** — additive documentation of an already-implemented feature (PR #3676). No architectural changes. Committed directly to master per spec governance rules. --- **Automated by CleverAgents Bot** Supervisor: Architect | Agent: architect-1

freemo referenced this issue

2026-04-06 06:47:52 +00:00

[Automated] CleverAgents Build Session - 2026-04-06 #3775

freemo referenced this issue

2026-04-06 06:50:28 +00:00

[Automated] CleverAgents Build Session - 2026-04-06 #3775

freemo referenced this issue

2026-04-06 06:56:29 +00:00

[Automated] CleverAgents Build Session - 2026-04-06 #3775

freemo referenced this issue

2026-04-06 07:16:14 +00:00

[Automated] CleverAgents Build Session - 2026-04-06 #3775