@cleocode/core 2026.3.44 → 2026.3.46

package/src/system/health.ts

@@ -1036,7 +1036,7 @@ export async function startupHealthCheck(projectRoot?: string): Promise<StartupH
       !globalSchemaCheck.ok;
 
     if (globalNeedsRepair) {
-      // Auto-repair: ensureGlobalScaffold is idempotent and safe
+      // Auto-repair home and templates via ensureGlobalScaffold (idempotent, safe)
       const scaffoldResult = await ensureGlobalScaffold();
 
       checks.push({
@@ -1049,12 +1049,23 @@ export async function startupHealthCheck(projectRoot?: string): Promise<StartupH
         repaired: scaffoldResult.home.action !== 'skipped',
       });
 
-      checks.push({
-        check: 'global_schemas',
-        status: 'pass',
-        message: `Schemas: ${scaffoldResult.schemas.installed} installed, ${scaffoldResult.schemas.updated} updated of ${scaffoldResult.schemas.total}`,
-        repaired: scaffoldResult.schemas.installed > 0 || scaffoldResult.schemas.updated > 0,
-      });
+      // Schemas are read at runtime from the package path; only copy if stale
+      if (!globalSchemaCheck.ok) {
+        const { ensureGlobalSchemas } = await import('../schema-management.js');
+        const schemaResult = ensureGlobalSchemas();
+        checks.push({
+          check: 'global_schemas',
+          status: 'pass',
+          message: `Schemas: ${schemaResult.installed} installed, ${schemaResult.updated} updated of ${schemaResult.total}`,
+          repaired: schemaResult.installed > 0 || schemaResult.updated > 0,
+        });
+      } else {
+        checks.push({
+          check: 'global_schemas',
+          status: 'pass',
+          message: `All ${globalSchemaCheck.installed} schemas current`,
+        });
+      }
 
       checks.push({
         check: 'global_templates',

package/src/ui/index.ts

@@ -59,9 +59,3 @@ export {
 //   injection.ts    -> CAAMP inject()/checkInjection()
 //   mcp-config.ts   -> CAAMP detectAllProviders()/installMcpServer()
 //   injection-registry.ts -> CAAMP getInstructionFiles()
-
-// Injection legacy utilities (kept for validation output support)
-export {
-  getValidationKey,
-  INJECTION_VALIDATION_KEYS,
-} from './injection-legacy.js';

package/src/validation/operation-gate-validators.ts

@@ -326,7 +326,7 @@ export async function validateLayer2Semantic(context: OperationContext): Promise
   // Session scope validation
   if (context.domain === 'session' && context.operation === 'start') {
     const scope = context.params?.scope as string | undefined;
-    if (scope && !scope.match(/^(epic|task|global):/)) {
+    if (scope && scope !== 'global' && !scope.match(/^(epic|task):/)) {
       violations.push({
         layer: GateLayer.SEMANTIC,
         severity: ErrorSeverity.ERROR,
@@ -334,7 +334,7 @@ export async function validateLayer2Semantic(context: OperationContext): Promise
         message: `Invalid session scope format: ${scope}`,
         field: 'scope',
         constraint: 'Must be epic:<id>, task:<id>, or global',
-        fix: 'Use format: epic:T1234, task:T5678, or global',
+        fix: 'Provide scope as "global" or "epic:TXXX"',
       });
     }
   }

package/templates/CLEO-INJECTION.md

@@ -0,0 +1,120 @@
+# CLEO Protocol
+
+Version: 2.1.0
+Status: ACTIVE
+
+## CLEO Identity
+
+You are a CLEO protocol agent. Use MCP-first operations:
+- `query` for reads
+- `mutate` for writes
+
+## Mandatory Efficiency Sequence
+
+Run cheapest-first at session start:
+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
+
+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
+
+## 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.
+
+## Session Quick Reference
+
+| Goal | Operation | Gateway |
+|------|-----------|---------|
+| Check active session | `session status` | query |
+| Resume context from last session | `session handoff.show` | query |
+| Start working | `session start` (scope required) | mutate |
+| Stop working | `session end` | mutate |
+
+For advanced session ops (find, suspend, resume, debrief, decisions): see `.cleo/agent-outputs/T5124-session-decision-tree.md`
+
+**Budget note**: `session list` defaults to 10 results (~500-2000 tokens). Prefer `session find` for discovery (~200-400 tokens).
+
+## Memory Protocol
+
+CLEO includes a native BRAIN memory system. Use the 3-layer retrieval pattern for token-efficient access:
+
+| Step | Operation | Gateway | ~Tokens | Purpose |
+|------|-----------|---------|---------|---------|
+| 1 | `memory brain.search` | query | 50/hit | Search index (IDs + titles) |
+| 2 | `memory brain.timeline` | query | 200-500 | Context around an anchor ID |
+| 3 | `memory brain.fetch` | query | 500/entry | Full details for filtered IDs |
+| Save | `memory brain.observe` | mutate | — | Save observation to brain.db |
+
+**Workflow**: Search first (cheap) → filter interesting IDs → fetch only what you need.
+
+**Example**:
+```
+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:**
+- Fetching all entries without searching first (expensive)
+- Skipping brain.search and going straight to brain.fetch
+
+## Memory Bridge
+
+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.
+
+**Contents**: Last session handoff, key learnings, active patterns, recent decisions, recent observations.
+
+**Refreshes on**: `session.end`, `tasks.complete`, `memory.observe` (decisions), `cleo refresh-memory`.
+
+If the file is missing, run `cleo init` or `cleo refresh-memory` to regenerate it.
+
+## 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`

package/templates/README.md

@@ -0,0 +1,29 @@
+# Templates
+
+Bundled templates shipped with `@cleocode/core`. Used by `cleo init`, `cleo upgrade`, and the global bootstrap flow.
+
+## Directory Structure
+
+| Path | Purpose | Used By |
+|------|---------|---------|
+| `CLEO-INJECTION.md` | Global injection protocol (thin bootstrap) | `~/.cleo/templates/` → `~/.agents/AGENTS.md` |
+| `config.template.json` | Project config defaults | `cleo init` → `.cleo/config.json` |
+| `global-config.template.json` | Global config defaults | Bootstrap → `~/.cleo/config.json` |
+| `cleo-gitignore` | Default `.cleo/.gitignore` content | `cleo init` |
+| `agent-registry.json` | Agent registry template | `cleo init` |
+| `github/ISSUE_TEMPLATE/` | GitHub issue templates (user-facing) | `cleo issue` command |
+| `git-hooks/` | Git hook templates | `cleo init` (optional) |
+
+## Template Resolution
+
+All templates are resolved at runtime via `getPackageRoot() + '/templates/'`. They are bundled in the published npm package — never copied to `~/.cleo/` except for `CLEO-INJECTION.md` which is symlinked for provider `@`-reference resolution.
+
+## Injection Chain
+
+```
+~/.agents/AGENTS.md
+  └── @~/.cleo/templates/CLEO-INJECTION.md (symlink → npm package)
+
+{project}/AGENTS.md
+  └── @~/.agents/AGENTS.md + @.cleo/project-context.json + @.cleo/memory-bridge.md
+```

package/templates/agent-registry.json

@@ -0,0 +1,305 @@
+{
+  "$schema": "https://cleo-dev.com/schemas/v1/agent-registry.schema.json",
+  "schemaVersion": "1.0.0",
+  "lastUpdated": "2026-01-27",
+  "agents": {
+    "claude-code": {
+      "id": "claude-code",
+      "displayName": "Claude Code",
+      "vendor": "Anthropic",
+      "globalDir": "$HOME/.claude",
+      "projectDir": ".claude",
+      "instructionFile": "CLAUDE.md",
+      "skillsDir": "skills",
+      "projectSkillsDir": ".claude/skills",
+      "priority": "high",
+      "status": "active",
+      "cliDetection": {
+        "method": "directory",
+        "check": "$HOME/.claude"
+      },
+      "agentSkillsCompatible": true,
+      "notes": "Primary CLEO target. Anthropic's official CLI."
+    },
+    "cursor": {
+      "id": "cursor",
+      "displayName": "Cursor",
+      "vendor": "Anysphere",
+      "globalDir": "$HOME/.cursor",
+      "projectDir": ".cursor",
+      "instructionFile": "AGENTS.md",
+      "skillsDir": "skills",
+      "projectSkillsDir": ".cursor/skills",
+      "priority": "high",
+      "status": "active",
+      "cliDetection": {
+        "method": "directory",
+        "check": "$HOME/.cursor"
+      },
+      "agentSkillsCompatible": true,
+      "notes": "Popular VS Code fork with AI integration"
+    },
+    "windsurf": {
+      "id": "windsurf",
+      "displayName": "Windsurf",
+      "vendor": "Codeium",
+      "globalDir": "$HOME/.codeium/windsurf",
+      "projectDir": ".windsurf",
+      "instructionFile": "AGENTS.md",
+      "skillsDir": "skills",
+      "projectSkillsDir": ".windsurf/skills",
+      "priority": "high",
+      "status": "active",
+      "cliDetection": {
+        "method": "directory",
+        "check": "$HOME/.codeium/windsurf"
+      },
+      "agentSkillsCompatible": true,
+      "notes": "Codeium's AI IDE"
+    },
+    "codex": {
+      "id": "codex",
+      "displayName": "OpenAI Codex",
+      "vendor": "OpenAI",
+      "globalDir": "$HOME/.codex",
+      "projectDir": ".codex",
+      "instructionFile": "AGENTS.md",
+      "skillsDir": "skills",
+      "projectSkillsDir": ".codex/skills",
+      "priority": "medium",
+      "status": "active",
+      "cliDetection": {
+        "method": "directory",
+        "check": "$HOME/.codex"
+      },
+      "agentSkillsCompatible": true,
+      "notes": "OpenAI's coding assistant"
+    },
+    "gemini-cli": {
+      "id": "gemini-cli",
+      "displayName": "Google Gemini",
+      "vendor": "Google",
+      "globalDir": "$HOME/.gemini",
+      "projectDir": ".gemini",
+      "instructionFile": "GEMINI.md",
+      "skillsDir": "skills",
+      "projectSkillsDir": ".gemini/skills",
+      "priority": "medium",
+      "status": "active",
+      "cliDetection": {
+        "method": "directory",
+        "check": "$HOME/.gemini"
+      },
+      "agentSkillsCompatible": true,
+      "notes": "Google's Gemini CLI assistant"
+    },
+    "github-copilot": {
+      "id": "github-copilot",
+      "displayName": "GitHub Copilot",
+      "vendor": "GitHub/Microsoft",
+      "globalDir": "$HOME/.copilot",
+      "projectDir": ".github",
+      "instructionFile": "AGENTS.md",
+      "skillsDir": "skills",
+      "projectSkillsDir": ".github/skills",
+      "priority": "medium",
+      "status": "active",
+      "cliDetection": {
+        "method": "directory",
+        "check": "$HOME/.copilot"
+      },
+      "agentSkillsCompatible": true,
+      "notes": "GitHub's AI pair programmer"
+    },
+    "opencode": {
+      "id": "opencode",
+      "displayName": "OpenCode",
+      "vendor": "OpenCode",
+      "globalDir": "$HOME/.config/opencode",
+      "projectDir": ".opencode",
+      "instructionFile": "AGENTS.md",
+      "skillsDir": "skills",
+      "projectSkillsDir": ".opencode/skills",
+      "priority": "medium",
+      "status": "active",
+      "cliDetection": {
+        "method": "directory",
+        "check": "$HOME/.config/opencode"
+      },
+      "agentSkillsCompatible": true,
+      "notes": "Open-source coding assistant"
+    },
+    "cline": {
+      "id": "cline",
+      "displayName": "Cline",
+      "vendor": "Cline",
+      "globalDir": "$HOME/.cline",
+      "projectDir": ".cline",
+      "instructionFile": "AGENTS.md",
+      "skillsDir": "skills",
+      "projectSkillsDir": ".cline/skills",
+      "priority": "medium",
+      "status": "active",
+      "cliDetection": {
+        "method": "directory",
+        "check": "$HOME/.cline"
+      },
+      "agentSkillsCompatible": true,
+      "notes": "VS Code extension for AI coding"
+    },
+    "kimi": {
+      "id": "kimi",
+      "displayName": "Kimi Coding",
+      "vendor": "Moonshot AI",
+      "globalDir": "$HOME/.kimi",
+      "projectDir": ".kimi",
+      "instructionFile": "AGENTS.md",
+      "skillsDir": "skills",
+      "projectSkillsDir": ".kimi/skills",
+      "priority": "medium",
+      "status": "active",
+      "cliDetection": {
+        "method": "directory",
+        "check": "$HOME/.kimi"
+      },
+      "agentSkillsCompatible": false,
+      "notes": "Moonshot AI's coding assistant"
+    },
+    "roo": {
+      "id": "roo",
+      "displayName": "Roo Code",
+      "vendor": "Roo",
+      "globalDir": "$HOME/.roo",
+      "projectDir": ".roo",
+      "instructionFile": "AGENTS.md",
+      "skillsDir": "skills",
+      "projectSkillsDir": ".roo/skills",
+      "priority": "low",
+      "status": "active",
+      "cliDetection": {
+        "method": "directory",
+        "check": "$HOME/.roo"
+      },
+      "agentSkillsCompatible": true,
+      "notes": "Roo coding assistant"
+    },
+    "continue": {
+      "id": "continue",
+      "displayName": "Continue",
+      "vendor": "Continue",
+      "globalDir": "$HOME/.continue",
+      "projectDir": ".continue",
+      "instructionFile": "AGENTS.md",
+      "skillsDir": "skills",
+      "projectSkillsDir": ".continue/skills",
+      "priority": "low",
+      "status": "active",
+      "cliDetection": {
+        "method": "directory",
+        "check": "$HOME/.continue"
+      },
+      "agentSkillsCompatible": false,
+      "notes": "Open-source AI coding assistant"
+    },
+    "antigravity": {
+      "id": "antigravity",
+      "displayName": "Antigravity",
+      "vendor": "Google",
+      "globalDir": "$HOME/.gemini/antigravity",
+      "projectDir": ".antigravity",
+      "instructionFile": "AGENTS.md",
+      "skillsDir": "global_skills",
+      "projectSkillsDir": ".antigravity/skills",
+      "priority": "low",
+      "status": "beta",
+      "cliDetection": {
+        "method": "directory",
+        "check": "$HOME/.gemini/antigravity"
+      },
+      "agentSkillsCompatible": true,
+      "notes": "Google's experimental coding assistant"
+    },
+    "goose": {
+      "id": "goose",
+      "displayName": "Goose",
+      "vendor": "Block",
+      "globalDir": "$HOME/.goose",
+      "projectDir": ".goose",
+      "instructionFile": "AGENTS.md",
+      "skillsDir": "skills",
+      "projectSkillsDir": ".goose/skills",
+      "priority": "low",
+      "status": "active",
+      "cliDetection": {
+        "method": "directory",
+        "check": "$HOME/.goose"
+      },
+      "agentSkillsCompatible": true,
+      "notes": "Block's open-source AI agent"
+    },
+    "kiro-cli": {
+      "id": "kiro-cli",
+      "displayName": "Kiro CLI",
+      "vendor": "Kiro",
+      "globalDir": "$HOME/.kiro",
+      "projectDir": ".kiro",
+      "instructionFile": "AGENTS.md",
+      "skillsDir": "skills",
+      "projectSkillsDir": ".kiro/skills",
+      "priority": "low",
+      "status": "beta",
+      "cliDetection": {
+        "method": "directory",
+        "check": "$HOME/.kiro"
+      },
+      "agentSkillsCompatible": true,
+      "notes": "Kiro command-line coding assistant"
+    },
+    "amp": {
+      "id": "amp",
+      "displayName": "Amp",
+      "vendor": "Sourcegraph",
+      "globalDir": "$HOME/.amp",
+      "projectDir": ".amp",
+      "instructionFile": "AGENTS.md",
+      "skillsDir": "skills",
+      "projectSkillsDir": ".amp/skills",
+      "priority": "low",
+      "status": "beta",
+      "cliDetection": {
+        "method": "directory",
+        "check": "$HOME/.amp"
+      },
+      "agentSkillsCompatible": true,
+      "notes": "Sourcegraph's AI coding assistant"
+    },
+    "trae": {
+      "id": "trae",
+      "displayName": "Trae",
+      "vendor": "ByteDance",
+      "globalDir": "$HOME/.trae",
+      "projectDir": ".trae",
+      "instructionFile": "AGENTS.md",
+      "skillsDir": "skills",
+      "projectSkillsDir": ".trae/skills",
+      "priority": "low",
+      "status": "beta",
+      "cliDetection": {
+        "method": "directory",
+        "check": "$HOME/.trae"
+      },
+      "agentSkillsCompatible": true,
+      "notes": "ByteDance's AI IDE"
+    }
+  },
+  "instructionFileMap": {
+    "CLAUDE.md": ["claude-code"],
+    "GEMINI.md": ["gemini-cli"],
+    "AGENTS.md": ["cursor", "windsurf", "codex", "github-copilot", "opencode", "cline", "kimi", "roo", "continue", "antigravity", "goose", "kiro-cli", "amp", "trae"]
+  },
+  "priorityTiers": {
+    "tier1": ["claude-code", "cursor", "windsurf"],
+    "tier2": ["codex", "gemini-cli", "github-copilot", "opencode", "cline", "kimi"],
+    "tier3": ["roo", "continue", "antigravity", "goose", "kiro-cli", "amp", "trae"]
+  }
+}

package/templates/cleo-gitignore

@@ -0,0 +1,74 @@
+# =============================================================================
+# .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.
+#
+# Canonical audit: .cleo/agent-outputs/T5159-cleo-file-audit.md
+# ADR: ADR-013-data-integrity-checkpoint-architecture.md
+# =============================================================================
+
+# Step 1: Ignore everything in .cleo/
+*
+
+# =============================================================================
+# ALLOW LIST — files and directories that SHOULD be tracked
+# =============================================================================
+
+# Step 2: Allow this .gitignore itself
+!.gitignore
+
+# Step 3: Allow project configuration files
+!config.json
+!project-context.json
+!project-info.json
+!setup-otel.sh
+!DATA-SAFETY-IMPLEMENTATION-SUMMARY.md
+
+# Step 4: Allow ADRs directory (architecture decisions — project-level, not CLEO-specific)
+!adrs/
+!adrs/**
+
+# Step 5: Allow RCASD lifecycle provenance directory
+# Structure: rcasd/{epic#}/research/, consensus/, architecture/, specs/, contributions/
+!rcasd/
+!rcasd/**
+
+# Step 6: Allow agent-outputs directory
+!agent-outputs/
+!agent-outputs/**
+
+# =============================================================================
+# EXPLICIT DENY — safety net that overrides allow rules above
+# =============================================================================
+
+# SQLite databases — NEVER track (data loss root cause, ADR-013)
+*.db
+*.db-shm
+*.db-wal
+*.db-journal
+
+# Logs — NEVER track (append-only runtime data)
+log.json
+tasks-log.jsonl
+todo-log.jsonl
+bypass-log.json
+qa-log.json
+
+# Caches and transient state
+.deps-cache/
+.context-alert-state.json
+.context-state*.json
+context-states/
+.git-checkpoint-state
+.migration-state.json
+
+# Instance-specific runtime data
+migrations.json
+sync/
+metrics/
+
+# Backups — NEVER track
+.backups/
+backups/