@cleocode/cleo 2026.3.12 → 2026.3.14

package/schemas/operation-constitution.schema.json

@@ -0,0 +1,438 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "CLEO Operation Constitution",
+  "description": "Validates the complete CLEO Operation Constitution document including the full registry, gateway matrices, and domain tables",
+  "type": "object",
+  "required": ["schemaVersion", "metadata", "registry", "gateways", "domains"],
+  "additionalProperties": false,
+  "definitions": {
+    "Gateway": {
+      "type": "string",
+      "enum": ["query", "mutate"],
+      "description": "CQRS gateway: read-only queries or state-changing mutations"
+    },
+    "CanonicalDomain": {
+      "type": "string",
+      "enum": ["tasks", "session", "memory", "check", "pipeline", "orchestrate", "tools", "admin", "nexus", "sticky"],
+      "description": "One of 10 canonical CLEO domains"
+    },
+    "Tier": {
+      "type": "integer",
+      "enum": [0, 1, 2],
+      "description": "Progressive disclosure tier: 0=basic, 1=extended, 2=full"
+    },
+    "ParamDef": {
+      "type": "object",
+      "required": ["name", "type", "required", "description"],
+      "properties": {
+        "name": {
+          "type": "string",
+          "pattern": "^[a-zA-Z][a-zA-Z0-9]*$",
+          "description": "Canonical camelCase parameter name"
+        },
+        "type": {
+          "type": "string",
+          "enum": ["string", "number", "boolean", "array"],
+          "description": "Runtime value type"
+        },
+        "required": {
+          "type": "boolean",
+          "description": "Whether parameter is required"
+        },
+        "description": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Human-readable description"
+        },
+        "cli": {
+          "type": "object",
+          "properties": {
+            "positional": { "type": "boolean" },
+            "short": { "type": "string", "pattern": "^-[a-zA-Z]$" },
+            "flag": { "type": "string" },
+            "variadic": { "type": "boolean" }
+          },
+          "additionalProperties": false
+        },
+        "mcp": {
+          "type": "object",
+          "properties": {
+            "hidden": { "type": "boolean" },
+            "enum": {
+              "type": "array",
+              "items": { "type": "string" }
+            }
+          },
+          "additionalProperties": false
+        }
+      },
+      "additionalProperties": false
+    },
+    "OperationDef": {
+      "type": "object",
+      "required": ["gateway", "domain", "operation", "description", "tier", "idempotent", "sessionRequired", "requiredParams"],
+      "properties": {
+        "gateway": { "$ref": "#/definitions/Gateway" },
+        "domain": { "$ref": "#/definitions/CanonicalDomain" },
+        "operation": {
+          "type": "string",
+          "pattern": "^[a-z][a-z0-9]*(\\.[a-z][a-z0-9]*)*$",
+          "description": "Dot-notation operation name (e.g. 'show', 'stage.validate')"
+        },
+        "description": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Brief human-readable description of the operation"
+        },
+        "tier": { "$ref": "#/definitions/Tier" },
+        "idempotent": {
+          "type": "boolean",
+          "description": "Whether the operation is safe to retry without side effects"
+        },
+        "sessionRequired": {
+          "type": "boolean",
+          "description": "Whether the operation requires an active session"
+        },
+        "requiredParams": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "pattern": "^[a-zA-Z][a-zA-Z0-9]*$"
+          },
+          "description": "Parameter keys that MUST be present in the request"
+        },
+        "params": {
+          "type": "array",
+          "items": { "$ref": "#/definitions/ParamDef" },
+          "description": "Full parameter descriptors (optional, replaces requiredParams when populated)"
+        },
+        "aliases": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "pattern": "^[a-z][a-z0-9]*(\\.[a-z][a-z0-9]*)*$"
+          },
+          "description": "Backward-compatible operation name aliases"
+        }
+      },
+      "additionalProperties": false
+    }
+  },
+  "properties": {
+    "schemaVersion": {
+      "type": "string",
+      "pattern": "^\\d{4}\\.\\d+\\.\\d+$",
+      "description": "Constitution schema version (e.g. '2026.3.3')"
+    },
+    "metadata": {
+      "type": "object",
+      "required": ["version", "status", "date", "totalOperations", "gateways", "domains"],
+      "additionalProperties": false,
+      "properties": {
+        "version": {
+          "type": "string",
+          "description": "Constitution document version"
+        },
+        "status": {
+          "type": "string",
+          "enum": ["DRAFT", "APPROVED", "DEPRECATED"],
+          "description": "Constitution approval status"
+        },
+        "date": {
+          "type": "string",
+          "format": "date",
+          "description": "Constitution approval date (ISO 8601)"
+        },
+        "task": {
+          "type": "string",
+          "pattern": "^T\\d+$",
+          "description": "Associated task ID (e.g. 'T5241')"
+        },
+        "supersedes": {
+          "type": "string",
+          "description": "Document this constitution supersedes"
+        },
+        "totalOperations": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "Total number of operations in registry"
+        },
+        "gateways": {
+          "type": "object",
+          "required": ["query", "mutate"],
+          "additionalProperties": false,
+          "properties": {
+            "query": {
+              "type": "integer",
+              "minimum": 0,
+              "description": "Number of query operations"
+            },
+            "mutate": {
+              "type": "integer",
+              "minimum": 0,
+              "description": "Number of mutate operations"
+            }
+          }
+        },
+        "domains": {
+          "type": "object",
+          "required": ["count", "names"],
+          "additionalProperties": false,
+          "properties": {
+            "count": {
+              "type": "integer",
+              "minimum": 1,
+              "maximum": 10,
+              "description": "Number of canonical domains"
+            },
+            "names": {
+              "type": "array",
+              "items": { "$ref": "#/definitions/CanonicalDomain" },
+              "minItems": 10,
+              "maxItems": 10,
+              "description": "List of all canonical domain names"
+            }
+          }
+        }
+      }
+    },
+    "registry": {
+      "type": "object",
+      "required": ["operations"],
+      "additionalProperties": false,
+      "properties": {
+        "operations": {
+          "type": "array",
+          "items": { "$ref": "#/definitions/OperationDef" },
+          "minItems": 1,
+          "description": "All 207 operations in the registry"
+        }
+      }
+    },
+    "gateways": {
+      "type": "object",
+      "required": ["query", "mutate"],
+      "additionalProperties": false,
+      "properties": {
+        "query": {
+          "type": "object",
+          "required": ["matrix", "operations"],
+          "additionalProperties": false,
+          "properties": {
+            "matrix": {
+              "type": "object",
+              "description": "Query gateway matrix: domain -> operations[]",
+              "patternProperties": {
+                "^(tasks|session|memory|check|pipeline|orchestrate|tools|admin|nexus|sticky)$": {
+                  "type": "array",
+                  "items": {
+                    "type": "string",
+                    "pattern": "^[a-z][a-z0-9]*(\\.[a-z][a-z0-9]*)*$"
+                  }
+                }
+              },
+              "additionalProperties": false
+            },
+            "operations": {
+              "type": "array",
+              "items": { "$ref": "#/definitions/OperationDef" },
+              "description": "All query operations"
+            }
+          }
+        },
+        "mutate": {
+          "type": "object",
+          "required": ["matrix", "operations"],
+          "additionalProperties": false,
+          "properties": {
+            "matrix": {
+              "type": "object",
+              "description": "Mutate gateway matrix: domain -> operations[]",
+              "patternProperties": {
+                "^(tasks|session|memory|check|pipeline|orchestrate|tools|admin|nexus|sticky)$": {
+                  "type": "array",
+                  "items": {
+                    "type": "string",
+                    "pattern": "^[a-z][a-z0-9]*(\\.[a-z][a-z0-9]*)*$"
+                  }
+                }
+              },
+              "additionalProperties": false
+            },
+            "operations": {
+              "type": "array",
+              "items": { "$ref": "#/definitions/OperationDef" },
+              "description": "All mutate operations"
+            }
+          }
+        }
+      }
+    },
+    "domains": {
+      "type": "object",
+      "description": "Domain tables: operations grouped by domain",
+      "required": ["tasks", "session", "memory", "check", "pipeline", "orchestrate", "tools", "admin", "nexus", "sticky"],
+      "additionalProperties": false,
+      "properties": {
+        "tasks": {
+          "type": "object",
+          "required": ["name", "purpose", "operations"],
+          "properties": {
+            "name": { "const": "tasks" },
+            "purpose": { "type": "string" },
+            "primaryStore": { "type": "string" },
+            "operations": {
+              "type": "array",
+              "items": { "$ref": "#/definitions/OperationDef" }
+            }
+          }
+        },
+        "session": {
+          "type": "object",
+          "required": ["name", "purpose", "operations"],
+          "properties": {
+            "name": { "const": "session" },
+            "purpose": { "type": "string" },
+            "primaryStore": { "type": "string" },
+            "operations": {
+              "type": "array",
+              "items": { "$ref": "#/definitions/OperationDef" }
+            }
+          }
+        },
+        "memory": {
+          "type": "object",
+          "required": ["name", "purpose", "operations"],
+          "properties": {
+            "name": { "const": "memory" },
+            "purpose": { "type": "string" },
+            "primaryStore": { "type": "string" },
+            "operations": {
+              "type": "array",
+              "items": { "$ref": "#/definitions/OperationDef" }
+            }
+          }
+        },
+        "check": {
+          "type": "object",
+          "required": ["name", "purpose", "operations"],
+          "properties": {
+            "name": { "const": "check" },
+            "purpose": { "type": "string" },
+            "primaryStore": { "type": "string" },
+            "operations": {
+              "type": "array",
+              "items": { "$ref": "#/definitions/OperationDef" }
+            }
+          }
+        },
+        "pipeline": {
+          "type": "object",
+          "required": ["name", "purpose", "operations"],
+          "properties": {
+            "name": { "const": "pipeline" },
+            "purpose": { "type": "string" },
+            "primaryStore": { "type": "string" },
+            "operations": {
+              "type": "array",
+              "items": { "$ref": "#/definitions/OperationDef" }
+            }
+          }
+        },
+        "orchestrate": {
+          "type": "object",
+          "required": ["name", "purpose", "operations"],
+          "properties": {
+            "name": { "const": "orchestrate" },
+            "purpose": { "type": "string" },
+            "primaryStore": { "type": "string" },
+            "operations": {
+              "type": "array",
+              "items": { "$ref": "#/definitions/OperationDef" }
+            }
+          }
+        },
+        "tools": {
+          "type": "object",
+          "required": ["name", "purpose", "operations"],
+          "properties": {
+            "name": { "const": "tools" },
+            "purpose": { "type": "string" },
+            "primaryStore": { "type": "string" },
+            "operations": {
+              "type": "array",
+              "items": { "$ref": "#/definitions/OperationDef" }
+            }
+          }
+        },
+        "admin": {
+          "type": "object",
+          "required": ["name", "purpose", "operations"],
+          "properties": {
+            "name": { "const": "admin" },
+            "purpose": { "type": "string" },
+            "primaryStore": { "type": "string" },
+            "operations": {
+              "type": "array",
+              "items": { "$ref": "#/definitions/OperationDef" }
+            }
+          }
+        },
+        "nexus": {
+          "type": "object",
+          "required": ["name", "purpose", "operations"],
+          "properties": {
+            "name": { "const": "nexus" },
+            "purpose": { "type": "string" },
+            "primaryStore": { "type": "string" },
+            "operations": {
+              "type": "array",
+              "items": { "$ref": "#/definitions/OperationDef" }
+            }
+          }
+        },
+        "sticky": {
+          "type": "object",
+          "required": ["name", "purpose", "operations"],
+          "properties": {
+            "name": { "const": "sticky" },
+            "purpose": { "type": "string" },
+            "primaryStore": { "type": "string" },
+            "operations": {
+              "type": "array",
+              "items": { "$ref": "#/definitions/OperationDef" }
+            }
+          }
+        }
+      }
+    },
+    "progressiveDisclosure": {
+      "type": "object",
+      "description": "Progressive disclosure contract by tier",
+      "properties": {
+        "tiers": {
+          "type": "array",
+          "minItems": 3,
+          "maxItems": 3,
+          "items": {
+            "type": "object",
+            "required": ["tier", "name", "description", "operationCount", "domains"],
+            "properties": {
+              "tier": { "$ref": "#/definitions/Tier" },
+              "name": {
+                "type": "string",
+                "enum": ["Core", "Extended", "Full System"]
+              },
+              "description": { "type": "string" },
+              "operationCount": { "type": "integer", "minimum": 0 },
+              "domains": {
+                "type": "array",
+                "items": { "$ref": "#/definitions/CanonicalDomain" }
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+}

package/schemas/system-flow-atlas.schema.json

@@ -0,0 +1,125 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "CLEO System Flow Atlas Structure",
+  "description": "Validates that a System Flow Atlas document contains all required sections",
+  "type": "object",
+  "properties": {
+    "title": {
+      "type": "string",
+      "const": "CLEO System Flow Atlas",
+      "description": "Document title"
+    },
+    "version": {
+      "type": "string",
+      "pattern": "^\\d{4}\\.\\d{1,2}\\.\\d{1,2}$",
+      "description": "CalVer version (YYYY.M.D)"
+    },
+    "status": {
+      "type": "string",
+      "enum": ["DRAFT", "REVIEW", "APPROVED", "STABLE", "SUPERSEDED", "ARCHIVED"],
+      "description": "Document lifecycle status"
+    },
+    "sections": {
+      "type": "object",
+      "description": "Required sections in the atlas document",
+      "properties": {
+        "purpose": {
+          "type": "boolean",
+          "description": "Section 1: Purpose exists"
+        },
+        "systemDomainMapping": {
+          "type": "boolean",
+          "description": "Section 2: Four systems mapped to 10 domains"
+        },
+        "requestFlow": {
+          "type": "boolean",
+          "description": "Section 3: End-to-end request flow diagram"
+        },
+        "domainInteractionGraph": {
+          "type": "boolean",
+          "description": "Section 4: Domain interaction graph"
+        },
+        "dataStores": {
+          "type": "boolean",
+          "description": "Section 5: Data stores and ownership boundaries"
+        },
+        "distillationFlow": {
+          "type": "boolean",
+          "description": "Section 6: LOOM distillation flow"
+        },
+        "flowExamples": {
+          "type": "boolean",
+          "description": "Section 7: Query/mutate flow examples"
+        },
+        "progressiveDisclosure": {
+          "type": "boolean",
+          "description": "Section 8: Progressive disclosure in practice"
+        },
+        "failureRecovery": {
+          "type": "boolean",
+          "description": "Section 9: Failure and recovery paths"
+        },
+        "observability": {
+          "type": "boolean",
+          "description": "Section 10: Observability and audit trails"
+        },
+        "invariants": {
+          "type": "boolean",
+          "description": "Section 11: Canonical invariants"
+        },
+        "glossary": {
+          "type": "boolean",
+          "description": "Section 12: Glossary"
+        }
+      },
+      "required": [
+        "purpose",
+        "systemDomainMapping",
+        "requestFlow",
+        "domainInteractionGraph",
+        "dataStores",
+        "distillationFlow",
+        "flowExamples",
+        "progressiveDisclosure",
+        "failureRecovery",
+        "observability",
+        "invariants",
+        "glossary"
+      ]
+    },
+    "domains": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "enum": [
+          "tasks",
+          "session",
+          "memory",
+          "check",
+          "pipeline",
+          "orchestrate",
+          "tools",
+          "admin",
+          "nexus",
+          "sticky"
+        ]
+      },
+      "minItems": 10,
+      "maxItems": 10,
+      "uniqueItems": true,
+      "description": "All 10 canonical domains MUST be referenced"
+    },
+    "systems": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "enum": ["BRAIN", "LOOM", "NEXUS", "LAFS"]
+      },
+      "minItems": 4,
+      "maxItems": 4,
+      "uniqueItems": true,
+      "description": "All 4 conceptual systems MUST be documented"
+    }
+  },
+  "required": ["title", "version", "status", "sections", "domains", "systems"]
+}

package/server.json

@@ -37,12 +37,12 @@
     "io.modelcontextprotocol.registry/publisher-provided": {
       "tools": [
         {
-          "name": "cleo_query",
-          "description": "Read-only operations across 11 domains: tasks, session, orchestrate, research, lifecycle, validate, release, system, issues, skills, providers"
+          "name": "query",
+          "description": "Read-only operations across 10 domains: tasks, session, orchestrate, memory, pipeline, check, admin, tools, nexus, sticky"
         },
         {
-          "name": "cleo_mutate",
-          "description": "Write operations across 11 domains: tasks, session, orchestrate, research, lifecycle, validate, release, system, issues, skills, providers"
+          "name": "mutate",
+          "description": "Write operations across 10 domains: tasks, session, orchestrate, memory, pipeline, check, admin, tools, nexus, sticky"
         }
       ],
       "features": [

package/templates/CLEO-INJECTION.md

@@ -6,17 +6,17 @@ Status: ACTIVE
 ## CLEO Identity
 
 You are a CLEO protocol agent. Use MCP-first operations:
-- `cleo_query` for reads
-- `cleo_mutate` for writes
+- `query` for reads
+- `mutate` for writes
 
 ## Mandatory Efficiency Sequence
 
 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)
+1. `query session status` — resume existing? (~200 tokens)
+2. `query admin dash` — project overview (~500 tokens)
+3. `query tasks current` — active task? (~100 tokens)
+4. `query tasks next` — what to work on (~300 tokens)
+5. `query tasks show` — full details for chosen task (~400 tokens)
 
 ## Agent Work Loop
 
@@ -87,9 +87,9 @@ CLEO includes a native BRAIN memory system. Use the 3-layer retrieval pattern fo
 
 **Example**:
 ```
-cleo_query memory brain.search {query: "authentication"}
-cleo_query memory brain.fetch {ids: ["O-abc123"]}
-cleo_mutate memory brain.observe {text: "Found auth uses JWT", title: "Auth discovery"}
+query memory brain.search {query: "authentication"}
+query memory brain.fetch {ids: ["O-abc123"]}
+mutate memory brain.observe {text: "Found auth uses JWT", title: "Auth discovery"}
 ```
 
 **Anti-patterns:**
@@ -99,8 +99,8 @@ cleo_mutate memory brain.observe {text: "Found auth uses JWT", title: "Auth disc
 ## Escalation
 
 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
+- **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