Implemented SkeletonCompressorService for ACMS context inheritance, producing
compressed context representations for propagation from parent plans to child
plans. Key design decisions and implementation details:
- SkeletonMetadata (frozen Pydantic model): records ratio, original_tokens,
compressed_tokens, and source_decision_ids for full auditability of each
compression pass. Persisted on Plan.skeleton_metadata.
- SkeletonCompressorService: stateless service accepting a list of
ContextFragment objects and a skeleton_ratio in [0.0, 1.0]. Fragments are
sorted by relevance descending with a stable secondary sort on fragment_id
to guarantee deterministic output. Token budget is original_tokens*(1-ratio);
fragments are greedily selected until budget is exhausted.
- Ratio semantics: 0.0 = no compression (pass-through), 1.0 = maximum
compression (single top fragment only), None = default 0.3.
- Integration: Plan model gains optional skeleton_metadata field exposed in
as_cli_dict() under the 'skeleton' key. Service registered in DI container
as skeleton_compressor_service (Singleton, stateless).
- Tests: 22 BDD scenarios (features/skeleton_compressor.feature) covering
ratio validation, stable ordering, metadata correctness, edge cases, and
plan model integration. 6 Robot Framework smoke tests. ASV benchmark suites
at 10/100/1000 fragment scales.
- Documentation: docs/reference/skeleton_compressor.md with ratio table,
algorithm description, metadata schema, and multi-decision plan example.
ISSUES CLOSED: #194
Implemented the Backend Abstraction Layer (BAL) for the Advanced Context
Management System, following the specification in docs/specification.md
Section ACMS > Backend Abstraction Layer and ADR-014.
Key additions:
- TextBackend protocol with search(query, scope, max_results) returning
list[TextResult], and TextResult frozen dataclass (uko_uri, content,
score, metadata fields)
- VectorBackend protocol with similarity_search(embedding, scope, top_k)
returning list[VectorResult], and VectorResult frozen dataclass
- GraphBackend protocol with sparql_query(query, scope),
get_triples(subject), and traverse(start, depth) methods returning
GraphResult frozen dataclass (triples, metadata fields)
- In-memory stub backends (InMemoryTextBackend, InMemoryVectorBackend,
InMemoryGraphBackend) that validate arguments and return empty results,
serving as development placeholders and test doubles
- DI container registration as configurable Singletons with provider
selection via override_providers()
- Behave BDD feature (35 scenarios / 83 steps) covering protocol
compliance, argument validation, result immutability, and DI resolution
- Robot Framework smoke tests (6 tests) for integration verification
- ASV benchmarks for stub query overhead and instantiation time
- Reference documentation at docs/reference/acms_backends.md
Design decisions:
- Used @runtime_checkable Protocol for structural subtyping, consistent
with existing ResourceHandler pattern
- Used frozen dataclasses (not Pydantic) for result types to minimize
overhead in the hot path of context assembly
- scope parameter typed as frozenset[str] for immutability and hashability
- Stubs registered as default Singletons; production backends swap via DI
ISSUES CLOSED: #498
Added three new built-in resource types: container-instance,
devcontainer-instance, and devcontainer-file. The devcontainer-instance
type inherits from container-instance per ADR-042 and is auto-discovered
when git-checkout or fs-directory resources contain .devcontainer/
directories per ADR-043.
Implementation includes:
- DevcontainerHandler extending BaseResourceHandler with snapshot strategy
- Auto-discovery module scanning .devcontainer/devcontainer.json and
root .devcontainer.json with JSON validation
- CLI support for devcontainer-instance and container-instance via
agents resource add with --path and --image flags
- Behave feature with 22 scenarios covering manual registration,
auto-discovery, invalid JSON handling, and protocol conformance
- Robot integration tests with 10 test cases for CLI round-trip and
DAG hierarchy validation
- ASV benchmarks measuring discovery throughput with varying subdirectory
counts, handler resolver cache performance, and result construction
- Reference documentation at docs/reference/devcontainer_resources.md
ISSUES CLOSED: #511
Add SafetyProfile domain model with configurable safety constraints
(checkpoint, human approval, cost limits, retry limits, skill
categories, sandbox requirement). Integrate into Action model with
from_config/as_cli_dict support, and persist via LifecycleActionModel
safety_profile_json column.
Include resolve_safety_profile() stub that raises NotImplementedError
for local mode, signalling that real enforcement is deferred.
Add comprehensive test coverage:
- 20 BDD scenarios in features/safety_profile.feature
- 6 Robot Framework smoke tests
- 5 ASV benchmark suites (11 timing functions)
Add docs/reference/safety_profile.md reference documentation.
ISSUES CLOSED: #332
Add --project flag to config set, config get, and config list CLI
commands, enabling per-project configuration overrides stored under
[project."<name>"] TOML tables in the global config file.
Project-scoped resolution slots between environment variable and global
levels in the ConfigService resolution chain. config list --project
shows only overrides for the named project with source annotations.
Implementation:
- ConfigService: add set_project_value() and get_project_overrides()
methods for TOML-backed project-scoped persistence and retrieval
- CLI config commands: wire --project flag through set, get, and list
subcommands; project-scoped list filters to overrides only
- Database persistence: project-scoped config stored as alternative
backend for projects not using TOML
- Documentation: update docs/reference/config_resolution.md with
project-scopable key lists, CLI examples, precedence diagram, and
non-scopable key rejection behavior
Tests:
- Behave: 12 BDD scenarios in features/config_project_scope.feature
covering set/get/list, precedence over global defaults, and
non-scopable key rejection
- Robot: 5 integration smoke tests in robot/config_project_scope.robot
for end-to-end project-scoped round-trip verification
- ASV: benchmarks/config_project_scope_bench.py measuring resolution
overhead with project scope active
All nox quality gates pass: lint, typecheck, unit_tests (7522 scenarios),
integration_tests (Config Project Scope suite passed), and coverage at
98% line rate (threshold 97%).
Closes#259
Add protocol stubs for remote server communication infrastructure:
- ServerClient: Health check and version negotiation protocol
- RemoteExecutionClient: Remote plan execution and status protocol
- AuthClient: Authentication and token management protocol
- StubServerClient/StubRemoteExecutionClient/StubAuthClient: Stub
implementations raising NotImplementedError for all methods
- ServerConnectionConfig: Validated config model (server_url, namespace,
auth_token_ref, tls_verify)
- Config keys: core.server_url, core.server_namespace, core.server_tls_verify
- CLI: agents connect <url> stub command with explicit warning
- CLI: agents info shows Server Mode (disabled/stubbed)
ISSUES CLOSED: #201
Add SubplanService for building child plans from DecisionService spawn
entries and SubplanConfig. The service validates resource scopes, merge
strategies, and max_parallel bounds before spawning.
Key additions:
- SubplanService: Orchestrates child plan creation from spawn entries
- SpawnMetadata: Persisted metadata (spawn_decision_id, parent/root
plan IDs, execution mode) for status output
- Spawn validation: Checks resource scopes, merge strategy, and
parallelism bounds before spawning
- Documentation: subplan_service.md with spawn workflow and lifecycle
ISSUES CLOSED: #197
- Return parent_decision_id in handler result dict and add meaningful
assertion to the corresponding Behave scenario (B1)
- Add ULID format validators to SubplanPayload for plan_id, dependencies,
and parent_decision_id, consistent with Decision model validation (S1)
- Add non-empty string validator for resource_scopes items (S2)
- Narrow broad except Exception to except (ValidationError, ValueError)
so programming errors surface as real failures (S3)
- Document strategy_with_subplan.yaml in actors_examples.md and assert
it is referenced in the "Verify all examples are documented" scenario (B2)
ISSUES CLOSED: #198
Replace coverage.py (sys.settrace-based) with slipcover (bytecode-based
instrumentation) for significantly faster coverage collection:
- Each behave-parallel worker runs under slipcover, producing per-feature
JSON coverage files with unique UUIDs to avoid write contention.
- After all workers finish, slipcover --merge combines per-worker data
into a single build/coverage.json report.
- XML report generated via slipcover --merge --xml for CI tooling.
- Terminal report with --fail-under=97 threshold enforcement.
- Robust JSON key-fallback logic handles both slipcover and coverage.py
output formats.
- CI workflow (ci.yml, nightly-quality.yml) updated with defensive key
lookup instead of hardcoded coverage.py format.
- Documentation updated to reflect slipcover as the coverage tool.
- CHANGELOG.md updated.
ISSUES CLOSED: #482
Created ADR-042 (Resource Type Inheritance) defining single-inheritance
`inherits` field on resource type definitions with field resolution,
collection merging, handler inheritance, polymorphic tool binding,
auto-discovery, and DAG query matching. Max depth 5, single inheritance.
Created ADR-043 (Devcontainer Integration) defining devcontainer-instance
as a subtype of container-instance with lazy activation lifecycle,
devcontainer.json parsing, three container-project association patterns
(auto-detect, explicit mount, clone-into), and execution environment
routing with a 6-level precedence chain.
Specification updates across 20+ sections:
- Glossary: Resource Type Inheritance, Devcontainer, Execution Environment
- Resource type YAML schema: `inherits` field with structure reference
- Handler, sandbox strategy, and coherence tables: devcontainer-instance
- Auto-discovery: devcontainer detection subsection with WBS diagram
- Tool capability metadata: structured environment subfields
- Technology stack: devcontainer CLI row
- Project model: execution environment subsection with YAML example
- CLI agents resource add: --mount, --clone-into flags + 4 new examples
- CLI agents plan use: --execution-environment, --execution-env-priority
- CLI agents project context set: same execution environment flags
- Command synopsis block: updated for all new flags
- Execution environment routing section with precedence table + algorithm
- Resource type YAML Example 6: Devcontainer Instance (inherited type)
- End-to-end Example 16: Devcontainer-Driven Development
- End-to-end Example 17: Explicit Container with Directory Mount
- End-to-end Example 18: Container with Remote Repo Clone
Also fixed ADR index: added missing ADR-036 through ADR-040 entries,
updated next ADR number to 044.
CONTRIBUTING.md fixes backported from sister project:
- Fixed State label capitalization (State/In Progress -> State/In progress,
State/In Review -> State/In review) to match label definitions.
- Subtasks section: changed from optional to required, with exception
clause for trivially simple issues.
- Parent links: updated to use Forgejo dependency system instead of
textual references in issue descriptions.
- Fixed nox session flag typos: nox -e -> nox -s (7 occurrences).
- Replaced "Epics and Legendaries" section with comprehensive "Ticket
Type Hierarchy" defining the three-tier hierarchy (Issue -> Epic ->
Legendary) with formal criteria tables, cross-cutting rules for
hierarchy enforcement, completion semantics, promotion/demotion, and
milestone relationship rules.
- Fixed broken internal links referencing old "Epics and Legendaries"
anchor to use "Ticket Type Hierarchy" (3 occurrences).
- Traceability example: replaced project-specific code reference with
generic example.
- Removed stray horizontal rule before Project-Specific Guidelines.
ISSUES CLOSED: #491
Implement SubplanExecutionService and SubplanMergeService to enable
parent plans to decompose work into coordinated child subplans with
configurable execution modes (sequential, parallel, dependency-ordered)
and merge strategies (git_three_way, sequential_apply, fail_on_conflict,
last_wins).
- SubplanExecutionService: schedules subplan execution with retry
support via SubplanFailureHandler, max_parallel limits, fail_fast
semantics, and topological DAG ordering for dependency mode
- SubplanMergeService: wraps sandbox merge infrastructure to combine
subplan sandbox outputs using the configured merge strategy
- BDD tests: 21 scenarios covering all execution modes, merge
strategies, validation, and integration flows
- Robot tests: 11 integration test cases with helper module
- ASV benchmarks: performance benchmarks for execution and merge
- Documentation: reference guide in docs/reference/subplans.md
ISSUES CLOSED: #184
Implement the complete configuration system with multi-level resolution
chain, typed key registry, and CLI integration per specification.
ConfigService changes:
- Expand _build_catalog() to register all 102 spec-aligned config keys
across 8 groups: core (14), server (4), actor (5), plan (8),
sandbox (5), index (12), context (43), provider (11)
- Each key carries exact dotted-dash name, Python type, default value,
explicit env var name per spec, project-scopability flag, and
description
- Fix _env_name() to convert dots and dashes to underscores
- Provider keys use standard env var names (e.g., OPENAI_API_KEY)
CLI commands rewiring:
- Rewrite config set/get/list to use ConfigService instead of Settings
- Add --verbose flag to config get showing full 5-level resolution chain
- Add --project flag to config set/get/list for project-scoped overrides
- Support both glob and regex patterns in config list
- Validate keys against ConfigService registry with actionable errors
- Retain backward-compatible helper functions delegating to ConfigService
Documentation:
- Add docs/reference/config_resolution.md covering resolution chain,
all 102 config keys, CLI commands, TOML format, and provider credentials
Testing:
- Update all 4 Behave feature files and step definitions to use new
spec-aligned key names, env vars, and defaults (119 scenarios passing)
- Add robot/config_resolution.robot with 10 integration test cases
- Add benchmarks/config_resolution_bench.py with 8 time + 2 memory suites
ISSUES CLOSED: #258
Add runtime autonomy constraints (max steps, tool budget, required
confirmations) and a structured audit trail for plan execution.
New domain models:
- AutonomyGuardrails: enforces step limits, tool budgets, and
confirmation gates with validators and check methods
- GuardrailAuditEntry: records each enforcement event with timestamp,
event type, guard name, result, reason, and context
- GuardrailAuditTrail: ordered collection of audit entries persisted
to plan metadata
New service:
- AutonomyGuardrailService: high-level service for configuring
guardrails per plan, checking constraints, recording audit entries,
and serializing/restoring state via plan metadata
Tests:
- Behave: 69 scenarios covering model validation, step/budget/
confirmation checks, audit trail recording, and service operations
- Robot: 8 test cases for autonomy guardrail CLI flag smoke testing
- ASV: 6 benchmark suites measuring enforcement overhead
Documentation:
- Updated docs/reference/automation_profiles.md with guardrail fields,
enforcement behavior, audit trail schema, and event type reference
ISSUES CLOSED: #204
Implemented namespace/project/plan/skill permission model with role
bindings (owner/admin/editor/viewer) and default deny policy. Added
enforcement hooks at CLI/service boundaries that are server-only; local
mode returns permissive defaults. Includes role enums, permission check
service, role matrix documentation.
Includes Behave BDD scenarios, Robot integration tests, ASV benchmarks,
and reference documentation.
ISSUES CLOSED: #344
Add SafetyProfile as a first-class concept in the specification, composed
within AutomationProfile via a 'safety' field. This eliminates the
dual-authority problem where both AutomationProfile and a separate
SafetyProfile defined the same three safety booleans (require_sandbox,
require_checkpoints, allow_unsafe_tools) with no spec-defined resolution.
Changes:
- specification.md: Add Safety Profile glossary entry, split Automatable
Tasks into thresholds + Safety Profile sub-section, update built-in
profile matrix with safety.* prefix, update YAML examples
- ADR-041 (new): Document composition decision, field schema, relationship
to Guards, constraints, consequences, rejected alternatives (inheritance,
mixin, flat)
- ADR-017: Update profile fields table, built-in profiles, constraints,
risks, and cross-reference to ADR-041
- reference/automation_profiles.md: Rename Safety Fields to Safety Profile
sub-section, expand built-in matrix, update YAML examples
- schema/automation_profile.schema.yaml: Nest safety fields under safety
object with all SafetyProfile fields
- adr/index.md: Add ADR-041 to Tier 3 inventory
Resolves spec gap identified in issue #332.
Introduce a lightweight checkpoint/rollback system for sandbox state
during plan execute and apply flows. CheckpointManager snapshots
the sandbox working directory before each phase and can restore it
on failure, giving the execution engine a reliable undo mechanism.
Key changes:
- SandboxCheckpoint model, Checkpointable protocol, and
CheckpointManager in infrastructure/sandbox/checkpoint.py
- PlanExecutor gains optional checkpoint_manager with pre/post
execute hooks and automatic rollback on failure
- PlanApplyService gains optional checkpoint_manager with pre-apply
checkpoint and rollback helper
- 12 BDD scenarios (features/sandbox_checkpoints.feature)
- 5 Robot Framework smoke tests (robot/sandbox_checkpoint_smoke.robot)
- ASV benchmarks for creation, rollback, and listing operations
- Reference documentation in docs/reference/sandbox.md
ISSUES CLOSED: #183
Add Alembic migration m4_002_skill_flattened_tools to extend the skills
table with five new columns: flattened_tools_json, includes_json,
capability_summary_json, yaml_text, and flattening_hash (SHA-256). A
defence-in-depth uniqueness constraint (uq_skills_name) is also added.
Update SkillModel with the new column definitions and extend
SkillRepository with update_flattened_tools(), get_flattened_tools(),
needs_refresh(), recompute_flattening_hash(), and
invalidate_cached_summaries() methods. The existing update() method
now nulls all cached fields on mutation (hash-based invalidation).
All new repository methods follow the session-factory pattern with
@database_retry and flush-but-don-t-commit semantics. Structured
logging via structlog records cache updates and invalidations.
Database schema docs updated with the new skills table columns and a
persistence-field-to-domain-model mapping table.
Tests:
- 6 Behave scenarios covering create, invalidation, hash staleness,
refresh recomputation, uniqueness constraint, and namespace filtering
- 2 Robot Framework smoke tests (round-trip and invalidation)
- 3 ASV benchmarks (persist, refresh check, namespace list)
ISSUES CLOSED: #166
Create DecisionService application-layer service that wraps
DecisionRepository with structured logging and UnitOfWork transaction
management. Wire DecisionService and PlanLifecycleService into the DI
container as Factory providers.
Inject DecisionService into PlanLifecycleService so that phase
transitions automatically record decisions: start_strategize records a
strategy_choice decision and start_execute records an
implementation_choice decision. Decision recording is optional and
never blocks lifecycle transitions.
Add Behave feature (5 scenarios), Robot Framework smoke tests (2 test
cases), ASV benchmarks (3 benchmark classes), and DI reference
documentation.
ISSUES CLOSED: #173
freemo
CoreRasurae
aditya
brent.edwards