@cleocode/skills 2026.5.42 → 2026.5.45

package/package.json

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

package/skills/ct-lead/SKILL.md

@@ -0,0 +1,146 @@
+---
+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."
+---
+
+# Phase Lead Protocol (ct-lead)
+
+> **The Mantra**: *Aggregate, don't expose. Subscribe 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
+fan out, converge, roll up, and return a single contract string. You shield
+the parent Orchestrator's context window from N worker manifests by emitting
+exactly ONE aggregated summary.
+
+## Core Identity (IMMUTABLE)
+
+| ID | Constraint |
+|----|------------|
+| LEAD-001 | You are spawned with `role=orchestrator` but you are NOT the top-level Orchestrator — you have a parent Orchestrator and you MUST return to it |
+| LEAD-002 | You MUST NOT write or edit code — every line of code is written by leaf workers you spawn |
+| LEAD-003 | You MUST NOT recurse beyond one tier — children spawned by a Lead MUST have `role=leaf` (no Lead-of-Leads — escalate to parent Orchestrator instead) |
+| LEAD-004 | You MUST return EXACTLY ONE rolled-up contract string — never forward raw worker outputs upstream |
+
+## Operational Rules
+
+| 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-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 `delegation.max_concurrent_children` | Wave width MUST NOT exceed the configured cap (default 10); split into multiple waves if larger |
+| LEAD-008 | Convergence over polling | Wait on conduit signals + `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 |
+
+## Spawn Inputs (what the parent gives you)
+
+The parent Orchestrator spawns you with a resolved prompt containing:
+
+| Token | Meaning |
+|-------|---------|
+| `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 |
+| `maxConcurrent` | Effective `delegation.max_concurrent_children` |
+| `subagentTimeoutSeconds` | Default 600 — wall-clock budget per worker |
+
+## Workflow
+
+### 1. Pre-flight (subscribe before spawn)
+
+```bash
+# Subscribe FIRST — race-free (LEAD-005)
+cleo conduit subscribe "epic-${EPIC}.wave-${WAVE}" --as-lead
+
+# Verify the wave is well-formed
+cleo orchestrate ready --epic "${EPIC}" --wave "${WAVE}" --json
+```
+
+### 2. Parallel Fanout (one batch)
+
+Issue ONE `delegate_task` call with the full worker list. Each worker gets
+`role=leaf`. See `references/spawn-pattern.md` for 3 / 5 / 10 worker examples.
+
+```
+delegate_task({
+  parent: { taskId: "<leadTaskId>", role: "orchestrator" },
+  tasks: [
+    { taskId: "T9101", role: "leaf", subagent_type: "cleo-subagent", model: "sonnet" },
+    { 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)
+
+```bash
+# Block on conduit signals — fires on every worker terminal status
+cleo conduit await "epic-${EPIC}.wave-${WAVE}" \
+  --expect "${WORKER_COUNT}" \
+  --timeout 600
+
+# Roll up authoritative status from pipeline_manifest
+cleo lead rollup --epic "${EPIC}" --wave "${WAVE}" --json \
+  > /tmp/rollup-${EPIC}-${WAVE}.json
+```
+
+`rollupWaveStatus` (T9082, `packages/core/src/orchestration/lead-rollup.ts`)
+returns `{ wave, total, complete, partial, blocked, failed, workers: [...] }`.
+
+### 4. Decide: retry / escalate / return
+
+See `references/aggregation-protocol.md` for the full decision matrix.
+Summary:
+
+| Rollup Outcome | Action |
+|----------------|--------|
+| All `complete` | Append rollup manifest entry → return `complete` contract |
+| Partial (some failed, retriable) | Re-spawn ONLY failed workers locally (≤1 retry per worker) → re-converge |
+| Partial (non-retriable / repeated failures) | Append rollup → return `partial` contract — let parent decide |
+| Blocked (dep unsatisfied / HITL required) | Append rollup → return `blocked` contract |
+| Timeout (600s wall) | Cancel in-flight workers, append rollup with `timeout:true` → return `partial` |
+
+### 5. Manifest + Return
+
+```bash
+# ONE rollup entry per wave — the parent reads only this
+cleo manifest append \
+  --task "${LEAD_TASK_ID}" \
+  --type lead-rollup \
+  --content "Wave ${WAVE}: ${COMPLETE}/${TOTAL} complete, ${FAILED} failed. Workers: ${IDS}" \
+  --status "${OVERALL_STATUS}"
+
+# Return EXACTLY ONE of:
+#   "Lead rollup complete. Manifest appended to pipeline_manifest."
+#   "Lead rollup partial. Manifest appended to pipeline_manifest."
+#   "Lead rollup blocked. Manifest appended to pipeline_manifest."
+```
+
+## Pitfalls
+
+- **Late subscribe**: subscribing AFTER `delegate_task` race-loses early completers — always subscribe first (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**: do not `while true; sleep` on task status — use `cleo conduit await` (LEAD-008).
+- **Unbounded retries**: cap local retry at 1 per worker — repeated failure escalates to parent.
+
+## Cross-references
+
+- **ADR-070** (T9081): Hierarchical orchestration — Lead role definition
+- **rollupWaveStatus** (T9082): `packages/core/src/orchestration/lead-rollup.ts` — convergence aggregator
+- **ct-orchestrator**: parent-tier skill that spawns you with `role=orchestrator`
+- **pipeline_manifest** table: ADR-027 single source of truth for all handoffs
+
+## References
+
+| Topic | File |
+|-------|------|
+| Worker fanout examples (3 / 5 / 10) | `references/spawn-pattern.md` |
+| Conduit + manifest drain semantics, retry policy, escalation | `references/aggregation-protocol.md` |

package/skills/ct-lead/references/aggregation-protocol.md

@@ -0,0 +1,172 @@
+# Aggregation Protocol — Conduit + Manifest Drain Semantics
+
+The Phase Lead converges on wave completion via TWO complementary channels:
+
+1. **Conduit topic** (`epic-<TID>.wave-<n>`) — low-latency event stream
+   carrying terminal-status signals (`complete` / `partial` / `blocked` /
+   `failed` / `timeout`) from each worker as it returns.
+2. **pipeline_manifest** (SQLite, ADR-027) — durable source of truth for
+   each worker's structured output (key_findings, files, gates).
+
+Conduit drives **timing**; manifest drives **content**. `rollupWaveStatus`
+(T9082) reads BOTH and produces the authoritative wave verdict.
+
+---
+
+## 1. Subscription timing
+
+The Lead MUST subscribe to the conduit topic BEFORE issuing `delegate_task`.
+Subscription is idempotent and cheap; late subscription races against
+fast-finishing workers and silently loses early `complete` signals.
+
+```bash
+# CORRECT — subscribe, then spawn
+cleo conduit subscribe "epic-T9080.wave-2" --as-lead
+cleo orchestrate spawn-batch --tasks T9301,T9302,T9303 ...
+
+# WRONG — fanout, then subscribe (race window)
+cleo orchestrate spawn-batch --tasks T9301,T9302,T9303 ...
+cleo conduit subscribe "epic-T9080.wave-2" --as-lead   # may miss T9301 done
+```
+
+The conduit retains buffered signals for `conduit.replay_window` (default 30s)
+to defend against tiny races, but relying on the buffer is brittle.
+
+---
+
+## 2. Drain loop
+
+The Lead blocks on `cleo conduit await` which yields when the expected number
+of terminal signals arrive OR the wall-clock timeout elapses.
+
+```bash
+cleo conduit await "epic-T9080.wave-2" \
+  --expect 5 \
+  --timeout 600 \
+  --json > /tmp/conduit-drain.json
+
+# Then read authoritative state from manifest
+cleo lead rollup --epic T9080 --wave wave-2 --json > /tmp/rollup.json
+```
+
+`rollupWaveStatus` returns:
+
+```json
+{
+  "epicId": "T9080",
+  "waveId": "wave-2",
+  "total": 5,
+  "complete": 4,
+  "partial": 0,
+  "blocked": 0,
+  "failed": 1,
+  "timeout": false,
+  "workers": [
+    { "taskId": "T9301", "status": "complete", "manifestEntryId": "..." },
+    { "taskId": "T9305", "status": "failed",   "reason": "E_GATE_FAILED:qaPassed" }
+  ]
+}
+```
+
+---
+
+## 3. Retry policy on partial failures
+
+The Lead has a STRICT local retry budget: **at most 1 retry per worker**.
+Repeated failure escalates to the parent Orchestrator via a `partial`
+return contract — the Lead does NOT loop forever.
+
+| Failure class | Retry locally? | Rationale |
+|---------------|----------------|-----------|
+| `E_TIMEOUT` (worker hit 600s) | NO — return `partial` | Time pressure suggests scope problem; parent decides re-budget |
+| `E_GATE_FAILED:testsPassed` | YES (1×) | Often flaky — single retry is cheap |
+| `E_GATE_FAILED:qaPassed` | YES (1×) | Lint/format intermittents acceptable |
+| `E_GATE_FAILED:implemented` | NO — return `partial` | Substantive — needs spec review |
+| `E_DEP_UNSATISFIED` | NO — return `blocked` | Wave was mis-scheduled; parent re-plans |
+| `E_HITL_REQUIRED` | NO — return `blocked` | By definition outside autonomous scope |
+| `E_INFRASTRUCTURE` (DB lock, fs full) | YES (1×, after 5s backoff) | Transient |
+| Worker returned `blocked` | NO — propagate `blocked` | Worker self-identified human dependency |
+
+Local retry shape:
+
+```bash
+# After first drain, identify retriable failures
+RETRIABLE=$(jq -r '.workers[] | select(.status=="failed" and (.reason|test("testsPassed|qaPassed|INFRASTRUCTURE"))) | .taskId' /tmp/rollup.json)
+
+# Re-spawn ONLY those (NEW conduit topic suffix to avoid replay collision)
+cleo orchestrate spawn-batch \
+  --parent "${LEAD_TASK_ID}" --parent-role orchestrator \
+  --topic "epic-T9080.wave-2.retry-1" \
+  --tasks "$(echo $RETRIABLE | tr ' ' ,)" \
+  --child-role leaf --timeout 600
+
+# Re-drain on the retry topic, merge into final rollup
+cleo conduit await "epic-T9080.wave-2.retry-1" --expect $(echo $RETRIABLE | wc -w) --timeout 600
+cleo lead rollup --epic T9080 --wave wave-2 --include-retries --json > /tmp/rollup-final.json
+```
+
+After the single retry pass, whatever `rollup-final.json` shows IS the
+verdict — no second retry pass.
+
+---
+
+## 4. 600-second subagent timeout handling
+
+Every leaf worker is bounded by a 600s wall-clock timeout (configurable via
+`subagentTimeoutSeconds`). The Lead's drain timeout MUST be at least equal
+to the worker timeout — typically equal, since workers report terminally
+on timeout via the conduit.
+
+Behaviour matrix:
+
+| Worker outcome at 600s | Conduit signal | Manifest entry | Lead action |
+|------------------------|----------------|----------------|-------------|
+| Worker returned a contract string in time | `complete`/`partial`/`blocked` | Present, full | Aggregate normally |
+| Worker exited cleanly past 600s (race) | None | Present | `rollupWaveStatus` reconciles via manifest |
+| Worker hung; runtime killed it | `timeout` | Stub entry with `status:timeout` | Treat as `failed` non-retriable; return `partial` |
+| Network partition between worker and conduit | None | None | Drain times out; `rollup` flags `missing` workers; return `partial` |
+
+The Lead's own wall-clock budget should be `subagentTimeoutSeconds + 60s`
+of slack to allow the rollup query and manifest append to complete.
+
+---
+
+## 5. Escalation decision tree
+
+```
+rollupWaveStatus() →
+├── all complete       → manifest append → "Lead rollup complete..."
+├── any blocked        → manifest append → "Lead rollup blocked..."
+├── retriable failures → local retry (1×) → re-rollup → recurse this tree
+└── non-retriable      → manifest append → "Lead rollup partial..."
+```
+
+Escalate to parent Orchestrator (return `partial` or `blocked`) when:
+- ANY worker requires HITL input (architectural decision, scope expansion)
+- Same worker fails after the single local retry
+- Conduit drain times out with `missing` workers
+- A worker reports `E_DEP_UNSATISFIED` (wave was mis-planned)
+- Cumulative wave wall-clock exceeds `subagentTimeoutSeconds + 60s`
+
+Retry locally (do NOT escalate yet) when:
+- Failure is in `testsPassed` / `qaPassed` / `INFRASTRUCTURE` class
+- Retry budget (1×) for that worker is unspent
+- Lead's own wall-clock has > 300s remaining
+
+---
+
+## 6. Rollup manifest entry shape
+
+Exactly ONE rollup entry per wave per Lead invocation:
+
+```bash
+cleo manifest append \
+  --task "${LEAD_TASK_ID}" \
+  --type lead-rollup \
+  --content "Wave wave-2 of T9080: 4/5 complete, 1 failed (T9305 E_GATE_FAILED:implemented). Retried 0. Workers: T9301(c), T9302(c), T9303(c), T9304(c), T9305(f)." \
+  --status partial
+```
+
+The parent Orchestrator reads ONLY this entry's `key_findings` — never the
+underlying worker manifest entries. This is the context-budget invariant
+that makes hierarchical orchestration scalable (ADR-070).

package/skills/ct-lead/references/spawn-pattern.md

@@ -0,0 +1,132 @@
+# Spawn Pattern — Worker Fanout Examples
+
+The Phase Lead fans out all workers in a single `delegate_task` batch.
+Width is bounded by `delegation.max_concurrent_children` (default 10).
+Each child carries `role=leaf` and inherits the wave's conduit topic.
+
+All examples assume:
+- Lead's own task ID: `T9080-lead-w2`
+- Epic: `T9080`
+- Wave: `wave-2`
+- Conduit topic: `epic-T9080.wave-2`
+
+---
+
+## Example 1 — 3-worker fanout (small wave)
+
+Typical for narrowly-scoped IVTR waves where deps fan in tightly.
+
+```json
+{
+  "tool": "delegate_task",
+  "args": {
+    "parent": { "taskId": "T9080-lead-w2", "role": "orchestrator" },
+    "conduitTopic": "epic-T9080.wave-2",
+    "timeoutSeconds": 600,
+    "tasks": [
+      { "taskId": "T9101", "role": "leaf", "subagent_type": "cleo-subagent", "model": "sonnet" },
+      { "taskId": "T9102", "role": "leaf", "subagent_type": "cleo-subagent", "model": "sonnet" },
+      { "taskId": "T9103", "role": "leaf", "subagent_type": "cleo-subagent", "model": "sonnet" }
+    ]
+  }
+}
+```
+
+CLI equivalent (one shell call, NOT a loop):
+
+```bash
+cleo orchestrate spawn-batch \
+  --parent T9080-lead-w2 --parent-role orchestrator \
+  --topic epic-T9080.wave-2 \
+  --timeout 600 \
+  --tasks T9101,T9102,T9103 \
+  --child-role leaf --model sonnet
+```
+
+---
+
+## Example 2 — 5-worker fanout (medium wave)
+
+```json
+{
+  "tool": "delegate_task",
+  "args": {
+    "parent": { "taskId": "T9080-lead-w2", "role": "orchestrator" },
+    "conduitTopic": "epic-T9080.wave-2",
+    "timeoutSeconds": 600,
+    "tasks": [
+      { "taskId": "T9201", "role": "leaf", "subagent_type": "cleo-subagent", "model": "sonnet" },
+      { "taskId": "T9202", "role": "leaf", "subagent_type": "cleo-subagent", "model": "sonnet" },
+      { "taskId": "T9203", "role": "leaf", "subagent_type": "cleo-subagent", "model": "sonnet" },
+      { "taskId": "T9204", "role": "leaf", "subagent_type": "cleo-subagent", "model": "sonnet" },
+      { "taskId": "T9205", "role": "leaf", "subagent_type": "cleo-subagent", "model": "sonnet" }
+    ]
+  }
+}
+```
+
+---
+
+## Example 3 — 10-worker fanout (max-width wave)
+
+This is the upper bound at default `delegation.max_concurrent_children = 10`.
+For wider waves, the parent Orchestrator MUST split into multiple Leads.
+
+```json
+{
+  "tool": "delegate_task",
+  "args": {
+    "parent": { "taskId": "T9080-lead-w2", "role": "orchestrator" },
+    "conduitTopic": "epic-T9080.wave-2",
+    "timeoutSeconds": 600,
+    "tasks": [
+      { "taskId": "T9301", "role": "leaf", "subagent_type": "cleo-subagent", "model": "sonnet" },
+      { "taskId": "T9302", "role": "leaf", "subagent_type": "cleo-subagent", "model": "sonnet" },
+      { "taskId": "T9303", "role": "leaf", "subagent_type": "cleo-subagent", "model": "sonnet" },
+      { "taskId": "T9304", "role": "leaf", "subagent_type": "cleo-subagent", "model": "sonnet" },
+      { "taskId": "T9305", "role": "leaf", "subagent_type": "cleo-subagent", "model": "sonnet" },
+      { "taskId": "T9306", "role": "leaf", "subagent_type": "cleo-subagent", "model": "sonnet" },
+      { "taskId": "T9307", "role": "leaf", "subagent_type": "cleo-subagent", "model": "sonnet" },
+      { "taskId": "T9308", "role": "leaf", "subagent_type": "cleo-subagent", "model": "sonnet" },
+      { "taskId": "T9309", "role": "leaf", "subagent_type": "cleo-subagent", "model": "sonnet" },
+      { "taskId": "T9310", "role": "leaf", "subagent_type": "cleo-subagent", "model": "sonnet" }
+    ]
+  }
+}
+```
+
+---
+
+## Anti-patterns
+
+DO NOT issue per-worker calls in a loop:
+
+```bash
+# WRONG — sequentializes the wave, defeats parallelism (LEAD-006)
+for t in T9301 T9302 T9303 T9304 T9305; do
+  cleo orchestrate spawn "$t"   # serial, blocks the lead
+done
+```
+
+DO NOT exceed `maxConcurrent`:
+
+```bash
+# WRONG — runtime rejects with E_WAVE_OVERSIZED
+cleo orchestrate spawn-batch --tasks $(seq -s, T9301 T9320)   # 20 > 10
+```
+
+DO NOT spawn workers with `role=orchestrator`:
+
+```json
+// WRONG — would create a Lead-of-Leads recursion (LEAD-003)
+{ "taskId": "T9301", "role": "orchestrator" }
+```
+
+## Sizing guidance
+
+| Worker count | When to use | Notes |
+|--------------|-------------|-------|
+| 1–3 | Narrow waves; single-package changes | Minimal overhead, fast convergence |
+| 4–6 | Typical IVTR implementation waves | Sweet spot for sonnet workers |
+| 7–10 | Max-width parallel waves | Watch conduit signal volume; close to convergence-limit |
+| >10  | Split across multiple Leads | Top Orchestrator spawns N Leads, each ≤10 workers |