@cleocode/skills 2026.5.109 → 2026.5.111

package/package.json

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

package/skills/ct-cleo/SKILL.md

@@ -2,7 +2,7 @@
 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.1.0
+  version: 2.2.0
   lastReviewed: 2026-05-23
   stability: stable
 ---
@@ -163,3 +163,38 @@ input JSON — `cleo show <epicId>` acceptance criteria → tasks array → `cle
 
 - Saga/Epic workflow: `cleo briefing inject --section task-creation`
 - Single task: `cleo add --type task --parent <id> --acceptance "..." --title "..."`
+
+---
+
+## Worktree-Aware CLI Routing (T10389 / ADR-068 amendment §3.1)
+
+Two CLI verbs auto-route their writes back to the canonical project
+root when invoked from inside an agent-spawned worktree:
+
+- `cleo docs add <ownerId> <file> --type <kind> --slug <slug>` — the
+  blob lands in the MAIN repo's `tasks.db`. The file path is resolved
+  against the WORKTREE cwd (not the canonical root) before dispatch,
+  so relative paths like `docs/note.md` work as expected from inside
+  the worktree.
+- `cleo changeset add --slug <slug> --tasks <ids> --kind <kind> --summary <text>` —
+  dual-writes to `<canonical-root>/.changeset/<slug>.md` AND the SSoT
+  blob store. The `.changeset/` file lands in the MAIN repo, never
+  the worktree.
+
+Both verbs detect stray `.cleo/tasks.db` inside the worktree
+(pre-T9803 leak or rogue write) and emit `E_STRAY_WORKTREE_DB` with a
+clear `rm -rf <worktree>/.cleo` remediation BEFORE the deeper DB
+chokepoint guard fires.
+
+```bash
+# from ~/.local/share/cleo/worktrees/<hash>/T10389/
+cleo docs add T10389 ./investigation.md --type research --slug t10389-research
+# stderr: [T10389] routing SSoT write from worktree cwd ... → canonical project root ...
+# row lands in main repo's tasks.db, retrievable via `cleo docs fetch t10389-research`
+```
+
+If you see `E_PATH_TRAVERSAL`, `E_FILE_ERROR: Cannot read file`, or
+`E_WT_DB_ISOLATION_VIOLATION` when calling either verb, update to a
+build that ships the T10389 fix-pack (closes T10353 + T10354 + T10294
++ T10365). Suppress the routing log with `CLEO_QUIET=1` for clean
+stderr in automation.

package/skills/ct-docs-write/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: ct-docs-write
 description: This skill should be used when creating, editing, or reviewing documentation files (markdown, MDX, README, guides). Use when the user asks to "write docs", "create documentation", "edit the README", "improve doc clarity", "make docs more readable", "follow the style guide", or "write user-facing content". Applies CLEO's conversational, clear, and user-focused writing style.
-version: 1.0.0
+version: 1.1.0
 tier: 3
 core: false
 category: composition
@@ -148,6 +148,32 @@ Match complexity to audience. Mismatch is the biggest style failure.
 Declare the audience in frontmatter — `audience: end-user | agent | maintainer`
 — so reviewers can apply the right rubric.
 
+## Verb Selection — pick the right writer
+
+`packages/core/src/docs/writer-registry.ts` is the SSoT for "which CLI verb
+writes which DocKind". Every `BuiltinDocKind` maps to EXACTLY ONE writer —
+the registry rejects multi-writer regressions at build time (T10366 ·
+Saga T10288 / Epic T10290). The decision tree:
+
+```text
+if kind === 'changeset'  → cleo changeset add --slug <handle> --kind <bump> --summary "..."
+elif kind === 'llm-readme'    → tooling-composed (system-managed; do not author by hand)
+elif kind === 'release-note'  → cleo release reconcile (system-managed)
+else                          → cleo docs add <ownerId> <path> --type <kind> --slug <handle>
+```
+
+`cleo changeset add` is the dedicated dual-write verb for `changeset` —
+the kind's `canonicalHome` is `ssot-first` in `.cleo/canon.yml`, so the
+`.changeset/*.md` file IS part of the contract (it's git-tracked). For
+every other human-authored kind (`adr`, `spec`, `research`, `handoff`,
+`note`, `plan`, `rcasd`) the canonical verb is `cleo docs add --type <kind>`.
+
+**Migration rule for examples in this guide:** any example that
+hand-writes `.changeset/*.md`, `.cleo/adrs/*.md`, `.cleo/research/*.md`,
+or `.cleo/agent-outputs/*.md` is OBSOLETE. Update it to use the
+registered verb instead. The CI gate `cleo check canon docs` will fail
+the PR otherwise (T9796).
+
 ## Through SDK (preferred)
 
 CLEO docs are first-class records in the docs SSoT — not loose markdown files.

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. Coordinates ct-docs-lookup, ct-docs-write, ct-docs-review, 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.2.0
+version: 3.5.0
 tier: 3
 core: false
 category: specialist
@@ -92,7 +92,8 @@ cleo docs add T1234 docs/drafts/feature-x.md \
 - `--type` MUST be one of `spec | adr | research | handoff | note | llm-readme`.
   Pick the type by the document's purpose, not its filename.
 - `--slug` is the human-friendly retrieval handle (kebab-case). If taken the
-  CLI returns `E_SLUG_TAKEN` with 3 alternatives — pick one, do not overwrite.
+  CLI returns `E_SLUG_RESERVED` (legacy alias `E_SLUG_TAKEN`) with 3
+  alternatives — pick one, do not overwrite.
 - The owner ID (`T1234` above) auto-classifies the attachment by prefix:
   `T###` → task, `ses_*` → session, `O-*` → observation.
 
@@ -126,6 +127,193 @@ The accepted positional + named surface is enumerated in
 flag names. Use the `--flag=value` form (`--type=spec`) or
 `--flag value` (`--type spec`) — both are recognised.
 
+#### Slug allocation goes through ONE chokepoint (T10392 · Saga T10288)
+
+Every code path that writes an attachment with a slug — `cleo docs add`,
+`cleo changeset add`, and any future writer — MUST first call the central
+allocator at `packages/core/src/docs/slug-allocator.ts:reserveSlug` BEFORE
+invoking `attachmentStore.put({ slug })`. The allocator:
+
+1. Normalises the slug to canonical kebab-case (lowercase, trim, single
+   hyphens).
+2. Acquires a per-slug in-process Mutex so concurrent reservations
+   serialise.
+3. Returns `{ ok: false, code: 'E_SLUG_RESERVED', suggestions }` when the
+   slug is taken — uniform shape across both writers.
+
+The `attachmentStore.put` chokepoint enforces this via a runtime assert
+(`SlugNotReservedByAllocatorError`) when `CLEO_STRICT_SLUG_ALLOCATOR=1`
+is set. Strict mode becomes default once `cleo changeset add` (T10388)
+finishes wiring through the allocator. `cleo docs add` LIVE as of T10386:
+the dispatch layer (`packages/cleo/src/dispatch/domains/docs.ts:add`)
+calls `reserveSlug(type, slug)` BEFORE `attachmentStore.put`. Collisions
+surface the uniform envelope:
+
+```json
+{
+  "success": false,
+  "error": {
+    "code": "E_SLUG_RESERVED",
+    "message": "slug 'foo' is already in use in this project",
+    "details": {
+      "suggestions": ["foo-2", "foo-3", "foo-4"],
+      "aliases": ["E_SLUG_TAKEN"]
+    }
+  }
+}
+```
+
+`details.aliases` retains the legacy `E_SLUG_TAKEN` code for ONE release of
+back-compat — downstream consumers grepping for the old code can still match
+via the alias array. Removed after T-E1.3 (T10388) lands `cleo changeset add`
+on the same chokepoint.
+
+Slugs share a GLOBAL namespace across all DocKinds — `reserveSlug('changeset',
+'foo')` followed by `reserveSlug('research', 'foo')` collides. The decision
+is recorded in **ADR-076 §6 amendment AMD-001** (slug
+`adr-076-canonical-docs-ssot`, T10390 / E1.5). Three-point evidence (human-memorable
+global lookup, DocKind-distinct prefix conventions, backward-compat cost) and
+the full counterfactual analysis live in that amendment. Matches the
+`uniq_attachments_slug` partial UNIQUE INDEX in migration `20260519000001`.
+
+When choosing a slug, follow the DocKind prefix conventions in the routing
+matrix above (`adr-NNN-*`, `spec-*`, `research-*`, `t<id>-*` for changesets,
+etc.) — this is what makes cross-kind collisions structurally near-impossible.
+
+#### One writer per DocKind — WriterRegistry SSoT (T10366 · Saga T10288 / Epic T10290)
+
+`packages/core/src/docs/writer-registry.ts:WriterRegistry` is the SSoT for
+"which CLI verb writes which DocKind". Every `BuiltinDocKind` maps to EXACTLY
+ONE writer descriptor — multi-writer regressions trip the registry at build
+time (the slug-collision class root-cause from T10294).
+
+**Decision tree — pick the verb without guessing:**
+
+```text
+if kind === 'changeset'          → cleo changeset add
+elif kind === 'llm-readme'       → tooling-composed (system-managed)
+elif kind === 'release-note'     → cleo release reconcile (system-managed)
+else                              → cleo docs add --type <kind>
+```
+
+In code:
+
+```ts
+import { WriterRegistry } from '@cleocode/core/internal';
+
+const desc = WriterRegistry.for('changeset');
+// → { kind: 'changeset', verb: 'changeset add', dispatchOp: 'changeset.add',
+//     coreFn: 'writeChangesetEntry', mode: 'ssot-first',
+//     sourcePath: 'packages/core/src/changesets/writer.ts' }
+
+// Resolve the verb programmatically — no string-matching in caller code.
+const verb = WriterRegistry.for(kind).verb; // 'docs add' | 'changeset add' | 'system-managed'
+```
+
+Descriptor modes mirror `.cleo/canon.yml`'s `canonicalHome`:
+- `'ssot'` — bytes live in the blob store; published copy is a mirror.
+- `'ssot-first'` — dual-write via a dedicated verb (`changeset` today).
+- `'system-managed'` — tooling-composed (e.g. `llm-readme`, `release-note`).
+
+Test parity: every `ssot-first` descriptor MUST match a kind whose
+`canonicalHome: 'ssot-first'` in `.cleo/canon.yml`, and vice versa.
+
+**Legitimate bypass — `WriterRegistry.systemManaged` (T10368):** writers
+for `system-managed` kinds (e.g. `generateDocsLlmsTxt`, `composeReleaseNotes`)
+do not go through `cleo docs add` because the bytes are tooling-composed
+rather than human-authored. The registry still names the producer via
+`coreFn`, so drift tooling can follow the breadcrumb from kind →
+core function without an exception list. Do NOT invent NEW `system-managed`
+entries to dodge the docs-add path — every kind authored by a human MUST
+flow through `cleo docs add` or `cleo changeset add`.
+
+**Cross-link to the allocator contract:** the registry calls
+{@link reserveSlug} BEFORE the writer delegates. A taken slug returns
+`{ ok: false, code: 'E_SLUG_RESERVED', details: { suggestions } }`
+with the SAME shape both `cleo docs add` and `cleo changeset add` surface
+to callers (closing the T10294 envelope-drift bug). See the
+"Slug allocation goes through ONE chokepoint" section above for the
+allocator contract and the legacy `E_SLUG_TAKEN` alias.
+
+T10366 establishes the registry contract; T10367 (docs add) and T10368
+(changeset add) wire the actual writer delegation. Until those land,
+`WriterRegistry.write()` returns `E_NOT_IMPLEMENTED` after consulting the
+allocator — callers should continue invoking the existing writers
+(`cleo docs add` dispatch handler, `writeChangesetEntry`) directly.
+
+**T10367 LIVE — `cleo docs add --type changeset` delegates to
+`writeChangesetEntry`.** The dispatch handler in
+`packages/cleo/src/dispatch/domains/docs.ts` now branches on
+`payload.type === 'changeset'` and routes the call through the
+canonical dual-write transaction. This eliminates the second writer
+for the `changeset` DocKind (the SG-DOCS-INTEGRITY invariant) — the
+bytes that land on `.changeset/<slug>.md` AND the SSoT blob are
+byte-identical regardless of which verb the operator invoked. The
+`cleo changeset add` CLI remains the friendlier authoring surface
+(it prompts for every required frontmatter field) while
+`cleo docs add --type changeset --file <path>` works for agents that
+already have a fully-formed changeset markdown blob in hand.
+
+Contract for the docs-add path:
+- The input file MUST carry valid changeset frontmatter
+  (`id`, `tasks`, `kind`, `summary`). Missing → `E_REQUIRES_CHANGESET_VERB`
+  with a fix hint pointing at `cleo changeset add` for guided authoring.
+- When `--slug` is also passed it MUST match the frontmatter `id`
+  (the frontmatter is canonical) — divergence → `E_SLUG_MISMATCH`.
+- The LAFS envelope on success carries `data.type === 'changeset'`,
+  `data.slug`, `data.attachmentId`, and `data.sha256` — round-trip
+  identical to what `cleo changeset add` emits.
+
+### Slug similarity warn (T10361 · closes T10167)
+
+`cleo docs add` runs a fuzzy-match check against existing slugs for the
+SAME DocKind at write-time. If the proposed `--slug` is close to an
+existing one (default threshold: normalised Levenshtein score ≥ `0.85`,
+< `1.0`), the CLI surfaces "did you mean: `cleo docs update <slug>`?"
+so an agent does not fork a near-duplicate when an update is the
+intent. Exact (`1.0`) matches fall through to the slug-collision path
+(`E_SLUG_TAKEN`) — they are NOT covered by this check.
+
+```bash
+# Near-duplicate slug — warn mode is the project default.
+$ cleo docs add T123 file.md --slug cant-spec --type spec
+INFO Similar to 'cantspec' (score 0.89) — did you mean: cleo docs update cantspec? Pass --allow-similar to bypass.
+# (write proceeds because mode=warn)
+
+# Same input under `mode: block` (configured in .cleo/canon.yml) — exits 6.
+$ cleo docs add T123 file.md --slug cant-spec --type spec
+{
+  "success": false,
+  "error": {
+    "code": 6,
+    "codeName": "E_SLUG_SIMILARITY",
+    "message": "Similar to 'cantspec' (score 0.89) — did you mean: cleo docs update cantspec? Pass --allow-similar to bypass.",
+    "fix": "Use `cleo docs update cantspec` if updating, or pass --allow-similar to add as a new doc.",
+    "alternatives": [
+      { "action": "update 'cantspec' instead", "command": "cleo docs update cantspec" },
+      { "action": "bypass the similarity check", "command": "cleo docs add T123 file.md --slug cant-spec --type spec --allow-similar" }
+    ]
+  }
+}
+
+# Intentional add (true near-twin, not an update) — bypass + audit-log.
+$ cleo docs add T123 file.md --slug cant-spec --type spec --allow-similar
+# appends one JSONL line to .cleo/audit/similar-bypass.jsonl
+```
+
+Project-level overrides live in `.cleo/canon.yml`:
+
+```yaml
+similarity:
+  warnThreshold: 0.85   # 0..1 — score above this triggers the hint
+  mode: warn            # 'warn' (default) | 'block'
+```
+
+`mode: block` is recommended for CI agents — it surfaces the intent
+mismatch as an exit code rather than a silently-printed warning that
+non-TTY callers ignore. The `--allow-similar` flag is ALWAYS the
+escape hatch and ALWAYS logged.
+
 ### Publish to a git-tracked path (when the doc must live on disk)
 
 ```bash
@@ -168,6 +356,35 @@ retrieval becomes impossible. Migrate every doc-type write to
 
 ---
 
+## Worktree-Aware Routing (T10389 / ADR-068 amendment §3.1)
+
+When running from an agent-spawned worktree (e.g. under
+`~/.local/share/cleo/worktrees/<hash>/<task>/`), `cleo docs add` and
+`cleo changeset add` automatically route the SSoT write back to the
+canonical project root. The bytes land in the MAIN repo's SSoT — never
+inside the worktree.
+
+You can pass file paths relative to the worktree cwd as usual:
+
+```bash
+cd ~/.local/share/cleo/worktrees/<hash>/<task>/
+cleo docs add T10389 docs/note.md --slug t10389-investigation --type note
+# stderr: [T10389] routing SSoT write from worktree cwd <...> → canonical project root <...>
+```
+
+The verbs detect a stray `.cleo/tasks.db` inside the worktree
+(pre-T9803 leak or rogue write) and emit `E_STRAY_WORKTREE_DB` BEFORE
+invoking the DB chokepoint, so the user gets actionable remediation
+(`rm -rf <worktree>/.cleo`) instead of the deeper
+`E_WT_DB_ISOLATION_VIOLATION` exception.
+
+Suppress the routing log line with `CLEO_QUIET=1` if you need clean
+stderr in automation. The fix-pack closes T10353 + T10354 + T10294's
+3-guard collision class (`E_PATH_TRAVERSAL` + `E_FILE_ERROR` +
+`E_WT_DB_ISOLATION_VIOLATION`).
+
+---
+
 ## Core Principle: MAINTAIN, DON'T DUPLICATE
 
 ```

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.0.0
+version: 2.1.0
 tier: 2
 core: true
 category: core
@@ -106,6 +106,28 @@ Context injection for implementation tasks spawned via cleo-subagent. Provides d
 
 ---
 
+## Worktree-Aware CLI Routing (T10389 / ADR-068 amendment §3.1)
+
+When you operate inside an agent-spawned worktree (e.g. under
+`~/.local/share/cleo/worktrees/<hash>/<task>/`), `cleo docs add` and
+`cleo changeset add` automatically route their SSoT writes back to the
+canonical project root. You can pass file paths relative to the
+worktree cwd — the verb pre-resolves them against the worktree before
+dispatching to the canonical-root-anchored sanitizer.
+
+Both verbs detect a stray `.cleo/tasks.db` inside the worktree and
+abort with `E_STRAY_WORKTREE_DB` + a clear remediation
+(`rm -rf <worktree>/.cleo`). If you see `E_PATH_TRAVERSAL`,
+`E_FILE_ERROR: Cannot read file`, or `E_WT_DB_ISOLATION_VIOLATION`,
+update to a recent CLEO build that carries the fix-pack closing T10353
+/ T10354 / T10294 / T10365.
+
+The routing prints a one-line info message to stderr (suppress with
+`CLEO_QUIET=1`):
+`[T10389] routing SSoT write from worktree cwd <cwd> → canonical project root <root>`
+
+---
+
 ## Subagent Protocol
 
 @skills/_shared/subagent-protocol-base.md

package/skills.json

@@ -5,7 +5,7 @@
     {
       "name": "ct-cleo",
       "description": "CLEO task management protocol - core guidance for session, task, and workflow operations. Provides CLI-based workflow, session protocol, task discovery patterns, RCSD lifecycle overview, error handling, and the Human Render Contract (ADR-077). Load this skill for detailed CLEO protocol guidance.",
-      "version": "2.1.0",
+      "version": "2.2.0",
       "path": "skills/ct-cleo/SKILL.md",
       "references": ["skills/ct-cleo/references/session-protocol.md", "skills/ct-cleo/references/loom-lifecycle.md", "skills/ct-cleo/references/anti-patterns.md"],
       "core": true,
@@ -17,7 +17,7 @@
       "compatibility": ["claude-code", "gemini-cli", "codex-cli"],
       "license": "MIT",
       "metadata": {
-        "version": "2.1.0",
+        "version": "2.2.0",
         "lastReviewed": "2026-05-23",
         "stability": "stable"
       }
@@ -41,7 +41,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.",
-      "version": "2.0.0",
+      "version": "2.1.0",
       "path": "skills/ct-task-executor/SKILL.md",
       "references": [],
       "core": true,
@@ -137,7 +137,7 @@
     {
       "name": "ct-documentor",
       "description": "Documentation creation, editing, and review with CLEO style guide compliance. Coordinates specialized skills for lookup, writing, and review.",
-      "version": "3.0.0",
+      "version": "3.4.0",
       "path": "skills/ct-documentor/SKILL.md",
       "references": [],
       "core": false,
@@ -169,7 +169,7 @@
     {
       "name": "ct-docs-write",
       "description": "Documentation writing with CLEO's conversational, clear, user-focused style. Use when creating, editing, or improving documentation files.",
-      "version": "1.0.0",
+      "version": "1.1.0",
       "path": "skills/ct-docs-write/SKILL.md",
       "references": [],
       "core": false,