@cleocode/cleo 2026.2.9 → 2026.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cleocode/cleo",
-  "version": "2026.2.9",
+  "version": "2026.3.0",
   "description": "CLEO V2 - TypeScript task management CLI for AI coding agents",
   "mcpName": "io.github.kryptobaseddev/cleo-mcp-server",
   "type": "module",
@@ -56,7 +56,7 @@
     "packages/ct-skills",
     "schemas",
     "templates",
-    "skills",
+    "packages/ct-skills/skills",
     "completions",
     "server.json"
   ],

package/packages/ct-skills/skills/ct-cleo/SKILL.md

@@ -77,6 +77,54 @@ ct dash                    # Project overview
 - `find` returns minimal fields only (99% less context)
 - Use `show` only when you need full details for a specific task
 
+### Work Selection Decision Tree
+
+```
+START
+├─ Has active session? → `session status`
+│  ├─ YES → Has active task? → `tasks current`
+│  │  ├─ YES → Continue working on it
+│  │  └─ NO → `tasks next` → pick suggestion → `tasks start {id}`
+│  └─ NO → `session list` → resume or start new
+│     └─ `session start --scope epic:{id} --auto-focus`
+├─ Know what to work on?
+│  ├─ YES → `tasks find "query"` → `tasks show {id}` → `tasks start {id}`
+│  └─ NO → `admin dash` → identify priority → `tasks next`
+└─ Epic-level work?
+   └─ `tasks tree {epicId}` → find actionable leaf → `tasks start {id}`
+```
+
+### Context Bloat Anti-Patterns
+
+| Anti-Pattern | Token Cost | Efficient Alternative | Savings |
+|-------------|-----------|----------------------|---------|
+| `tasks list` (no filters) | 2000-5000 | `tasks find "query"` | 80-90% |
+| `admin help --tier 2` first | 2000+ | `admin help` (tier 0 default) | 60-75% |
+| `tasks show` for every task | 400 x N | `tasks find` then `show` for 1-2 | 70-90% |
+| Reading full epic tree | 1000-3000 | `tasks next` for suggestions | 80% |
+| Repeated `session list` | 300 x N | Once at startup, cache result | 90% |
+| `tasks analyze` before starting | 800-1500 | `tasks next --explain` | 50% |
+
+### Progressive Disclosure Triggers
+
+Load only what you need. Escalate tiers when the task demands it:
+
+**Stay at Tier 0** (default -- 80% of work):
+- Single task execution (implement, fix, test)
+- Task discovery and status updates
+- Session start/end
+
+**Escalate to Tier 1** when:
+- Managing research artifacts or consensus docs
+- Running validation/compliance checks
+- Working with memory or check domains
+
+**Escalate to Tier 2** when:
+- Orchestrating multi-agent workflows
+- Managing release pipelines
+- Working with nexus cross-project operations
+- Spawning subagents with protocol injection
+
 ## Session Protocol
 
 Sessions track work context across agent interactions.
@@ -130,28 +178,7 @@ After EVERY command:
 
 ## RCSD-IVTR Lifecycle
 
-Projects follow a structured lifecycle with gate enforcement:
-
-```
-RCSD PIPELINE (setup):  Research -> Consensus -> Specification -> Decomposition
-EXECUTION (delivery):   Implementation -> Contribution -> Release
-```
-
-Each stage has a lifecycle gate. Entering a later stage requires prior stages to be `completed` or `skipped`. Gate enforcement is configured in `.cleo/config.json` (`strict` | `advisory` | `off`).
-
-### Conditional Protocols (9 Types)
-
-| Protocol | Use Case |
-|----------|----------|
-| Research | Information gathering |
-| Consensus | Multi-agent decisions |
-| Specification | Document creation |
-| Decomposition | Task breakdown |
-| Implementation | Code execution |
-| Contribution | Work attribution |
-| Release | Version management |
-| Artifact Publish | Artifact distribution |
-| Provenance | Supply chain integrity |
+**Lifecycle**: See CLEO-INJECTION.md standard tier for full RCASD-IVTR+C pipeline details, or `references/rcsd-lifecycle.md` for gate enforcement and subagent architecture.
 
 ## Time Estimates Prohibited
 

package/templates/CLEO-INJECTION.md

@@ -1,45 +1,47 @@
 # CLEO Protocol
 
-Version: 2.0.0
+Version: 2.1.0
 Status: ACTIVE
 
-<!-- MVI Progressive Disclosure: minimal -> standard -> orchestrator -->
-
-<!-- TIER:minimal -->
 ## CLEO Identity
 
 You are a CLEO protocol agent. Use MCP-first operations:
 - `cleo_query` for reads
 - `cleo_mutate` for writes
 
-## Startup Checklist
+## Mandatory Efficiency Sequence
 
-Run these in order at the start of every session:
-1. `cleo_query session list` — check for existing active sessions first
-2. `cleo_query admin help` — load the operation matrix
-3. `cleo_query tasks find` with your query — discover relevant tasks
+Run cheapest-first at session start:
+1. `cleo_query session status` — resume existing? (~200 tokens)
+2. `cleo_query admin dash` — project overview (~500 tokens)
+3. `cleo_query tasks current` — active task? (~100 tokens)
+4. `cleo_query tasks next` — what to work on (~300 tokens)
+5. `cleo_query tasks show` — full details for chosen task (~400 tokens)
 
-## MCP Tools
+## Agent Work Loop
 
-`cleo_query` examples:
-- `tasks show`
-- `tasks find`
+Repeat until session ends:
+1. `tasks current` or `tasks next` → pick task
+2. `tasks show {id}` → read requirements
+3. Do the work (code, test, document)
+4. `tasks complete {id}` → mark done
+5. `tasks next` → continue or end session
 
-`cleo_mutate` examples:
-- `tasks add`
-- `tasks update`
-- `tasks complete`
+## Context Ethics
 
-## CLI Fallback
+Every MCP call costs tokens. Budget wisely:
 
-Use `ct` when MCP is unavailable.
+| Operation | ~Tokens | When to Use |
+|-----------|---------|-------------|
+| `tasks find` | 200-400 | Discovery (NOT `tasks list`) |
+| `tasks show` | 300-600 | After choosing a specific task |
+| `tasks list` | 1000-5000 | ONLY for direct children of a known parent |
+| `admin help` | 500-2000 | ONCE per session, at tier 0 first |
 
-```bash
-ct find "query"
-ct show T1234
-ct add "Task title"
-ct done T1234
-```
+**Anti-patterns:**
+- Calling `tasks list` without filters (returns ALL tasks with notes)
+- Calling `admin help --tier 2` before trying tier 0
+- Reading full task details for tasks you won't work on
 
 ## Error Handling
 
@@ -56,121 +58,13 @@ Always check `success` and exit code values. Treat non-zero exit code as failure
 ## Time Estimates Prohibited
 
 Agents MUST NOT provide hours/days/week estimates. Use `small`, `medium`, `large` sizing.
-<!-- /TIER:minimal -->
-
-<!-- TIER:standard -->
-## Session Protocol
-
-**Step 0 (MANDATORY):** Always call `cleo_query session list` before starting a session.
-
-Use session operations to start and end work:
-- MCP `session` operations (`start`, `end`)
-- CLI `ct session` commands
-
-```bash
-ct session list                                           # ALWAYS first
-ct session start --scope epic:T001 --auto-focus --name "Work Session"
-ct session end --note "summary"                           # ALWAYS when done
-```
-
-## RCASD-IVTR+C Lifecycle
-
-Canonical name is RCASD. Legacy references may still mention RCSD for compatibility.
-
-Lifecycle protocols:
-- Research
-- Consensus
-- Specification
-- Decomposition
-- Implementation
-- Contribution
-- Release
-- Artifact Publish
-- Provenance
-
-Record lifecycle artifacts in `MANIFEST.jsonl`.
-
-## Token System
-
-Use Token placeholders such as `{{TASK_ID}}` during composition.
-
-## Skill Ecosystem
-
-Load focused skills for complex workflows, including `ct-orchestrator`.
-
-## Release Workflow
-
-Use CLI release flow:
-
-```bash
-ct release ship patch
-```
-<!-- /TIER:standard -->
-
-<!-- TIER:orchestrator -->
-## Architecture Overview
-
-CLEO uses a 2-tier orchestration model: orchestrator control + delegated execution.
-
-## ORC Constraints
-
-- ORC-001
-- ORC-002
-- ORC-003
-- ORC-004
-- ORC-005
-- ORC-006
-- ORC-007
-- ORC-008
-
-## BASE Constraints
-
-- BASE-001
-- BASE-002
-- BASE-003
-- BASE-004
-- BASE-005
-- BASE-006
-- BASE-007
-
-## Spawn Pipeline
-
-Orchestrate subagent sequencing using `orchestrate` planning operations:
-- `analyze`
-- `ready`
-- `next`
-
-## Protocol Stack
-
-Apply the protocol stack in order with explicit gate checks.
-
-## Token Pre-Resolution
-
-All orchestration token payloads must satisfy `tokenResolution.fullyResolved` before execution.
-
-## Lifecycle Gate Enforcement
-
-Support both strict and advisory gate modes.
-
-## Anti-Patterns
-
-### Orchestrator Anti-Patterns
-
-Avoid speculative spawning, gate skipping, and hidden state mutation.
-
-### Subagent Anti-Patterns
-
-Avoid direct release actions, protocol bypass, and unmanaged context growth.
 
-## Subagent Lifecycle
+## Escalation
 
-Subagent flow:
-- SPAWN
-- INJECT
-- EXECUTE
-- OUTPUT
-- RETURN
-<!-- /TIER:orchestrator -->
+For deeper guidance beyond this minimal protocol:
+- **Session & lifecycle**: `cleo_query admin help` or load `ct-cleo` skill
+- **Orchestration**: `cleo_query admin help --tier 2` or load `ct-orchestrator` skill
+- **Operations reference**: `docs/specs/CLEO-OPERATIONS-REFERENCE.md`
 
 ## References
 

package/templates/cleo-gitignore

@@ -1,65 +1,82 @@
-# CLEO Project Data - Selective Git Tracking
+# =============================================================================
+# .cleo/.gitignore — Deny-by-default for CLEO project data
+# =============================================================================
+# STRATEGY: Ignore everything, then explicitly allow only tracked files.
+# This prevents runtime data (databases, logs, caches, metrics) from ever
+# being accidentally committed.
 #
-# Strategy: Track core task/config files, ignore transient/generated data.
-#
-# TRACKED (not listed here, so git picks them up):
-#   todo.json, todo-archive.json, config.json, sessions.json,
-#   project-context.json, todo-log.jsonl, .sequence,
-#   templates/, schemas/
-#
-# IGNORED (listed below):
+# Canonical audit: .cleo/agent-outputs/T5159-cleo-file-audit.md
+# ADR: ADR-013-data-integrity-checkpoint-architecture.md
+# =============================================================================
 
-# Lock and temp files
-*.lock
-*.tmp
+# Step 1: Ignore everything in .cleo/
+*
 
-# Operational backups (runtime safety nets, not source)
-.backups/
-backups/
+# =============================================================================
+# ALLOW LIST — files and directories that SHOULD be tracked
+# =============================================================================
 
-# Metrics and telemetry exports
-metrics/
+# Step 2: Allow this .gitignore itself
+!.gitignore
 
-# Audit logs (high-volume, session-specific)
-audit-log-*.json
+# Step 3: Allow project configuration files
+!config.json
+!project-context.json
+!project-info.json
+!setup-otel.sh
+!DATA-SAFETY-IMPLEMENTATION-SUMMARY.md
 
-# Context state (transient session data)
-.context-state.json
-.context-state-session_*.json
-context-states/
+# Step 4: Allow schemas directory
+!schemas/
+!schemas/**
 
-# SQLite WAL/journal files (transient database state)
-*.db-journal
-*.db-wal
-*.db-shm
+# Step 5: Allow templates directory
+!templates/
+!templates/**
 
-# Research artifacts (agent working data)
-research/
+# Step 6: Allow ADRs directory (architecture decisions — project-level, not CLEO-specific)
+!adrs/
+!adrs/**
 
-# RCASD lifecycle state (generated per-epic)
-rcasd/
+# Step 7: Allow RCASD lifecycle provenance directory
+# Structure: rcasd/{epic#}/research/, consensus/, architecture/, specs/, contributions/
+!rcasd/
+!rcasd/**
 
-# Legacy RCSD path (backward compatibility)
-rcsd/
+# Step 8: Allow agent-outputs directory
+!agent-outputs/
+!agent-outputs/**
 
-# Session working files
-.current-session
-.git-checkpoint-state
+# =============================================================================
+# EXPLICIT DENY — safety net that overrides allow rules above
+# =============================================================================
 
-# Backup metadata
-backup-metadata.json
+# SQLite databases — NEVER track (data loss root cause, ADR-013)
+*.db
+*.db-shm
+*.db-wal
+*.db-journal
 
-# Corrupted/backup copies of data files
-*.corrupted
-*.bak
-*.bak*
-*.backup-*
+# Logs — NEVER track (append-only runtime data)
+log.json
+tasks-log.jsonl
+todo-log.jsonl
+bypass-log.json
+qa-log.json
 
-# Agent outputs (generated by LLM agents, not source)
-agent-outputs/
+# Caches and transient state
+.deps-cache/
+.context-alert-state.json
+.context-state*.json
+context-states/
+.git-checkpoint-state
+.migration-state.json
 
-# Cache directories
-.cache/
+# Instance-specific runtime data
+migrations.json
+sync/
+metrics/
 
-# Note: tasks.db is intentionally NOT ignored.
-# CLEO tracks the SQLite database in git for data safety.
+# Backups — NEVER track
+.backups/
+backups/

package/templates/git-hooks/pre-commit

@@ -1,15 +1,13 @@
 #!/bin/sh
-# Pre-commit guardrails — reject SQLite runtime files.
-#
-# SQLite WAL/SHM/journal files are runtime artifacts that must never be
-# committed. They can corrupt the database when checked out on another
-# machine. This covers tasks.db, brain.db, and any future SQLite databases.
+# Pre-commit guardrails:
+#   1. Reject SQLite WAL/SHM files (data corruption risk).
+#   2. Block commits when core CLEO files are gitignored (data integrity).
 #
 # Installation: Automatically installed via `cleo init`
 
 set -e
 
-# ── WAL/SHM/journal files ─────────────────────────────────────────────
+# ── 1. WAL/SHM/journal files ──────────────────────────────────────────
 BAD_FILES=$(git diff --cached --name-only | grep -E '\.(db-wal|db-shm|db-journal)$' || true)
 
 if [ -n "$BAD_FILES" ]; then
@@ -20,3 +18,23 @@ if [ -n "$BAD_FILES" ]; then
   echo "To fix: git rm --cached <file>"
   exit 1
 fi
+
+# ── 2. Core file gitignore protection ─────────────────────────────────
+PROTECTED_FILES=".cleo/tasks.db .cleo/config.json .cleo/.gitignore .cleo/project-info.json .cleo/project-context.json"
+IGNORED_CORE=""
+
+for f in $PROTECTED_FILES; do
+  if [ -f "$f" ] && git check-ignore -q "$f" 2>/dev/null; then
+    IGNORED_CORE="$IGNORED_CORE $f"
+  fi
+done
+
+if [ -n "$IGNORED_CORE" ]; then
+  echo "ERROR: Critical CLEO files are being ignored by .gitignore:"
+  echo "$IGNORED_CORE"
+  echo ""
+  echo "These files MUST be tracked by git for CLEO data integrity."
+  echo "Check .gitignore and .cleo/.gitignore for rules ignoring these files."
+  echo "To fix: remove the ignore rule, then: git add <file>"
+  exit 1
+fi

package/schemas/archive/agent-configs.schema.json

@@ -1,120 +0,0 @@
-{
-  "$schema": "http://json-schema.org/draft-07/schema#",
-  "$id": "https://cleo-dev.com/schemas/v1/agent-configs.schema.json",
-  "schemaVersion": "1.0.0",
-  "title": "CLEO Agent Configurations Registry Schema",
-  "description": "Global registry tracking agent configuration files (CLAUDE.md, AGENTS.md, GEMINI.md) at ~/.cleo/agent-configs.json. Monitors CLEO instruction injection versions and setup status across all supported LLM agent CLIs.",
-  "type": "object",
-  "required": ["schemaVersion", "lastUpdated", "configs"],
-  "additionalProperties": false,
-
-  "properties": {
-    "schemaVersion": {
-      "type": "string",
-      "pattern": "^\\d+\\.\\d+\\.\\d+$",
-      "description": "Schema version for this registry file (semver). Initial version: 1.0.0."
-    },
-    "lastUpdated": {
-      "type": "string",
-      "format": "date-time",
-      "description": "ISO 8601 timestamp of last registry modification. Updated when any config entry changes."
-    },
-    "configs": {
-      "type": "object",
-      "description": "Agent configuration files keyed by absolute file path. Each entry tracks injection version and setup status for one agent config file.",
-      "additionalProperties": {
-        "$ref": "#/definitions/agentConfigEntry"
-      }
-    }
-  },
-
-  "definitions": {
-    "agentConfigEntry": {
-      "type": "object",
-      "description": "Single agent configuration file tracking entry. Monitors CLEO instruction injection version and setup state.",
-      "required": ["version", "method", "setupDate", "status"],
-      "additionalProperties": false,
-      "properties": {
-        "version": {
-          "type": "string",
-          "pattern": "^\\d+\\.\\d+\\.\\d+$",
-          "description": "CLEO version of injected instructions. Extracted from <!-- CLEO:START vX.X.X --> marker."
-        },
-        "method": {
-          "type": "string",
-          "enum": ["@", "inline", "embed"],
-          "description": "Injection method used: @=@ reference to ~/.cleo/docs/, inline=marker-based injection, embed=full content embedded."
-        },
-        "setupDate": {
-          "type": "string",
-          "format": "date-time",
-          "description": "ISO 8601 timestamp when this config file was first created/configured by CLEO."
-        },
-        "lastChecked": {
-          "type": ["string", "null"],
-          "format": "date-time",
-          "description": "ISO 8601 timestamp of most recent validation check. Null if never validated since setup."
-        },
-        "status": {
-          "type": "string",
-          "enum": ["current", "outdated", "missing", "invalid"],
-          "description": "Config file health status: current=version matches CLI, outdated=old version detected, missing=file not found, invalid=corrupt or unparseable."
-        },
-        "cliVersion": {
-          "type": ["string", "null"],
-          "pattern": "^\\d+\\.\\d+\\.\\d+$",
-          "description": "CLEO CLI version when last checked. Used to detect version drift between agent config and installed CLI."
-        },
-        "agentType": {
-          "type": ["string", "null"],
-          "enum": ["claude", "gemini", "codex", "kimi", null],
-          "description": "Agent type inferred from config file name/path. Null if cannot determine."
-        },
-        "notes": {
-          "type": ["string", "null"],
-          "maxLength": 500,
-          "description": "Optional notes about this config (e.g., manual edits detected, custom setup, migration status)."
-        }
-      }
-    }
-  },
-
-  "examples": [
-    {
-      "schemaVersion": "1.0.0",
-      "lastUpdated": "2026-01-05T14:23:45Z",
-      "configs": {
-        "/home/user/.claude/CLAUDE.md": {
-          "version": "0.50.2",
-          "method": "@",
-          "setupDate": "2026-01-01T10:00:00Z",
-          "lastChecked": "2026-01-05T14:23:45Z",
-          "status": "current",
-          "cliVersion": "0.50.2",
-          "agentType": "claude",
-          "notes": null
-        },
-        "/home/user/.claude/AGENTS.md": {
-          "version": "0.50.2",
-          "method": "@",
-          "setupDate": "2026-01-01T10:00:00Z",
-          "lastChecked": "2026-01-05T14:23:45Z",
-          "status": "current",
-          "cliVersion": "0.50.2",
-          "agentType": null,
-          "notes": null
-        },
-        "/home/user/.gemini/GEMINI.md": {
-          "version": "0.50.1",
-          "method": "@",
-          "setupDate": "2026-01-01T10:00:00Z",
-          "lastChecked": "2026-01-05T14:23:45Z",
-          "status": "outdated",
-          "cliVersion": "0.50.2",
-          "agentType": "gemini",
-          "notes": "Needs update to v0.50.2"
-        }
-      }
-    }
-  ]
-}