@cleocode/skills 2026.10.21 → 2026.10.22

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cleocode/skills",
-  "version": "2026.10.21",
+  "version": "2026.10.22",
   "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.24.16
+  version: 2.24.21
   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-17
+  lastReviewed: 2026-10-24
   stability: stable
 ---
 
@@ -234,7 +234,7 @@ This internal budget contract does not add a `--token-budget` flag to add/update
 |------|------------------|
 | `references/session-protocol.md` | start, resume or end sessions; pick skills |
 | `references/orchestrator-constraints.md` | spawn subagents from an orchestrator |
-| `references/loom-lifecycle.md` | move an epic through the LOOM stages |
+| `references/planning-loop.md` | plan an epic, run its waves, verify its tasks |
 | `references/anti-patterns.md` | check a plan against known mistakes |
 | `references/memory.md` | recall or record BRAIN memory (progressive disclosure) |
 | `references/sticky-notes.md` | capture a thought before it is a task: `cleo sticky jot "..."`, then `cleo sticky convert <id> --to-task` |

package/skills/ct-cleo/__tests__/injection-content.test.ts

@@ -7,7 +7,8 @@
  *
  * Checks:
  * - Contains `cleo memory observe` (not bare `cleo observe`)
- * - Contains `cleo orchestrate start` in Session Start section
+ * - Sends agents to no RCASD/IVTR verb (`cleo orchestrate start`,
+ *   `cleo lifecycle complete`, `cleo orchestrate ivtr`) (T13942)
  * - Contains "Memory Protocol (JIT)" H2 section
  * - Contains "Escalation" H2 section
  * - At least 6 distinct `cleo <verb>` command patterns
@@ -139,8 +140,10 @@ describe('CLEO-INJECTION.md — command correctness', () => {
     expect(bareObserveInstructions).toHaveLength(0);
   });
 
-  it('contains "cleo orchestrate start" in documentation', () => {
-    expect(injectionContent).toMatch(/cleo orchestrate start/);
+  it('sends agents to no RCASD or IVTR verb (T13942)', () => {
+    expect(injectionContent).not.toMatch(/cleo orchestrate start/);
+    expect(injectionContent).not.toMatch(/cleo lifecycle complete/);
+    expect(injectionContent).not.toMatch(/cleo orchestrate ivtr/);
   });
 
   it('contains "cleo session status" command', () => {

package/skills/ct-cleo/references/orchestrator-constraints.md

@@ -18,7 +18,6 @@
 ### CLI Spawn Operations
 
 ```bash
-cleo orchestrate start T001
 cleo orchestrate analyze T001
 cleo orchestrate ready T001
 cleo orchestrate next T001

package/skills/ct-cleo/references/planning-loop.md

@@ -0,0 +1,55 @@
+# Planning Loop: plan, execute, verify
+
+How CLEO work flows (T13958). RCASD stage records and the IVTR loop are retired
+from agent instructions (epic T13932). `pipeline_stage` is a label on tasks; it
+gates work only where a project turns on the stage gate (below).
+
+## 1. Plan
+
+- One plan document per epic, in the CleoDocs store:
+  `cleo docs add <epicId> ./<slug>-plan.md --type plan --slug <slug>-plan`.
+  Sections: findings, decision, spec (acceptance criteria), decomposition.
+- Decisions go to BRAIN:
+  `cleo memory decision-store --decision "..." --rationale "..." --linked-task <epicId>`.
+  Owner decisions go through the ask tool first.
+- Tasks: `cleo add --type task --parent <epicId> --acceptance "A|B"`, with
+  dependencies via `--depends`.
+- **Stage gate** (`lifecycle.stageGate`, off by default, T13970): when a project sets it
+  to `strict`, a child cannot complete (exit 80) while its parent epic sits in a planning
+  stage (research to decomposition), and the epic cannot advance once children sit at its
+  stage; `advisory` only warns. An epic inherits its saga's stage, or starts at research
+  when it has no parent. With the gate on, run `cleo update <epicId> --pipeline-stage
+  implementation` once the plan is written and BEFORE adding children; if children
+  already sit at its stage, report the epic to the lead or owner. The setting is their
+  choice: never change `lifecycle.stageGate` yourself. Evidence strictness stays on
+  `lifecycle.mode` either way.
+
+## 2. Execute
+
+- `cleo orchestrate waves <epicId>` for wave numbers, `cleo orchestrate ready <epicId>`
+  for what may run now, `cleo orchestrate spawn <taskId> --lead-mbx <you>` for each
+  worker prompt.
+- Agents coordinate over AgentMBX; task state and evidence stay in CLEO.
+- Autonomous runs go through CLEO Goal (ADR-097).
+
+## 3. Verify
+
+- `cleo done <id> --plan`, record each gate with `cleo verify <id> --gate <gate>
+  --evidence "<atoms>"`, then `cleo complete <id>`.
+- Each PR head gets an independent review before merge.
+
+## Spawn protocols are labels
+
+Spawn protocols (research, consensus, specification, decomposition,
+implementation, validation, testing, release, contribution) choose the spawn
+prompt's stage guidance. They are not gates.
+
+## When `cleo complete` refuses
+
+- Exit 80 with unproven evidence gates (the common case in strict mode): run
+  `cleo done <id> --plan`, record what it names, then complete.
+- Exit 80 naming a planning-stage parent epic: the project turned on
+  `lifecycle.stageGate`; advance the epic before children exist (above), otherwise
+  report it to the lead or owner, who decide on the setting.
+- Exit 83 (`E_IVTR_INCOMPLETE`): the task carries `ivtr_state` from the retired
+  IVTR loop, which no command clears; report it to the lead or owner.

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

@@ -1,6 +1,6 @@
 ---
 name: ct-codebase-mapper
-version: 2.2.1
+version: 2.3.5
 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.2.1
+  version: 2.3.5
   tier: on-demand
   install: harness
   covers:
     - packages/cleo/src/cli/commands/nexus.ts
     - packages/cleo/src/cli/commands/map.ts
-  lastReviewed: 2026-10-11
+  lastReviewed: 2026-10-24
   stability: stable
 ---
 
@@ -44,12 +44,26 @@ Two instruments, used together:
 cleo nexus status
 ```
 
-Read `nodeCount`, `lastIndexedAt` and `staleFileCount` against `fileCount`.
-Queries auto-refresh up to 25 stale files; beyond that they warn
-`W_NEXUS_INDEX_STALE`. Refresh with `cleo nexus analyze` (incremental; `--full`
+Read `nodeCount`, `lastIndexedAt` and `staleFileCount` against `fileCount`,
+and `freshness.commitsBehind` (commits on `freshness.baseRef` the index has
+not seen) with `freshness.ageDays`.
+Queries refresh a stale index inline when the last run's cost, scaled to the
+repository and the stale set, fits `nexus.autoRefresh.budgetMs`; otherwise they
+warn `W_NEXUS_INDEX_STALE`. `freshness.changedFilesSinceIndex` is a quick
+git-diff count of tracked files changed since the indexed revision. Refresh with `cleo nexus analyze` (incremental; `--full`
 rebuilds). An empty or stale index gives confident-looking but incomplete
 answers — say which you relied on.
 
+`registry` counts the registered projects by recorded health. When
+`registry.unreachable` is above zero, `registry.cleanCommand` is the dry run
+(`cleo nexus projects clean --orphans --dry-run`) that shows which rows are
+really gone; report it, and leave removal to the owner. `registry.otherHost`
+counts rows whose project lives on another machine sharing the store (a live
+location on another device); `projects clean` never removes those and lists
+them under `otherHost`. A legacy row with no location record is judged only by
+its path root, so a same-username path from another machine stays removable:
+read the dry run before removing.
+
 `assessment.referenceCount` is how many static references the graph could not
 resolve, so known callers are incomplete. Inspect them a page at a time:
 
@@ -77,6 +91,8 @@ cleo map --focus concerns     # one area: stack | architecture | structure |
                               #   conventions | testing | integrations | concerns
 cleo map --store              # same survey, findings stored to BRAIN
                               #   (tagged source: 'codebase-map')
+cleo map --brief              # one line per folder of exported names (nexus graph,
+                              #   else git-tracked walk), --budget N chars (default 2000)
 ```
 
 ## 3. Find the structure
@@ -102,11 +118,29 @@ 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.
 
-On a stale index, `impact` and `context` refresh it inline only when the last
-analysis recorded a cost that bounds the run; otherwise they answer from the
-stale index and say so. `--no-refresh` (or `CLEO_NEXUS_AUTO_REFRESH=false`)
+On a stale index, `impact` and `context` refresh it inline when the size-scaled
+cost estimate fits the budget: one refresh at a time per project, a larger one
+only when `cleo run` admits it, and none for 30 minutes after one fails or is
+aborted (`freshness.refreshCooldownUntil`; the next `cleo nexus analyze` ends
+the pause). An aborted refresh keeps its parse work for the next run. Otherwise
+they answer from the stale index and say so. `--no-refresh` (or `CLEO_NEXUS_AUTO_REFRESH=false`)
 always answers from the index as it stands.
 
+Every graph answer carries `data.freshness` (`indexedRevision`, `baseRef`,
+`commitsBehind` to the base branch, `commitsBehindHead`, `ageDays`). When the
+index is more than `nexus.freshness.maxCommitsBehind` (default 50) commits
+behind the checked-out HEAD, or the symbol is missing from an index that is
+stale for this checkout, the query fails with
+`E_NEXUS_INDEX_STALE` (exit 111) and `error.fix` names the reindex command. Run
+it, then repeat the query. `--allow-stale` (`impact`, `context`) or
+`CLEO_NEXUS_ALLOW_STALE=1` accepts the stale answer; say that you did.
+
+`cleo nexus reindex-on-merge --enable` opts a project into a background
+reindex after each merge into the base branch (the CLEO `post-merge` hook; it
+waits for idle `cleo run` admission and gives up after 300s). `cleo nexus
+status` shows the last real outcome as `reindexOnMerge` (ran, deferred or
+failed, with the reason); skips are not recorded.
+
 ## 5. Across projects: where each one lives, and its state
 
 ```bash

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.25
+version: 3.1.31
 protocol: contribution
 dependencies: []
 sharedResources:
@@ -14,7 +14,7 @@ compatibility:
   - gemini-cli
 license: MIT
 metadata:
-  version: 3.1.25
+  version: 3.1.31
   tier: core
   install: harness
   covers:
@@ -26,7 +26,7 @@ metadata:
     - packages/core/src/hooks.ts
     - packages/core/templates/git-hooks/**
     - packages/contracts/src/git-hooks.ts
-  lastReviewed: 2026-10-16
+  lastReviewed: 2026-10-24
   stability: stable
 ---
 
@@ -106,6 +106,10 @@ subject `initial: cleo init` (the empty commit `cleo init` makes so HEAD resolve
 only on a parentless first commit (T13582); a later commit with that subject, or any
 longer or different subject, still needs a task ID. A template change adds the
 previously shipped hash to `legacy-hashes.json` so installed copies refresh.
+
+`cleo init` and `cleo upgrade` no longer seed the CleoOS hub (Pi extensions, CANT
+workflows, justfile) into the global CLEO home (T13994, ADR-098); only the deprecated
+`cleo admin scaffold-hub` still does.
 It probes CLEO_PROJECT_HOOK_V1 before invoking the implemented CLI adapter;
 missing or incompatible runners warn and allow. `cleo hook run --probe -- execution`
 answers EXEC or INERT (older builds answer V1; stable builds before 2026.10.17 are
@@ -115,6 +119,15 @@ checkout whose activation is on (T13774). Verify nested checkout paths, linked
 worktrees, custom hook paths, historical release bodies and corrupt receipts
 with focused Git fixtures before changing this delivery path.
 
+The fourth managed hook, `post-merge` (T14010), never blocks. In shell, before
+starting anything, it requires the `cleo.nexusReindexOnMerge` git marker and
+HEAD on the base branch; otherwise it starts no process. When both hold it
+starts `cleo nexus reindex-on-merge` detached. That command runs one at a time
+per project (`.cleo/nexus-reindex.lock`) at the lowest admission priority: it
+never joins the `cleo run` queue, tries only when nothing is waiting, and
+records `deferred` after `nexus.reindexOnMerge.timeoutSeconds` (300). Turn it
+on or off with `cleo nexus reindex-on-merge --enable` / `--disable`.
+
 ---
 
 
@@ -191,7 +204,7 @@ fix/T456-token-validation          # Bug fix
 
 ## Gate System (Simplified)
 
-Not all gates apply to all changes. Follow the decision matrix.
+Not all gates apply to all changes. Follow the decision matrix. Required gates also follow the task's evidence kind (`verification.requiredGatesByKind`): research and documentation tasks owe the required gates without `testsPassed`/`qaPassed` until their work touches any non-document path, which restores the full code gates.
 
 ### G0: Pre-Flight Check
 
@@ -518,6 +531,11 @@ cleo complete T1550
 Provider delivery receives canonical SDK file reads and Git discovery through a contracts port.
 Adapters do not acquire a runtime dependency on core for these utilities.
 
+CLEO's own harness hooks are separate from project hooks: `cleo hook heavy-command`
+(PreToolUse), `cleo hook stop` (Stop; it runs ask-enforce) and, for Claude Code, `cleo hook session-end`
+(SessionEnd) and `cleo hook subagent-start` (SubagentStart, the ct-lean rules for Agent-tool subagents) are installed together by
+`cleo init`/`cleo upgrade` or `cleo doctor heavy-command-hook --fix`, and fail open.
+
 Project business rules live in tracked `.cleo/hooks.json`; generated provider entries
 are delivery outputs. hooks-v1 was promoted in v2026.10.17 and is released in source
 (T13776), so every build activates and runs project hooks. The release gate
@@ -542,18 +560,22 @@ provider records use bounded regular-file reads; FIFOs are rejected. Unsupported
 provider bindings remain unsupported in delivery summaries, including mixed bindings.
 
 The Stop event has ONE CLEO entry per provider, `cleo hook stop --provider claude-code|codex`
-(T13796), in order goal tick → ask-enforce → session end. The goal runtime goes first, only when
+(T13796), in order goal tick → ask-enforce. Stop fires at every turn end, so it NEVER ends the CLEO
+session (T13913): ending there deleted the terminal binding every turn. Claude Code's `SessionEnd`
+hook (`cleo hook session-end`, always installed) runs `cleo session end --quiet` detached, waited for
+at most 20 s; Codex has no session-end event, so its sessions end explicitly. The goal runtime goes first, only when
 `.opencode/goals/` exists (`CLEO_GOAL_TICK_COMMAND`, default `ocg tick`, Stop JSON on stdin,
 JSON-only stdout, at most 60 s, its process group SIGKILLed at the deadline): a block is
-re-serialised as exactly `{decision, reason}` (reason capped) and skips the rest. Next, an ask-enforce block (T13420) wins and keeps
-the session open, because the agent still owes the owner an ask. Otherwise Claude Code's runs
-`cleo session end --quiet` as before; Codex's never ends the session (its Stop fires every turn
-and never did). Every step fails open to the session end (missing, failing or timed-out tick;
+re-serialised as exactly `{decision, reason}` (reason capped) and skips the rest. Otherwise
+ask-enforce (T13420) answers. Every step fails open (missing, failing or timed-out tick;
 ask-enforce error); `CLEO_GOAL_TICK=off` skips the tick; `CLEO_ASK_ENFORCE=off` or heavy-command
 mode `off` (`CLEO_HEAVY_COMMAND_HOOK` / `resources.heavyCommandHook`, read at run time) skips the
 ask check, as they removed its separate hook before.
 Sync folds the separate ask-enforce and old session-end Stop entries into it in place; Codex's
-rides the heavy-command mode, Claude Code's always stays.
+rides the heavy-command mode, Claude Code's always stays. `cleo doctor heavy-command-hook`
+reports the hook `outdated` when the Stop, SessionEnd or SubagentStart entry is missing or was
+written by another build (a binary updated without a re-sync, T13960); `--fix` re-syncs them.
+`cleo self-update` re-syncs only the project it runs in.
 
 Init, upgrade and inspection share the commit-msg, pre-commit and pre-push installer.
 Git determines effective hooksPath and the common directory, including linked worktrees.

package/skills/ct-documentor/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: ct-documentor
 description: Documentation coordinator with CLEO style guide compliance. Routes every canonical-doc write (spec, adr, research, handoff, note, llm-readme) through the docs SSoT via `cleo docs add` / `cleo docs publish` / `cleo docs fetch` — never raw filesystem writes. Carries the CLEO writing and review guides as references and coordinates ct-spec-writer and ct-adr-recorder. Use when creating or updating documentation files, consolidating scattered documentation, or validating documentation against style standards. Triggers on documentation tasks, doc update requests, or style guide compliance checks.
-version: 3.25.4
+version: 3.26.0
 protocol: null
 dependencies:
   - ct-spec-writer
@@ -16,13 +16,13 @@ compatibility:
   - gemini-cli
 license: MIT
 metadata:
-  version: 3.25.4
+  version: 3.26.0
   tier: core
   install: harness
   covers:
     - packages/cleo/src/cli/commands/docs.ts
     - packages/contracts/src/docs-taxonomy.ts
-  lastReviewed: 2026-10-16
+  lastReviewed: 2026-10-23
   stability: stable
 ---
 
@@ -577,48 +577,31 @@ three invariants: stuck-saga closure (AC1), sibling-saga isolation
 another stuck docs-canon Saga so the recovery pattern stays under
 test.
 
-### Docs->memory auto-emit (T9976 · regression-tested by T10375)
-
-Every successful `cleo docs add` fires a fire-and-forget memory observation
-into `brain_observations`. The CLI never blocks on this write — a BRAIN
-failure cannot fail `docs add` — but the observation is the bridge that
-makes `cleo memory find '<slug>'` surface attached docs.
-
-**Title shape**: `"Doc attached: <slug>"` (or `"Doc attached: <attachmentId>"`
-when no slug is provided). This is what the FTS index matches on, so the
-slug is also a memory-discovery key — not just a docs-lookup key.
-
-**Narrative payload** (the {@link DocAttachmentObservationPayload} contract):
-
-```jsonc
-{
-  "kind": "doc-attachment",        // discriminator
-  "attachmentId": "<id>",          // assigned by the docs store
-  "ownerId": "<T#### | SG-#### | …>",
-  "slug": "<kebab-slug>",          // omitted only when --slug not passed
-  "type": "<docKind>",             // omitted only when --type not passed
-  "addedAt": "<ISO 8601 timestamp>"
-}
-```
-
-The payload is consumed by `cleo memory verify <observationId>` for
-round-trip checks against the docs store — see AC3 of the original T9976
-suite at `packages/cleo/src/dispatch/domains/__tests__/docs-memory-observation.test.ts`.
-
-**Retroactive sweeps**: when migrating manual `Write`-based docs back into
-the SSoT (the T10371 + T10373 pattern), the auto-emit fires uniformly for
-the kebab-case slugs the sweep uses (`t<num>-<kebab>`, `adr-<num>-<kebab>`).
-Regression coverage lives at
-`packages/cleo/src/dispatch/domains/__tests__/docs-memory-observation-retroactive.test.ts`
-(T10375). Add a new case to that table whenever you discover a slug shape
-not yet under test.
-
-**Anti-pattern**: do NOT write a `cleo memory observe` manually after a
-`cleo docs add` — the auto-emit already happened, and the duplicate
-observation pollutes the FTS index. No CLI command back-fills that
-observation for attachments that pre-date the auto-emit feature: the
-`memory backfill-docs` verb planned in T9976 AC4 never shipped. Leave such
-attachments as they are rather than hand-writing a duplicate observation.
+### Docs->BRAIN link (T13985 · owner decision D11180)
+
+Every successful `cleo docs add` links the document to its owner in the BRAIN
+graph as `llmtxt:<sha256> --documents--> <ownerType>:<ownerId>` (for example
+`task:T1234`). The `llmtxt:<sha256>` node carries the slug (or file name) as
+its label. The link is canonical, so it is written even when
+`brain.autoCapture` is off; the owner's `embeds` edge is automatic capture and
+follows that setting. The write runs in the docs projection after the
+attachment is stored, so a BRAIN failure never fails `docs add`.
+
+There is no "Doc attached" observation any more (T9976's auto-emit was retired
+by D11180): find a document through `cleo docs` (`list`, `find`, `fetch`), not
+`cleo memory find`. Legacy "Doc attached" rows still in a store are kept out
+of recall, and `cleo memory verify <observationId>` still round-trips one
+against the docs store.
+
+The internal `memory.backfill-docs` operation writes the missing `documents`
+edges for attachments that predate the link (idempotent). Regression coverage:
+`packages/cleo/src/dispatch/domains/__tests__/docs-memory-observation.test.ts`
+and `docs-memory-observation-retroactive.test.ts` (slug shapes from the
+T10371 + T10373 sweep).
+
+**Anti-pattern**: do NOT write a `cleo memory observe` after a
+`cleo docs add` to "register" the document: the documents edge already links
+it, and an observation only adds noise to recall.
 
 #### System-managed exemptions (T10368)
 

package/skills/ct-lead/SKILL.md

@@ -1,20 +1,20 @@
 ---
 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."
+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, read worker completion messages on AgentMBX 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.8
+  version: 1.1.3
   tier: core
   install: harness
   covers:
     - packages/core/src/orchestration/lead-rollup.ts
     - packages/core/src/orchestration/waves.ts
-  lastReviewed: 2026-09-30
+  lastReviewed: 2026-10-23
   stability: stable
 ---
 
 # Phase Lead Protocol (ct-lead)
 
-> **The Mantra**: *Aggregate, don't expose. Subscribe before spawn. Convergence over polling. Roll up in one contract.*
+> **The Mantra**: *Aggregate, don't expose. Name your mailbox before spawn. Convergence over polling. Roll up in one contract.*
 
 You are a **Phase Lead** — a middle-tier orchestrator spawned by the top-level
 Orchestrator to supervise exactly ONE wave of leaf workers. Your job is to
@@ -35,10 +35,10 @@ exactly ONE aggregated summary.
 
 | ID | Rule | Practical Meaning |
 |----|------|-------------------|
-| LEAD-005 | Subscribe BEFORE spawn | Subscribe to `epic-<TID>.wave-<n>` conduit topic before issuing any `delegate_task` — late subscribers miss early completion events |
+| LEAD-005 | Name your mailbox BEFORE spawn | Spawn each worker with `cleo orchestrate spawn <taskId> --lead-mbx <you>` so its prompt names your AgentMBX mailbox. Mailboxes keep messages, so a fast worker is never missed |
 | LEAD-006 | Parallel fanout | All workers in a wave fan out via a SINGLE `delegate_task` batch (`tasks: [...]`) — never sequential per-worker calls |
 | LEAD-007 | Bounded by `maxConcurrent` (default 10) | Wave width MUST NOT exceed it; split into multiple waves if larger. No config key or runtime check enforces this yet (`delegation.max_concurrent_children` is not read by CLEO) — the Lead enforces it |
-| LEAD-008 | Convergence over polling | Wait on conduit signals + `rollupWaveStatus`; do not poll task status in a busy loop |
+| LEAD-008 | Convergence over polling | Wait on AgentMBX completion messages + `rollupWaveStatus`; do not poll task status in a busy loop |
 | LEAD-009 | Roll up via `rollupWaveStatus` | Always call `rollupWaveStatus(epicId, waveId)` before returning — never hand-aggregate manifest rows |
 | LEAD-010 | One summary upstream | Return ONE contract string to parent Orchestrator; detail lives in pipeline_manifest under your wave's roll-up entry |
 | LEAD-011 | Honest reporting | Distinguish `complete` / `partial` / `blocked` in the return contract — partial completions MUST list unresolved worker tasks in the manifest entry |
@@ -52,18 +52,25 @@ The parent Orchestrator spawns you with a resolved prompt containing:
 | `epicId` | Parent epic (e.g., `T9080`) |
 | `waveId` | Wave index within the epic (e.g., `wave-2`) |
 | `workerTasks[]` | Pre-resolved leaf task IDs in this wave (deps already satisfied) |
-| `conduitTopic` | `epic-<epicId>.wave-<waveId>` — your subscription topic |
+| `mailbox` | Your AgentMBX name — workers send their completion message there |
 | `maxConcurrent` | Wave width cap passed by the parent (default 10) |
 | `subagentTimeoutSeconds` | Default 600 — wall-clock budget per worker |
 
 ## Workflow
 
-### 1. Pre-flight (subscribe before spawn)
+### 1. Pre-flight (name your mailbox before spawn)
 
-```bash
-# Subscribe FIRST — race-free (LEAD-005)
-cleo conduit subscribe --topic "epic-${EPIC}.wave-${WAVE}"
+Run `mbx_whoami` for your AgentMBX name; if it shows no identity, claim one
+with `mbx_identity` before any other mbx tool. Then build each worker's prompt
+with `cleo orchestrate spawn <taskId> --lead-mbx <you>` (LEAD-005): the
+prompt's Agent Coordination section names your mailbox. `cleo orchestrate
+fanout` does not carry the name yet (T13966); when you use it, put your
+mailbox in the task notes, where workers are told to look. Claude Code
+Agent-tool subagents share their parent's identity, so they return results
+directly instead of mailing them. Agent messages travel over AgentMBX, not
+CONDUIT (D11172).
 
+```bash
 # Verify the wave is well-formed: ready tasks and the computed wave plan
 cleo orchestrate ready "${EPIC}"
 cleo orchestrate waves "${EPIC}"
@@ -85,20 +92,20 @@ delegate_task({
     { taskId: "T9102", role: "leaf", subagent_type: "cleo-subagent", model: "sonnet" },
     /* ... up to maxConcurrent ... */
   ],
-  conduitTopic: "epic-T9080.wave-2",
   timeoutSeconds: 600
 })
 ```
 
-### 3. Convergence (drain conduit + manifest)
+### 3. Convergence (AgentMBX messages + manifest)
+
+Read worker completion messages with `mbx_inbox` / `mbx_read` (or
+`agentmbx inbox --as <you>` inside the provider session that holds the MCP
+lease) between waits, bounded by the wave budget; ack
+each one you acted on. Messages give timing; the manifest gives content.
 
 ```bash
 # WAVE = the wave number `cleo orchestrate waves` prints now (1-based);
-# topic and roll-up use the same number.
-
-# Read worker terminal signals on the wave topic. There is no blocking
-# await: poll with --since between checks, bounded by the wave budget.
-cleo conduit listen --topic "epic-${EPIC}.wave-${WAVE}" --since "${SPAWNED_AT}"
+# roll-up uses the same number.
 
 # Roll up authoritative status from pipeline_manifest
 cleo orchestrate roll-up "${EPIC}" --wave "${WAVE}" --json \
@@ -106,9 +113,8 @@ cleo orchestrate roll-up "${EPIC}" --wave "${WAVE}" --json \
 ```
 
 > **Wave contract (T12682).** One wave number `n` names everything: it is
-> the 1-based number `cleo orchestrate waves <epic>` prints, spawned workers
-> publish on `epic-<epicId>.wave-<n>`, and `cleo orchestrate roll-up <epic>
-> --wave <n>` takes the same `n` (`--wave 0` is refused with
+> the 1-based number `cleo orchestrate waves <epic>` prints, and `cleo
+> orchestrate roll-up <epic> --wave <n>` takes the same `n` (`--wave 0` is refused with
 > `E_CLEO_VALIDATION`, pointing at `cleo orchestrate waves`).
 >
 > **What a wave number guarantees (T12683).** A task's wave is its
@@ -121,8 +127,8 @@ cleo orchestrate roll-up "${EPIC}" --wave "${WAVE}" --json \
 >   finished waves without renumbering the rest.
 > - **Not stable** when a dependency edge is added or removed anywhere
 >   upstream, including in another epic: downstream waves shift. If you
->   subscribed ahead to `epic-<epicId>.wave-<n>`, re-read `cleo orchestrate
->   waves` after any dependency change.
+>   noted a wave number ahead of time, re-read `cleo orchestrate waves`
+>   after any dependency change.
 > - **Numbers can skip, and an epic's first wave can be above 1** (a task
 >   whose external prerequisite sits at depth 3 is in wave 4). Always take
 >   `n` from `cleo orchestrate waves`; never assume the first wave is 1.
@@ -140,6 +146,8 @@ cleo orchestrate roll-up "${EPIC}" --wave "${WAVE}" --json \
 
 `rollupWaveStatus` (T9082, `packages/core/src/orchestration/lead-rollup.ts`)
 returns `{ wave, total, complete, partial, blocked, failed, workers: [...] }`.
+Its `conduitMessages` option is deprecated (T13981): pass nothing and let the
+roll-up read the manifest; AgentMBX messages only tell you when to roll up.
 
 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
@@ -179,11 +187,11 @@ cleo manifest append \
 
 ## Pitfalls
 
-- **Late subscribe**: subscribing AFTER `delegate_task` race-loses early completers — always subscribe first (LEAD-005).
+- **Unnamed mailbox**: a worker that does not know your AgentMBX name cannot report to you — pass `--lead-mbx` on every spawn (LEAD-005).
 - **Sequential fanout**: spawning workers one-by-one defeats parallelism and breaks the wave model — use ONE batch (LEAD-006).
 - **Recursive Leads**: do NOT spawn a Lead from within a Lead — escalate to parent Orchestrator with a `blocked` contract instead (LEAD-003).
 - **Forwarding raw outputs**: never paste worker manifest entries upstream — parent's context budget assumes ONE rollup string per wave (LEAD-004).
-- **Polling task status**: do not `while true; sleep` on `cleo show` — read the wave topic with `cleo conduit listen --topic … --since …` and aggregate with `cleo orchestrate roll-up` (LEAD-008).
+- **Polling task status**: do not `while true; sleep` on `cleo show` — read your AgentMBX inbox and aggregate with `cleo orchestrate roll-up` (LEAD-008).
 - **Unbounded retries**: cap local retry at 1 per worker — repeated failure escalates to parent.
 
 ## Cross-references
@@ -198,4 +206,4 @@ cleo manifest append \
 | Topic | File |
 |-------|------|
 | Worker fanout examples (3 / 5 / 10) | `references/spawn-pattern.md` |
-| Conduit + manifest drain semantics, retry policy, escalation | `references/aggregation-protocol.md` |
+| AgentMBX + manifest drain semantics, retry policy, escalation | `references/aggregation-protocol.md` |