@cleocode/skills 2026.5.114 → 2026.5.120

package/package.json

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

package/skills/ct-cleo/SKILL.md

@@ -2,8 +2,8 @@
 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.2.0
-  lastReviewed: 2026-05-23
+  version: 2.3.0
+  lastReviewed: 2026-05-24
   stability: stable
 ---
 
@@ -198,3 +198,60 @@ If you see `E_PATH_TRAVERSAL`, `E_FILE_ERROR: Cannot read file`, or
 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.
+
+---
+
+## CLI Output Contract (ADR-086 / Epic T9927 / E9 of Saga T9855)
+
+`cleo` stdout is now **envelope-only**. NEVER pipe `cleo` output through
+`tail`/`jq`/`python` — every common shape has a first-class flag.
+
+| Need | Flag | Example |
+|------|------|---------|
+| Scalar extract (no jq) | `--field <jsonpointer>` | `cleo add 'X' --acceptance "..." --field /data/task/id` |
+| ID-only pipeline | `--output id` | `cleo list --parent EPIC --output id \| while read c; do …; done` |
+| Affected count | `--output count` | `cleo list --parent EPIC --status pending --output count` |
+| TSV (no header) | `--output table` | `cleo list --parent EPIC --output table` |
+| Silent (exit code only) | `--output silent` | `cleo update T123 --status done --output silent` |
+| 1-line per record | `--summary` | `cleo list --parent EPIC --summary` |
+| Suppress stderr noise | `--quiet` | `id=$(cleo add 'X' --acceptance "..." --quiet --field /data/task/id)` |
+| Full record (legacy) | `--full` | `cleo show T123 --full` |
+
+### Defaults
+
+- **Read ops** (`show`, `list`, `find`) — return the full LAFS envelope.
+- **Mutate ops** (`add`, `add-batch`, `update`, `complete`) — return a
+  minimal envelope `{success, data: {count, ids[]}}` (T9931). Use `--full`
+  to opt back into the full record set.
+- **stdout** carries exactly ONE LAFS envelope terminated by a single
+  newline. Sub-step logs/progress/warnings route through Pino → stderr.
+  This is regression-locked by CI gates `lint-stdout-discipline` (T10135)
+  and `lint-stdout-write-allowlist` (T9924).
+
+### Canonical agent patterns
+
+```bash
+# Scalar extract — no jq needed.
+id=$(cleo add 'Title' --type task --parent T9927 --acceptance "..." \
+       --field /data/task/id)
+
+# ID-only pipeline — no JSON parsing.
+cleo list --parent T9927 --output id | while read child; do
+  cleo verify "$child" --gate qaPassed --evidence "tool:lint;tool:typecheck"
+done
+
+# Count-only check.
+remaining=$(cleo list --parent T9927 --status pending --output count)
+
+# Fully clean pipeline — stdout has IDs, stderr is empty unless error.
+cleo add-batch --file /tmp/batch.json --parent T9927 --quiet --output id
+```
+
+### Anti-patterns (REJECTED — these are CLI bugs if they appear post-E9)
+
+- ❌ `cleo show T123 | tail -1 | jq -r .data.task.id` → use `--field /data/task/id`
+- ❌ `cleo list --parent E1 | jq -r '.data.tasks[].id'` → use `--output id`
+- ❌ `cleo show T123 | python3 -c 'import json,sys; …'` → use `--field`
+- ❌ `cleo add 'X' 2>&1 | grep -oE 'T[0-9]+'` → use `--field /data/task/id`
+
+Full contract + RFC 2119 invariants: `cleo docs fetch adr-086-cli-output-contract-e9`.

package/skills/ct-documentor/SKILL.md

@@ -1,13 +1,13 @@
 ---
 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.12.0
+version: 3.14.0
 tier: 3
 core: false
 category: specialist
 protocol: null
 metadata:
-  version: 3.12.0
+  version: 3.14.0
   lastReviewed: 2026-05-24
   stability: stable
 dependencies:
@@ -78,6 +78,51 @@ materializing through `cleo docs add` + (optionally) `cleo docs publish`.
 
 ---
 
+## Decision: update vs supersede vs create (T10168 · Saga T9855 / E12)
+
+Before adding a new doc, ALWAYS ask: is this **a new doc**, **a change to an existing doc**, or **a replacement for an existing doc**?
+
+```
+┌─────────────────────────────────────────────────────────────────────┐
+│  Question                              │ Verb                        │
+├─────────────────────────────────────────────────────────────────────┤
+│  Same idea, fixing/extending content?  │ cleo docs update <slug>     │
+│  → typo in ADR-076                     │   (T10161 — in-place patch) │
+│  → adding a clarifying paragraph       │                             │
+│  → refreshing a stale section          │                             │
+│                                                                       │
+│  Replacing the whole canonical model?  │ cleo docs supersede         │
+│  → "saga model v2" replaces v1         │   <old> <new> (T10162)      │
+│  → ADR-080 replaces ADR-073            │   (lifecycle flip + lineage)│
+│  → new architecture supplants old      │                             │
+│                                                                       │
+│  Genuinely new idea?                   │ cleo docs find --similar    │
+│  → drafting a new spec                 │   <slug> FIRST (T10163)     │
+│  → fresh ADR for a new concern         │   → if no hit, cleo docs add│
+│  → recording a new investigation       │   → if hit, route to update │
+│                                                                       │
+│  Tracing the lineage graph?            │ cleo docs graph             │
+│  → "what does this doc replace?"       │   --root <slug> (T10164)    │
+│  → "what tasks reference this ADR?"    │                             │
+└─────────────────────────────────────────────────────────────────────┘
+```
+
+### Examples
+
+- **"Fix a typo in ADR-076 saga-first-class"** → `cleo docs update adr-076-saga-first-class --body /tmp/fixed.md --message "fix typo in §2"`. NOT a new doc. NOT a supersession. Just patch in place; T10161 squashes patches within a 5-minute window so consecutive typo fixes don't bloat the audit log.
+
+- **"Replace the entire saga-orchestration model with v2"** → `cleo docs add T9999 v2.md --type adr --slug adr-080-saga-orchestration-v2` followed by `cleo docs supersede adr-073-above-epic-naming adr-080-saga-orchestration-v2 --reason "v2 canonicalizes the SG- prefix + 4-tier hierarchy"`. Both rows survive in the attachments table; readers see `lifecycle_status=superseded` on v1 and `supersedes=adr-073` on v2.
+
+- **"Drafting a new spec for the BRAIN recovery pipeline"** → FIRST run `cleo docs find --similar brain-recovery` (T10163). If similarity > 0.85 against an existing draft, ROUTE the request into `cleo docs update` instead — the existing draft is the canonical surface. If no near-match, proceed with `cleo docs add T#### draft.md --type spec --slug spec-brain-recovery-pipeline`.
+
+- **"Auditing the supersession chain for ADR-039"** → `cleo docs graph --root adr-039-lafs-envelope-unification --depth 3`. Returns a DocProvenanceGraph envelope (T10166 contract) with nodes + edges, optionally `--format dot` for graphviz visualization.
+
+### Anti-patterns (INSTANT REJECTION)
+
+- ❌ Calling `cleo docs add` with a slug that's only a typo-distance away from an existing doc — the auto-warn (T10167) fires `W_SLUG_SIMILAR`; respect it and route to `cleo docs update` instead of bypassing with `--allow-similar`.
+- ❌ Editing a `.cleo/adrs/*.md` file directly with `Write` — bypasses the SSoT writer; T10366 `WriterRegistry` is the chokepoint and the docs SSoT will reconcile auto-emit drift.
+- ❌ Creating a new doc when an existing one needs updating — bloats the attachments table and breaks lineage. The decision tree above resolves this — when in doubt, run `cleo docs find --similar <proposed-slug>` first.
+
 ## Through SDK (preferred)
 
 Documentation work flows through the docs SSoT in three steps —
@@ -147,11 +192,12 @@ invoking `attachmentStore.put({ slug })`. The allocator:
 
 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:
+is set. Strict mode becomes default in the next release after both
+writers are wired. **BOTH writers are LIVE on the allocator as of T10388**:
+`cleo docs add` (T10386 — `packages/cleo/src/dispatch/domains/docs.ts:add`)
+and `cleo changeset add` (T10388 — `packages/core/src/changesets/writer.ts:writeChangesetEntry`)
+both call `reserveSlug(kind, slug)` BEFORE any filesystem or DB mutation.
+Collisions surface the uniform envelope:
 
 ```json
 {
@@ -167,10 +213,10 @@ surface the uniform envelope:
 }
 ```
 
-`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.
+`details.aliases` retains the legacy `E_SLUG_TAKEN` (docs-add path) /
+`E_SSOT_WRITE_FAILED` (changeset-add path) codes for ONE release of
+back-compat — downstream consumers grepping for the old codes can still match
+via the alias array. Removed after E2 (T10290 — DocKind writer dedup) lands.
 
 Slugs share a GLOBAL namespace across all DocKinds — `reserveSlug('changeset',
 'foo')` followed by `reserveSlug('research', 'foo')` collides. The decision
@@ -484,6 +530,46 @@ observation pollutes the FTS index. Use `cleo memory backfill-docs` (AC4
 of T9976) only to repair attachments that pre-date the auto-emit feature
 or were written outside the SSoT.
 
+#### System-managed exemptions (T10368)
+
+Not every `.md` write inside `packages/core/src/**` is a DocKind authoring
+path. Release composers, RCASD migration tooling, nexus wiki generators, and
+the publish-mirror copier all emit Markdown bytes from inside `core/` but
+SHOULD NOT route through `WriterRegistry.write` — they are deterministic
+derived artifacts, not user-authored canonical documents.
+
+These legitimate bypasses live in `SYSTEM_MANAGED_ENTRIES` inside
+`writer-registry.ts`. Every entry cites an ADR pointer:
+
+```ts
+WriterRegistry.listSystemManaged();
+// → [
+//   { id: 'release.plan-json',          adrRef: 'ADR-028 ...' },
+//   { id: 'release.changelog',          adrRef: 'ADR-028 §2.5 ...' },
+//   { id: 'lifecycle.rcasd-migration',  adrRef: 'ADR-076 ...' },
+//   { id: 'lifecycle.stage-artifact',   adrRef: 'ADR-076 ...' },
+//   { id: 'sessions.handoff-markdown',  adrRef: 'ADR-076 ...' },
+//   { id: 'nexus.wiki-overview',        adrRef: 'ADR-076 ...' },
+//   { id: 'docs.publish-mirror',        adrRef: 'ADR-076 ...' },
+// ]
+
+// Path-based exemption lookup — used by the writer-audit test + T10369 lint:
+const hit = WriterRegistry.isSystemManaged('.cleo/release/v2026.5.103.plan.json');
+// → { id: 'release.plan-json', kind: null, adrRef: 'ADR-028 ...', ... }
+```
+
+When adding a NEW `.md` writer inside `packages/core/src/**`, you MUST
+either:
+
+1. Route through `WriterRegistry.write({kind, slug, payload})` (the
+   canonical path for DocKind authoring), OR
+2. Append a new entry to `SYSTEM_MANAGED_ENTRIES` with an ADR pointer
+   ratifying the bypass.
+
+The `writer-audit.test.ts` regression test fails when a new `.md` writer
+appears without either path. T10369 (next in the epic) promotes this from a
+unit test to a full CI lint gate.
+
 ### Slug similarity warn (T10361 · closes T10167)
 
 `cleo docs add` runs a fuzzy-match check against existing slugs for the

package/skills/ct-validator/SKILL.md

@@ -77,6 +77,62 @@ Governance: see **ADR-051** (programmatic gate integrity) which defines the evid
 
 ---
 
+## Blast-Radius Test Scope (MANDATORY · T9842)
+
+When acting as the IVTR Lead in the **Validate** phase (R2), the targeted test
+files named in the task spec are NOT sufficient evidence on their own when the
+Implement phase touched an infrastructure file. Targeted-only test review is
+how cross-package regressions slip past the Lead.
+
+### Precedent — T9814 R2
+
+T9814 swapped `BEGIN IMMEDIATE` for SAVEPOINTs in
+`packages/core/src/store/sqlite-data-accessor.ts` to support nested
+transactions for `add-batch`. Every targeted test passed (6/6 add-batch,
+34/34 add, 9/9 allocate). IVTR Lead R2 approved on the targeted scope. CI
+then surfaced `agent-resolver.test.ts preferTier` failing — the resolver
+depended on the outer `BEGIN IMMEDIATE` semantics that SAVEPOINTs do not
+replicate verbatim. Hotfix commit `baa996d2b` restored the outer-tx case.
+The Lead's targeted-only review missed a regression CI caught seconds later.
+
+### Rule
+
+If ANY file in the impl-phase evidence bundle's `filesChanged` matches a
+canonical infrastructure path, the Lead MUST run the full per-package vitest
+suite for every touched package — NOT the targeted files alone.
+
+### Canonical infrastructure paths
+
+- `packages/core/src/store/**` — DB chokepoint, transactions, migrations
+- `packages/core/src/orchestration/**` — spawn-prompt, dispatch resolution, IVTR
+- `packages/core/src/dispatch/**` and `packages/cleo/src/dispatch/**` — typed dispatch
+- `packages/contracts/src/**` — cross-package types (every consumer rebuilds)
+- `packages/worktree/src/**` — worktree-create / git-shim integration
+- `packages/core/src/migration/**` — schema bootstrapping
+- any path whose basename contains `transaction`, `pragma`, or `migration`
+
+### Required test commands per touched package
+
+```bash
+pnpm --filter @cleocode/<pkg> run test  # for each touched package
+```
+
+Attach the JSON output of each run as evidence
+(`cleo docs add --labels test-output`) and reference the sha256 set in the
+`--next` call. Approving on targeted-only results when infrastructure paths
+are touched is grounds for loop-back with reason `infra-test-scope-violation`.
+
+### Enforcement
+
+The IVTR Lead spawn prompt is auto-enriched by `resolvePhasePrompt()` in
+`packages/core/src/lifecycle/ivtr-loop.ts` — when an infrastructure touch is
+detected via `detectInfrastructureTouch()` (`packages/core/src/lifecycle/infra-touch.ts`),
+a `### Blast-Radius Test Scope — MANDATORY (T9842)` block is appended to
+the Validate-phase Lead prompt, listing the touched packages and the exact
+`pnpm --filter` commands the Lead must run.
+
+---
+
 ## Output Format
 
 ### Validation Report Structure

package/skills.json

@@ -4,8 +4,8 @@
   "skills": [
     {
       "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.2.0",
+      "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, the Human Render Contract (ADR-077), and the CLI Output Contract (ADR-086). Load this skill for detailed CLEO protocol guidance.",
+      "version": "2.3.0",
       "path": "skills/ct-cleo/SKILL.md",
       "references": [
         "skills/ct-cleo/references/session-protocol.md",
@@ -27,8 +27,8 @@
       ],
       "license": "MIT",
       "metadata": {
-        "version": "2.2.0",
-        "lastReviewed": "2026-05-23",
+        "version": "2.3.0",
+        "lastReviewed": "2026-05-24",
         "stability": "stable"
       }
     },