@cleocode/skills 2026.9.22 → 2026.9.24

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cleocode/skills",
-  "version": "2026.9.22",
+  "version": "2026.9.24",
   "description": "CLEO skill definitions - bundled with CLEO monorepo",
   "main": "index.js",
   "types": "index.d.ts",

package/skills/ct-cleo/SKILL.md

@@ -2,14 +2,14 @@
 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.22.2
+  version: 2.24.1
   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-09-28
+  lastReviewed: 2026-09-29
   stability: stable
 ---
 
@@ -48,8 +48,8 @@ send routine status chatter: report only when done or when a decision is needed.
 
 ## Project identity and moving between devices
 
-A project is identified by its portable `project_id` in `.cleo/project-id`
-(tracked, write-once; ADR-094). A path is only a per-device hint, so a moved or
+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:
@@ -57,7 +57,7 @@ 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` — missing, conflicting or uncommitted id.
+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.
@@ -143,7 +143,7 @@ stderr; `session status` / `briefing` label a guessed session `unbound: true`.
 
 ## Typed decisions (`cleo decide`, T12491)
 
-`decide` answers typed questions (yes/no, choice, score) through a swappable Jev-wire provider and falls back to local heuristics when unconfigured or failing. It needs two settings, an API URL and a key: `printf %s "$KEY" | cleo decide config --url <u> --key-stdin` (optional `--model`; `--clear` removes them). The key is kept in a 0600 file and never printed. `cleo decide status` probes reachability and `cleo decide ask --state <text> --noul <q>` runs one debug question.
+`decide` answers typed questions (yes/no, choice, score) through a swappable Jev-wire provider and falls back to local heuristics when unconfigured or failing. Pick a provider and supply its key: `printf %s "$KEY" | cleo decide config --provider layahost --key-stdin` (layahost, the default, needs only the key and uses model `laya-auto`); a custom endpoint is `--provider jev --url <u>`. `--model` overrides the model and `--clear` removes the settings. On a terminal, `cleo decide config` with no flags runs a setup wizard that reads the key hidden. The key is kept in a 0600 file and never printed. `cleo decide status` probes reachability and `cleo decide ask --state <text> --noul <q>` runs one debug question.
 
 ## Quick Reference
 
@@ -213,7 +213,7 @@ Dry-run creates no committed attestation; failed writes leave no committed recei
 
 Use `cleo show <id> --full` to inspect task fields before editing them. Compact
 records name every omitted field in `_withheld`, including empty or null values;
-the size is UTF-8 content bytes for strings and serialized JSON bytes otherwise.
+the size is UTF-8 content bytes for strings and serialized JSON bytes otherwise. A `list/*/field` key (`acRows/*/id`) names a field omitted from every element, summed.
 Repeated projection retains earlier omissions. A record without `_withheld` is
 complete at the record projection boundary; an envelope can separately report
 omitted records or fields. Never overwrite a field because a compact read omitted it.

package/skills/ct-codebase-mapper/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: ct-codebase-mapper
-version: 2.0.1
+version: 2.1.0
 description: Orient in an unfamiliar or large codebase with CLEO's code-intelligence graph (cleo nexus) and project map (cleo map). Use before planning or editing unfamiliar code, for brownfield onboarding, to find what a change would break, or to map a project's structure, communities and execution flows. Triggers on "map the codebase", "understand this project", "what calls X", "what would break", "brownfield analysis", "project structure".
 protocol: null
 dependencies: []
@@ -17,13 +17,13 @@ triggers:
   - project structure
   - blast radius
 metadata:
-  version: 2.0.1
+  version: 2.1.0
   tier: on-demand
   install: harness
   covers:
     - packages/cleo/src/cli/commands/nexus.ts
     - packages/cleo/src/cli/commands/map.ts
-  lastReviewed: 2026-09-28
+  lastReviewed: 2026-09-29
   stability: stable
 ---
 
@@ -83,6 +83,20 @@ caller, so an empty footprint alone never establishes that a change is safe.
 When a symbol name is ambiguous, pass the qualified candidate the command
 returns and confirm against the source.
 
+## 5. Across projects: where each one lives, and its state
+
+```bash
+cleo nexus projects status                    # every project, per device: path, branch, dirty, ahead/behind
+cleo nexus projects status --dirty --behind   # filters: --missing --dirty --behind --ahead --stale --errored
+cleo nexus projects status --device current   # one machine (device id, hostname or current)
+cleo nexus projects status --refresh          # re-probe this device first (bounded; --fetch also fetches)
+```
+
+The output lists counts first, then one page (`--limit`, `--offset`). It reads
+recorded probes. `ahead`/`behind` are as of `remote.fetchedAt`, and `stale`
+flags an old or missing probe or fetch. Read `matched` and `hasMore` before
+concluding "none".
+
 ## When to use
 
 | Situation | Start with |
@@ -92,6 +106,7 @@ returns and confirm against the source.
 | About to change a function or type | `cleo nexus impact <symbol>` |
 | "Who calls this / what does this call?" | `cleo nexus context <symbol>` |
 | Tech-debt review | `cleo map --focus concerns` |
+| "Which machines hold this project, and is it pushed?" | `cleo nexus projects status` |
 
 ## `cleo map` output
 

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

@@ -1,7 +1,7 @@
 ---
 name: ct-dev-workflow
 description: Development workflow orchestration for task-driven development with atomic commits, conventional commit messages, and systematic release processes. Enforces task traceability, branch discipline, smart test scope selection, and GitHub Actions integration. Use when committing code, creating releases, managing branches, or following contribution protocols. Triggers on commit operations, release preparation, or workflow compliance needs.
-version: 3.1.3
+version: 3.1.4
 protocol: contribution
 dependencies: []
 sharedResources:
@@ -14,12 +14,12 @@ compatibility:
   - gemini-cli
 license: MIT
 metadata:
-  version: 3.1.3
+  version: 3.1.4
   tier: core
   install: harness
   covers:
     - .github/workflows/release-prepare.yml
-  lastReviewed: 2026-09-28
+  lastReviewed: 2026-09-29
   stability: stable
 ---
 
@@ -276,6 +276,20 @@ git push origin HEAD
 # - Uploads artifacts
 ```
 
+**Release preflight (`release-prepare.yml`).** `cleo release open <version>`
+checks main's HEAD SHA and dispatches with `skip-tests=true` when the `ci.yml`
+push run for that SHA is green AND ran every Linux `Unit Tests` shard green (a
+docs-only push that skipped the tests does not count), and
+`skip-macos-tests=true` when the nightly macOS jobs for that SHA are green; the
+SHA travels as `verified-sha`, and the workflow ignores the skips if it checks
+out another commit or `verified-sha` is empty. Otherwise the 4
+Linux and 4 macOS test shards run. The decision is in the run summary.
+
+**Bump-PR merge.** Its `pull_request` runs stay `action_required` (no GitHub
+App), so the orchestrator admin-merges once the dispatched `CI` run on the PR
+head SHA is green: `gh pr merge <n> --admin --merge` — see
+`docs/release/merge-queue-runbook.md`.
+
 ---
 
 ## Quick Decision Matrix

package/skills/ct-lead/SKILL.md

@@ -2,13 +2,13 @@
 name: ct-lead
 description: "Phase Lead orchestration playbook for spawning and supervising a parallel worker swarm in one wave. Use when spawned by ct-orchestrator with role=orchestrator to fan out N leaf workers via delegate_task, drain the epic-{TID}.wave-{n} conduit topic plus pipeline_manifest, await rollupWaveStatus convergence, and return ONE rolled-up contract string to the parent Orchestrator. Triggers: 'phase lead', 'wave lead', 'supervise wave', 'fan out workers', 'aggregate worker results', 'rollup wave', any task with role=orchestrator that is itself a child of another orchestrator. Implements ADR-070 hierarchical orchestration."
 metadata:
-  version: 1.0.5
+  version: 1.0.7
   tier: core
   install: harness
   covers:
     - packages/core/src/orchestration/lead-rollup.ts
     - packages/core/src/orchestration/waves.ts
-  lastReviewed: 2026-09-28
+  lastReviewed: 2026-09-29
   stability: stable
 ---
 
@@ -126,10 +126,25 @@ cleo orchestrate roll-up "${EPIC}" --wave "${WAVE}" --json \
 >
 > `orchestrate ready`, `plan` and `parallel start --wave <n>` never re-run
 > finished tasks.
+>
+> **Order within a wave (T12692).** Members of a wave, the `orchestrate
+> ready` list and the focus ready wave are in the SAME order as `cleo next`
+> (D11161): priority band, then attested severity (unset is unknown and never
+> outranks an attested P1 of the same band), then a bounded tiebreak (deps,
+> phase, leverage, age), then `createdAt`, then id. Spawn in that order when
+> the wave is wider than `maxConcurrent`. Only the order moves; the wave
+> number is still structural depth.
 
 `rollupWaveStatus` (T9082, `packages/core/src/orchestration/lead-rollup.ts`)
 returns `{ wave, total, complete, partial, blocked, failed, workers: [...] }`.
 
+A stored manifest row with malformed metadata no longer fails the roll-up
+(T12686): it is skipped, every other worker is still reported, and a
+`W_MANIFEST_ROW_MALFORMED` warning names the row, the bad field and the
+repair. Treat that warning as missing coverage, not a clean wave: run
+`cleo doctor manifest-rows` to list such rows, `--repair` to see the plan,
+and `--repair --apply` to rewrite them with a receipt.
+
 ### 4. Decide: retry / escalate / return
 
 See `references/aggregation-protocol.md` for the full decision matrix.

package/skills/ct-orchestrator/SKILL.md

@@ -2,13 +2,13 @@
 name: ct-orchestrator
 description: "Pipeline-aware orchestration skill for managing complex workflows through subagent delegation. Use when the user asks to \"orchestrate\", \"orchestrator mode\", \"run as orchestrator\", \"delegate to subagents\", \"coordinate agents\", \"spawn subagents\", \"multi-agent workflow\", \"context-protected workflow\", \"agent farm\", \"HITL orchestration\", \"pipeline management\", or needs to manage complex workflows by delegating work to subagents while protecting the main context window. Enforces ORC-001 through ORC-009 constraints. Provider-neutral — works with any AI agent runtime."
 metadata:
-  version: 4.0.4
+  version: 4.0.5
   tier: core
   install: harness
   covers:
     - packages/cleo/src/cli/commands/orchestrate.ts
     - packages/core/src/orchestration/spawn-prompt.ts
-  lastReviewed: 2026-09-28
+  lastReviewed: 2026-09-29
   stability: stable
 ---
 
@@ -160,6 +160,16 @@ Agent({
 })
 ```
 
+**Task claims (T12502)**: spawn gives the task's claim lease to the worker's own
+session and records your session as its spawner (`spawnedBySessionId`, written
+only by the spawn — a self-declared `CLEO_PARENT_SESSION_ID` does not count), so
+the lease moves between you and your worker without an override. A task another session holds refuses the
+spawn with `E_TASK_CLAIMED`; a failed spawn hands the lease back to you. The
+prompt tells the worker to begin every Bash call with
+`cd <worktree> && export CLEO_SESSION_ID=… CLEO_AGENT_ID=… CLEO_AGENT_ROLE=… || exit 1`,
+since harness shells keep neither cwd nor env between calls (the git shim reads
+`CLEO_AGENT_ROLE`). Do not strip that line.
+
 **Other harnesses**: Pass the resolved prompt to whatever "give this prompt to an agent" mechanism the runtime provides. Results flow back through pipeline_manifest (via `cleo manifest append`) — the universal handoff medium.
 
 ### Valid Return Messages

package/skills/ct-task-executor/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: ct-task-executor
 description: General implementation task execution for completing assigned CLEO tasks by following instructions and producing concrete deliverables. Handles coding, configuration, documentation work with quality verification against acceptance criteria and progress reporting. Use when executing implementation tasks, completing assigned work, or producing task deliverables. Triggers on implementation tasks, general execution needs, or task completion work.
-version: 2.7.3
+version: 2.7.5
 protocol: implementation
 adrRefs:
   - ADR-070
@@ -17,16 +17,18 @@ compatibility:
   - gemini-cli
 license: MIT
 metadata:
-  version: 2.7.3
+  version: 2.7.5
   tier: core
   install: harness
   covers:
     - packages/cleo/src/cli/commands/verify.ts
     - packages/cleo/src/cli/commands/complete.ts
+    - packages/cleo/src/cli/commands/start.ts
+    - packages/cleo/src/cli/commands/claim.ts
     - packages/core/src/validation/protocols/cant/implementation.cant
     - packages/core/src/validation/protocols/protocols-markdown/implementation.md
   loomStage: implementation
-  lastReviewed: 2026-09-28
+  lastReviewed: 2026-09-29
   stability: stable
 ---
 
@@ -281,6 +283,41 @@ If deliverables don't pass acceptance criteria:
 4. Complete task only if failure is documented and understood
 5. Return appropriate status message
 
+### Concurrent Edits (`E_CONFLICT`, exit 23)
+
+Another agent may edit the same task while you work. `cleo update` and
+`cleo complete` refuse a write based on a stale read with `E_CONFLICT`; nothing
+was written. `error.details` carries `currentVersion`, `changedFields`,
+per-field `changes` (`was`/`now`) and the stored `current` values. Re-read the
+task, merge your change onto it, then retry. To guard a write explicitly, pass
+the version you read:
+
+```bash
+cleo show T1234 --field /data/task/updatedAt   # the version you read
+cleo update T1234 --title "New title" --if-match <updatedAt>
+cleo complete T1234 --if-match <updatedAt>
+```
+
+`--add-labels`, `--add-depends` and `--add-files` merge with concurrent writers and never need a retry.
+
+### Claimed Tasks (`E_TASK_CLAIMED`, exit 35)
+
+`cleo start` (and spawn) takes your session's time-limited claim lease on the
+task. If another session holds it, the start is refused with `E_TASK_CLAIMED`
+and nothing is written; `error.details` names the `holder` (session, agent,
+`leaseExpiresAt`), whether the lease has `expired`, and the `override` flag.
+Your mutations renew your leases; `cleo stop`, `cleo complete` and ending your
+session release them. The human `assignee` is a separate field.
+
+```bash
+cleo claim T1234 --renew        # extend your lease during a long step
+cleo start T1234 --take-over    # holder's lease EXPIRED (audited)
+cleo start T1234 --force-claim  # holder is LIVE: only with a clear reason (audited)
+```
+
+Never force a live claim to get unblocked: pick another task (`cleo next`) or
+report the conflict to your orchestrator.
+
 ---
 
 ## Session Management

package/skills/manifest.json

@@ -226,7 +226,7 @@
     },
     {
       "name": "ct-cleo",
-      "version": "2.22.2",
+      "version": "2.24.1",
       "description": "CLEO task management protocol - session, task, and workflow guidance. Use when managing tasks, sessions, or multi-agent workflows with the CLEO CLI protocol.",
       "path": "skills/ct-cleo",
       "tier": 0,
@@ -302,7 +302,7 @@
     },
     {
       "name": "ct-codebase-mapper",
-      "version": "2.0.1",
+      "version": "2.1.0",
       "description": "Orient in an unfamiliar or large codebase with CLEO's code-intelligence graph (cleo nexus) and project map (cleo map). Use before planning or editing unfamiliar code, for brownfield onboarding, to find what a change would break, or to map a project's structure, communities and execution flows. Triggers on \"map the codebase\", \"understand this project\", \"what calls X\", \"what would break\", \"brownfield analysis\", \"project structure\".",
       "path": "skills/ct-codebase-mapper",
       "tier": 1,
@@ -566,7 +566,7 @@
     },
     {
       "name": "ct-dev-workflow",
-      "version": "3.1.3",
+      "version": "3.1.4",
       "description": "Development workflow orchestration for task-driven development with atomic commits, conventional commit messages, and systematic release processes. Enforces task traceability, branch discipline, smart test scope selection, and GitHub Actions integration. Use when committing code, creating releases, managing branches, or following contribution protocols. Triggers on commit operations, release preparation, or workflow compliance needs.",
       "path": "skills/ct-dev-workflow",
       "tier": 0,
@@ -965,7 +965,7 @@
     },
     {
       "name": "ct-lead",
-      "version": "1.0.5",
+      "version": "1.0.7",
       "description": "Phase Lead orchestration playbook for spawning and supervising a parallel worker swarm in one wave. Use when spawned by ct-orchestrator with role=orchestrator to fan out N leaf workers via delegate_task, drain the epic-{TID}.wave-{n} conduit topic plus pipeline_manifest, await rollupWaveStatus convergence, and return ONE rolled-up contract string to the parent Orchestrator. Triggers: 'phase lead', 'wave lead', 'supervise wave', 'fan out workers', 'aggregate worker results', 'rollup wave', any task with role=orchestrator that is itself a child of another orchestrator. Implements ADR-070 hierarchical orchestration.",
       "path": "skills/ct-lead",
       "tier": 0,
@@ -983,7 +983,7 @@
     },
     {
       "name": "ct-orchestrator",
-      "version": "4.0.4",
+      "version": "4.0.5",
       "description": "Pipeline-aware orchestration skill for managing complex workflows through subagent delegation. Use when the user asks to \\\"orchestrate\\\", \\\"orchestrator mode\\\", \\\"run as orchestrator\\\", \\\"delegate to subagents\\\", \\\"coordinate agents\\\", \\\"spawn subagents\\\", \\\"multi-agent workflow\\\", \\\"context-protected workflow\\\", \\\"agent farm\\\", \\\"HITL orchestration\\\", \\\"pipeline management\\\", or needs to manage complex workflows by delegating work to subagents while protecting the main context window. Enforces ORC-001 through ORC-009 constraints. Provider-neutral — works with any AI agent runtime.",
       "path": "skills/ct-orchestrator",
       "tier": 0,
@@ -1472,7 +1472,7 @@
     },
     {
       "name": "ct-task-executor",
-      "version": "2.7.3",
+      "version": "2.7.5",
       "description": "General implementation task execution for completing assigned CLEO tasks by following instructions and producing concrete deliverables. Handles coding, configuration, documentation work with quality verification against acceptance criteria and progress reporting. Use when executing implementation tasks, completing assigned work, or producing task deliverables. Triggers on implementation tasks, general execution needs, or task completion work.",
       "path": "skills/ct-task-executor",
       "tier": 0,