3 changed files with 312 additions and 0 deletions
@@ -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).*
@@ -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/):
+
+```
+<type>(<scope>): <short summary>
+
+<optional body>
+```
+
+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 #<issue_number>`.
+- **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_<N> @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)
@@ -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