cleveragents-core/CHANGELOG.md

Changelog

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

[Unreleased]

Fixed

• 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

• Developer Setup Guide (#9123): Added comprehensive developer setup guide at docs/development/setup.md covering prerequisites, development workflow, testing, linting, and commit guidelines.

• 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 → pr-creator, pr-checker → pr-ci-test-fixer, pr-status-checker → pr-status-analyzer, pr-self-reviewer → pr-reviewer, pr-fix-orchestrator → 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.

Changed

• 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.

• 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.

• 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.

---

[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 permissions screen. (#1004)

• TUI — Actor thought blocks: Expandable reasoning trace widgets rendered inline in the conversation stream with muted styling. Collapsed by default; expand with Space or click. (#1005)

• UKO provenance tracking: Every typed triple now carries sourceResource, validFrom, and isCurrent metadata. A revision chain enables temporal queries and point-in-time ontology state reconstruction.

• JSON-RPC 2.0 A2A wire format: A2aRequest/A2aResponse fields renamed to standard JSON-RPC 2.0 names (method, id, result, error). The A2aVersionNegotiator handles backward compatibility.

• Database resource handler: Full CRUD and checkpoint/rollback support for SQLite, PostgreSQL, MySQL, and DuckDB resources via the resource DAG.

• Estimation lifecycle hook: actor.default.estimation config key wires an estimation actor into the Strategize-to-Estimate lifecycle hook.

• Persona system: YAML-backed personas bind actors, argument presets, and scope references to named identities; persisted in ~/.config/cleveragents/personas/.

• Session management: Create, list, export, and import conversation sessions; full JSON export/import for portability; Markdown transcript export (--format md) for human-readable sharing.

• First-run experience: ActorSelectionOverlay guides new users to pick an actor on first TUI launch; creates a "default" persona automatically.

• Server mode: agents server connect configures a remote CleverAgents server; Kubernetes Helm chart in k8s/ for production deployment.

• A2A integration: Agent-to-Agent protocol facade wires CLI and TUI to live application services (session, plan, registry, event).

• Permissions screen: TUI overlay for reviewing tool permission requests with unified, side-by-side, and context diff views; session-scoped allow/reject decisions.

• Inline permission questions: PermissionQuestionWidget renders single-file permission requests directly in the conversation stream with single-key shortcuts.

• Invariant reconciliation: InvariantReconciliationActor runs automatically at every plan phase transition; failures block the transition and emit INVARIANT_VIOLATED.

• UKO runtime: Universal Knowledge Ontology query interface, inference engine, and graph persistence for ACMS context strategies.

Fixed

• LangChainChatProvider.name and model_id are now mutable properties with setters, fixing an AttributeError when PlanService attempted to resolve provider names after instantiation. (#1553)

---

[3.7.0] — 2026-03-15

Added

• Interactive TUI (agents tui) — full-screen Textual app with multi-session tabs, persona switching, slash commands (67 commands across 14 groups), reference picker (@), shell mode (!), context-sensitive F1 help, and Ctrl+T argument preset cycling.
• Slash command system — 67 commands across 14 groups accessible via / overlay.
• Reference picker — @ key opens a file/resource reference picker that inserts references into the input field.
• TUI persona system — YAML-backed personas bind actors, argument presets, and scope references; persisted in ~/.config/cleveragents/personas/.
• TUI session export/import — full JSON round-trip and Markdown transcript export (--format md).

---

[3.6.0] — 2026-02-28

Added

• Advanced Context Management System (ACMS) with three-tier context strategy.
• UKO Runtime (Universal Knowledge Ontology) with graph persistence and inference engine.
• Implicit inference engine producing uko:implicitSiblingOf, uko:implicitContains, and uko:implicitDependsOn triples with confidence 0.7.

---

[3.5.0] — 2026-02-14

Added

• Autonomy hardening: advisory locking, validation pipeline, definition-of-done gating.
• Resource DAG with dependency tracking and type hierarchy with multiple inheritance.
• Container resource types (container.docker, container.podman).
• LSP resource types (lsp.*).

---

[3.4.0] — 2026-01-31

Added

• ACMS v1 with context scaling strategies.
• Resource type inheritance system (ADR-042).
• Safety profile extraction (ADR-041).

---

[3.3.0] — 2026-01-17

Added

• Corrections and subplans support in plan lifecycle.
• Checkpoint and rollback for all resource writes.
• Decision tree versioning and history (ADR-034).
• Decision tree rollback and replay (ADR-035).

---

[3.2.0] — 2026-01-03

Added

• Decisions, validations, and invariants in plan lifecycle.
• Validation abstraction layer (ADR-013).
• Invariant system (ADR-016).
• Automation profiles (ADR-017).
• Semantic error prevention (ADR-018).

---

[3.1.0] — 2025-12-20

Added

• MCP (Model Context Protocol) adapter and client (ADR-029).
• LSP (Language Server Protocol) client integration (ADR-027).
• Agent Skills Standard (AgentSkills.io) support (ADR-028).
• Skill abstraction definition (ADR-030).

---

[3.0.0] — 2025-12-06

Added

• Initial public release of CleverAgents Core.
• Unified agents / cleveragents CLI entry points.
• Layered architecture: Entry Points → Application → Domain → Infrastructure → Integration → Core.
• Actor system with YAML-defined LangGraph node graphs.
• Tool system with four-stage lifecycle (activate → validate → execute → deactivate).
• Skill system with three-tier progressive disclosure.
• Resource system with DAG and type hierarchy.
• A2A (Agent-to-Agent) protocol facade.
• DI container (cleveragents.application.container).
• LangChain/LangGraph integration (ADR-022).
• Provider registry with fallback chain (OpenAI → Anthropic → Google → Azure → OpenRouter → Groq → Together → Cohere).
• Observability: structured logging, metrics, audit trail, token/cost tracking.
• BDD test suite (Behave + Robot Framework).
• Nox automation for lint, typecheck, tests, docs, benchmarks.
• MkDocs-powered documentation with CleverAgents branding.