@cleocode/core 2026.3.76 → 2026.4.2

package/src/validation/operation-verification-gates.ts

@@ -1,13 +1,13 @@
 /**
  * Operation Verification Gate System for CLEO
  *
- * Implements 4-layer validation gate system for MCP/dispatch operations:
+ * Implements 4-layer validation gate system for dispatch operations:
  * Layer 1: Schema Validation (JSON Schema compliance)
  * Layer 2: Semantic Validation (Business rules)
  * Layer 3: Referential Validation (Cross-entity integrity)
  * Layer 4: Protocol Validation (RCASD-IVTR+C lifecycle)
  *
- * Moved from src/mcp/lib/verification-gates.ts to core for proper layering.
+ * Moved to core for proper layering (formerly in dispatch).
  *
  * @task T2936
  * @task T5707
@@ -341,7 +341,7 @@ export const GATE_SEQUENCE = [
 // ============================================================================
 
 /**
- * Workflow gate names per MCP-SERVER-SPECIFICATION.md Section 7.1
+ * Workflow gate names per protocol specification Section 7.1
  *
  * @task T3141
  */

package/src/validation/param-utils.ts

@@ -3,7 +3,7 @@
  *
  * Converts operation parameter definitions into the shapes required by:
  *  - Commander.js (CLI adapter): positionals + option strings
- *  - MCP JSON Schema (MCP adapter): input_schema object
+ *  - JSON Schema (dispatch adapter): input_schema object
  *
  * Canonical location: src/core/validation/param-utils.ts
  * Re-exported from: src/dispatch/lib/param-utils.ts (backward compat)
@@ -14,7 +14,7 @@
  */
 
 // Inlined from dispatch layer — these types define operation/param shapes
-// used for building CLI args and MCP schemas. Kept here to avoid
+// used for building CLI args and dispatch schemas. Kept here to avoid
 // core depending on dispatch (wrong direction).
 interface OperationDef {
   gateway: string;
@@ -38,7 +38,7 @@ interface ParamCliDef {
   [key: string]: unknown;
 }
 
-interface ParamMcpDef {
+interface ParamSchemaDef {
   name?: string;
   description?: string;
   enum?: string[];
@@ -55,11 +55,12 @@ interface ParamDef {
   enum?: string[];
   items?: { type: ParamType };
   cli?: ParamCliDef;
-  mcp?: ParamMcpDef;
+  /** Schema config for dispatch adapter. */
+  mcp?: ParamSchemaDef;
 }
 
 // ---------------------------------------------------------------------------
-// JSON Schema subset for MCP input_schema
+// JSON Schema subset for dispatch input_schema
 // ---------------------------------------------------------------------------
 
 export type JsonSchemaType = 'string' | 'number' | 'boolean' | 'array' | 'object';
@@ -78,7 +79,7 @@ export interface JSONSchemaObject {
 }
 
 // ---------------------------------------------------------------------------
-// 1. buildMcpInputSchema
+// 1. buildMcpInputSchema (name kept for backward compat)
 // ---------------------------------------------------------------------------
 
 /**
@@ -86,7 +87,7 @@ export interface JSONSchemaObject {
  *
  * Algorithm:
  *  1. Iterate `def.params`
- *  2. Skip params where `mcp.hidden === true`
+ *  2. Skip params where schema `mcp.hidden === true`
  *  3. Map ParamType → JSON Schema type
  *  4. Collect names where `required === true` into `required[]`
  *  5. Return { type: 'object', properties, required }
@@ -96,7 +97,7 @@ export function buildMcpInputSchema(def: OperationDef): JSONSchemaObject {
   const required: string[] = [];
 
   for (const param of def.params ?? []) {
-    // Skip CLI-only params from MCP schema
+    // Skip CLI-only params from dispatch schema
     if (param.mcp?.hidden === true) continue;
 
     const prop: JsonSchemaProperty = {
@@ -154,14 +155,14 @@ export interface CommanderArgSplit {
  *
  * - `cli.positional === true` → goes into `positionals[]`
  * - everything else with a `cli` key → goes into `options[]`
- * - Params with no `cli` key → MCP-only; excluded from both arrays
+ * - Params with no `cli` key → dispatch-only; excluded from both arrays
  */
 export function buildCommanderArgs(def: OperationDef): CommanderArgSplit {
   const positionals: ParamDef[] = [];
   const options: ParamDef[] = [];
 
   for (const param of def.params ?? []) {
-    // Params with no cli key are MCP-only — skip for Commander
+    // Params with no cli key are dispatch-only — skip for Commander
     if (param.cli === undefined) continue;
 
     if (param.cli.positional === true) {

package/src/validation/validate-ops.ts

@@ -865,23 +865,23 @@ export function coreComplianceRecord(
  */
 export function coreTestStatus(projectRoot: string): {
   batsTests: { available: boolean; directory: string | null };
-  mcpTests: { available: boolean; directory: string | null };
+  dispatchTests: { available: boolean; directory: string | null };
   message: string;
 } {
   const testDir = join(projectRoot, 'tests');
-  const mcpTestDir = join(projectRoot, 'src', 'mcp', '__tests__');
+  const dispatchTestDir = join(projectRoot, 'src', 'dispatch', '__tests__');
 
   const hasBatsTests = existsSync(testDir);
-  const hasMcpTests = existsSync(mcpTestDir);
+  const hasDispatchTests = existsSync(dispatchTestDir);
 
   return {
     batsTests: {
       available: hasBatsTests,
       directory: hasBatsTests ? 'tests/' : null,
     },
-    mcpTests: {
-      available: hasMcpTests,
-      directory: hasMcpTests ? 'src/mcp/__tests__/' : null,
+    dispatchTests: {
+      available: hasDispatchTests,
+      directory: hasDispatchTests ? 'src/dispatch/__tests__/' : null,
     },
     message: 'Use validate.test.run to execute tests',
   };

package/templates/CLEO-INJECTION.md

@@ -1,144 +1,72 @@
 # CLEO Protocol
 
-Version: 2.2.0
-Status: ACTIVE
+Version: 2.4.0 | CLI-only dispatch | `cleo <command> [args]`
 
-## Runtime Environment
+## Session Start (cheapest-first)
 
-<!-- CleoOS injects CLEO_RUNTIME=cleoos when launching agents from a workspace -->
-<!-- When this variable is absent, assume standalone CLI mode -->
-
-**Mode**: `${CLEO_RUNTIME:-standalone}`
-
-### Channel Preference
-
-| Runtime | Primary Channel | Fallback | Rationale |
-|---------|----------------|----------|-----------|
-| `standalone` | CLI (`cleo <command>`) | MCP (query/mutate) | CLI is cheaper (fewer tokens), more reliable, and baked into core |
-| `cleoos` | Workspace-provided | CLI | CleoOS workspace manages channel routing via capability matrix |
-
-When running in **standalone** mode (the default):
-- Prefer CLI commands over MCP tool calls for all CLEO operations
-- CLI commands are shorter, use fewer tokens, and bypass the MCP dispatch layer
-- Use MCP only when the provider does not support shell execution
-
-When running in **CleoOS** mode:
-- Follow the workspace-provided channel routing preferences
-- CleoOS manages the capability matrix and optimal channel selection
-- This mode is a work-in-progress — fall back to CLI if unsure
-
-## CLEO Identity
-
-You are a CLEO protocol agent. CLEO operations are available via CLI (primary) and MCP (fallback):
-- CLI: `cleo <command> [args]` — preferred for token efficiency (flat commands, not domain-prefixed)
-- MCP: `query`/`mutate` gateways with `{domain, operation, params}` — use when CLI is unavailable
-
-## Mandatory Efficiency Sequence
-
-Run cheapest-first at session start:
 1. `cleo session status` — resume existing? (~200 tokens)
 2. `cleo dash` — project overview (~500 tokens)
 3. `cleo current` — active task? (~100 tokens)
 4. `cleo next` — what to work on (~300 tokens)
 5. `cleo show {id}` — full details for chosen task (~400 tokens)
 
-## Agent Work Loop
+## Work Loop
 
-Repeat until session ends:
 1. `cleo current` or `cleo next` → pick task
 2. `cleo show {id}` → read requirements
 3. Do the work (code, test, document)
 4. `cleo complete {id}` → mark done
 5. `cleo next` → continue or end session
 
-## Context Ethics
-
-Every MCP call costs tokens. Budget wisely:
-
-| 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 |
-
-**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
-
-Always check `success` and exit code values. Treat non-zero exit code as failure.
-
 ## Task Discovery
 
-**ALWAYS use `tasks find` for discovery. NEVER use `tasks list` for browsing.**
-
-- `tasks find` → minimal fields, fast, low context cost ✓
-- `tasks list` → full notes arrays, huge, use only for direct children ✗
-- `tasks show` → full details for a specific known task ID ✓
-
-## Time Estimates Prohibited
-
-Agents MUST NOT provide hours/days/week estimates. Use `small`, `medium`, `large` sizing.
+**Use `cleo find` for discovery. NEVER `cleo list` for browsing.**
 
-## Session Quick Reference
+| Command | ~Tokens | Use |
+|---------|---------|-----|
+| `cleo find "query"` | 200-400 | Search tasks (default) |
+| `cleo show <id>` | 300-600 | Full details for one task |
+| `cleo list --parent <id>` | 1000-5000 | Direct children only |
 
-| Goal | CLI (Primary) | MCP (Fallback) |
-|------|--------------|----------------|
-| Check active session | `cleo session status` | `query session status` |
-| Resume context | `cleo briefing` | `query session briefing.show` |
-| Start working | `cleo session start --scope global` | `mutate session start {scope: "global"}` |
-| Stop working | `cleo session end` | `mutate session end` |
+## Session Commands
 
-For advanced session ops (find, suspend, resume, debrief, decisions): see `.cleo/agent-outputs/T5124-session-decision-tree.md`
+| Goal | Command |
+|------|---------|
+| Check session | `cleo session status` |
+| Resume context | `cleo briefing` |
+| Start session | `cleo session start --scope global` |
+| End session | `cleo session end --note "..."` |
 
-**Budget note**: `session list` defaults to 10 results (~500-2000 tokens). Prefer `session find` for discovery (~200-400 tokens).
+## Memory (BRAIN)
 
-## Memory Protocol
+3-layer retrieval — search first, then fetch:
 
-CLEO includes a native BRAIN memory system. Use the 3-layer retrieval pattern for token-efficient access:
+| Step | Command | ~Tokens |
+|------|---------|---------|
+| Search | `cleo memory find "query"` | 50/hit |
+| Context | `cleo memory timeline <id>` | 200-500 |
+| Details | `cleo memory fetch <id>` | 500/entry |
+| Save | `cleo observe "text" --title "title"` | — |
 
-| Step | Operation | Gateway | ~Tokens | Purpose |
-|------|-----------|---------|---------|---------|
-| 1 | `memory find` | query | 50/hit | Search index (IDs + titles) |
-| 2 | `memory timeline` | query | 200-500 | Context around an anchor ID |
-| 3 | `memory fetch` | query | 500/entry | Full details for filtered IDs |
-| Save | `memory observe` | mutate | — | Save observation to brain.db |
+Memory bridge (`.cleo/memory-bridge.md`) auto-refreshes on session end and task completion.
 
-**Workflow**: Search first (cheap) → filter interesting IDs → fetch only what you need.
-
-**Example** (CLI):
-```
-cleo memory find "authentication"
-cleo memory fetch O-abc123
-cleo observe "Found auth uses JWT" --title "Auth discovery"
-```
-
-**Anti-patterns:**
-- Fetching all entries without searching first (expensive)
-- Skipping memory find and going straight to memory fetch
-
-## Memory Bridge
+## Error Handling
 
-CLEO auto-generates `.cleo/memory-bridge.md` from brain.db content. This file is `@`-referenced
-in AGENTS.md so providers automatically load project memory context at session start.
+Check exit code (`0` = success) and `"success"` in JSON output after every command.
 
-**Contents**: Last session handoff, key learnings, active patterns, recent decisions, recent observations.
+| Exit | Code | Fix |
+|:----:|------|-----|
+| 4 | `E_NOT_FOUND` | `cleo find` to verify ID |
+| 6 | `E_VALIDATION` | Check field lengths |
+| 10 | `E_PARENT_NOT_FOUND` | `cleo exists <id>` |
 
-**Refreshes on**: `session.end`, `tasks.complete`, `memory.observe` (decisions), `cleo refresh-memory`.
+## Rules
 
-If the file is missing, run `cleo init` or `cleo refresh-memory` to regenerate it.
+- No time estimates — use `small`, `medium`, `large` sizing
+- Token budget: avoid `cleo list` without `--parent`, avoid `cleo help --tier 2` before tier 0
+- Do not read full task details for tasks you won't work on
 
 ## Escalation
 
-For deeper guidance beyond this minimal protocol:
-- **Session & lifecycle**: `query admin help` or load `ct-cleo` skill
-- **Orchestration**: `query admin help --tier 2` or load `ct-orchestrator` skill
-- **Operations reference**: `docs/specs/CLEO-OPERATIONS-REFERENCE.md`
-
-## References
-
-- `docs/specs/CLEO-OPERATIONS-REFERENCE.md`
-- `docs/specs/VERB-STANDARDS.md`
+- Load **ct-cleo** skill for full protocol details
+- Load **ct-orchestrator** skill for multi-agent workflows

package/dist/hooks/handlers/mcp-hooks.d.ts

@@ -1,48 +0,0 @@
-/**
- * MCP Prompt/Response Hook Handlers - Wave 2 of T5237
- *
- * Handlers for onPromptSubmit, onResponseComplete, and system Notification
- * events that capture ALL gateway operations (read and write) to BRAIN.
- * By default, NO brain capture (too noisy). Enable via:
- *   - Config: brain.captureMcp = true  (checked first)
- *   - Env:    CLEO_BRAIN_CAPTURE_MCP=true  (overrides config)
- * Auto-registers on module load.
- *
- * Note: File-change Notification events (those with filePath + changeType) are
- * handled by file-hooks.ts. This module handles message-bearing system
- * notifications (Notification payloads with a message field).
- *
- * @task T166
- */
-import type { NotificationPayload, PromptSubmitPayload, ResponseCompletePayload } from '../types.js';
-/**
- * Handle PromptSubmit - optionally capture ALL gateway prompt events to BRAIN.
- *
- * No-op by default. Enable via brain.captureMcp config or CLEO_BRAIN_CAPTURE_MCP env.
- * For selective mutation-only capture, use work-capture-hooks.ts instead.
- */
-export declare function handlePromptSubmit(projectRoot: string, payload: PromptSubmitPayload): Promise<void>;
-/**
- * Handle ResponseComplete - optionally capture ALL gateway response events to BRAIN.
- *
- * No-op by default. Enable via brain.captureMcp config or CLEO_BRAIN_CAPTURE_MCP env.
- * For selective mutation-only capture, use work-capture-hooks.ts instead.
- */
-export declare function handleResponseComplete(projectRoot: string, payload: ResponseCompletePayload): Promise<void>;
-/**
- * Handle Notification — capture system notifications as BRAIN observations.
- *
- * Only fires for Notification payloads that carry a message field (i.e. system
- * notifications). File-change notifications (filePath + changeType) are
- * handled exclusively by file-hooks.ts and are skipped here to avoid
- * double-capture.
- *
- * Gated behind brain.autoCapture config. Never throws.
- *
- * @param projectRoot - Absolute path to the project root directory.
- * @param payload     - Notification event payload.
- *
- * @task T166
- */
-export declare function handleSystemNotification(projectRoot: string, payload: NotificationPayload): Promise<void>;
-//# sourceMappingURL=mcp-hooks.d.ts.map

package/dist/hooks/handlers/mcp-hooks.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"mcp-hooks.d.ts","sourceRoot":"","sources":["../../../src/hooks/handlers/mcp-hooks.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAGH,OAAO,KAAK,EACV,mBAAmB,EACnB,mBAAmB,EACnB,uBAAuB,EACxB,MAAM,aAAa,CAAC;AA0BrB;;;;;GAKG;AACH,wBAAsB,kBAAkB,CACtC,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,mBAAmB,GAC3B,OAAO,CAAC,IAAI,CAAC,CAef;AAED;;;;;GAKG;AACH,wBAAsB,sBAAsB,CAC1C,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,uBAAuB,GAC/B,OAAO,CAAC,IAAI,CAAC,CAef;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,wBAAwB,CAC5C,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,mBAAmB,GAC3B,OAAO,CAAC,IAAI,CAAC,CAoBf"}

package/dist/mcp/index.d.ts

@@ -1,42 +0,0 @@
-/**
- * MCP environment detection - CLEO-specific runtime mode resolution.
- *
- * Detects dev-ts vs prod-npm mode by reading ~/.cleo/VERSION.
- * This is the only CLEO-specific concern here — all provider detection,
- * config writing, and MCP server installation is delegated to @cleocode/caamp.
- *
- * @task T4676
- * @epic T4663
- */
-/** Resolved environment mode for MCP server config. */
-export interface McpEnvMode {
-    mode: 'dev-ts' | 'prod-npm' | 'unknown';
-    /** Absolute path to the source directory (dev-ts mode only). */
-    source: string | null;
-    /** Resolved install channel for npm package invocation. */
-    channel: 'stable' | 'beta' | 'dev' | 'unknown';
-}
-/** Resolve MCP server name by channel. */
-export declare function getMcpServerName(env: McpEnvMode): string;
-/**
- * Detect the current CLEO environment mode by reading ~/.cleo/VERSION.
- *
- * The VERSION file format:
- *   Line 1: version number
- *   Lines 2+: key=value pairs (mode, source, etc.)
- *
- * @task T4584
- */
-export declare function detectEnvMode(): McpEnvMode;
-/**
- * Generate the MCP server entry for the cleo server based on env mode.
- *
- * Returns a config object compatible with CAAMP's McpServerConfig:
- * - dev-ts: { command: 'node', args: ['<source>/dist/mcp/index.js'] }
- * - prod-npm stable: { command: 'npx', args: ['-y', '@cleocode/cleo@latest', 'mcp'] }
- * - prod-npm beta: { command: 'npx', args: ['-y', '@cleocode/cleo@beta', 'mcp'] }
- *
- * @task T4584
- */
-export declare function generateMcpServerEntry(env: McpEnvMode): Record<string, unknown>;
-//# sourceMappingURL=index.d.ts.map

package/dist/mcp/index.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/mcp/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAMH,uDAAuD;AACvD,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,QAAQ,GAAG,UAAU,GAAG,SAAS,CAAC;IACxC,gEAAgE;IAChE,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,2DAA2D;IAC3D,OAAO,EAAE,QAAQ,GAAG,MAAM,GAAG,KAAK,GAAG,SAAS,CAAC;CAChD;AAED,0CAA0C;AAC1C,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,UAAU,GAAG,MAAM,CAIxD;AAED;;;;;;;;GAQG;AACH,wBAAgB,aAAa,IAAI,UAAU,CAuF1C;AAED;;;;;;;;;GASG;AACH,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAuB/E"}

package/src/__tests__/audit-prune.test.d.ts

@@ -1,2 +0,0 @@
-export {};
-//# sourceMappingURL=audit-prune.test.d.ts.map

package/src/__tests__/caamp-skill-install.test.d.ts

@@ -1,14 +0,0 @@
-/**
- * T4718: Test CAAMP skill install + integrity check end-to-end.
- *
- * Verifies the full skill installation flow:
- * 1. CAAMP adapter in src/core/caamp/ exists and exports correctly
- * 2. Skill discovery via parseSkillFile
- * 3. Skill installation to canonical paths
- * 4. Integrity after install
- *
- * @task T4718
- * @epic T4663
- */
-export {};
-//# sourceMappingURL=caamp-skill-install.test.d.ts.map

package/src/__tests__/cli-mcp-parity.integration.test.d.ts

@@ -1,34 +0,0 @@
-/**
- * CLI/MCP Parity Integration Tests
- *
- * Verifies that the CLI and MCP paths produce identical results for shared
- * operations. Both CLI and MCP ultimately route through the same domain
- * handlers (TasksHandler, SessionHandler, etc.), which delegate to the same
- * src/core/ functions.
- *
- * Test strategy:
- *   1. Direct domain handler parity — call handler.query()/handler.mutate()
- *      and dispatchRaw() for the same operation; assert identical data.
- *   2. CLI dispatch path — call dispatchRaw() and verify it reaches the same
- *      handler as MCP would via createDomainHandlers().
- *   3. Cross-adapter data identity — same mock engine function is called with
- *      identical args from both CLI and MCP code paths.
- *   4. MCP gateway normalization gap — document that handleMcpToolCall passes
- *      'cleo_query' as gateway but the registry expects 'query' (a real gap).
- *
- * Architecture under test:
- *   CLI:  dispatchRaw('query', domain, op, params)
- *           → getCliDispatcher() → Dispatcher (sanitizer mw)
- *           → TasksHandler.query(op, params)
- *           → task-engine fn → core/tasks/*
- *
- *   MCP:  handleMcpToolCall('cleo_query', domain, op, params)
- *           → getMcpDispatcher() → Dispatcher (sanitizer+rl+gates+protocol+audit mw)
- *           → same TasksHandler.query(op, params)  [same handler instance via createDomainHandlers()]
- *           → same task-engine fn → same core/tasks/*
- *
- * @task T4796
- * @epic T4654
- */
-export {};
-//# sourceMappingURL=cli-mcp-parity.integration.test.d.ts.map

package/src/__tests__/cli-mcp-parity.integration.test.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"cli-mcp-parity.integration.test.d.ts","sourceRoot":"","sources":["cli-mcp-parity.integration.test.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG"}