@cleocode/cleo 2026.3.2 → 2026.3.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cleocode/cleo",
-  "version": "2026.3.2",
+  "version": "2026.3.6",
   "description": "CLEO V2 - TypeScript task management CLI for AI coding agents",
   "mcpName": "io.github.kryptobaseddev/cleo-mcp-server",
   "type": "module",
@@ -24,9 +24,9 @@
     "dev": "tsc --noEmit --watch",
     "dev:setup": "bash dev/setup-ts-dev.sh",
     "dev:watch": "node build.mjs --watch",
-    "test": "vitest run",
-    "test:watch": "vitest",
-    "test:coverage": "vitest run --coverage",
+    "test": "LOG_LEVEL=silent NODE_NO_WARNINGS=1 vitest run",
+    "test:watch": "LOG_LEVEL=silent NODE_NO_WARNINGS=1 vitest",
+    "test:coverage": "LOG_LEVEL=silent NODE_NO_WARNINGS=1 vitest run --coverage",
     "lint": "tsc --noEmit",
     "prepare": "npm run build",
     "prepack": "npm run build",

package/packages/ct-skills/index.js

@@ -6,7 +6,7 @@ const fs = require('fs');
 const LIBRARY_ROOT = __dirname;
 const SKILLS_ROOT = path.join(LIBRARY_ROOT, 'skills');
 const PROFILES_ROOT = path.join(LIBRARY_ROOT, 'profiles');
-const PROTOCOLS_ROOT = path.join(LIBRARY_ROOT, 'protocols');
+const PROTOCOLS_ROOT = path.join(LIBRARY_ROOT, '..', '..', 'src', 'protocols');
 const SHARED_ROOT = path.join(SKILLS_ROOT, '_shared');
 
 // --- Package metadata ---

package/packages/ct-skills/package.json

@@ -6,9 +6,7 @@
   "types": "index.d.ts",
   "files": [
     "skills",
-    "protocols",
     "profiles",
-    "_shared",
     "*.json",
     "*.js",
     "*.d.ts"

package/packages/ct-skills/profiles/core.json

@@ -1,6 +1,6 @@
 {
   "name": "core",
-  "description": "Minimum viable CLEO skill set",
+  "description": "Orchestration and pipeline awareness",
   "extends": "minimal",
   "skills": ["ct-orchestrator"],
   "includeProtocols": ["agent-protocol"]

package/packages/ct-skills/profiles/full.json

@@ -1,11 +1,10 @@
 {
   "name": "full",
-  "description": "All CT-SKILLS",
+  "description": "All skills including execution, documentation, quality, and meta",
   "extends": "recommended",
   "skills": [
-    "ct-dev-workflow", "ct-test-writer-bats", "ct-library-implementer-bash",
-    "ct-documentor", "ct-docs-lookup", "ct-docs-write", "ct-docs-review",
-    "ct-skill-creator", "ct-skill-lookup", "ct-contribution", "ct-gitbook"
+    "ct-dev-workflow", "ct-documentor", "ct-docs-lookup", "ct-docs-write", "ct-docs-review",
+    "ct-contribution", "ct-grade", "ct-skill-creator"
   ],
-  "includeProtocols": ["contribution", "release", "testing", "artifact-publish", "provenance"]
+  "includeProtocols": ["implementation", "contribution", "release", "testing", "artifact-publish", "provenance"]
 }

package/packages/ct-skills/profiles/minimal.json

@@ -1,7 +1,7 @@
 {
   "name": "minimal",
-  "description": "Bare minimum — just the default fallback skill",
-  "skills": ["ct-task-executor"],
+  "description": "Solo task execution with core CLEO protocol — no orchestration needed",
+  "skills": ["ct-cleo", "ct-task-executor"],
   "includeShared": true,
-  "includeProtocols": ["implementation"]
+  "includeProtocols": []
 }

package/packages/ct-skills/profiles/recommended.json

@@ -1,7 +1,7 @@
 {
   "name": "recommended",
-  "description": "Core + RCSD pipeline skills",
+  "description": "Full RCASD pipeline skills for epic-driven development",
   "extends": "core",
   "skills": ["ct-epic-architect", "ct-research-agent", "ct-spec-writer", "ct-validator"],
-  "includeProtocols": ["research", "specification", "decomposition", "consensus", "validation"]
+  "includeProtocols": ["research", "consensus", "specification", "decomposition", "validation", "adr"]
 }

package/packages/ct-skills/provider-skills-map.json

@@ -0,0 +1,97 @@
+{
+  "$schema": "https://lafs.dev/schemas/v1/provider-skills-map.schema.json",
+  "version": "1.0.0",
+  "description": "Provider skill path discovery and precedence rules for CLEO skill deployment",
+  "providers": {
+    "claude-code": {
+      "globalSkills": "$HOME/.claude/skills",
+      "projectSkills": ".claude/skills",
+      "agentsGlobal": null,
+      "agentsProject": null,
+      "readsFromDotAgents": false,
+      "precedence": "vendor-only",
+      "symlinkSupported": true,
+      "notes": "Created Agent Skills standard but uses vendor path exclusively"
+    },
+    "codex-cli": {
+      "globalSkills": "$HOME/.agents/skills",
+      "projectSkills": ".agents/skills",
+      "agentsGlobal": "$HOME/.agents/skills",
+      "agentsProject": ".agents/skills",
+      "readsFromDotAgents": true,
+      "precedence": "agents-canonical",
+      "symlinkSupported": true,
+      "notes": "Uses .agents/skills as canonical location"
+    },
+    "gemini-cli": {
+      "globalSkills": "$HOME/.gemini/skills",
+      "projectSkills": ".gemini/skills",
+      "agentsGlobal": "$HOME/.agents/skills",
+      "agentsProject": ".agents/skills",
+      "readsFromDotAgents": true,
+      "precedence": "agents-first",
+      "symlinkSupported": true,
+      "notes": ".agents/skills takes precedence over .gemini/skills within same tier"
+    },
+    "cursor": {
+      "globalSkills": "$HOME/.cursor/skills",
+      "projectSkills": ".cursor/skills",
+      "agentsGlobal": null,
+      "agentsProject": ".agents/skills",
+      "readsFromDotAgents": "project-only",
+      "precedence": "vendor-global-agents-project",
+      "symlinkSupported": true,
+      "notes": "Global uses vendor path; project supports .agents/skills"
+    },
+    "github-copilot": {
+      "globalSkills": "$HOME/.copilot/skills",
+      "projectSkills": ".github/skills",
+      "agentsGlobal": "$HOME/.agents/skills",
+      "agentsProject": ".agents/skills",
+      "readsFromDotAgents": true,
+      "precedence": "agents-supported",
+      "symlinkSupported": true,
+      "notes": "Supports both vendor and .agents paths at all levels"
+    },
+    "windsurf": {
+      "globalSkills": "$HOME/.codeium/windsurf/skills",
+      "projectSkills": ".windsurf/skills",
+      "agentsGlobal": null,
+      "agentsProject": null,
+      "readsFromDotAgents": false,
+      "precedence": "vendor-only",
+      "symlinkSupported": false,
+      "notes": "Vendor-specific paths only, no .agents support"
+    },
+    "opencode": {
+      "globalSkills": "$HOME/.config/opencode/skills",
+      "projectSkills": ".opencode/skills",
+      "agentsGlobal": "$HOME/.agents/skills",
+      "agentsProject": ".agents/skills",
+      "readsFromDotAgents": true,
+      "precedence": "agents-supported",
+      "symlinkSupported": true,
+      "notes": "User confirms .agents/ support; verify via opencode docs"
+    },
+    "kimi-coding": {
+      "globalSkills": "$HOME/.kimi/skills",
+      "projectSkills": ".kimi/skills",
+      "agentsGlobal": null,
+      "agentsProject": null,
+      "readsFromDotAgents": false,
+      "precedence": "vendor-only",
+      "symlinkSupported": false,
+      "notes": "Model-based provider; skill path support uncertain"
+    },
+    "antigravity": {
+      "globalSkills": "$HOME/.antigravity/skills",
+      "projectSkills": ".agent/skills",
+      "agentsGlobal": null,
+      "agentsProject": ".agents/skills",
+      "readsFromDotAgents": "project-only",
+      "precedence": "vendor-global-agents-project",
+      "symlinkSupported": true,
+      "notes": "Project-level .agents/skills confirmed in Google codelabs"
+    }
+  }
+}

package/packages/ct-skills/skills/_shared/skill-chaining-patterns.md

@@ -16,7 +16,7 @@ This reference defines patterns for multi-level skill invocation and context pro
 
 ## Pattern 1: Single-Level Spawning
 
-The orchestrator delegates work to a subagent via Task tool with skill injection.
+The orchestrator delegates work to a subagent via `orchestrate.spawn` with skill injection.
 
 ### Flow
 
@@ -25,7 +25,7 @@ The orchestrator delegates work to a subagent via Task tool with skill injection
 │   ORCHESTRATOR  │
 │  (ct-orchestrator)
 └────────┬────────┘
-         │ Task tool + skill template
+         │ orchestrate.spawn → provider adapter
          ▼
 ┌─────────────────┐
 │    SUBAGENT     │
@@ -35,18 +35,15 @@ The orchestrator delegates work to a subagent via Task tool with skill injection
 
 ### Implementation
 
-```bash
-# Orchestrator prepares context
-source lib/token-inject.sh
-export TI_TASK_ID="T1234"
-export TI_DATE="$(date +%Y-%m-%d)"
-export TI_TOPIC_SLUG="auth-research"
-ti_set_defaults
-
-# Load skill template with tokens
-template=$(ti_load_template "skills/ct-research-agent/SKILL.md")
-
-# Spawn via Task tool (includes subagent protocol block)
+```
+# 1. Generate fully-resolved spawn prompt via MCP
+cleo_mutate({ domain: "orchestrate", operation: "spawn", params: { taskId: "T1234" }})
+
+# 2. Provider adapter executes the prompt using its native mechanism
+#    - Claude Code: Task tool with cleo-subagent type
+#    - OpenCode: config-driven agent spawn
+#    - Codex: SDK agent creation
+#    - Others: file-based prompt handoff
 ```
 
 ### Context Propagation
@@ -127,13 +124,13 @@ A subagent can itself become an orchestrator, spawning further subagents for com
 │    ORCHESTRATOR     │  Level 0: Main workflow
 │   (ct-orchestrator) │
 └─────────┬───────────┘
-          │ Task tool
+          │ orchestrate.spawn
           ▼
 ┌─────────────────────┐
 │ SUB-ORCHESTRATOR    │  Level 1: Epic decomposition
 │ (ct-epic-architect) │
 └─────────┬───────────┘
-          │ Task tool
+          │ orchestrate.spawn
           ▼
 ┌─────────────────────┐
 │    WORKER AGENT     │  Level 2: Task execution
@@ -184,13 +181,13 @@ Detailed findings go to output files, not manifest or response:
 
 ### Rule 4: Token Injection (SHOULD)
 
-Use `lib/token-inject.sh` for dynamic token replacement:
+All tokens are resolved before prompt injection via `orchestrate.spawn`:
 
-```bash
+```
 # Required tokens for all subagents
-TI_TASK_ID    # Current task identifier
-TI_DATE       # Execution date (YYYY-MM-DD)
-TI_TOPIC_SLUG # URL-safe topic name
+TASK_ID       # Current task identifier
+DATE          # Execution date (YYYY-MM-DD)
+TOPIC_SLUG    # URL-safe topic name
 ```
 
 ---
@@ -211,14 +208,14 @@ TI_TOPIC_SLUG # URL-safe topic name
 
 Before spawning subagent:
 - [ ] Identify appropriate skill for task type
-- [ ] Prepare token context (TI_TASK_ID, TI_DATE, TI_TOPIC_SLUG)
-- [ ] Load skill template with `ti_load_template()`
-- [ ] Include subagent protocol block in prompt
+- [ ] Prepare token context (TASK_ID, DATE, TOPIC_SLUG)
+- [ ] Use `orchestrate.spawn` to generate fully-resolved prompt
+- [ ] Verify token resolution is complete (`tokenResolution.fullyResolved`)
 
 Before chaining to another skill:
 - [ ] Determine if skill shares context (same agent) or needs delegation
 - [ ] For same-agent: Use `Skill(skill="name")` or `/skill-name`
-- [ ] For new agent: Use Task tool with full protocol injection
+- [ ] For new agent: Use `orchestrate.spawn` with full protocol injection
 
 Before completion:
 - [ ] Verify manifest entry appended
@@ -231,7 +228,7 @@ Before completion:
 
 | Skill | Demonstrates |
 |-------|--------------|
-| `ct-orchestrator` | Single-level spawning via Task tool |
+| `ct-orchestrator` | Single-level spawning via orchestrate.spawn |
 | `ct-documentor` | Skill chaining (lookup → write → review) |
 | `ct-epic-architect` | Potential multi-level orchestration |
 

package/packages/ct-skills/skills/_shared/testing-framework-config.md

@@ -71,15 +71,15 @@ CLEO supports 16 testing frameworks. Configure your project's testing setup in `
 
 ## Supported Frameworks
 
-| Framework | Extension | Ecosystem |
-|-----------|-----------|-----------|
-| bats | .bats | Bash |
-| jest, vitest, playwright, cypress, mocha, ava, uvu, tap | .test.js/.ts | Node.js |
-| node:test, deno, bun | .test.ts | Runtime built-ins |
-| pytest | _test.py | Python |
-| go | _test.go | Go |
-| cargo | .rs | Rust |
-| custom | varies | Any |
+| Framework | Extension | Ecosystem | Notes |
+|-----------|-----------|-----------|-------|
+| vitest | .test.ts | Node.js | **Default for CLEO projects** |
+| jest, playwright, cypress, mocha, ava, uvu, tap | .test.js/.ts | Node.js | |
+| node:test, deno, bun | .test.ts | Runtime built-ins | |
+| pytest | _test.py | Python | |
+| go | _test.go | Go | |
+| cargo | .rs | Rust | |
+| custom | varies | Any | |
 
 ## Validation Gates
 

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

@@ -40,6 +40,8 @@ MCP is the **primary** entry point. Use `cleo_query` for reads and `cleo_mutate`
 | `system` | `context` | Context window usage |
 | `skills` | `list` | Available skills |
 | `skills` | `show` | Skill details (`params: { name }`) |
+| `pipeline` | `stage.status` | Pipeline stage for epic (`params: { epicId }`) |
+| `pipeline` | `stage.validate` | Validate gate before advancing (`params: { epicId, stage }`) |
 
 ### Key Write Operations (`cleo_mutate`)
 
@@ -54,6 +56,8 @@ MCP is the **primary** entry point. Use `cleo_query` for reads and `cleo_mutate`
 | `tasks` | `start` | Start working on a task (`params: { taskId }`) |
 | `research` | `link` | Link research to task (`params: { taskId, entryId }`) |
 | `orchestrate` | `spawn` | Generate spawn prompt for subagent (`params: { taskId }`) |
+| `pipeline` | `stage.record` | Record pipeline stage progress (`params: { epicId, stage, status }`) |
+| `pipeline` | `stage.gate.pass` | Advance pipeline to next stage (`params: { epicId, stage }`) |
 
 ## CLI Fallback
 
@@ -180,6 +184,23 @@ After EVERY command:
 
 **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.
 
+## Pipeline Awareness
+
+Epics follow the RCASD-IVTR+C lifecycle managed through pipeline stages. Use `pipeline.stage.status` to check where an epic is in its lifecycle:
+
+| Stage | Purpose |
+|-------|---------|
+| `research` | Information gathering and analysis |
+| `consensus` | Validate claims and decisions |
+| `architecture_decision` | ADR and specification |
+| `specification` | Formal requirements |
+| `decomposition` | Task breakdown |
+| `implementation` | Build functionality |
+| `validation` | Verify against criteria |
+| `testing` | Test coverage |
+| `release` | Version and publish |
+| `contribution` | Multi-agent consensus tracking |
+
 ## Time Estimates Prohibited
 
 - **MUST NOT** estimate hours, days, weeks, or temporal duration
@@ -192,5 +213,4 @@ For detailed guidance on specific topics, see:
 
 - **Session Protocol**: `references/session-protocol.md`
 - **RCSD Lifecycle**: `references/rcsd-lifecycle.md`
-- **Orchestrator Constraints**: `references/orchestrator-constraints.md`
 - **Anti-Patterns**: `references/anti-patterns.md`

package/packages/ct-skills/skills/ct-dev-workflow/SKILL.md

@@ -20,7 +20,7 @@ license: MIT
 
 # Development Workflow Context Injection
 
-**Protocol**: @protocols/contribution.md
+**Protocol**: @src/protocols/contribution.md
 **Type**: Context Injection (cleo-subagent)
 **Version**: 3.0.0
 

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

@@ -23,7 +23,7 @@ license: MIT
 
 # Documentation Specialist Context Injection
 
-**Protocol**: @protocols/implementation.md
+**Protocol**: @src/protocols/implementation.md
 **Type**: Context Injection (cleo-subagent)
 **Version**: 3.0.0
 

package/packages/ct-skills/skills/ct-epic-architect/SKILL.md

@@ -20,7 +20,7 @@ license: MIT
 
 # Epic Architect Context Injection
 
-**Protocol**: @protocols/decomposition.md
+**Protocol**: @src/protocols/decomposition.md
 **Type**: Context Injection (cleo-subagent)
 **Version**: 3.0.0
 

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

@@ -0,0 +1,214 @@
+---
+name: ct-grade
+description: Session grading for agent behavioral analysis. Use when evaluating agent session quality, running grade scenarios, or interpreting grade results. Triggers on grading tasks, session quality checks, or behavioral analysis needs.
+version: 1.0.0
+tier: 2
+core: false
+category: quality
+protocol: null
+dependencies: []
+sharedResources: []
+compatibility:
+  - claude-code
+  - cursor
+  - windsurf
+  - gemini-cli
+license: MIT
+---
+
+# Session Grading Guide
+
+Session grading evaluates agent behavioral patterns against the CLEO protocol. It reads the audit log for a completed session and applies a 5-dimension rubric to produce a score (0-100), letter grade (A-F), and diagnostic flags.
+
+## When to Use Grade Mode
+
+Use grading when you need to:
+- Evaluate how well an agent followed CLEO protocol during a session
+- Identify behavioral anti-patterns (skipped discovery, missing session.end, etc.)
+- Track improvement over time across multiple sessions
+- Validate that orchestrated subagents followed protocol
+
+Grading requires audit data. Sessions must be started with the `--grade` flag to enable audit log capture.
+
+## Starting a Grade Session
+
+### CLI
+
+```bash
+# Start a session with grading enabled
+ct session start --scope epic:T001 --name "Feature work" --grade
+
+# The --grade flag enables detailed audit logging
+# All MCP and CLI operations are recorded for later analysis
+```
+
+### MCP
+
+```
+cleo_mutate({ domain: "session", operation: "start",
+  params: { scope: "epic:T001", name: "Feature work", grade: true }})
+```
+
+## Running Scenarios
+
+The grading rubric evaluates 5 behavioral scenarios that map to protocol compliance:
+
+### 1. Fresh Discovery
+Tests whether the agent checks existing sessions and tasks before starting work. Evaluates `session.list` and `tasks.find` calls at session start.
+
+### 2. Task Hygiene
+Tests whether task creation follows protocol: descriptions provided, parent existence verified before subtask creation, no duplicate tasks.
+
+### 3. Error Recovery
+Tests whether the agent handles errors correctly: follows up `E_NOT_FOUND` with recovery lookups (`tasks.find` or `tasks.exists`), avoids duplicate creates after failures.
+
+### 4. Full Lifecycle
+Tests session discipline end-to-end: session listed before task ops, session properly ended, MCP-first usage patterns.
+
+### 5. Multi-Domain Analysis
+Tests progressive disclosure: use of `admin.help` or skill lookups, preference for `cleo_query` (MCP) over CLI for programmatic access.
+
+## Evaluating Results
+
+### CLI
+
+```bash
+# Grade a specific session
+ct grade <sessionId>
+
+# List all past grade results
+ct grade --list
+```
+
+### MCP
+
+```
+# Grade a session
+cleo_query({ domain: "admin", operation: "grade",
+  params: { sessionId: "abc-123" }})
+
+# List past grades
+cleo_query({ domain: "admin", operation: "grade.list" })
+```
+
+## Understanding the 5 Dimensions
+
+Each dimension scores 0-20 points, totaling 0-100.
+
+### S1: Session Discipline (20 pts)
+
+| Points | Criteria |
+|--------|----------|
+| 10 | `session.list` called before first task operation |
+| 10 | `session.end` called when work is complete |
+
+**What it measures**: Does the agent check existing sessions before starting, and properly close sessions when done?
+
+### S2: Discovery Efficiency (20 pts)
+
+| Points | Criteria |
+|--------|----------|
+| 0-15 | `find:list` ratio >= 80% earns full 15; scales linearly below |
+| 5 | `tasks.show` used for detail retrieval |
+
+**What it measures**: Does the agent prefer `tasks.find` (low context cost) over `tasks.list` (high context cost) for discovery?
+
+### S3: Task Hygiene (20 pts)
+
+Starts at 20 and deducts for violations:
+
+| Deduction | Violation |
+|-----------|-----------|
+| -5 each | `tasks.add` without a description |
+| -3 | Subtasks created without `tasks.exists` parent check |
+
+**What it measures**: Does the agent create well-formed tasks with descriptions and verify parents before creating subtasks?
+
+### S4: Error Protocol (20 pts)
+
+Starts at 20 and deducts for violations:
+
+| Deduction | Violation |
+|-----------|-----------|
+| -5 each | `E_NOT_FOUND` error not followed by recovery lookup within 5 ops |
+| -5 | Duplicate task creates detected (same title in session) |
+
+**What it measures**: Does the agent recover gracefully from errors and avoid creating duplicate tasks?
+
+### S5: Progressive Disclosure Use (20 pts)
+
+| Points | Criteria |
+|--------|----------|
+| 10 | `admin.help` or skill lookup calls made |
+| 10 | `cleo_query` (MCP gateway) used for programmatic access |
+
+**What it measures**: Does the agent use progressive disclosure (help/skills) and prefer MCP over CLI?
+
+## Interpreting Scores
+
+### Letter Grades
+
+| Grade | Score Range | Meaning |
+|-------|-----------|---------|
+| **A** | 90-100 | Excellent protocol adherence. Agent follows all best practices. |
+| **B** | 75-89 | Good. Minor gaps in one or two dimensions. |
+| **C** | 60-74 | Acceptable. Several protocol violations need attention. |
+| **D** | 45-59 | Below expectations. Significant anti-patterns present. |
+| **F** | 0-44 | Failing. Major protocol violations across multiple dimensions. |
+
+### Reading the Output
+
+The grade result includes:
+- **score/maxScore**: Raw numeric score (e.g., `85/100`)
+- **percent**: Percentage score
+- **grade**: Letter grade (A-F)
+- **dimensions**: Per-dimension breakdown with score, max, and evidence
+- **flags**: Specific violations or improvement suggestions
+- **entryCount**: Number of audit entries analyzed
+
+### Flags
+
+Flags are actionable diagnostic messages. Each flag identifies a specific behavioral issue:
+
+- `session.list never called` -- Check existing sessions before starting new ones
+- `session.end never called` -- Always end sessions when done
+- `tasks.list used Nx` -- Prefer `tasks.find` for discovery
+- `tasks.add without description` -- Always provide task descriptions
+- `Subtasks created without tasks.exists parent check` -- Verify parent exists first
+- `E_NOT_FOUND not followed by recovery lookup` -- Follow errors with `tasks.find` or `tasks.exists`
+- `No admin.help or skill lookup calls` -- Load `ct-cleo` for protocol guidance
+- `No MCP query calls` -- Prefer `cleo_query` over CLI
+
+## Common Anti-patterns
+
+| Anti-pattern | Impact | Fix |
+|-------------|--------|-----|
+| Skipping `session.list` at start | -10 S1 | Always check existing sessions first |
+| Forgetting `session.end` | -10 S1 | End sessions when work is complete |
+| Using `tasks.list` instead of `tasks.find` | -up to 15 S2 | Use `find` for discovery, `list` only for known parent children |
+| Creating tasks without descriptions | -5 each S3 | Always provide a description with `tasks.add` |
+| Ignoring `E_NOT_FOUND` errors | -5 each S4 | Follow up with `tasks.find` or `tasks.exists` |
+| Creating duplicate tasks | -5 S4 | Check for existing tasks before creating new ones |
+| Never using `admin.help` | -10 S5 | Use progressive disclosure for protocol guidance |
+| CLI-only usage (no MCP) | -10 S5 | Prefer `cleo_query`/`cleo_mutate` for programmatic access |
+
+## Grade Result Schema
+
+Grade results are stored in `.cleo/metrics/GRADES.jsonl` as append-only JSONL. Each entry conforms to `schemas/grade.schema.json` with these fields:
+
+- `sessionId` (string, required) -- Session that was graded
+- `taskId` (string, optional) -- Associated task ID
+- `totalScore` (number, 0-100) -- Aggregate score
+- `maxScore` (number, default 100) -- Maximum possible score
+- `dimensions` (object) -- Per-dimension `{ score, max, evidence[] }`
+- `flags` (string[]) -- Specific violations or suggestions
+- `timestamp` (ISO 8601) -- When the grade was computed
+- `entryCount` (number) -- Audit entries analyzed
+- `evaluator` (`auto` | `manual`) -- How the grade was computed
+
+## MCP Operations
+
+| Gateway | Domain | Operation | Description |
+|---------|--------|-----------|-------------|
+| `cleo_query` | `admin` | `grade` | Grade a session (`params: { sessionId }`) |
+| `cleo_query` | `admin` | `grade.list` | List all past grade results |