feat(acms): add skeleton compressor #525

2026-03-03T01:58:16Z

freemo commented

2026-03-03 01:58:16 +00:00

Summary

Implements the ACMS skeleton compressor service for context inheritance between parent and child plans.

Closes #194

Approach

SkeletonMetadata (frozen Pydantic model): records compression ratio, original/compressed token counts, and source decision IDs for auditability. Persisted on the Plan model as skeleton_metadata.
SkeletonCompressorService: stateless service that accepts context fragments and a skeleton_ratio in [0.0, 1.0], sorts fragments by relevance (descending, stable), and greedily selects fragments within a token budget of original_tokens * (1 - ratio).
Ratio semantics: 0.0 = pass-through, 1.0 = max compression (single top fragment), default = 0.3.
Deterministic ordering: stable sort on (-relevance, fragment_id) ensures identical inputs always produce identical output.
DI registration: skeleton_compressor_service singleton in the container.

Changes

New files (8)

src/cleveragents/domain/models/core/skeleton_metadata.py
src/cleveragents/application/services/skeleton_compressor.py
docs/reference/skeleton_compressor.md
features/skeleton_compressor.feature (22 scenarios)
features/steps/skeleton_compressor_steps.py
robot/skeleton_compressor.robot (6 smoke tests)
robot/helper_skeleton_compressor.py
benchmarks/skeleton_compressor_bench.py

Modified files (6)

src/cleveragents/domain/models/core/plan.py — added skeleton_metadata field
src/cleveragents/domain/models/core/__init__.py — exported SkeletonMetadata
src/cleveragents/application/services/__init__.py — exported service symbols
src/cleveragents/application/container.py — registered service
vulture_whitelist.py — added public API entries
CHANGELOG.md — added entry

Quality Gates

Lint: passed
Typecheck: 0 errors (Pyright strict)
Unit tests: 22/22 skeleton scenarios pass
Integration tests: 6/6 Robot tests pass
Coverage: 97% (meets threshold)
Benchmarks: validated at 10/100/1000 fragment scales

## Summary Implements the ACMS skeleton compressor service for context inheritance between parent and child plans. Closes #194 ## Approach - **SkeletonMetadata** (frozen Pydantic model): records compression ratio, original/compressed token counts, and source decision IDs for auditability. Persisted on the `Plan` model as `skeleton_metadata`. - **SkeletonCompressorService**: stateless service that accepts context fragments and a `skeleton_ratio` in [0.0, 1.0], sorts fragments by relevance (descending, stable), and greedily selects fragments within a token budget of `original_tokens * (1 - ratio)`. - **Ratio semantics**: 0.0 = pass-through, 1.0 = max compression (single top fragment), default = 0.3. - **Deterministic ordering**: stable sort on `(-relevance, fragment_id)` ensures identical inputs always produce identical output. - **DI registration**: `skeleton_compressor_service` singleton in the container. ## Changes ### New files (8) - `src/cleveragents/domain/models/core/skeleton_metadata.py` - `src/cleveragents/application/services/skeleton_compressor.py` - `docs/reference/skeleton_compressor.md` - `features/skeleton_compressor.feature` (22 scenarios) - `features/steps/skeleton_compressor_steps.py` - `robot/skeleton_compressor.robot` (6 smoke tests) - `robot/helper_skeleton_compressor.py` - `benchmarks/skeleton_compressor_bench.py` ### Modified files (6) - `src/cleveragents/domain/models/core/plan.py` — added `skeleton_metadata` field - `src/cleveragents/domain/models/core/__init__.py` — exported `SkeletonMetadata` - `src/cleveragents/application/services/__init__.py` — exported service symbols - `src/cleveragents/application/container.py` — registered service - `vulture_whitelist.py` — added public API entries - `CHANGELOG.md` — added entry ## Quality Gates - Lint: passed - Typecheck: 0 errors (Pyright strict) - Unit tests: 22/22 skeleton scenarios pass - Integration tests: 6/6 Robot tests pass - Coverage: 97% (meets threshold) - Benchmarks: validated at 10/100/1000 fragment scales

freemo added the

Type

Feature

label 2026-03-03 02:15:12 +00:00

freemo added this to the v3.4.0 milestone 2026-03-03 02:27:46 +00:00

freemo force-pushed feature/m6-acms-skeleton-compress from 46f585e1d8 to e9ef585800

2026-03-03 03:11:20 +00:00

Compare

freemo scheduled this pull request to auto merge when all checks succeed 2026-03-03 03:11:35 +00:00

freemo scheduled this pull request to auto merge when all checks succeed 2026-03-03 03:11:48 +00:00

freemo force-pushed feature/m6-acms-skeleton-compress from e9ef585800 to 0bafa7b9f9

2026-03-03 03:30:52 +00:00