cleveragents-core/docs/CHANGELOG.md

This file is a mirror of the authoritative root file. For the latest version, see the root CHANGELOG.md.

Changelog

All notable changes to this project will be documented in this file. The format follows Keep a Changelog.

[Unreleased]

Changed

• CI coverage job now waits for unit_tests (#10714): Added unit_tests to the needs list of the coverage job in ci.yml. Previously the coverage job ran in parallel with unit tests, which could produce misleading pass results when tests were still in-flight or had already failed. Coverage now only starts after unit tests succeed, eliminating redundant parallel test execution and ensuring coverage results are always meaningful.

• Diagnostics spec examples expanded to all 9 providers (#5320): Updated the agents diagnostics command examples in the specification to show all 9 supported providers (OpenAI, Anthropic, Google, Gemini, Azure, OpenRouter, Cohere, Groq, Together), matching the implementation from PR #3469. Rich, plain, JSON, and YAML example outputs now reflect comprehensive provider coverage with accurate warning counts and per-provider recommendations.

Added

• SubplanExecutionService lazy wiring in CLI (#10268): Wired subplan_service from the DI container into _get_plan_executor() so PlanExecutor can spawn child plans during the Execute phase. When SubplanService is available but SubplanExecutionService is not explicitly injected, _execute_subplans() now lazily creates a SubplanExecutionService using the parent plan's subplan_config and the _execute_child_plan callback. Added recursion guard and strategize result validation to _execute_child_plan to prevent re-entrant or orphaned child plan execution.

• TDD: MCPToolAdapter.infer_resource_slots() TypeError with null properties (#10470): Added a TDD issue-capture Behave scenario that reproduces the bug where MCPToolAdapter.infer_resource_slots() raises TypeError when the input schema contains {"properties": None}. The test is tagged @tdd_expected_fail and will pass (by inversion) until the underlying bug is fixed.

• Architecture Pool Supervisor Milestone Assignment (#7521): Added a "PR Workflow for Major Changes" section to the architecture-pool-supervisor agent definition documenting the milestone assignment step for spec PRs. The agent now has forgejo_update_pull_request permission to assign PRs to the current active milestone after creation, improving traceability of specification changes within project milestone planning. Includes BDD test coverage for the new workflow documentation and permission configuration.

• Git Worktree TOCTOU Race Condition (#7507): Fixed a Time-Of-Check-To-Time-Of-Use (TOCTOU) race condition in git_worktree.py that could cause git worktree add operations to fail under concurrent execution. The fix replaces the unsafe mkdtemp() + rmdir() pattern with a parent-directory approach that maintains the OS-level uniqueness guarantee throughout the entire operation. The parent temporary directory is now persisted and properly cleaned up on both success and failure paths. Comprehensive BDD test coverage validates the fix under concurrent execution and confirms proper cleanup behavior.

Fixed

• Actor namespace/name disambiguation (#11254): When action YAML references actors using namespace/name format (e.g. strategy_actor: local/my-strategist), the _parse_actor_name() functions no longer mistake the namespace prefix for an LLM provider name. A new _is_known_provider() utility checks whether the first slash-separated segment matches a known ProviderType (e.g. openai, anthropic); if not, the input is treated as namespace/name. PlanLifecycleService now provides resolve_actor_provider_model() to resolve namespaced references to their underlying provider/model via the actor registry. All affected call sites — StrategyActor, LLMStrategizeActor, LLMExecuteActor, and SessionWorkflow._resolve_llm() — pre-resolve actor names before passing them to the LLM provider, fixing the ValueError: Unknown provider type crash when using namespaced actor references.

• Built-in actors v3 YAML format (#10883): Fixed agents actor run failing for built-in actors (e.g., openai/gpt-4, anthropic/claude-3-opus) due to missing v3 type field in stored configuration. ActorRegistry.ensure_built_in_actors() now generates and persists v3 YAML text with type: llm and description fields, ensuring built-in actors work identically to custom actors. The _generate_builtin_actor_yaml() helper creates spec-compliant YAML that passes ReactiveConfigParser._is_v3_format() validation. Includes BDD scenarios and unit tests covering YAML generation, schema validation, and multiple provider handling.

• Atomic server_connect config writes (#993): Fixed server_connect in cli/commands/server.py to write all three config values (server.url, server.namespace, server.tls-verify) atomically. A snapshot of the config file is taken before any writes; if any set_value() call fails, the snapshot is restored and compensating CONFIG_CHANGED events are emitted for already-applied keys so the audit trail reflects the rollback. Added emit_config_changed() helper to ConfigService for decoupled event emission in rollback flows. Added close() method to ReactiveEventBus for proper resource cleanup in tests. Resolved merge conflict in config_service.py integrating the PR's emit_config_changed() helper with master's scoped config infrastructure. Removed # type: ignore[assignment] by introducing a typed _AutoDiscover sentinel class. BDD regression coverage in features/tdd_server_connect_atomic_writes.feature.

• Atomic load_from_metadata for Autonomy Guardrails (#7504): Fixed AutonomyGuardrailService.load_from_metadata() to validate both AutonomyGuardrails and GuardrailAuditTrail models before writing either to state, ensuring atomic updates. Previously, a validation failure on the audit trail after guardrails were already written would leave the system in an inconsistent state with partial updates. The method now uses a two-phase validate-then-write approach: all model validation occurs in Phase 1, and state mutations only happen in Phase 2 after all validations succeed.

• ReactiveConfigParser route synthesis for v3 actors (#10807): Fixed agents actor run silently returning empty output for v3 type:llm actors. _build_from_v3() and _build() now synthesise a default single-node graph route when agents are created without explicit routes, ensuring run_single_shot() can invoke the LLM via GraphExecutor. The nested actors: map format also translates the v3 actor: "provider/model" key into separate provider and model keys so the correct LLM provider is instantiated.

• ActorRegistry.add() spec-compliant YAML support (#4466): The registry now accepts actor YAML using the spec's actors: map format with nested config: blocks, in addition to the legacy top-level provider/model format. The unsafe flag and graph descriptor from nested config are now correctly preserved during registration. Multi-actor YAML (>1 entry in actors:/agents: map) is now rejected by add() with a ValidationError. Nested config.options are now correctly preserved. The unsafe coercion now uses strict is True or == 1 instead of bool() to prevent truthy non-boolean YAML values (e.g. unsafe: "no") from being treated as unsafe.

• UKO Runtime Layer 2 (Paradigm) Indexing (#9351): Added missing rdf:type uko-oo:Class triple emission in PythonAnalyzer._extract_class() so that Python class definitions are now correctly classified at layer 2 (paradigm/OO) in addition to layer 3 (technology). Added the corresponding Behave scenario Indexing a Python file populates layer 2 (paradigm) to features/uko_runtime.feature, completing four-layer guarantee verification for the UKO runtime.

• Actor CLI v3 YAML Schema Support (#6283): Fixed three components to add full v3 ActorConfigSchema support to the actor CLI registration and execution paths. ActorConfiguration.from_blob() now detects v3 format (top-level type key of llm/graph/tool) and correctly extracts provider, model, and graph descriptors — including type: tool actors without a model field. ActorRegistry.add() validates against the full Pydantic v2 schema, persists skills/lsp/description in the config blob, and compiles graph actors with proper metadata. ReactiveConfigParser._build_from_v3() now uses correct source/target edge keys (fixing KeyError in to_graph_config()), handles config: null nodes without crashing, propagates context_view/memory/context/ env_vars/response_format/lsp_capabilities/lsp_context_enrichment into agent configs, and validates entry_node against the nodes map. Exception handling narrowed from broad except Exception to specific NotFoundError and ActorCompilationError. v3 registration logic extracted to v3_registry.py to keep registry.py under the 500-line limit. 19 BDD scenarios cover all v3 paths including tool actors, update mode, LSP dict bindings, and field propagation.

• TDD Non-AssertionError Guard Visibility (#8294): apply_tdd_inversion in features/environment.py now emits its non-assertion exception guard warning to both the structured logger and stderr via a new _warning_with_stderr helper. This makes the guard firing visible in standard Behave console output and CI log snippets where the structured logging sink may not be displayed. BDD infrastructure coverage added: a new scenario in tdd_expected_fail_infrastructure.feature asserts that the warning is emitted to stderr when a non-AssertionError exception is encountered in an @tdd_expected_fail scenario, and a second scenario asserts the warning is NOT emitted when the exception is an AssertionError. The CONTRIBUTING.md now documents that @tdd_expected_fail step definitions must signal expected failures via AssertionError.

• Parallel Behave Runner Log Noise Reduction (#8351): The parallel behave runner now suppresses captured stdout/stderr for passing worker chunks and only replays diagnostics for failed, errored, or crashed chunks. This makes failure output significantly easier to spot in CI and local runs. A worker crash (unhandled exception) is detected via an all-zero summary and the captured traceback is always surfaced.

• Bug Hunt Pool Supervisor Non-Blocking Tracking: Updated bug-hunt-pool-supervisor to make the automation tracking step non-blocking. The automation-tracking-manager call in step 5 is now best-effort — if it does not complete within a reasonable time or fails, the supervisor skips it and continues to the next cycle. Added explicit rule 9 clarifying that tracking must never block the main loop. Core functionality (module scanning and worker dispatch) takes priority over status reporting.

• Name Validator Server-Qualified Format (#9074): Updated actor, skill, and tool name validators to accept the spec-required [[server:]namespace/]name format. Previously, server-qualified names like dev:freemo/custom-analysis were incorrectly rejected. Added BDD scenarios for server-qualified name acceptance and rejection. All three validators (ActorConfigSchema.validate_name, NAMESPACED_NAME_RE, _TOOL_NAME_PATTERN) now correctly support optional server prefixes while maintaining backward compatibility with existing namespace/name names.

• Automation Profile Silent Fallback (#8232): _resolve_profile_for_plan in PlanLifecycleService now raises a clear ValidationError when a plan's automation profile name is not a known built-in profile, instead of silently falling back to "manual". Users who configured custom automation profiles (e.g. "semi-auto", "acme/strict") will now receive an actionable error message listing available built-in profiles. The resolved profile name is also logged at debug level for observability.

Added

• Wired StrategyActor into the real plan execution path: _get_plan_executor in plan.py now resolves the strategy actor via resolve_strategy_actor() (reading the actor.default.strategy config key) instead of always constructing LLMStrategizeActor. run_strategize in PlanExecutor now passes resources (derived from plan.project_links) and project_context to the actor so the LLM prompt receives full project context. Strategy decisions are serialised as JSON in plan.error_details["strategy_decisions_json"] so _build_decisions can reconstruct the full hierarchy (dependency ordering, parent/child structure) during Execute instead of rebuilding from definition_of_done. StrategizeStubActor.execute accepts **kwargs for forward-compatibility. Added BDD coverage for the stored-JSON path, corrupt-JSON fallback, resource-passing, and stub extra-kwargs scenarios. (#828)

• TDD Issue-Capture Test Activation (#7025): Replaced 234 bare @skip tags across 82 Behave feature files with the correct @tdd_expected_fail @tdd_issue @tdd_issue_<N> tag system. Scenarios whose referenced bugs were already fixed had @tdd_expected_fail removed and now run as permanent regression guards. Net result: 629 features active in CI (up from ~545), zero @skip tags remain.

• Git Worktree Sandbox Apply (#4454): The plan apply command now merges LLM-generated changes via git merge from an isolated worktree branch instead of flat shutil.copy2. Displays spec-aligned Apply Summary (plan ID, artifacts, insertions/deletions, project, timestamp), Sandbox Cleanup panel, and ✓ OK Changes applied footer. Non-git projects fall back to the original flat file copy.

• Context Hydration Fix (#4454): Fixed ContextFragment metadata types (detail_depth and relevance_score must be strings, not int/float) that caused Pydantic validation errors during context assembly, resulting in the LLM receiving zero file context.

• Automation Tracking System: Replaced shared session state issue tracking with individual per-agent tracking issues. Each agent now creates its own [AUTO-<PREFIX>] titled issues with standardized headers, reporting intervals, and health indicators. Agents: session-persister, implementation-orchestrator, system-watchdog, backlog-groomer, human-liaison. Documentation at docs/development/automation-tracking.md.

• Automated Health Monitoring and Recovery: The system-watchdog now runs audit_automation_tracking_health() every 5 minutes, detecting stalled agents when tracking issues are >20% overdue from their declared reporting interval. On detection, it terminates stalled sessions via the OpenCode Server API, performs root-cause analysis, creates high-priority diagnostic issues, and closes stale tracking issues with recovery notes.

• Centralized Label Management (forgejo-label-manager): A new specialized subagent centralizes all Forgejo label operations across the agent system. Enforces the organization-level label system, prohibits label creation, and validates label compliance. Agents backlog-groomer, human-liaison, project-owner, epic-planner, new-issue-creator, and issue-state-updater now delegate all label operations to this subagent.

• PR-Issue Label Synchronization: PRs now inherit Priority/, MoSCoW/, Points/, and State/ labels from their associated issues at creation time (pr-api-creator). The backlog-groomer adds a continuous Pass 19 for ongoing PR-issue label synchronization. The issue-state-updater syncs PR state labels whenever issue states change.

• Automation Tracking Announcements: Extended automation-tracking-manager with announcement issue support (CREATE_ANNOUNCEMENT_ISSUE, CLOSE_ANNOUNCEMENT_ISSUE, LIST_TRACKING_ISSUES, READ_ANNOUNCEMENTS, REVIEW_OWN_ANNOUNCEMENTS). Supervisors and workers now read critical announcements before each cycle for cross-agent awareness. Priority-based filtering (Critical/High/Medium/Low) reduces noise. Backlog-groomer performs intelligent cleanup with age thresholds by priority.

• PR Agent Reorganization: All PR-related agents renamed and reorganized to follow the *-pool-supervisor naming pattern. New agents added: pr-editor (safe PR editing with description preservation), pr-manager (unified PR interface), and pr-merge-pool-supervisor (automated PR merging supervisor). Renamed: pr-api-creator to pr-creator, pr-checker to pr-ci-test-fixer, pr-status-checker to pr-status-analyzer, pr-self-reviewer to pr-reviewer, pr-fix-orchestrator to pr-fix-pool-supervisor.

• Automated PR Merging (pr-merge-pool-supervisor): New supervisor continuously monitors for merge-ready PRs and merges them automatically when all criteria are met (approvals, CI passing, no conflicts). Supports both formal reviews and comment-based approvals (LGTM, ready to merge, etc.).

• Implementation Worker Workflow Completion: implementation-worker now implements work claiming protocols with conflict detection, comprehensive review feedback handling with intelligent parsing, sophisticated merge conflict resolution with multiple strategies, and parallel subtask execution with wave-based dependency analysis. Pass rate improved from 48.15% to 84.8%.

• Container Resource Stop Support: agents resource stop now correctly stops container-instance and devcontainer-instance resource types.

• Centralized Automation Tracking Manager (automation-tracking-manager): The manager is now the single interface for all tracking issue operations (CREATE_TRACKING_ISSUE, UPDATE_TRACKING_ISSUE, CLOSE_TRACKING_ISSUE, READ_TRACKING_STATE, GET_NEXT_CYCLE_NUMBER). Agents delegate to the manager rather than calling the Forgejo API directly, ensuring sequential cycle numbers across restarts and preventing duplicate issues. Migrated agents include system-watchdog, implementation-pool-supervisor, timeline-update-pool-supervisor, project-owner-pool-supervisor, product-builder, and backlog-grooming-pool-supervisor. The legacy shared/automation_tracking.md module was removed.

• Documentation Writer Tracking (docs-writer): The documentation writer now participates in the automation tracking system by creating individual [AUTO-DOCS] Documentation Report (Cycle N) issues every 10 cycles (~3.3 hours). The manager applies the mandatory Automation Tracking label automatically, while teams may add additional workflow labels as needed. See docs/development/automation-tracking.md and the new docs/development/docs-writer.md reference.

• ACMS / UKO API Documentation (docs/api/acms.md): Added comprehensive API reference for the cleveragents.acms package covering the four-layer UKO ontology hierarchy, VocabularyRegistry, ProvenanceInfo, UKOClass, UKOProperty, UKOVocabulary, Layer2Dependency, ParadigmVocabulary, DetailLevelMapBuilder, and all Layer 3 language vocabulary types (Python, TypeScript, Rust, Java). The new page is linked from the API Reference index and the MkDocs navigation.

Changed

• product-builder Worker Allocation Tier Comments (#8169): Clarified the N_FULL tier comment to explicitly document that PR fixing is handled by implementation-pool-supervisor via its PR-First Priority rule. Updated the N_QUARTER comment to enumerate the pools it covers (UAT, bug hunting, test infra). Prevents confusion about which supervisor handles PR fix work.

• Decision Tree Full ULID Display (#5825): The agents plan tree command now displays full 26-character ULIDs for all decisions instead of truncating them to 8 characters. This enables users to copy decision IDs directly from tree output and use them in follow-up CLI commands like agents plan correct without manual ID reconstruction. Added "Decision IDs (for correction)" section with human-readable labels for easy reference. Applies to both table and rich/plain text output formats.

• Automation Tracking Format: All automation tracking issues now use a standardized header format with mandatory Reporting Interval: <interval> (Next report expected: <ts>) declarations, enabling precise staleness detection.

• PR Review Policy: Reduced PR review requirement from 2 approvals to 1. Self-approval is now permitted including for automated bot PRs. Approval can be a formal review OR an approval comment (LGTM, Approved, ready to merge).

• Label Delegation Enforcement: automation-tracking-manager now enforces delegation to forgejo-label-manager for all label operations, preventing "invalid label ID" errors and ensuring label application uses correct name-to-ID mapping.

• Automation Tracking Label Guidance: Documentation now clarifies that the manager automatically applies the Automation Tracking label and that additional labels such as Type/Automation, State/In Progress, or Priority/Medium remain optional workflow choices rather than mandatory.

• Automation Tracking Agent Prefix Registry: Expanded from 5 agents to 18 agents. New prefixes include AUTO-DOCS, AUTO-REV-POOL, AUTO-UAT-POOL, AUTO-BUG-POOL, AUTO-INF-POOL, AUTO-ARCH, AUTO-EPIC, AUTO-EVLV, AUTO-GUARD, AUTO-SPEC, AUTO-TIME, AUTO-PROJ-OWN, and AUTO-PROD-BLDR.

Fixed

• Plan Concurrency Race Condition (#7989): Fixed critical race condition in execute_plan() and apply_plan() where concurrent CLI/worker sessions could simultaneously modify the same plan, corrupting plan state. LockService is now wired into the plan lifecycle with plan-level advisory locking. Each invocation generates a unique caller identity (UUID) to prevent re-entrant lock acquisition by concurrent sessions on the same plan. Concurrent attempts now raise LockConflictError instead of silently racing. Lock is acquired before phase transition and released in a finally block to ensure cleanup even on error.

• --format color ANSI Output (#7910): Fixed format_output routing the color format option to _format_plain, which produced plain uncoloured text instead of ANSI escape sequences. The color format is now routed to format_output_session which uses the ColorMaterializer to emit proper ANSI-coloured output. --format plain and all other formats remain unaffected.

• ContextTierService Thread Safety (#7547): Added threading.RLock to ContextTierService to prevent RuntimeError: dictionary changed size during iteration and data corruption under concurrent plan execution. All public methods (store, get, promote, demote, evict_lru, enforce_staleness, get_metrics, get_all_fragments, get_hot_fragments, get_for_actor, get_scoped_view, get_scoped_by_resource, get_scoped_metrics) now acquire the reentrant lock before accessing the hot/warm/cold tier dicts. The service was previously documented as single-threaded but registered as a DI Singleton, causing potential data corruption when parallel subplans shared the same instance. The TierRuntimeMixin.enforce_staleness() and ScopedTierMixin.get_scoped_by_resource() / get_scoped_metrics() methods are also protected. The DI container registration as providers.Singleton is now correct and safe.

• TOCTOU Race Condition in Git Worktree Sandbox (#7507): Fixed Time-Of-Check-To-Time-Of-Use race condition in GitWorktreeSandbox.create() by replacing unsafe mkdtemp+rmdir pattern with persistent parent directory approach. Parent directory is now held throughout operation lifetime and properly cleaned up in all error paths (timeout, CalledProcessError, OSError) and in the cleanup() method, eliminating race window where another process could claim the worktree path. Comprehensive BDD coverage added for all error-path cleanup branches.

• Validation Gate Empty-Run Guard (#7508): Fixed ApplyValidationSummary.all_required_passed returning True when zero validations were run, silently bypassing the apply gate. The property now returns False when the validation result set is empty (is_empty is True), ensuring that apply is blocked unless at least one validation was actually executed. Also added required_total property for completeness. Updated consolidated_validation.feature scenarios to reflect the corrected blocking behavior for empty summaries and no-attachment runs.

• ACMS context tier hydration: ContextTierService no longer starts empty on every CLI invocation. A new context_tier_hydrator.py reads files from linked project resources (via git ls-files or os.walk), creates TieredFragment objects, and stores them in the tier service before context assembly in LLMExecuteActor.execute(). The LLM now receives real file context during plan execution. Respects max file size (256 KB), total budget (10 MB), binary file exclusion, and .git/node_modules/__pycache__ directory skipping. (#1028)

• Sandbox root wiring: _get_plan_executor() now passes sandbox_root=.cleveragents/sandbox/, so LLM file output (FILE: blocks) is written to disk during the execute phase. (#4222)

• SubplanExecutionService fail_fast cancellation (#7582): Fixed a race condition where already-running parallel subplans were not cancelled when fail_fast fired. Previously, Future.cancel() only prevented queued futures from starting but had no effect on in-flight futures that completed after stop_flag was set -- their COMPLETE results were incorrectly included in the merge output. The fix adds a post-completion guard that overrides any non-ERRORED/non-CANCELLED result to CANCELLED when stop_flag is active, and clears the associated output to prevent it from entering the merge. Also replaces the O(n) linear status lookup in the as_completed() loop with an O(1) status_map dict pre-computed before the executor block.

• Robot Framework TDD Listener Guards (#5436): Added three guard conditions to the tdd_expected_fail_listener end_test() function to prevent blindly inverting ALL test failures to passes, which was masking infrastructure errors and causing flaky CI behavior. Guards: setup/teardown error detection, non-assertion failure detection (infrastructure errors), and dry-run mode detection. Also fixed Variable Should Exist syntax errors in e2e test files and removed tdd_expected_fail from 4 context assembly e2e tests where bugs were already fixed.

• PluginLoader entry point prefix validation (#7476): Parse entry point targets before import, enforce the module allowlist ahead of loading, and add Behave plus Robot Framework regression coverage to ensure disallowed prefixes never execute untrusted module-level code in either unit or integration flows.

• issue-state-updater Bash Script Errors: Removed problematic bash script examples that tried to invoke task forgejo-label-manager as a bash command (the Task tool cannot be invoked from bash). Replaced with clear step-by-step operational instructions and direct label management via API.

• automation-tracking-manager Label Delegation Syntax: Fixed incorrect delegation syntax when calling forgejo-label-manager. The manager now uses correct natural language requests (e.g., "Apply labels to issue #123: Automation Tracking") instead of structured parameters, ensuring tracking issues receive proper labels.

• product-builder Missing Supervisors: Added missing pr-fix-pool-supervisor and pr-merge-pool-supervisor to the product-builder's supervisor launch list (18 total supervisors). Updated all numeric references, pre-flight checklists, and validation logic.

• ActionRepository.update() now uses explicit bulk sa_delete() + session.flush() before re-inserting child rows for action_arguments and action_invariants, fixing a sqlite3.IntegrityError: UNIQUE constraint failed crash when agents plan use was called on an action that already had arguments registered via action create. (#4197)

---

[3.8.0] -- 2026-04-05

Added

• Wired Invariant Reconciliation Actor auto-invocation into PlanLifecycleService phase transitions (start_strategize, execute_plan, apply_plan). Reconciliation failures now block the transition with ReconciliationBlockedError and emit INVARIANT_VIOLATED events. Post-correction reconciliation runs via CORRECTION_APPLIED event subscription (best-effort). Added InvariantService Singleton provider in the DI container.

• TUI -- Shell danger detection: The TUI shell mode (! prefix) now detects dangerous command patterns before execution. A configurable pattern registry classifies commands by danger level (warning, critical) and surfaces a user warning overlay before proceeding. Patterns cover destructive filesystem operations, privilege escalation, network exfiltration, and more. (#1003)

• TUI -- Permission Question Widget: A new inline PermissionQuestionWidget renders permission requests directly in the conversation stream for single-file operations. Users can allow/reject with single-key shortcuts (a/A/r/R), navigate with arrow keys, confirm with Enter, or press v to open the full