@cleocode/cleo 2026.2.5 → 2026.2.7

package/README.md

@@ -1,17 +1,17 @@
-<p alis|version-[0-9]\+\.[0-9]\+\.[0-9]\+-|version-2026.2.5-|g|version-[0-9]\+\.[0-9]\+\.[0-9]\+-|version-2026.2.4-|g|version-[0-9]\+\.[0-9]\+\.[0-9]\+-|version-2026.2.3-|gn="center">
+<p align="center">
   <img src="docs/images/banner.png" alt="CLEO banner" width="900">
 </p>
 
 <h1 align="center">CLEO</h1>
-<h3 align="center">Command Line Entity Orchestrator</h3>
+<h3 align="center">The Portable Brain and Memory System for AI Software Development</h3>
 
 <p align="center">
-  <strong>The task management system designed for AI coding agents and solo developers</strong>
+  <strong>The contract between you and your AI coding agent</strong>
 </p>
 
 <p align="center">
   <img src="https://img.shields.io/badge/License-BSL%201.1-blue" alt="License: Business Source License 1.1">
-  <a href="CHANGELOG.md"><img src="https://img.shields.io/badge/version-2026.2.1-blue.svg" alt="Version"></a>
+  <a href="CHANGELOG.md"><img src="https://img.shields.io/badge/version-2026.2.6-blue.svg" alt="Version"></a>
   <a href="docs/specs/LLM-AGENT-FIRST-SPEC.md"><img src="https://img.shields.io/badge/design-LLM--Agent--First-purple.svg" alt="LLM-Agent-First"></a>
   <a href="tests/"><img src="https://img.shields.io/badge/tests-passing-brightgreen.svg" alt="Tests"></a>
 </p>
@@ -67,35 +67,46 @@
 
 ## One Developer. One Agent. One Source of Truth.
 
-**CLEO** (Command Line Entity Orchestrator) is a vendor-neutral Brain and Memory system for AI software development. It's the **contract between you and your AI coding agent**—not just a task tracker, but a structured protocol for portable memory, provenance, and deterministic agent execution.
+**CLEO** is a vendor-neutral **Brain and Memory system** for AI software development. It provides portable project memory, verifiable provenance, and agent-safe orchestration across any repository, model provider, or coding tool.
+
+> CLEO originated as "Command Line Entity Orchestrator" but has evolved beyond that acronym. CLEO is the proper name for the complete platform.
 
-- **Agents hallucinate**. CLEO validates every operation before execution.
-- **Agents lose context**. CLEO persists state across sessions with immutable audit trails.
-- **Agents need structure**. CLEO outputs JSON by default, with human-readable formatting opt-in.
+- **Agents hallucinate**. CLEO validates every operation with four-layer anti-hallucination.
+- **Agents lose context**. CLEO persists state in SQLite with immutable audit trails.
+- **Agents need structure**. CLEO outputs JSON by default via the LAFS protocol.
 
 Optimized for [Claude Code](https://claude.ai/claude-code), and intentionally portable across model providers, agent runtimes, and coding tools.
 
-### Canonical Product Identity
+### Four Systems
+
+CLEO is composed of four interdependent systems:
+
+- **BRAIN — Memory & Cognition**: Persistent memory backend storing observations, patterns, learnings, and decisions. Provides FTS5 search, vector similarity, and graph-based retrieval.
+- **RCASD-IVTR+C — Structured Lifecycle**: Ten-stage pipeline from Research through Release, plus cross-cutting Contribution protocol. Deterministic gates and manifest-based provenance.
+- **NEXUS — Cross-Project Network**: Connective layer between registered CLEO projects. Global graphs, shared patterns, and federated queries while preserving per-project isolation.
+- **LAFS — Agent Communication Contract**: The [LLM-Agent-First Specification](https://github.com/kryptobaseddev/lafs-protocol) protocol. JSON envelopes, MVI progressive disclosure, field filtering, and deterministic exit codes.
 
-CLEO provides:
+### Five Pillars
 
-- **Portable Memory**: Project -> Epic -> Task hierarchy, research manifests, and agent outputs
-- **Provenance by Default**: Every artifact traceable to task, decision, agent, and operation
-- **Interoperable Interfaces**: CLI + MCP + provider/tool adapters without vendor lock-in
-- **Deterministic Safety**: Validation layers, lifecycle gates, atomic writes, immutable audit logs
-- **Cognitive Retrieval**: Page index + graph/vector/RAG for Tier M/L contextual reasoning
+1. **Portable Memory (BRAIN)** — Per-project `.cleo/` directory with `tasks.db` (project work) and `brain.db` (memory/cognition). Move the directory, the brain moves with it.
+2. **Agent Communication Contract (LAFS)** — Provider-neutral protocol: JSON envelopes, MVI-tiered progressive disclosure, field filtering, deterministic exit codes.
+3. **Structured Lifecycle (RCASD-IVTR+C)** — Research → Consensus → Architecture Decision → Specification → Decomposition → Implementation → Validation → Testing → Release + Contribution.
+4. **Deterministic Safety** — Four-layer validation (schema, semantic, referential, state machine), atomic writes, immutable audit logs, lifecycle gate enforcement.
+5. **Cognitive Retrieval (BRAIN + NEXUS)** — Three-tier retrieval: FTS5 keyword search, vector similarity, graph-based discovery. NEXUS extends retrieval across project boundaries.
 
 ### Current State vs Strategic Direction
 
 | State | What It Means |
 |------|----------------|
-| **Current (Shipped)** | Bash-native CLI is production baseline with atomic operations, anti-hallucination validation, lifecycle enforcement, and persistent project memory |
-| **Strategic (Gated)** | Nexus validation, memory/reasoning expansion, and Tier M/L multi-agent intelligence are roadmap-driven and evidence-gated |
+| **Shipped** | TypeScript CLI + MCP server, SQLite storage (`tasks.db`), atomic operations, four-layer anti-hallucination, RCASD-IVTR+C lifecycle gates, session management, vectorless RAG (5 discovery methods), LAFS envelopes |
+| **Gated** | Dedicated `brain.db` (FTS5, vector, PageIndex), `nexus.db` (cross-project graph), knowledge graph with version chains, agent profiles, federated queries |
 
 ### MCP Server
 
 The MCP server is included in the `@cleocode/cleo` package. No separate install needed.
 
+For provider-specific MCP setup and profile management (Claude Code, OpenCode, Antigravity, etc.), use CAAMP as the canonical installer/config manager.
+
 **Auto-configure** across your AI tools:
 
 ```bash
@@ -150,11 +161,11 @@ cleo_mutate domain=tasks   operation=complete params={"taskId": "T1234", "notes"
 cleo_mutate domain=issues  operation=add.bug  params={"title": "...", "body": "...", "dryRun": true}
 ```
 
-11 domains, 140 operations (75 query + 65 mutate) across tasks, sessions, issues, orchestration, research, lifecycle, validation, releases, skills, providers, and system management. See the [MCP Usage Guide](docs/guides/mcp-usage-guide.mdx) for beginner-friendly walkthroughs.
+10 canonical domains, 164 operations (93 query + 71 mutate) across tasks, sessions, memory, check, pipeline, orchestration, tools, admin, nexus, and sharing. See the [MCP Usage Guide](docs/guides/mcp-usage-guide.mdx) for beginner-friendly walkthroughs.
 
 ### Source of Truth Hierarchy
 
-1. [`docs/concepts/vision.mdx`](docs/concepts/vision.mdx) - immutable product vision
+1. [`docs/concepts/vision.md`](docs/concepts/vision.md) - immutable product vision
 2. [`docs/specs/PORTABLE-BRAIN-SPEC.md`](docs/specs/PORTABLE-BRAIN-SPEC.md) - canonical normative contract
 3. [`README.md`](README.md) - operational public contract
 4. [`docs/specs/CLEO-STRATEGIC-ROADMAP-SPEC.md`](docs/specs/CLEO-STRATEGIC-ROADMAP-SPEC.md) - phased execution plan
@@ -174,7 +185,7 @@ Traditional task management assumes human users. But when your primary "user" is
 | Trust | Validation |
 | Memory | Persistence |
 
-**CLEO is built for agents first.** The `--human` flag is for you—the developer reviewing what your agent sees.
+**CLEO is built for agents first.** The `--human` flag is for you — the developer reviewing what your agent sees.
 
 ---
 
@@ -210,7 +221,7 @@ Four layers of validation prevent AI-generated errors:
 Before any write operation:
 ```bash
 ✓ ID exists (prevent hallucinated references)
-✓ ID unique (across todo.json AND archive)
+✓ ID unique (across active and archived tasks)
 ✓ Status valid (pending|active|blocked|done)
 ✓ Timestamps sane (not future, completedAt > createdAt)
 ✓ Dependencies acyclic (no circular references)
@@ -234,6 +245,27 @@ IDs are **flat, sequential, and eternal**. No hierarchical IDs like `T001.2.3` t
 
 ## Quick Start
 
+### Installation Channels (Stable, Beta, Dev)
+
+CLEO supports three runtime channels:
+
+- **Stable**: production users (`cleo`, `cleo-mcp`, optional `ct`)
+- **Beta**: prerelease validation (`cleo-beta`, `cleo-mcp-beta`, optional `ct-beta`)
+- **Dev**: contributor-isolated runtime (`cleo-dev`, `cleo-mcp-dev`, no `ct`)
+
+The dev channel is designed to run in parallel with stable and should use isolated data (`~/.cleo-dev`).
+
+### Contributor Dev Setup (Isolated)
+
+Use the installer dev mode for canonical `cleo-dev` behavior:
+
+```bash
+./install.sh --dev
+cleo-dev env info --json
+```
+
+`npm link` caveat: raw `npm link` follows `package.json` bin mappings and can expose `cleo`/`ct`. Use `./install.sh --dev` when you need strict dev-channel isolation.
+
 ### TL;DR - Just Install It
 
 **Option 1: One-liner (Easiest)**
@@ -267,7 +299,7 @@ git clone https://github.com/kryptobaseddev/cleo.git && cd cleo && ./installer/i
 
 Then initialize in your project:
 ```bash
-cd /path/to/your/project && cleo init
+cd /path/to/your/project && cleo-dev init
 ```
 
 <details>
@@ -277,21 +309,17 @@ cd /path/to/your/project && cleo init
 
 | Dependency | Version | Install |
 |------------|---------|---------|
-| **Bash** | 4.0+ | Pre-installed (check: `bash --version`). macOS: `brew install bash` |
-| **jq** | 1.6+ | `apt install jq` / `brew install jq` / `dnf install jq` |
-| **flock** | Any | For atomic file operations. Linux: pre-installed. macOS: `brew install flock` or `brew install util-linux` |
+| **Node.js** | 24+ | https://nodejs.org/ |
+| **npm** | Latest with Node.js | Included with Node |
 | **curl** or **wget** | Any | Pre-installed on most systems (for remote install) |
-| **sha256sum** | Any | For checksum verification. Linux: pre-installed. macOS: comes with coreutils |
 
 **Optional (Advanced Features):**
 
 | Dependency | For | Install |
 |------------|-----|---------|
-| **Python 3.x** | Skill creator scripts | Pre-installed on most systems |
-| **PyYAML** | Skill creator scripts | `pip install pyyaml` |
-| **ajv-cli** | JSON Schema validation | `npm install -g ajv-cli` |
+| **sqlite3 CLI** | Manual DB inspection/debugging | platform package manager |
 
-> **Note**: The core CLEO CLI is pure Bash. Python is only needed for skill creation/validation scripts.
+> **Note**: CLEO is TypeScript/Node.js. Contributor docs in `CONTRIBUTING.md` cover full dev setup.
 
 </details>
 
@@ -322,37 +350,39 @@ curl -fsSL https://raw.githubusercontent.com/kryptobaseddev/cleo/main/install.sh
 git clone https://github.com/kryptobaseddev/cleo.git
 cd cleo
 
-# Install for development (creates symlinks to repo)
+# Install dev channel (isolated command names)
 ./installer/install.sh --dev
 
+# Verify isolated runtime
+cleo-dev env info --json
+
 # Or install as release (copies files)
 ./installer/install.sh --release
 ```
 
+`npm link` caveat: raw `npm link` follows package bin mappings and can expose `cleo`/`ct`. Use `./installer/install.sh --dev` when you need strict `cleo-dev` isolation.
+
 #### Verify Installation
 
 ```bash
 cleo version
-cleo --validate
+cleo env info --json
 ```
 
-#### Claude CLI Aliases (Optional)
+Provider alias/config utilities are managed by CAAMP.
 
-Install optimized aliases for Claude Code CLI:
+#### Initialize in Your Project
 
 ```bash
-cleo setup-claude-aliases
+cd /path/to/your/project
+cleo init
 ```
 
-This installs `cc`, `ccy`, `ccr`, and other aliases across bash, zsh, PowerShell, and CMD.exe. See [setup-claude-aliases docs](docs/commands/setup-claude-aliases.md) for details.
-
-> **Tip**: During interactive installation, you'll be prompted to install aliases automatically.
-
-#### Initialize in Your Project
+For contributor dev channel:
 
 ```bash
 cd /path/to/your/project
-cleo init
+cleo-dev init
 ```
 
 > **Note**: The installer creates symlinks in `~/.local/bin/`, which works immediately with Claude Code and most modern shells.
@@ -441,6 +471,8 @@ cleo migrate run
 
 ### The `ct` Shortcut
 
+`ct` is a stable-channel compatibility alias. Dev channel intentionally does not provide `ct`; use `cleo-dev`.
+
 ```bash
 ct list        # Same as cleo list
 ct add "Task"  # Same as cleo add "Task"
@@ -475,7 +507,7 @@ autoload -Uz compinit && compinit
 # Example usage
 cleo add --parent <TAB>     # Shows T001, T002 (epic/task only)
 cleo list --status <TAB>    # Shows pending, active, blocked, done
-cleo focus set <TAB>        # Shows pending/active task IDs
+cleo start <TAB>             # Shows pending/active task IDs
 ```
 
 ---
@@ -487,7 +519,7 @@ cleo focus set <TAB>        # Shows pending/active task IDs
 
 | Category | Commands | Purpose |
 |----------|----------|---------|
-| **Write (14)** | `add`, `update`, `complete`, `focus`, `session`, `phase`, `archive`, `promote`, `reparent`, `populate-hierarchy`, `delete`, `uncancel`, `reopen`, `verify` | Modify task state |
+| **Write (14)** | `add`, `update`, `complete`, `start`, `session`, `phase`, `archive`, `promote`, `reparent`, `populate-hierarchy`, `delete`, `uncancel`, `reopen`, `verify` | Modify task state |
 | **Read (17)** | `list`, `show`, `find`, `analyze`, `next`, `dash`, `deps`, `blockers`, `phases`, `labels`, `stats`, `log`, `commands`, `exists`, `export`, `history`, `research` | Query and analyze |
 | **Sync (3)** | `sync`, `inject`, `extract` | TodoWrite integration |
 | **Orchestration (5)** | `orchestrator`, `context`, `tree`, `import-tasks`, `export-tasks` | Multi-agent coordination |
@@ -506,14 +538,14 @@ cleo archive
 
 # Session workflow
 cleo session start
-cleo focus set T001           # Only ONE active task allowed
-cleo focus note "Working on JWT validation"
+cleo start T001               # Only ONE active task allowed
+cleo update T001 --notes "Working on JWT validation"
 cleo session end
 
 # Analysis & planning
 cleo dash                     # Project overview
 cleo analyze                  # Task triage with leverage scoring
-cleo analyze --auto-focus     # Auto-set focus to highest leverage task
+cleo analyze --auto-start     # Auto-start highest leverage task
 cleo next --explain           # What should I work on?
 cleo blockers analyze         # Critical path analysis
 
@@ -682,11 +714,11 @@ Agents lose context between invocations. Sessions provide checkpoints:
 # Morning routine
 cleo session start
 cleo dash              # Where am I?
-cleo focus show        # What was I working on?
+cleo current           # What was I working on?
 
 # Work session
-cleo focus set T042
-cleo focus note "Implementing validation logic"
+cleo start T042
+cleo update T042 --notes "Implementing validation logic"
 cleo update T042 --notes "Tests passing"
 
 # End of day
@@ -700,7 +732,7 @@ cleo session end
 
 | Command | Purpose | Storage |
 |---------|---------|---------|
-| `focus note "text"` | Session-level progress | Replaces `.focus.sessionNote` |
+| `update T001 --notes "text"` | Task-level progress | Appends to `.tasks[].notes[]` |
 | `update T001 --notes "text"` | Task-specific history | Appends to `.tasks[].notes[]` with timestamp |
 
 ### Session Maintenance (v0.60.0+)
@@ -767,10 +799,10 @@ esac
 Every file modification follows this exact sequence:
 
 ```
-1. Write to temp file (.todo.json.tmp)
-2. Validate temp (schema + anti-hallucination)
-3. IF INVALID: Delete temp → Abort → Exit with error
-4. IF VALID: Backup original → Atomic rename → Rotate backups
+1. Prepare write operation
+2. Validate (schema + anti-hallucination)
+3. IF INVALID: Abort → Exit with error
+4. IF VALID: Backup → Execute write → Log to audit trail
 ```
 
 **No partial writes. No corruption.** The OS guarantees atomic rename.
@@ -788,7 +820,7 @@ Checksums detect corruption but don't block multi-writer scenarios (CLI + TodoWr
 ### Backup System
 
 - **Automatic**: Safety backup before every write
-- **Rotation**: 10 versioned backups (`.backups/todo.json.1` through `.10`)
+- **Rotation**: Versioned backups in `.cleo/.backups/`
 - **Recovery**: `cleo restore` or `cleo backup --list`
 
 ---
@@ -877,9 +909,8 @@ CLEO_FORMAT=json              # Force output format
 
 ```
 ~/.cleo/                     # Global installation
-├── scripts/                 # Command implementations (56 scripts)
-├── lib/                     # Shared libraries (58 files)
-├── schemas/                 # JSON Schema definitions
+├── nexus.db                 # Cross-project network: registry, graph, permissions (gated)
+├── config.json              # Global CLEO configuration
 ├── skills/                  # Modular agent skills (14 skills)
 │   ├── manifest.json        # Skill registry with versions
 │   ├── ct-epic-architect/   # Epic creation skill
@@ -889,10 +920,11 @@ CLEO_FORMAT=json              # Force output format
 └── docs/                    # Documentation
 
 your-project/.cleo/          # Per-project instance
-├── todo.json                # Active tasks (source of truth)
-├── todo-archive.json        # Completed tasks (immutable)
-├── todo-log.jsonl           # Audit trail (append-only)
-├── config.json              # Project configuration
+├── tasks.db                 # Project work: tasks, sessions, lifecycle, audit (SQLite)
+├── brain.db                 # Memory & cognition: observations, patterns, learnings (gated)
+├── config.json              # Runtime settings: policies, validation, session behavior
+├── project-info.json        # Project identity: projectHash, schema versions, health
+├── project-context.json     # LLM agent metadata: language, framework, conventions
 └── .backups/                # Automatic versioned backups
 ```
 
@@ -979,7 +1011,7 @@ fi
 
 # Agent parses structured output
 ACTIVE=$(cleo list | jq -r '.tasks[] | select(.status=="active") | .id')
-cleo focus note "Working on $ACTIVE"
+cleo update $ACTIVE --notes "Working on task"
 
 # Context-efficient task discovery
 cleo find "auth" | jq '.matches[0].id'  # 99% less tokens than list
@@ -1147,9 +1179,9 @@ See [docs/PLUGINS.md](docs/PLUGINS.md) for extension development.
 | `command not found` | Check `~/.local/bin` in PATH, run `source ~/.bashrc` |
 | `Permission denied` | `chmod 755 ~/.cleo/scripts/*.sh` |
 | `Invalid JSON` | `cleo validate --fix` or `cleo restore` |
-| `Duplicate ID` | `cleo restore .cleo/.backups/todo.json.1` |
+| `Duplicate ID` | `cleo validate --fix` or `cleo restore` |
 | `Checksum mismatch` | `cleo validate --fix` |
-| `Multiple active tasks` | `cleo focus set <correct-id>` (resets others) |
+| `Multiple active tasks` | `cleo start <correct-id>` (resets others) |
 | `Schema outdated` | `cleo migrate run` |
 
 ### Debug Mode
@@ -1198,18 +1230,24 @@ Target metrics (optimized for 1000+ tasks):
 
 ## The Philosophy
 
-CLEO is built on three pillars:
+CLEO is built on five pillars:
+
+### 1. Portable Memory (BRAIN)
+Every project carries its own `.cleo/` directory with SQLite databases. Move the directory, and the entire brain moves with it. No cloud dependencies, no vendor lock-in.
+
+### 2. Agent Communication Contract (LAFS)
+JSON output by default. MVI progressive disclosure. Deterministic exit codes. Field filtering for token efficiency. The `--human` flag is opt-in for developer visibility.
 
-### 1. Agent-First, Human-Accessible
-JSON output by default. Exit codes for branching. Structured errors. The `--human` flag is opt-in for developer visibility.
+### 3. Structured Lifecycle (RCASD-IVTR+C)
+Every significant piece of work follows a ten-stage pipeline from Research through Release, with gate enforcement and manifest-based provenance.
 
-### 2. Validate Everything
-LLMs hallucinate. Every operation validates before execution. Schema enforcement, semantic checks, state machine rules. If it fails validation, it doesn't happen.
+### 4. Deterministic Safety
+LLMs hallucinate. Four-layer validation (schema, semantic, referential, state machine) prevents every operation from corrupting state. Atomic writes. Immutable audit logs.
 
-### 3. Persist Everything
-Agents lose context. Immutable audit trails, automatic backups, session checkpoints. Pick up exactly where you left off.
+### 5. Cognitive Retrieval (BRAIN + NEXUS)
+Three-tier retrieval for token-efficient context loading. FTS5 keyword search, vector similarity, and graph-based discovery — with NEXUS extending across project boundaries.
 
-**One developer. One agent. One source of truth.**
+**One developer. One AI agent. One source of truth.**
 
 ---