cleveragents-core/CHANGELOG.md

Changelog

Unreleased

• Added general-purpose domain event system under cleveragents.infrastructure.events. EventType StrEnum defines 38 typed event identifiers across 9 domains (plan lifecycle, decision, invariant, actor, tool, resource, sandbox, context, validation, session, budget). DomainEvent is a frozen Pydantic model with event_type, auto-UTC timestamp, auto-ULID correlation_id, plan_id, root_plan_id, session_id, actor_name, project_name, and details fields. EventBus is a @runtime_checkable Protocol with emit() and subscribe() methods. ReactiveEventBus is an RxPY Subject-backed in-process bus that dispatches synchronously to type-filtered handlers and exposes a raw rx.Observable stream for advanced operators. LoggingEventBus is a structlog-based bus for audit logging that requires no RxPY dependency. DecisionService and PlanLifecycleService accept an optional event_bus parameter (backward-compatible) and emit DECISION_CREATED, PLAN_CREATED, and PLAN_PHASE_CHANGED on significant state changes. ReactiveEventBus is registered as a Singleton in the DI container and wired into both services automatically. Includes Behave BDD unit tests (27 scenarios, 75 steps, 100% coverage on all new source files), Robot Framework smoke tests (9 cases), ASV performance benchmarks (5 suites), and reference documentation (docs/reference/event_bus.md). (#473)
• Validated M4 acceptance criteria for v3.3.0 milestone closure. All M4 E2E verification tests and correction/subplan smoke tests pass against the final v3.3.0 implementation. Added CLI-exercising integration tests for plan use, plan execute, and plan tree commands to verify the milestone success criteria through actual Typer CLI invocations. Fixed CONTRIBUTORS.md alphabetical ordering. Full nox quality gates pass: lint, format, typecheck, unit tests, integration tests, coverage (97%), security scan, dead code detection, docs build, wheel build, and ASV benchmarks. (#495)
• Added minimal LSP server stub with agents lsp serve CLI command supporting the initialize, shutdown, and exit lifecycle handshake over JSON-RPC stdin/stdout transport with Content-Length header framing. Unsupported methods return MethodNotFound (-32601); requests before initialize return ServerNotInitialized (-32002); requests after shutdown return InvalidRequest (-32600). Transport hardening includes 10 MB max content-length, 32 max header lines, graceful recovery from malformed messages, and recursion-depth protection. LspServer stores an AcpLocalFacade for future server-mode wiring. --log-level flag controls logging verbosity. Includes 48 Behave BDD scenarios, Robot Framework smoke tests, ASV startup latency benchmarks, and docs/reference/lsp_stub.md. (#203)
• Validated M3 acceptance criteria for v3.2.0 milestone closure. All 10 E2E verification tests pass against the final implementation, exercising real CLI command paths (plan use, plan execute, plan tree, plan explain, project-scoped invariant add/list, dry-run and live plan correct), database-backed persistence, context snapshots, and invariant enforcement during strategize. Added acceptance criteria tags and milestone documentation to the robot suite. (#494)
• Added scoped backend view filtering for project-resource isolation in ACMS. ResourceScope holds the resolved set of resource ULIDs and project names visible to a plan (immutable, with include_paths/exclude_paths glob filtering via PurePath.full_match()). ScopedBackendView wraps text/vector/graph backends to auto-inject the scope parameter into every query, and filters TieredFragment visibility by project name and resource ID. ScopedBackendSet bundles scoped views for all three backend types. ResourceAliasResolver translates user-facing aliases to canonical resource ULIDs with uniqueness validation. resolve_resource_scope() builds a ResourceScope from projects with allowlist/denylist filtering. validate_project_scope() and validate_resource_scope() guard against out-of-scope access. Three enforcement hooks added to ContextTierService: get_scoped_by_resource, validate_fragment_scope, store_with_scope_check. Includes 74 Behave BDD scenarios (with full coverage-gap tests), 8 Robot Framework integration tests, ASV benchmarks, and reference documentation. (#193)
• Added builtin/plan-subplan tool for strategy actors to emit SUBPLAN_SPAWN or SUBPLAN_PARALLEL_SPAWN decisions. Validates payload via SubplanPayload (Pydantic), applies defaults (merge strategy, max_parallel, dependencies), generates rationale text, and optionally persists the Decision via an injected DecisionService. Includes register_subplan_tool, make_plan_subplan_spec factory, Behave unit tests, Robot Framework integration smoke tests, ASV benchmarks, and an actor YAML example. (#198)
• Extended CorrectionService._compute_affected_subtree() to BFS over both the structural decision tree (parent-child) and the influence DAG (decision_dependencies edges). Added cycle detection guard via visited set. Updated DecisionService.record_decision() to accept dependency_decision_ids parameter for recording influence relationships during decision creation. Added DecisionService.get_influence_edges() to retrieve influence DAG as adjacency list. All public methods on CorrectionService (analyze_impact, execute_revert, execute_correction, generate_dry_run_report) now accept optional influence_edges parameter. Includes Behave BDD scenarios, Robot Framework integration tests, and ASV benchmarks. (#542)
• Added Semantic Escalation system with AutonomyController class implementing should_proceed_automatically() that computes confidence scores from weighted factors (past_success_rate, codebase_familiarity, risk_assessment, invariant_complexity) and compares them against automation profile thresholds. Includes EscalationDecision, ConfidenceFactors, OperationContext, and HistoricalOutcome domain models. Historical success tracking records outcomes for future confidence computation. Integrates with all 8 built-in automation profiles. DI-wired as singleton autonomy_controller. Includes 48 Behave BDD scenarios, 10 Robot Framework integration tests, and ASV benchmarks. (#546)
• Added context strategy registry with ContextStrategy protocol, StrategyCapabilities, BackendSet, PlanContext, StrategyConfig, ContextStrategyResult, and StrategyRegistryEntry domain models. Six built-in stub strategies (simple-keyword, semantic-embedding, breadth-depth-navigator, arce, temporal-archaeology, plan-decision-context) with spec-mandated quality scores and backend requirements. StrategyRegistry supports config-driven registration, per-strategy timeout/max-fragment limits, per-project enable/disable overrides, plugin discovery from "module:ClassName" strings, and validation that strategies declare supported resource types. (#191)
• Fixed context inspect to display project-scoped tier fragment counts instead of global counts. Added ContextTierService.get_scoped_metrics() which returns fragment population counts filtered to the target project while keeping hit/miss counters as global service metrics. (#499)
• Fixed context simulate --focus to filter fragments by the specified focus URIs during dry-run assembly. Previously, focus URIs were passed to ContextRequest but not applied to fragment selection, making --focus a no-op. (#499)
• Wired project context CLI stubs (inspect, simulate, set, show) to live ACMS pipeline services. context inspect queries ContextTierService for tier metrics and per-project fragments with optional filtering by strategy, focus area, breadth, and depth. context simulate performs dry-run context assembly using CRP models with configurable token budget and assembly strategies. context set gains 12 ACMS pipeline options (hot_max_tokens, warm_max_decisions, cold_max_decisions, summary_max_tokens, temporal_scope, auto_refresh, focus_area, breadth, depth, assembly_strategy, retrieval_strategy, summary_strategy). context show displays ACMS pipeline configuration alongside context policy. Includes 28 Behave BDD scenarios for wiring coverage, updated Robot Framework integration tests, and reference documentation. (#499)
• Added async command execution infrastructure allowing plan phases (Execute, Apply) to run as background jobs processed by a thread pool of workers. AsyncJob Pydantic v2 domain model with ULID primary key, status state machine (queued -> running -> succeeded/failed/cancelled), and payload schema versioning. AsyncWorker service with ThreadPoolExecutor-backed concurrent execution, race-safe cancellation contract, stuck job detection, and job cleanup. InMemoryJobStore with atomic snapshot_counts() and single-pass remove_expired(). Plan lifecycle service wired to enqueue jobs when async.enabled is True. Error messages redacted via shared/redaction.py before persisting to the audit trail. Configurable via async.enabled, async.max_workers, async.poll_interval, async.job_timeout, async.job_ttl. Includes AsyncJobModel SQLAlchemy model, Alembic migration, Behave BDD scenarios, Robot Framework integration tests, ASV benchmarks, and docs/reference/async_architecture.md. (#312)
• Added hot/warm/cold context tiers with ContextTier, ActorRole, TieredFragment, TierBudget, ActorContextView, TierMetrics, and ScopedBackendView models. ContextTierService provides store/get, promotion/demotion with cold-tier summarisation hook, LRU eviction, per-actor filtered views (strategist/executor/reviewer), and project-scoped isolation. Settings: context_max_tokens_hot, context_max_decisions_warm, context_max_decisions_cold. DI-wired as singleton context_tier_service. Includes Behave BDD scenarios, Robot Framework integration tests, ASV benchmarks, and docs/reference/context_tiers.md. (#208)
• Added ExecutionEnvironment enum (host, container) and execution environment routing with priority chain (tool > plan > project > default). Includes ExecutionEnvironmentResolver service, --execution-environment CLI flags on agents plan use and agents plan execute, project-level context config support via agents project context set --execution-environment, tool runner wiring with container availability validation, and clear error when container is selected but no container resource is linked. Covered by Behave BDD scenarios, Robot Framework smoke tests, and ASV benchmarks. (#512)
• Added multi-project subplan support with MultiProjectMetadata, ProjectScope, ChangeSetSummary, CrossProjectDependency, and ProjectScopeResolver domain models. MultiProjectService provides scope initialization, context resolution, per-project changeset recording, and cross-project constraint validation. Plan model extended with multi_project_metadata field, is_multi_project property, and get_project_scope() method. CLI plan status shows per-project changeset summaries for multi-project plans. Includes Behave BDD scenarios, Robot Framework smoke tests, ASV benchmarks, and reference documentation. (#199)
• Added large-project hierarchical decomposition with 4+ levels and bounded context per subplan. Includes clustering heuristics (directory, language, size), bounded dependency closure with memoization for 10K+ files, DAG execution ordering with cycle detection, and DecisionService integration for strategy_choice + subplan_spawn recording. Configurable via planner_max_depth, planner_max_files_per_subplan, planner_max_tokens_per_subplan, planner_min_files_per_subplan settings. (#205)
• Added LLMTrace Pydantic v2 domain model and llm_traces database table with LLMTraceRepository for persisting LLM call telemetry (tokens, cost, latency, tool calls, context hash, streaming flag, retry count, error). Defined 14 OperationalMetricKey values with MetricEntry / MetricCollector for plan-level metrics. TraceService provides recording, querying, metric computation, and optional LangSmith forwarding when LANGCHAIN_TRACING_V2=true. (#500)
• Added SafetyProfile domain model with configurable safety constraints (allowed skill categories, sandbox/checkpoint requirements, human-approval flag, cost/retry limits) and integrated it into the Action model via from_config/as_cli_dict. Persistence backed by safety_profile_json column on LifecycleActionModel with Alembic migration c4_001_safety_profile_column. Includes resolve_safety_profile() stub that raises NotImplementedError in local mode (real enforcement deferred to server mode). Covered by 26 Behave BDD scenarios, 6 Robot Framework smoke tests, 5 ASV benchmark suites, and docs/reference/safety_profile.md reference documentation. (#332)
• Added devcontainer-instance, devcontainer-file, and container-instance built-in resource types with DevcontainerHandler and auto-discovery logic that scans for .devcontainer/ directories when git-checkout or fs-directory resources are linked. Includes CLI support, Behave/Robot/ASV tests, and reference documentation. (#511)
• Added skeleton compressor service (SkeletonCompressorService) for ACMS context inheritance. Compresses parent plan context fragments by skeleton_ratio (0.0–1.0) for propagation to child plans. Persists SkeletonMetadata (ratio, token counts, source decision IDs) on the plan model for auditability. Includes stable fragment ordering, ratio validation with default handling, and compression summary. (#194)
• Wired ACP local facade handlers to live application services. session.create/close delegate to SessionService; plan.create/execute/status/diff/apply delegate to PlanLifecycleService; registry.list_tools and registry.list_resources delegate to ToolRegistry and ResourceRegistryService; event.subscribe delegates to AcpEventQueue. context.get returns a stub pending ACMS pipeline. Added domain-to-ACP error code mapping (NOT_FOUND, VALIDATION_ERROR, INVALID_STATE, PLAN_ERROR, etc.) via map_domain_error(). (#501)
• Added plan explain and plan tree CLI commands for decision tree inspection with json/yaml/table/rich output formats, and flags for superseded decisions, context snapshots, and reasoning details. (#174)
• Replaced behave-parallel subprocess-per-feature execution model (342 Python interpreter startups) with in-process execution via behave's Runner API. Sequential mode runs all features in a single Runner.run() call; parallel mode uses multiprocessing.Pool with fork for COW sharing of heavy modules. Coverage pipeline simplified to a single slipcover invocation wrapping the entire process. Unit tests: 24m21s -> 2m05s (91% reduction); coverage report: 75m20s -> 3m00s (96% reduction). (#481)
• Optimized 20 medium-slow BDD features (10-100s tier). Capped time.sleep and asyncio.sleep globally at 10ms in before_all to eliminate retry/backoff waits; originals saved as time._original_sleep / asyncio._original_sleep for timing-sensitive tests. Replaced subprocess.run CLI invocations with CliRunner in coverage step files. Switched persistence features to in-memory SQLite by default. Total tier runtime reduced from 565s to 21s (96%). (#480)
• Optimized the 8 slowest BDD feature files (100-248s each, 64% of total runtime). Added @mock_only tag support to skip unnecessary DB setup, extracted shared service-setup helpers in services_coverage_steps.py (~200 lines of duplicated boilerplate removed), and introduced lightweight in-memory plan service for actor-resolution tests. (#479)
• Added pre-migrated SQLite template database via scripts/create_template_db.py to eliminate repeated Alembic migrations per BDD scenario. Nox sessions propagate the template via CLEVERAGENTS_TEMPLATE_DB env var; features/environment.py monkey-patches MigrationRunner.init_or_upgrade to copy the template for fresh scenario temp DBs, falling through to real migrations for :memory:, existing files, and migration-runner unit tests. (#483)
• Replaced coverage.py (sys.settrace) with slipcover (bytecode instrumentation) for faster coverage collection. Each behave-parallel worker now produces per-feature JSON coverage files; slipcover --merge combines them. CI workflow JSON key lookups handle both slipcover and coverage.py output formats. Documentation updated to reflect slipcover as the coverage tool. (#482)
• Added checkpointing and rollback with CheckpointService for creating, listing, pruning, and deleting sandbox snapshots, and restoring sandbox state via plan rollback <plan_id> <checkpoint_id> CLI command. Checkpoint domain models (Checkpoint, CheckpointMetadata, CheckpointRetentionPolicy, RollbackResult) store sandbox refs, decision alignment, checkpoint type (pre_write, post_step, manual), filesystem path, size, and structured audit metadata (reason, source tool, phase). Retention policy auto-prunes oldest interior checkpoints when exceeding max_checkpoints (default 50), preserving the first and most recent. Guards reject rollback when plan is applied or sandbox is missing. CorrectionService accepts an optional CheckpointService integration point for future revert delegation. CheckpointRepository and CheckpointModel back persistence via the session-factory pattern (ADR-007), with UnitOfWorkContext.checkpoints for cross-repository atomicity. Alembic migration m6_001_checkpoint_metadata adds the checkpoint_metadata table. Includes Behave BDD scenarios (33 scenarios, 129 steps), Robot Framework integration tests (11 test cases), ASV benchmarks, and docs/reference/checkpointing.md. (#206)
• Added semantic validation service with AST-based rules for syntax errors, missing imports, broken references, duplicate imports, API misuse, and missing symbols. Includes rule registry, file-hash LRU cache, severity mapping, and ValidationPipeline integration. (#448)
• Added comprehensive M6 autonomy acceptance test suite covering ACP local facade dispatch (session/plan/registry/context/event operations), event queue pub/sub with local callbacks and close semantics, HTTP transport stub rejection, version negotiation, automation profile built-ins (8 profiles), custom profile creation/validation/YAML loading, guard enforcement (denylist, allowlist, call-limit, cost-budget, write-approval, apply-approval), and profile service 4-level resolution precedence. Includes Behave BDD scenarios (52), Robot Framework integration tests (11), ASV performance benchmarks (5 suites), JSON fixtures, and documentation update. (#211)
• Added MCP refresh hooks to wire notifications/tools/list_changed events from MCP servers to SkillRegistry. Introduced SkillRegistry.refresh(name) and refresh_all() to recompute flattened tool sets on demand. Added MCPRefreshHook with configurable debounce window (default 0.5 s) to coalesce rapid notification bursts into a single refresh call. Refresh skips tool-ref validation when no ToolRegistry is configured and emits a single WARNING with recovery steps. Results are summarised as an immutable SkillRefreshResult (refreshed / failed / skipped counts) for CLI and log output. Includes Behave unit tests (19 scenarios), Robot Framework integration tests (10 tests), ASV benchmarks, and docs/reference/skill_refresh.md. (#168)
• Added agents skill refresh <name>|--all command to recompute tool flattening and sync MCP-backed skills. Enhanced skill list, skill show, and skill tools outputs with capability summary fields, tool counts, and description columns. Added --format json/yaml schemas for refresh output. Updated CLI reference documentation with refresh examples and caching behavior. (#167)
• Added UKO Layer 0-3 ontology scaffolding (RDF/TTL) aligned with specification Section 14. Layer 0 (uko:) defines InformationUnit, Container, Atom, Annotation, Boundary plus contains/references/dependsOn relationships, content properties (hasRendering, renderingDepth, hasFullContent), provenance properties (sourceResource, sourcePath, sourceRange), and temporal properties (validFrom, validUntil, isCurrent, isRevisionOf). Layer 1 (uko-code:) defines Module, Callable, TypeDefinition, TestCase, Import plus hasReturnType/hasParameters/testsCallable. Layer 2 (uko-oo:) defines Class, Interface, Method, Attribute plus inheritsFrom/implements with rdfs:subPropertyOf. Layer 3 is reserved for DetailLevelMap insertions. Loader supports semantic domain prefixes, hyphenated prefix names, full-URI layer detection, multi-parent rdfs:subClassOf (DAG traversal via BFS), rdfs:domain/rdfs:range/rdfs:subPropertyOf resolution, and non-existent parent validation. (#189)
• Added ACMS v1 context assembly pipeline with UKO and CRP integration, three fusion strategies (relevance, recency, tiered), budget-constrained assembly, and extensible strategy registration. (#188)
• Added AgentSkillSpec loader that parses SKILL.md frontmatter and progressive disclosure sections into structured SkillStep objects with stable 1-based ordering. Supports namespaced naming (namespace/short_name), optional steps, version, compatibility, metadata, and allowed-tools frontmatter fields. Explicit validation raises actionable errors for missing name/description and invalid namespace format. Agent Skills are mapped to AgentSkillToolDescriptor with source="agent_skill" and read-only defaults. Support directories (scripts/, references/, assets/) are discovered automatically and exposed as read-only AgentSkillResourceSlot bindings. Includes docs/reference/agent_skills.md, Behave unit tests, Robot Framework integration tests, and ASV benchmarks. (#160)
• Added MCP adapter runtime (MCPToolAdapter) to connect to external MCP servers via stdio, SSE, and streamable-http transports. Supports full connection lifecycle (connect with timeout, reconnect, disconnect), tool discovery, input-validated invocation, and bulk registration into ToolRegistry with source="mcp" and checkpointable=False. Includes Behave unit tests, Robot integration test, ASV benchmarks, and docs/reference/mcp_adapter.md.

fix(permissions): address code-review findings for permission system (#448)

• Added input validation to check_permission() and get_role_bindings(): empty or whitespace-only principal and scope_id arguments now raise ValueError after stripping, preventing silent lookup misses.
• Aligned module docstring and reference docs to clarify that the enforce_permission decorator is available but not yet wired into CLI or service call sites — integration is deferred to a future pass.
• Added permissions.md to the docs nav in gen_ref_pages.py.
• Added Behave BDD scenarios covering empty, whitespace-only, and leading/trailing-whitespace inputs for both check_permission() and get_role_bindings().

feat(actor): extend hierarchical actor YAML schema and loader

• Extended actor YAML schema with hierarchical graph support: per-node LSP bindings (lsp_binding), tool-source references (tool_sources), and subgraph actor_ref.
• Added graph reachability validation — all nodes must be reachable from entry_node via edges or conditional routing targets.
• Improved loader error reporting with YAML line/column positions and Pydantic field-path hints.
• Added docs/reference/actor_config.md — practical configuration reference with hierarchical examples and error cases.
• Fixed examples/actors/graph_workflow.yaml to use actor_ref instead of deprecated actor_path.
• Added Robot smoke test for loading hierarchical actor YAML via ActorLoader.discover() (#157).
• Added decision persistence layer with DecisionRepository, DecisionModel, Alembic migration, tree queries (BFS traversal, path-to-root), superseded lookup, and ordered decision path retrieval. Includes Behave BDD scenarios, Robot Framework integration tests, and ASV benchmarks. (#171)
• Added token/cost tracking, budget enforcement (per-plan and per-day), provider fallback selection with capability filtering, and cost metadata for plan execution. New config keys budget_per_plan, budget_per_day, and fallback_providers control spending limits and provider ordering. Budget warnings are emitted at 90% usage, and requests are blocked at 100%. Per-provider cost table includes default token cost estimates for offline reporting. Budget exhaustion events are persisted in plan metadata for auditability. (#324)
• Added comprehensive Behave, Robot Framework, and ASV test coverage for CLI extension features including automation profile resolution, invariant ordering, actor override error cases, and output format snapshot assertions.
• Added comprehensive E2E test suite for M2 (Actor Graphs + Tool Sources) epic covering actor YAML loading, skill registry, tool lifecycle, and MCP stub tool discovery with Behave BDD scenarios, Robot Framework integration tests, and ASV performance benchmarks.
• Added plan-level and project-level advisory locking with configurable timeouts, re-entrant acquisition, conflict detection, lock renewal, graceful shutdown release, startup cleanup of expired locks, and diagnostics check for stale lock reporting. (#327)
• Added core plan apply service with diff review output (plain, rich, JSON, YAML), artifact summaries, apply summary persistence, merge-failure handling with sandbox rollback, and empty ChangeSet guard. (#155)
• Added validation pipeline with rule-based checks, severity levels (required vs informational), result aggregation, deterministic execution ordering, per-validation timeouts, and gate enforcement that blocks apply when required validations fail. (#175)
• Added validation-gated apply pipeline that blocks the Apply phase when required Execute-phase validations have not passed, transitions plans to constrained state with actionable CLI hints, and runs validation attachments during apply. (#176)
• Added diff review artifact model with inline comments, approval status, per-resource grouping, before/after content hashes, and plan apply service integration for plan diff and plan status outputs. (#303)
• Added definition-of-done gating that evaluates DoD criteria before apply, blocks phase transitions when required conditions are unmet, and stores pass/fail reasoning in the plan validation summary. (#178)
• Added error recovery patterns (retry, fallback, skip, abort) with structured recovery hints in CLI error output, plan executor integration, and error recovery service for capturing error category, recovery action, and retry history. (#186)
• Hardened template rendering by replacing unsafe Jinja2 usage with a sandboxed renderer that denies attribute access, function calls, and filters, allowing only {var} substitution from a fixed allowlist with max template length and max output size enforcement. (#319)
• Enforced explicit exception handling by introducing a CleverAgentsError base class with structured error types for configuration, provider, and file I/O failures, error code mapping, bare-except prohibition, and secret redaction in error details. (#320)
• Added 32 BDD scenarios to boost unit test coverage from 97.0% to 97.2%.
• Added Behave BDD scenarios for six under-tested modules (container, correction service, plan lifecycle service, plan CLI, skill CLI, database models) to exercise uncovered lines, exception-handling paths, and partial branches. (#446)
• Fixed failing Robot Framework integration tests related to security secrets handling.
• Fixed style check violations across the codebase.
• Fixed failing unit tests.
• Added changeset persistence and diff artifact storage for tracking multi-file changes across plan execution phases. (#163)
• Added AsyncResourceTracker for unified async resource lifecycle with timeout-bounded cleanup, leak detection via finalizer, and async context manager support.
• Enhanced LangGraphBridge with graceful task cancellation that awaits in-flight tasks.
• Added StateManager.close() and AcpEventQueue.close() for proper resource disposal.
• Tightened read-only enforcement: write-capable tools are now blocked on read-only plans regardless of the tool's own read_only flag.
• Added ReadOnlyViolationError to ChangeSetCapture to prevent write artifacts on read-only plans.
• Added CLI fail-fast guards on plan execute and plan apply for read-only plans.
• Added DecisionService with record/list/tree helpers and SnapshotStore for hash-based deduplication of context snapshots during plan execution.
• Expanded CONTRIBUTING.md with detailed guidance on the issue creation process, label system, ticket lifecycle, pull request requirements, and review/merge process.
• Added commit scope, quality, and message format guidelines to CONTRIBUTING.md.
• Migrated implementation timeline from the monolithic implementation plan to docs/timeline.md.
• Migrated implementation notes to docs/implementation-notes.md.
• Relocated remaining implementation plan content to the specification and CONTRIBUTING.md, and removed implementation_plan.md from the repository.
• Updated CONTRIBUTING.md to include project-specific conventions for tooling, testing, type checking, and code style.

v1.0.0

First release.