cleveragents-core/CHANGELOG.md

# Changelog

All notable changes to this project will be documented in this file.
The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).

## [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.