/ct-cleo

name: ct-cleo
description: CLEO task management protocol - session, task, and workflow guidance. Use when managing tasks, sessions, or multi-agent workflows with the CLEO CLI protocol.
metadata:
  version: 2.24.24
  tier: core
  install: harness
  covers:
    - packages/cleo/src/cli/commands/session.ts
    - packages/cleo/src/cli/commands/focus.ts
    - packages/cleo/src/cli/commands/sticky.ts
  lastReviewed: 2026-10-25
  stability: stable

CLEO Protocol Guide

Trustworthy project knowledge

After confirming the assigned worktree, orient with briefing/focus. Check current coverage and sourced authority before acting on retrieved guidance. `UNKNOWN` impact is incomplete assessment; `NONE` is no detected impact in assessed static coverage, never proof of no runtime callers. Resolve ambiguous symbols explicitly. Preserve historical handoffs and follow sourced corrections separately.

Consume repair findings as a matrix of scope, evidence, responsibility, operation, prerequisites, verification, and recovery. The calling agent supplies sourced resolutions; no background model is required. Escalate unresolved owner decisions, reject stale proposals, verify postconditions, and record useful incident learning with project/revision evidence. A failed diagnostic is not clean. Provider reference delivery must be verified or embedded self-contained; static instruction checks do not establish live Codex, Claude, or Kimi behavior.

Asking the owner (HITL ask tool)

Whenever you need the owner to answer, decide, approve or choose ANYTHING, use the ask tool (`AskUserQuestion` in Claude Code, or the provider equivalent listed in CAAMP's `PROVIDER_ASK_TOOLS`) with 2-4 concrete, selectable options, recommended first, each stating what happens and its trade-offs. Never ask inside a response or bury a question in prose. Answer first in every reply: the first line is the result, answer or decision; then only the evidence the reader needs and what was skipped or unverified. No preamble, recap or routine status chatter: report only when done or when a decision is needed.

• **Subagents never ask the human.** Return the question with its options to your

orchestrator (`blocked` plus `{question, options[{label, description}], recommended}` in the manifest); the orchestrator asks via its ask tool.

• **No ask tool in the harness:** emit one LAFS `hitl.request` envelope

`{question, options[{label, description}], recommended}` and stop.

Project identity and moving between devices

A project is identified by its portable `project_id` in `.cleo/project.json` (tracked, id write-once, plus its name; ADR-096; legacy mirror `.cleo/project-id`). A path is only a per-device hint, so a moved or restored checkout keeps its identity. After a new device, restore or migration, or when a known repo reports "Not inside a CLEO project", registry paths are unreachable, or nexus hits `ENOENT` on an old path, run and report:

1. `cleo doctor projects` — machine-wide: moved, missing, split and temp rows with remedies. Dry-run by default; `--apply` rebinds only on nonce proof and writes a receipt; `--rollback <id>` restores. 2. `cleo doctor project-identity` — legacy, missing, conflicting or uncommitted id, name drift; `--resolve --dry-run` then `--resolve` is the only migration. 3. `cleo doctor --all-projects` — unreachable registered projects. 4. `cleo nexus projects clean --orphans --dry-run` — NEVER without `--dry-run`; it deletes rows for projects that merely moved. 5. `cleo doctor credentials` — credentials still keyed by an old path. 6. `cleo doctor global-delivery` — `~/.cleo`, the global hub reference and every harness CLEO skill install must resolve (a `~/.cleo` link carried by dotfiles from Linux dangles on macOS and silences all of them). `--repair` relinks with a receipt.

Guarded knowledge repair

Use `cleo doctor knowledge --dry-run` to inspect findings and sourced proposals. Persist reviewed JSON with `cleo doctor knowledge --prepare proposal.json --actor AGENT`. Discover retained jobs with `--jobs --actor AGENT`; continue with `--limit` and returned JSON `--cursor`. Follow each `inspectArgv`; never guess the latest job. Partial diagnostics remain unresolved, and job status alone does not verify current effects. For job operations, supply the original explicit actor and proposal ID: `cleo doctor knowledge --apply JOB --actor AGENT --proposal-id PROPOSAL`; replace `--apply` with `--inspect`, `--cancel`, or `--resume` for that operation. Inspection returns original receipts, separate rollback corrections, diagnostic failures, and a paged append-only ledger; use `--limit` and `--offset` until covered. Never copy a stored actor merely to bypass `E_REPAIR_ACTOR`.

Each invocation shares one two-second default budget across assessment, preparation, locks, application and verification (`--budget-ms` permits an explicit override). A later explicit apply/resume starts a new bounded attempt; it does not renew an expired attempt or bypass immutable resource checks. Synchronous SQLite is cooperative, not timer-preemptible. On failure, retain any `prepared` job and `attemptFailure` including pending finalization. Cancellation requests do not reverse committed effects. Resume retains failed/cancelled outcomes and uncertain expired-running history; live owners cannot be stolen and completed effects are not reapplied. After rollback, apply/resume reject with `E_REPAIR_ROLLED_BACK`; inspect `recoveryState` for the original historical receipt and separate rollback receipt.

Recover via `cleo doctor knowledge --rollback RECEIPT --actor AGENT --proposal-id NEW_ID`. Inspect both receipts. Versioned quarantine recovery restores only `invalid_at`, preserving validated paired citation-count/timestamp usage; protected edits conflict. Legacy receipts require exact images. Recovery records actual before/after images, not byte restoration of old usage. Prepared rollback still guards the full current image;