diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md new file mode 100644 index 000000000..f379935df --- /dev/null +++ b/docs/CHANGELOG.md @@ -0,0 +1,153 @@ +# Changelog (Documentation) + +> **Note:** This file is the documentation-tree mirror of the project changelog. +> The authoritative source is the [root CHANGELOG.md](../CHANGELOG.md) at the +> repository root. This page is rendered as part of the MkDocs site for +> convenient in-docs browsing. + +--- + +## [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. +- **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. +- **TUI — Permission Question Widget**: A new inline `PermissionQuestionWidget` renders + permission requests directly in the conversation stream for single-file operations. +- **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. +- **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`). +- **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`). +- **Server mode**: `agents server connect` configures a remote CleverAgents server; Kubernetes + Helm chart in `k8s/` for production deployment. +- **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. + +--- + +## [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. + +--- + +*For the complete changelog including unreleased changes and detailed fix notes, see the +[root CHANGELOG.md](../CHANGELOG.md).* diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md new file mode 100644 index 000000000..eb8091ba4 --- /dev/null +++ b/docs/CONTRIBUTING.md @@ -0,0 +1,157 @@ +# Contributing to CleverAgents Core (Documentation) + +> **Note:** This page is the documentation-tree mirror of the project contributing guide. +> The authoritative source is the [root CONTRIBUTING.md](../CONTRIBUTING.md) at the +> repository root. This page provides a quick-start summary for contributors browsing +> the MkDocs site. + +--- + +## Quick Start + +1. **Fork** the repository on Forgejo and clone your fork locally. +2. **Create a branch** following the naming convention: + - Features: `feature/mN-short-description` + - Bug fixes: `bugfix/mN-short-description` + - TDD tests: `tdd/mN-short-description` + - Documentation: `docs/short-description` +3. **Make your changes**, following the guidelines below. +4. **Run the full test suite** with `nox` before submitting. +5. **Open a Pull Request** targeting `master`. + +--- + +## Development Setup + +### Prerequisites + +- Python 3.11+ +- [uv](https://github.com/astral-sh/uv) package manager +- [nox](https://nox.thea.codes/) for task automation +- [pre-commit](https://pre-commit.com/) for commit hooks + +### Initial Setup + +```bash +# Clone the repository +git clone https://git.cleverthis.com/cleveragents/cleveragents-core.git +cd cleveragents-core + +# Install dependencies and set up pre-commit hooks +scripts/setup-dev.sh +``` + +The `setup-dev.sh` script will: + +- Create a virtual environment with `uv` +- Install all development dependencies +- Configure pre-commit hooks (lint, format, typecheck, commit-msg validation) + +--- + +## Testing Instructions + +All tests are run via `nox`. **Do not invoke `behave`, `robot`, or pytest directly.** + +| Command | Purpose | +|---------|---------| +| `nox` | Full suite: lint, typecheck, security, unit tests, integration tests, coverage | +| `nox -s unit_tests` | Behave BDD unit tests only | +| `nox -s integration_tests` | Robot Framework integration tests only | +| `nox -s coverage_report` | Coverage report (must stay ≥ 97%) | +| `nox -s lint` | Ruff linting | +| `nox -s typecheck` | Pyright strict type checking | +| `nox -s benchmark` | ASV performance benchmarks | + +### Test Framework Conventions + +- **Unit tests** use [Behave](https://behave.readthedocs.io/) (BDD/Gherkin) under `features/`. +- **Integration and end-to-end tests** use [Robot Framework](https://robotframework.org/) under `robot/`. +- **No pytest-style tests** — there is intentionally no `tests/` directory. +- **Mocks** belong exclusively under `features/mocks/`. Never place mock code in `src/`. + +### Coverage Requirement + +Unit test coverage must remain **above 97%** at all times. This is enforced as a CI merge gate. + +--- + +## Code Style Guidelines + +### Python + +- **Formatter**: [Ruff](https://docs.astral.sh/ruff/) (configured in `pyproject.toml`) +- **Linter**: Ruff +- **Type checker**: [Pyright](https://github.com/microsoft/pyright) in strict mode +- All code must pass `nox -s typecheck` — never use `# type: ignore` comments. +- Imports must be at the top of each file; no scattered or conditional imports + (exception: `if TYPE_CHECKING:` blocks for circular-import avoidance only). +- Prefer `from module import ClassName` over `import module` when only a few names are used. + +### File Organization + +| Directory | Contents | +|-----------|---------| +| `src/cleveragents/` | Production source code only — no tests, mocks, or examples | +| `features/` | Behave BDD tests and mocks (`features/mocks/`) | +| `robot/` | Robot Framework integration and e2e tests | +| `docs/` | MkDocs documentation (Markdown) | +| `scripts/` | Utility scripts | +| `examples/` | Example code | +| `k8s/` | Kubernetes Helm chart | + +### Commit Messages + +Commit messages must follow [Conventional Commits](https://www.conventionalcommits.org/): + +``` +(): + + +``` + +Valid types: `feat`, `fix`, `docs`, `refactor`, `test`, `chore`, `perf`, `ci`. + +The first line of the commit message must match the **Commit Message** field in the issue +metadata exactly. This is enforced by the pre-commit `commit-msg` hook via Commitizen. + +--- + +## Pull Request Submission Process + +### Before Opening a PR + +1. Ensure `nox` passes with no failures. +2. Ensure coverage is ≥ 97% (`nox -s coverage_report`). +3. Ensure all pre-commit hooks pass (`pre-commit run --all-files`). +4. Rebase your branch on the latest `master`. + +### PR Requirements + +- **Title**: Must match the issue's Commit Message metadata field. +- **Body**: Must reference the issue with `Closes #`. +- **Branch protection**: The `status-check` CI gate must pass (lint, typecheck, security, + unit_tests, coverage). +- **Review**: At least 1 approval required. Self-approval is permitted for automated PRs. + +### Bug Fix Workflow (TDD) + +All bug fixes follow a mandatory TDD workflow: + +1. A `Type/Testing` issue is created with a failing test tagged `@tdd_issue @tdd_issue_ @tdd_expected_fail`. +2. The TDD PR is merged to `master` first (test passes CI via result inversion). +3. The bug fix PR removes `@tdd_expected_fail` and implements the fix. +4. CI enforces that `@tdd_expected_fail` is removed when the fix PR closes the bug issue. + +See the [root CONTRIBUTING.md](../CONTRIBUTING.md) for the complete workflow, label system, +ticket lifecycle, and project-specific guidelines. + +--- + +## Additional Resources + +- [Architecture Overview](architecture.md) +- [Specification](specification.md) +- [Development Guides](development/testing.md) +- [CI/CD Pipeline](development/ci-cd.md) +- [ADR Index](adr/index.md) diff --git a/mkdocs.yml b/mkdocs.yml index 48a98aa71..c568e77b9 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -44,6 +44,8 @@ nav: - Documentation Writer: development/docs-writer.md - Implementation Timeline: timeline.md - FAQ: faq.md + - Changelog: CHANGELOG.md + - Contributing: CONTRIBUTING.md - Reference: reference/ - Architecture Decision Records (ADRs): - Overview: adr/index.md