CHANGELOG.md

@@ -322,31 +322,129 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [3.1.0] — 2025-12-20
 
+**Milestone:** Actor Compiler + Full LLM Integration
+
 ### 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).
+- **Actor YAML → LangGraph Compilation** (ADR-031, ADR-032): Actors are now fully declarative.
+  A YAML configuration file describing an actor's graph topology — nodes, edges, conditional
+  routing, skill references, and LSP bindings — is compiled by the Actor Compiler into a
+  LangGraph `StateGraph` at registration time. The compiler validates graph topology (circular
+  reference detection, node type validation, skill reference checks) before accepting
+  registration.
+- **Jinja2 YAML Template Preprocessing** (ADR-032): Actor YAML files are preprocessed with
+  Jinja2 before parsing, enabling environment variable interpolation (`{{ env.MY_KEY }}`),
+  conditional blocks, and template inheritance for shared actor configurations.
+- **MCP (Model Context Protocol) Adapter** (ADR-029): `MCPToolAdapter` integrates external MCP
+  servers as first-class tool sources. Supports `stdio`, `sse`, and `streamable-http`
+  transports. Capability inference from tool names (overridable in YAML). Transparent sandbox
+  path rewriting for filesystem-based tools. Dynamic tool refresh via
+  `notifications/tools/list_changed` events. MCP tools participate in the full four-stage tool
+  lifecycle.
+- **Validation Runner** (ADR-013): Validations are attached to resources and run automatically
+  during the Execute phase. `ApplyValidationSummary` aggregates results and blocks Apply if any
+  required validation fails or if no validations were run (empty-run guard). Supported types:
+  shell command, Python callable, BDD scenario, and custom plugins.
+- **Multi-File Generation**: The LLM execution actor can create, modify, and delete multiple
+  files in a single plan execution via `FILE:` blocks and structured diff output. All operations
+  are written to the git worktree sandbox during Execute and merged during Apply.
+- **Skill Registry** (ADR-012, ADR-028, ADR-030): Central catalog of all skills. Unifies four
+  tool sources — built-in tools, MCP tools, Agent Skills (AgentSkills.io), and custom tools —
+  under a single skill abstraction. Flattens all sources into a unified tool surface per actor,
+  resolving name collisions at registration time.
+- **Agent Skills Standard** (ADR-028): Adopts the [AgentSkills.io](https://AgentSkills.io)
+  standard for packaging instruction-driven workflows as `SKILL.md` files with optional
+  `scripts/`, `references/`, and `assets/` directories. Three-tier progressive disclosure:
+  metadata (~50–100 tokens) at registration, full instructions on activation, resources on
+  demand.
+- **LSP (Language Server Protocol) Client Integration** (ADR-027): Actors declare LSP server
+  bindings in their `lsp:` YAML section. Language intelligence (diagnostics, type information,
+  completions, symbol references, definition lookups) is exposed as tools via `LSPToolAdapter`
+  and as ACMS context enrichment.
+- **Actor Abstraction Definition** (ADR-031): Formal definition of the actor abstraction.
+  Actors are YAML-configured conversational units implemented as LangGraph `StateGraph`
+  instances. The actor/agent distinction is precise: actors are the superset (anything
+  conversational); agents are a specialized subset (LLM-backed with tool-calling and memory).
+- **Skill Abstraction Definition** (ADR-030): Formal definition of the skill abstraction
+  unifying all four tool sources. Actors acquire capabilities exclusively through skills.
+- **Decision Recording Protocol** (ADR-033): Structured protocol for recording decisions at
+  each phase transition: decision ID (ULID), type, rationale, constraints, and parent
+  references.
+- New CLI commands: `agents tool add/remove/list/show`, `agents validation attach/detach/list/run`,
+  `agents skill show/remove`.
+
+### Changed
+
+- Skill YAML format now requires explicit `source` tags for non-built-in tools; MCP servers
+  must be declared in the `mcp_servers` section.
+- Actor YAML files must include an explicit `nodes` section; implicit single-LLM defaults are
+  no longer supported.
+
+### See Also
+
+- [v3.1.0 Release Notes](docs/release-notes/v3.1.0.md)
 
 ---
 
 ## [3.0.0] — 2025-12-06
 
+**Milestone:** Minimal Local Source-Code Workflow (Initial Public Release)
+
 ### 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.
+- **Plan Lifecycle: Action → Strategize → Execute → Apply** (ADR-006): Four-phase structured
+  workflow for AI-assisted source-code editing. Action defines work templates; Strategize
+  gathers context and produces a decision tree (read-only); Execute runs in a sandboxed
+  environment with checkpoints; Apply merges the changeset into real project resources.
+  Supports phase reversion (Execute → Strategize, Apply → Strategize), hierarchical child
+  plans, and automation profile-controlled human review gates at every transition.
+- **Git Worktree Sandbox**: Changes are isolated in a dedicated git branch and worktree
+  (`cleveragents/plan-<plan_id>`) during Execute. On Apply, changes are merged via `git merge`.
+  On rollback, the worktree is discarded entirely. Non-git projects fall back to flat file copy.
+  Displays spec-aligned Apply Summary (plan ID, artifacts, insertions/deletions, project,
+  timestamp) and Sandbox Cleanup panel.
+- **SQLite Persistence** (ADR-019): All domain entities persisted in a local SQLite database.
+  Zero-configuration for local mode. WAL mode for concurrent reads. Alembic migrations for
+  version-controlled schema evolution. ULID identifiers (lexicographically sortable,
+  time-ordered, globally unique). Repository pattern with Unit of Work for transactional
+  consistency. Domain code fully decoupled from SQLAlchemy via protocol interfaces.
+- **Actor-Based LLM Execution Path** (ADR-010, ADR-022, ADR-031): Actors are YAML-configured
+  conversational units implemented as LangGraph `StateGraph` instances. Hierarchical
+  composition (actor graphs referencing other actors by name). Role specialization: strategy,
+  execution, estimation, and invariant actor roles. Provider registry with fallback chain:
+  OpenAI → Anthropic → Google → Azure → OpenRouter → Groq → Together → Cohere.
+- **ChangeSet from Tool Invocations**: Every tool invocation that modifies a resource during
+  Execute is tracked in the plan's ChangeSet (files added/modified/deleted, insertion/deletion
+  counts, per-file diff references, checkpoint associations). The ChangeSet is the input to
+  Apply and the basis for the Apply Summary.
+- **Pydantic v2 Domain Models** (ADR-004): All domain entities (Plan, Decision, Action,
+  Resource, Actor, Tool, Skill, Session, Invariant, AutomationProfile, Checkpoint,
+  CorrectionAttempt) are Pydantic v2 `BaseModel` subclasses. Runtime type validation at every
+  layer boundary. JSON Schema generation for tool-calling protocols. Pydantic Settings for
+  environment variable loading and configuration validation.
+- **Unified `agents` / `cleveragents` CLI entry points** (ADR-021).
+- **Layered architecture** (ADR-001): Entry Points → Application → Domain → Infrastructure →
+  Integration → Core. Domain code never imports from Infrastructure.
+- **Tool system** (ADR-011): Four-stage lifecycle (activate → validate → execute → deactivate).
+  Tool Registry with capability metadata (read-only vs. write) for safety enforcement.
+- **Skill system** (ADR-012): Three-tier progressive disclosure. Metadata at registration;
+  full instructions on activation; resources on demand.
+- **Resource system** (ADR-008): Project assets managed through a DAG with dependency tracking.
+  Supports git-checkout, file, database, and custom resource types.
+- **A2A (Agent-to-Agent) protocol facade** (ADR-026).
+- **DI container** (`cleveragents.application.container`) (ADR-003).
+- **LangChain/LangGraph integration** (ADR-022): LangChain for provider-agnostic LLM
+  abstraction; LangGraph for stateful workflow orchestration with checkpointing and streaming.
+- **Observability** (ADR-025): Structured logging, metrics, audit trail, token/cost tracking.
+- **Plan resume** (`agents plan resume`): Resume interrupted plans from their last checkpoint.
+- **BDD test suite**: Behave (Gherkin feature files) + Robot Framework for integration and
+  end-to-end tests.
+- **Nox automation**: lint, typecheck, tests, docs, benchmarks.
+- **MkDocs-powered documentation** with CleverAgents branding and auto-generated API reference.
+- New CLI commands: `agents plan create/use/execute/apply/resume/list/show/tree/correct/cancel`,
+  `agents actor add/list/show`, `agents resource add/list/stop`, `agents skill add/list`,
+  `agents init`, `agents project list`.
+
+### See Also
+
+- [v3.0.0 Release Notes](docs/release-notes/v3.0.0.md)

docs/release-notes/index.md

@@ -0,0 +1,63 @@
+# Release Notes
+
+This directory contains formal release notes for each CleverAgents Core milestone.
+Release notes provide a comprehensive, user-facing record of what was delivered in each
+version — including key features, CLI commands, breaking changes, and migration guidance.
+
+For a condensed changelog following the [Keep a Changelog](https://keepachangelog.com/en/1.1.0/)
+format, see the [CHANGELOG](../../CHANGELOG.md) at the repository root.
+
+---
+
+## Releases
+
+| Version | Date | Milestone | Notes |
+|---------|------|-----------|-------|
+| [v3.1.0](./v3.1.0.md) | 2025-12-20 | Actor Compiler + Full LLM Integration | Actor YAML→LangGraph compilation, MCP adapter, validation runner, multi-file generation, skill registry |
+| [v3.0.0](./v3.0.0.md) | 2025-12-06 | Minimal Local Source-Code Workflow | Initial public release — plan lifecycle, git worktree sandbox, SQLite persistence, actor-based LLM path, Pydantic v2 domain models |
+
+---
+
+## Release Series
+
+### v3.x — Core Platform
+
+The v3.x series establishes the CleverAgents Core platform: the plan lifecycle, actor system,
+tool and skill infrastructure, persistence layer, and LLM integration. Each minor release
+adds a significant capability layer while maintaining backward compatibility within the series.
+
+| Version | Focus |
+|---------|-------|
+| v3.0.0 | Minimal Local Source-Code Workflow — foundational plan lifecycle and execution engine |
+| v3.1.0 | Actor Compiler + Full LLM Integration — declarative actors, MCP, skills |
+| v3.2.0 | Decisions, Validations, and Invariants |
+| v3.3.0 | Corrections, Subplans, Checkpoint/Rollback |
+| v3.4.0 | ACMS v1, Resource Type Inheritance, Safety Profiles |
+| v3.5.0 | Autonomy Hardening, Resource DAG, Container/LSP Resources |
+| v3.6.0 | Advanced Context Management System (ACMS), UKO Runtime |
+| v3.7.0 | Interactive TUI |
+| v3.8.0 | Invariant Reconciliation, TUI Shell Safety, UKO Provenance, JSON-RPC 2.0 A2A |
+
+---
+
+## How to Read Release Notes
+
+Each release note document follows a consistent structure:
+
+1. **Overview** — The milestone goal and what was delivered
+2. **Key Features Delivered** — Detailed description of each major feature
+3. **CLI Commands Introduced** — New commands available after upgrading
+4. **Technical Highlights** — Architecture decisions and implementation details
+5. **Breaking Changes** — Any changes that require updates to existing configurations or code
+6. **Migration Guide** — Step-by-step instructions for upgrading from the previous version
+7. **Architecture Decision Records** — ADRs accepted as part of this milestone
+
+---
+
+## Related Resources
+
+- [CHANGELOG](../../CHANGELOG.md) — Condensed changelog (Keep a Changelog format)
+- [Architecture Overview](../architecture.md)
+- [ADR Index](../adr/index.md)
+- [API Reference](../api/index.md)
+- [Timeline](../timeline.md)

docs/release-notes/v3.0.0.md

@@ -0,0 +1,233 @@
+# Release Notes — v3.0.0
+
+**Release Date:** 2025-12-06  
+**Milestone:** Minimal Local Source-Code Workflow  
+**Type:** Major Release (Initial Public Release)
+
+---
+
+## Overview
+
+v3.0.0 is the initial public release of **CleverAgents Core** — the foundational milestone that
+establishes the complete end-to-end workflow for AI-assisted local source-code editing. This
+release delivers a production-ready, four-phase plan lifecycle, a git-worktree-based sandbox,
+SQLite-backed persistence, an actor-driven LLM execution path, and a full suite of Pydantic v2
+domain models.
+
+The goal of this milestone was to prove the core loop: a user describes work → the system
+strategizes, executes in isolation, and applies changes to the real project — with full
+traceability, rollback capability, and human review gates at every transition.
+
+---
+
+## Key Features Delivered
+
+### Plan Lifecycle: Action → Strategize → Execute → Apply
+
+Every unit of work in CleverAgents follows a structured four-phase lifecycle (ADR-006):
+
+| Phase | Description |
+|-------|-------------|
+| **Action** | A reusable plan template defining work, actors, and invariants — not yet bound to a project |
+| **Strategize** | Read-only context gathering; produces a decision tree of approach choices and resource selections |
+| **Execute** | Sandboxed execution; actors invoke tools, write changes, and create checkpoints |
+| **Apply** | Controlled commit; merges the sandboxed changeset into real project resources |
+
+Phase transitions are gated by automation profiles, enabling fully autonomous or human-reviewed
+workflows. Phase reversion (Execute → Strategize, Apply → Strategize) provides structured
+recovery without plan abandonment.
+
+### Git Worktree Sandbox
+
+Changes are isolated in a dedicated git branch and worktree (`cleveragents/plan-<plan_id>`)
+during execution. On apply, changes are merged back via `git merge`. On rollback, the worktree
+is discarded entirely. Non-git projects fall back to a flat file copy strategy.
+
+See [Git Worktree Sandbox module documentation](../modules/git-worktree-sandbox.md) for full
+API reference.
+
+### SQLite Persistence
+
+All domain entities — plans, decisions, resources, actors, sessions, checkpoints, and more —
+are persisted in a local SQLite database (ADR-019). Key design choices:
+
+- **Zero-configuration**: no external database server required for local mode
+- **WAL mode**: concurrent reads during parallel plan execution
+- **Alembic migrations**: version-controlled, reversible schema evolution
+- **ULID identifiers**: lexicographically sortable, time-ordered, globally unique entity IDs
+- **Repository pattern**: domain code is fully decoupled from SQLAlchemy via protocol interfaces
+
+### Actor-Based LLM Execution Path
+
+Actors are YAML-configured conversational units implemented as LangGraph `StateGraph` instances
+(ADR-031, ADR-022). Every custom actor is technically a graph — from a single LLM node to a
+complex multi-stage orchestrator. Key capabilities:
+
+- **Hierarchical composition**: actor graphs can reference other actors by name, enabling
+  "orchestrator of orchestrators" patterns with no depth limit
+- **Role specialization**: strategy, execution, estimation, and invariant actor roles
+- **Skill-based capability acquisition**: actors gain tool access exclusively through the skill
+  system — no direct tool references outside skills
+- **Provider registry with fallback chain**: OpenAI → Anthropic → Google → Azure → OpenRouter →
+  Groq → Together → Cohere
+
+### ChangeSet from Tool Invocations
+
+During the Execute phase, every tool invocation that modifies a resource is tracked in the
+plan's ChangeSet. The ChangeSet records:
+
+- Files added, modified, and deleted
+- Insertion and deletion line counts
+- Per-file diff references
+- Checkpoint associations for fine-grained rollback
+
+The ChangeSet is the input to the Apply phase and the basis for the Apply Summary displayed
+to the user.
+
+### Pydantic v2 Domain Models
+
+All domain entities (Plan, Decision, Action, Resource, Actor, Tool, Skill, Session, Invariant,
+AutomationProfile, Checkpoint, CorrectionAttempt) are Pydantic v2 `BaseModel` subclasses
+(ADR-004). This provides:
+
+- Runtime type validation at every layer boundary
+- JSON Schema generation for tool-calling protocols
+- Structured, actionable validation error messages for CLI display
+- Pydantic Settings for environment variable loading and configuration validation
+
+---
+
+## CLI Commands Introduced
+
+| Command | Description |
+|---------|-------------|
+| `agents` / `cleveragents` | Unified CLI entry points |
+| `agents plan create` | Create a new plan from an action template |
+| `agents plan use <action>` | Bind an action to a project and enter Strategize |
+| `agents plan execute <plan_id>` | Transition a plan from Strategize to Execute |
+| `agents plan apply <plan_id>` | Apply sandboxed changes to the real project |
+| `agents plan resume <plan_id>` | Resume an interrupted plan from its last checkpoint |
+| `agents plan list` | List all plans with status |
+| `agents plan show <plan_id>` | Show plan details and decision tree |
+| `agents plan tree <plan_id>` | Display the decision tree for a plan |
+| `agents plan correct <plan_id>` | Correct a decision and revert to Strategize |
+| `agents plan cancel <plan_id>` | Cancel a plan |
+| `agents actor add` | Register a new actor from a YAML definition |
+| `agents actor list` | List registered actors |
+| `agents actor show <name>` | Show actor details |
+| `agents resource add` | Register a project resource |
+| `agents resource list` | List registered resources |
+| `agents resource stop` | Stop a running resource instance |
+| `agents skill add` | Register a skill |
+| `agents skill list` | List registered skills |
+| `agents init` | Initialize a new CleverAgents project |
+| `agents project list` | List configured projects |
+
+---
+
+## Technical Highlights
+
+### Layered Architecture (ADR-001)
+
+Six-layer clean architecture enforced at import boundaries:
+
+```
+Entry Points → Application → Domain → Infrastructure → Integration → Core
+```
+
+Domain code never imports from Infrastructure. All persistence and LLM calls go through
+protocol interfaces injected by the DI container (ADR-003).
+
+### Tool System (ADR-011)
+
+Four-stage tool lifecycle: **activate → validate → execute → deactivate**. Tools are
+registered in the Tool Registry with capability metadata (read-only vs. write) for safety
+enforcement. Tool input/output schemas are Pydantic models that generate JSON Schema for
+LLM tool-calling.
+
+### Skill System (ADR-012)
+
+Three-tier progressive disclosure: metadata (~50–100 tokens) loads at registration; full
+instructions load only when the skill is activated; resources (scripts, references, assets)
+load on demand. This keeps startup token cost minimal even with dozens of skills registered.
+
+### Resource System (ADR-008)
+
+Resources are project assets managed through a DAG with dependency tracking. The resource
+system supports git-checkout, file, database, and custom resource types. Resources are
+bound to plans and sandboxed per the lifecycle phases.
+
+### Observability (ADR-025)
+
+Structured logging, metrics, audit trail, and token/cost tracking are wired throughout the
+execution path. Every tool invocation, phase transition, and decision is recorded.
+
+### BDD Test Suite
+
+Behavior-Driven Development with Behave (Gherkin feature files) and Robot Framework for
+integration and end-to-end tests. Nox automation for lint, typecheck, tests, docs, and
+benchmarks.
+
+### MkDocs Documentation
+
+MkDocs-powered documentation with CleverAgents branding, auto-generated API reference pages,
+and ADR index.
+
+---
+
+## Breaking Changes
+
+This is the initial public release. There are no breaking changes from a prior stable version.
+
+---
+
+## Migration Guide
+
+No migration required. This is the first stable release.
+
+To get started:
+
+```bash
+pip install cleveragents-core
+agents init
+agents actor add path/to/my-actor.yaml
+agents plan create --action local/my-action --project my-project
+```
+
+---
+
+## Architecture Decision Records
+
+The following ADRs were accepted as part of this milestone:
+
+| ADR | Title |
+|-----|-------|
+| ADR-001 | Layered Architecture |
+| ADR-002 | Namespace System |
+| ADR-003 | Dependency Injection |
+| ADR-004 | Data Validation (Pydantic v2) |
+| ADR-005 | Technical Stack |
+| ADR-006 | Plan Lifecycle |
+| ADR-007 | Decision Tree and Correction |
+| ADR-008 | Resource System |
+| ADR-009 | Project Model |
+| ADR-010 | Actor and Agent Architecture |
+| ADR-011 | Tool System |
+| ADR-012 | Skill System |
+| ADR-015 | Sandbox and Checkpoint |
+| ADR-019 | Storage and Persistence |
+| ADR-021 | CLI and Output Rendering |
+| ADR-022 | LangChain/LangGraph Integration |
+| ADR-024 | Configuration System |
+| ADR-025 | Observability and Logging |
+
+---
+
+## Related Documentation
+
+- [Architecture Overview](../architecture.md)
+- [Plan Lifecycle (ADR-006)](../adr/ADR-006-plan-lifecycle.md)
+- [Actor Abstraction (ADR-031)](../adr/ADR-031-actor-abstraction-definition.md)
+- [Storage and Persistence (ADR-019)](../adr/ADR-019-storage-and-persistence.md)
+- [Git Worktree Sandbox](../modules/git-worktree-sandbox.md)
+- [v3.1.0 Release Notes](./v3.1.0.md)

docs/release-notes/v3.1.0.md

@@ -0,0 +1,304 @@
+# Release Notes — v3.1.0
+
+**Release Date:** 2025-12-20  
+**Milestone:** Actor Compiler + Full LLM Integration  
+**Type:** Minor Release
+
+---
+
+## Overview
+
+v3.1.0 delivers the **Actor Compiler** and **Full LLM Integration** milestone, building directly
+on the foundational plan lifecycle and persistence layer introduced in v3.0.0. This release
+makes actors fully declarative: a YAML file describing a LangGraph node graph is compiled at
+registration time into a runnable `StateGraph` instance. It also integrates the Model Context
+Protocol (MCP) adapter, a validation runner, multi-file generation support, and the skill
+registry — completing the core capability acquisition pipeline.
+
+---
+
+## Key Features Delivered
+
+### Actor YAML → LangGraph Compilation
+
+Actors are now fully declarative. A YAML configuration file describing an actor's graph
+topology — nodes, edges, conditional routing, skill references, and LSP bindings — is compiled
+by the Actor Compiler into a LangGraph `StateGraph` at registration time (ADR-031, ADR-032).
+
+**What this means in practice:**
+
+- No Python code is required to define a new actor
+- Actors are registered via `agents actor add path/to/actor.yaml`
+- The compiler validates the graph topology (detects circular references, validates node types,
+  checks skill references) before accepting the registration
+- Jinja2 template preprocessing (ADR-032) allows environment variable interpolation and
+  conditional blocks in actor YAML files
+
+**Example actor YAML:**
+
+```yaml
+name: local/code-reviewer
+description: Reviews code changes for correctness, style, and security issues
+skills:
+  - local/code-analysis
+  - local/git-tools
+nodes:
+  - id: reviewer
+    type: agent
+    model: openai/gpt-4o
+    system_prompt: |
+      You are a senior software engineer reviewing code changes.
+      Use your tools to analyze the diff and provide structured feedback.
+  - id: format_output
+    type: tool
+    tool: local/format-review-output
+edges:
+  - from: reviewer
+    to: format_output
+  - from: format_output
+    to: END
+```
+
+### MCP Adapter
+
+The Model Context Protocol (MCP) adapter (`MCPToolAdapter`) integrates external MCP servers
+as first-class tool sources (ADR-029). MCP tools are registered in the Tool Registry with
+extended capability metadata and are available to any actor assigned a skill that includes them.
+
+**Key capabilities:**
+
+- **Transport support**: `stdio`, `sse`, and `streamable-http` transports
+- **Capability inference**: tool names are analyzed to infer read-only vs. write capability
+  (overridable in YAML)
+- **Sandbox path rewriting**: file paths in MCP tool arguments are transparently rewritten to
+  sandbox paths; results are rewritten back to logical paths
+- **Dynamic tool refresh**: the adapter subscribes to `notifications/tools/list_changed` events
+  and updates the Tool Registry without restarting
+- **Four-stage lifecycle**: MCP tools participate in the same activate → validate → execute →
+  deactivate lifecycle as built-in tools
+
+**Declaring an MCP server in a skill:**
+
+```yaml
+name: local/github-tools
+mcp_servers:
+  - name: github
+    transport: stdio
+    command: npx
+    args: ["-y", "@modelcontextprotocol/server-github"]
+    env:
+      GITHUB_PERSONAL_ACCESS_TOKEN: "${GITHUB_TOKEN}"
+```
+
+### Validation Runner
+
+The validation runner executes attached validations during the Execute phase and gates the
+Apply transition on their results (ADR-013). Validations are attached to resources and run
+automatically when the plan's execution actor modifies those resources.
+
+**Validation types supported:**
+
+- Shell command validations (exit code 0 = pass)
+- Python callable validations
+- BDD scenario validations (Behave)
+- Custom validation plugins
+
+The `ApplyValidationSummary` aggregates results across all validations and blocks Apply if
+any required validation fails or if no validations were run (empty-run guard).
+
+### Multi-File Generation
+
+The Execute phase now supports generating and modifying multiple files in a single plan
+execution. The LLM execution actor can:
+
+- Create new files via `FILE:` blocks in its output
+- Modify existing files via structured diff output
+- Delete files via explicit deletion markers
+- Respect `.gitignore` and project-level exclusion rules
+
+All file operations are written to the git worktree sandbox during Execute and merged to the
+real project during Apply.
+
+### Skill Registry
+
+The Skill Registry is the central catalog of all skills available to actors (ADR-012,
+ADR-028, ADR-030). In v3.1.0, the registry supports four tool sources unified under a single
+skill abstraction:
+
+| Source | Description |
+|--------|-------------|
+| **Built-in tools** | Core tools shipped with CleverAgents (file I/O, shell, git) |
+| **MCP tools** | External tools discovered from MCP servers |
+| **Agent Skills** | Instruction-driven workflows from `SKILL.md` files (AgentSkills.io standard) |
+| **Custom tools** | User-defined Python callables registered via YAML |
+
+The registry flattens all four sources into a unified tool surface for each actor, resolving
+name collisions at registration time.
+
+### Agent Skills Standard (AgentSkills.io)
+
+CleverAgents adopts the [AgentSkills.io](https://AgentSkills.io) standard for packaging
+instruction-driven workflows (ADR-028). Skills are authored as `SKILL.md` files with optional
+`scripts/`, `references/`, and `assets/` directories.
+
+**Progressive disclosure tiers:**
+
+| Tier | What loads | Token cost |
+|------|-----------|------------|
+| Metadata | `name` + `description` from frontmatter | ~50–100 tokens per skill |
+| Instructions | Full `SKILL.md` Markdown body | Loaded only when skill is activated |
+| Resources | `scripts/`, `references/`, `assets/` | Loaded on demand during execution |
+
+### LSP Integration (ADR-027)
+
+Language Server Protocol (LSP) client integration gives actors language intelligence
+(diagnostics, type information, completions, symbol references, definition lookups) without
+coupling to any IDE. LSP servers are declared in actor YAML via the `lsp:` section and
+activated at actor startup.
+
+---
+
+## CLI Commands Introduced
+
+| Command | Description |
+|---------|-------------|
+| `agents tool add` | Register a new tool from a YAML definition |
+| `agents tool remove` | Unregister a tool |
+| `agents tool list` | List registered tools |
+| `agents tool show <name>` | Show tool details and schema |
+| `agents validation attach` | Attach a validation to a resource |
+| `agents validation detach` | Detach a validation from a resource |
+| `agents validation list` | List validations attached to a resource |
+| `agents validation run` | Run validations manually |
+| `agents skill show <name>` | Show skill details and tool surface |
+| `agents skill remove` | Unregister a skill |
+
+---
+
+## Technical Highlights
+
+### Jinja2 YAML Template Preprocessing (ADR-032)
+
+Actor YAML files are preprocessed with Jinja2 before parsing. This enables:
+
+- Environment variable interpolation: `{{ env.MY_API_KEY }}`
+- Conditional blocks: `{% if env.DEBUG %}...{% endif %}`
+- Template inheritance for shared actor configurations
+
+### Actor Abstraction Formalization (ADR-031)
+
+The actor abstraction is formally defined: an actor is a YAML-configured conversational unit
+implemented as a LangGraph `StateGraph`. The actor/agent distinction is precise:
+
+- **Actor**: anything conversational — the general abstraction (superset)
+- **Agent**: a specialized actor with LLM reasoning, tool-calling, and memory (subset)
+
+Every custom actor IS a graph. This unification eliminates separate "workflow," "pipeline,"
+and "orchestrator" concepts.
+
+### Skill Abstraction Definition (ADR-030)
+
+The skill abstraction unifies four tool sources (built-in, MCP, Agent Skills, custom) under
+a single interface. Actors acquire capabilities exclusively through skills — there is no
+mechanism for an actor to gain tool capabilities outside the skill system.
+
+### Decision Recording Protocol (ADR-033)
+
+Decisions are recorded at each phase transition with a structured protocol: decision ID
+(ULID), decision type, rationale, constraints, and parent decision references. The decision
+tree is the persistent record of why every change was made.
+
+---
+
+## Breaking Changes
+
+### Skill YAML Format
+
+The `tools` section in skill YAML now requires explicit `source` tags for non-built-in tools:
+
+```yaml
+# v3.0.0 (implicit source)
+tools:
+  - name: my-tool
+
+# v3.1.0 (explicit source required for MCP and Agent Skills)
+tools:
+  - name: my-tool
+    source: builtin
+
+mcp_servers:
+  - name: github
+    transport: stdio
+    command: npx
+    args: ["-y", "@modelcontextprotocol/server-github"]
+```
+
+### Actor YAML: `nodes` Required
+
+Actor YAML files must now include a `nodes` section. Single-LLM actors that previously
+relied on implicit defaults must be updated to declare their node explicitly:
+
+```yaml
+# v3.1.0 minimum actor YAML
+name: local/my-actor
+description: My actor
+skills:
+  - local/my-skill
+nodes:
+  - id: llm
+    type: agent
+    model: openai/gpt-4o
+```
+
+---
+
+## Migration Guide
+
+### Updating Skill YAML Files
+
+Add explicit `source` tags to any non-built-in tools in your skill YAML files. MCP servers
+should be moved to the `mcp_servers` section. Agent Skills should be declared in the
+`agent_skills` section.
+
+### Updating Actor YAML Files
+
+Add a `nodes` section to any actor YAML files that relied on implicit single-LLM defaults.
+Specify the model, system prompt, and any tool nodes explicitly.
+
+### Re-registering Actors
+
+After updating YAML files, re-register actors:
+
+```bash
+agents actor add path/to/updated-actor.yaml --replace
+```
+
+---
+
+## Architecture Decision Records
+
+The following ADRs were accepted as part of this milestone:
+
+| ADR | Title |
+|-----|-------|
+| ADR-013 | Validation Abstraction |
+| ADR-027 | Language Server Protocol (LSP) Integration |
+| ADR-028 | Agent Skills Standard (AgentSkills.io) |
+| ADR-029 | Model Context Protocol (MCP) Adoption |
+| ADR-030 | Skill Abstraction Definition |
+| ADR-031 | Actor Abstraction Definition |
+| ADR-032 | Jinja2 YAML Template Preprocessing |
+| ADR-033 | Decision Recording Protocol |
+
+---
+
+## Related Documentation
+
+- [MCP Adapter (ADR-029)](../adr/ADR-029-model-context-protocol.md)
+- [Actor Abstraction (ADR-031)](../adr/ADR-031-actor-abstraction-definition.md)
+- [Agent Skills Standard (ADR-028)](../adr/ADR-028-agent-skills-standard.md)
+- [Skill Abstraction (ADR-030)](../adr/ADR-030-skill-abstraction-definition.md)
+- [API — Actor](../api/actor.md)
+- [API — Skills](../api/skills.md)
+- [API — MCP](../api/mcp.md)
+- [v3.0.0 Release Notes](./v3.0.0.md)