@cleocode/skills 2026.9.20 → 2026.9.22

package/skills/ct-orchestrator/references/orchestrator-recovery.md

@@ -18,11 +18,8 @@
 ## Context Budget Monitoring
 
 ```bash
-# Check current context usage
-cleo orchestrate context
-
-# With specific token count
-cleo orchestrate context --tokens 5000
+# Check context usage for an epic
+cleo orchestrate context T1575
 ```
 
 **Status Thresholds**:
@@ -54,15 +51,14 @@ Orchestrator sessions may span multiple Claude conversations. This is expected a
 ### Cleanup Commands
 
 ```bash
-# Standard garbage collection (ended/suspended sessions only)
+# Standard garbage collection
 cleo session gc
 
-# Include stale active sessions (>7 days old by default)
-cleo session gc --include-active
+# Also end active sessions older than N days
+cleo session gc --max-age 7
 
-# Preview what would be cleaned
-cleo session gc --dry-run
-cleo session gc --include-active --dry-run
+# There is no dry-run; inspect first
+cleo session list --status active
 ```
 
 ### Configuration
@@ -84,12 +80,12 @@ cleo config set retention.autoEndActiveAfterDays 14  # Extend to 2 weeks
 
 2. **Session suspend for long waits**: Suspend when blocked on external factors
    ```bash
-   cleo session suspend --note "Awaiting code review"
+   cleo session suspend <sessionId> --reason "Awaiting code review"
    ```
 
 3. **Periodic cleanup**: Run garbage collection periodically to remove stale sessions
    ```bash
-   cleo session gc --include-active
+   cleo session gc --max-age 7
    ```
 
 4. **Multi-day work**: No need to restart sessions daily - orchestrator sessions are designed for extended work periods
@@ -99,15 +95,9 @@ cleo config set retention.autoEndActiveAfterDays 14  # Extend to 2 weeks
 ## Validation
 
 ```bash
-# Full protocol validation
-cleo orchestrate validate
-
-# Validate for specific epic
-cleo orchestrate validate --epic T1575
-
-# Validate specific subagent output
-cleo orchestrate validate --subagent research-id-2026-01-18
+# Validate one task's subagent output
+cleo orchestrate validate T1586
 
-# Manifest only
-cleo orchestrate validate --manifest
+# Validate a specific output file, and that a manifest entry was appended
+cleo orchestrate validate T1586 --file <output-path> --manifest
 ```

package/skills/ct-orchestrator/references/orchestrator-spawning.md

@@ -11,14 +11,13 @@ Spawning is ALWAYS a two-step process: CLEO **prepares** the prompt, then the pr
 
 ```bash
 # Get next dependency-safe task
-cleo orchestrate next --epic T1575
+cleo orchestrate next T1575
 
 # Generate fully-resolved spawn prompt
 cleo orchestrate spawn T1586
 
-# Or specify a skill template
-cleo orchestrate spawn T1586 --template ct-research-agent
-cleo orchestrate spawn T1586 --template RESEARCH-AGENT  # aliases work
+# Or override the protocol (the skill follows from it)
+cleo orchestrate spawn T1586 --protocol research
 ```
 
 The `spawn` command returns:
@@ -110,7 +109,7 @@ skills/ct-documentor/SKILL.md
 
 ```bash
 # Step 1: Get ready task
-cleo orchestrate next --epic T1575
+cleo orchestrate next T1575
 # Returns: { nextTask: { id: "T1586", title: "...", priority: "high" } }
 
 # Step 2: Generate spawn prompt (handles all token injection)
@@ -148,7 +147,7 @@ The function performs these steps automatically:
 
 | Step | Action | Details |
 |------|--------|---------|
-| 1 | Read task from CLEO | `cleo show T1234 --format json` |
+| 1 | Read task from CLEO | `cleo show T1234` |
 | 2 | Select skill | Auto-dispatch from task type/labels or use override |
 | 3 | Validate skill | Check compatibility with target model |
 | 4 | Inject protocol | Load skill template + subagent protocol |
@@ -161,7 +160,7 @@ The function performs these steps automatically:
 Step 6 validates that the generated prompt contains the `SUBAGENT PROTOCOL` marker. This is **mandatory** and will fail loudly if missing:
 
 - **Exit code**: `EXIT_PROTOCOL_MISSING` (60)
-- **Fix command**: `cleo research inject`
+- **Fix command**: `cleo orchestrate spawn <taskId>` (regenerates the prompt with the protocol embedded)
 - **Validation function**: `orchestrator_verify_protocol_injection()`
 
 If validation fails, the spawn is **blocked** and you must fix the skill template or manually inject the protocol block.
@@ -266,7 +265,7 @@ ti_set_context "T1234" "$(date +%Y-%m-%d)" "auth-implementation"
 
 # Set defaults and get task context
 ti_set_defaults
-task_json=$(cleo show T1234 --format json)
+task_json=$(cleo show T1234)
 ti_set_task_context "$task_json"
 ```
 
@@ -290,6 +289,6 @@ Use Task tool with:
 # Check manifest for completion
 {{RESEARCH_SHOW_CMD}} <research-id>
 
-# Or use jq
-jq -s '.[-1] | {id, status, key_findings}' {{MANIFEST_PATH}}
+# Or list the task's pipeline_manifest entries
+cleo manifest list --task <taskId> --json --limit 1
 ```

package/skills/ct-orchestrator/references/orchestrator-tokens.md

@@ -16,7 +16,7 @@ The `spawn` command handles token injection automatically. For manual injection,
 # 3. Gets task context from CLEO
 # 4. Extracts manifest summaries
 # 5. Injects all tokens
-cleo orchestrate spawn T1586 --template ct-research-agent
+cleo orchestrate spawn T1586 --protocol research
 ```
 
 ### Manual Token Injection
@@ -33,7 +33,7 @@ export TI_TOPIC_SLUG="my-research-topic"
 ti_set_defaults
 
 # 3. Optional: Get task context from CLEO
-task_json=$(cleo show T1234 --format json)
+task_json=$(cleo show T1234)
 ti_set_task_context "$task_json"
 
 # 4. Load and inject skill template
@@ -70,7 +70,7 @@ template=$(ti_load_template "skills/ct-research-agent/SKILL.md")
 
 | Token | Default Value |
 |-------|---------------|
-| `{{OUTPUT_DIR}}` | `.cleo/agent-outputs` |
+| `{{OUTPUT_DIR}}` | `.cleo/agent-outputs` (legacy token — do not write there; record output with `cleo docs add`) |
 
 
 ### Task Context Tokens (populated from CLEO task data)
@@ -113,7 +113,7 @@ For fine-grained control over token injection, use `lib/token-inject.sh` directl
 |----------|--------|--------|
 | **Required** | `{{TASK_ID}}`, `{{DATE}}`, `{{TOPIC_SLUG}}` | Must be set before injection |
 | **Task Commands** | `{{TASK_SHOW_CMD}}`, `{{TASK_START_CMD}}`, `{{TASK_COMPLETE_CMD}}`, etc. | CLEO defaults |
-| **Output Paths** | `{{OUTPUT_DIR}}`, `{{MANIFEST_PATH}}` | CLEO defaults |
+| **Output Paths** | `{{OUTPUT_DIR}}` | Legacy CLEO default — record output with `cleo docs add` and manifest entries with `cleo manifest append` |
 | **Task Context** | `{{TASK_TITLE}}`, `{{TASK_DESCRIPTION}}`, `{{DEPENDS_LIST}}`, etc. | From CLEO task data |
 | **Manifest Context** | `{{MANIFEST_SUMMARIES}}` | From recent pipeline_manifest entries |
 
@@ -129,7 +129,7 @@ ti_set_context "T1234" "2026-01-20" "auth-research"
 ti_set_defaults
 
 # 3. Get task context from CLEO
-task_json=$(cleo show T1234 --format json)
+task_json=$(cleo show T1234)
 ti_set_task_context "$task_json"
 
 # 4. Load and inject skill template
@@ -155,8 +155,8 @@ echo "$template" | grep -c '{{' && echo "WARNING: Uninjected tokens remain"
 ## Subagent Protocol Tokens
 
 Token defaults (from `skills/_shared/placeholders.json`):
-- `{{OUTPUT_DIR}}` -> `.cleo/agent-outputs`
-- `{{MANIFEST_PATH}}` -> retired (ADR-027) — use `cleo manifest append`
+- `{{OUTPUT_DIR}}` -> `.cleo/agent-outputs` (legacy token — record output with `cleo docs add`, never raw writes there)
+- The flat manifest path token is retired (ADR-027) — use `cleo manifest append`
 
 ### Inline Protocol Block (when CLI unavailable)
 
@@ -164,8 +164,8 @@ Token defaults (from `skills/_shared/placeholders.json`):
 ## SUBAGENT PROTOCOL (RFC 2119 - MANDATORY)
 
 OUTPUT REQUIREMENTS:
-1. MUST write findings to: {{OUTPUT_DIR}}/{{DATE}}_{{TOPIC_SLUG}}.md
-2. MUST append ONE entry via `cleo manifest append <json>` (writes to pipeline_manifest table per ADR-027/T1093)
+1. MUST record findings with `cleo docs add {{TASK_ID}} --content - --type <kind> --slug {{TOPIC_SLUG}}` (never a raw file under `.cleo/agent-outputs/`)
+2. MUST append ONE entry via `cleo manifest append --entry '<json>'` (writes to pipeline_manifest table per ADR-027/T1093)
 3. MUST return ONLY: "Research complete. Manifest appended to pipeline_manifest."
 4. MUST NOT return research content in response.
 

package/skills/ct-provenance-keeper/SKILL.md

@@ -1,6 +1,15 @@
 ---
 name: ct-provenance-keeper
 description: "Generates in-toto v1 attestations, SLSA-level provenance records, SBOMs (CycloneDX or SPDX), and sigstore/cosign signatures for published artifacts. Invoked by ct-artifact-publisher as a delegation for signing and attestation. Records the full commit, then build, then artifact, then attestation, then registry chain in .cleo/releases.json and rejects publishes whose digest does not match the attestation. Triggers when artifact-publish reaches the provenance step or when a release needs SLSA L2+ attestation."
+metadata:
+  version: 1.0.2
+  tier: on-demand
+  install: harness
+  covers:
+    - packages/core/src/validation/protocols/cant/provenance.cant
+    - packages/core/src/validation/protocols/protocols-markdown/provenance.md
+  lastReviewed: 2026-09-28
+  stability: stable
 ---
 
 # Provenance Keeper
@@ -127,11 +136,10 @@ Each release appends a record in the following shape. The skill MUST populate ev
 Validate the provenance entry through `cleo check protocol`:
 
 ```bash
-cleo check protocol \
-  --protocolType provenance \
-  --taskId T4902 \
-  --hasAttestation true \
-  --hasSbom true
+cleo check protocol provenance \
+  --task-id T4902 \
+  --has-attestation true \
+  --has-sbom true
 ```
 
 Exit code 0 = provenance record is complete and verified. Exit code 90 = invalid config. Exit code 91 = signing key missing. Exit code 92 = signature invalid. Exit code 93 = digest mismatch (refuse to bind attestation). Exit code 94 = attestation format or subject is invalid.
@@ -158,4 +166,4 @@ Exit code 0 = provenance record is complete and verified. Exit code 90 = invalid
 5. Default to sigstore keyless signing via OIDC in CI; fall back to gpg only when configured.
 6. Generate CycloneDX SBOMs for every artifact with runtime dependencies.
 7. `.cleo/releases.json` is append-only; never mutate past entries.
-8. Validate every run via `cleo check protocol --protocolType provenance`.
+8. Validate every run via `cleo check protocol provenance`.

package/skills/ct-release-orchestrator/SKILL.md

@@ -2,14 +2,20 @@
 name: ct-release-orchestrator
 description: "Orchestrates the canonical 4-verb release pipeline introduced by SPEC-T9345: cleo release plan, then cleo release open, then PR + GHA tag workflow, then cleo release reconcile. The deprecated cleo release ship monolith was deleted in T10103 — do not invoke it. Use ship-e2e-smoke to validate the full pipeline end-to-end (dry-run by default). The full verb-to-state map is in docs/release/verb-matrix.md. Use when shipping a new version, validating the release pipeline end-to-end, or promoting a completed epic to released status."
 protocol: release
-loomStage: release
 adrRefs:
   - ADR-053
   - ADR-063
   - ADR-065
 metadata:
-  version: 3.0.0
-  lastReviewed: 2026-05-22
+  version: 3.0.2
+  tier: on-demand
+  install: harness
+  covers:
+    - packages/core/src/validation/protocols/cant/release.cant
+    - packages/core/src/validation/protocols/protocols-markdown/release.md
+    - packages/cleo/src/cli/commands/release.ts
+  loomStage: release
+  lastReviewed: 2026-09-28
   stability: stable
 ---
 
@@ -30,7 +36,7 @@ Owns the canonical 4-verb release pipeline established by SPEC-T9345 and finalis
 | 1 | `cleo release plan <ver> --epic <id>` | _(none)_ → `planned` | Builds the Release Plan envelope; auto-writes `CHANGELOG.md` (T10105 closes the silent-skip gap) |
 | 2 | `cleo release open <ver>` | `planned` → `pr-opened` | Dispatches `release-prepare.yml`; the workflow cuts the branch + opens the PR |
 | 3 | _(GHA)_ `release-prepare.yml` → PR merge | `pr-opened` → `pr-merged` | Owned by CI; verify via `cleo release pr-status <ver>` |
-| 4 | _(GHA)_ `auto-tag-on-release-merge.yml` (T10104) | `pr-merged` → `tag-pushed` | Auto-tag on merge — no manual `git tag` needed |
+| 4 | `git tag -a v<ver> -m "Release v<ver>" && git push origin v<ver>` | `pr-merged` → `tag-pushed` | Explicit tag after the release PR merges — `auto-tag-on-release-merge.yml` is retired (T10434, ADR-087); the tag push triggers `release.yml` |
 | 5 | `cleo release reconcile <ver>` | `tag-pushed` → `published` | Backfills 11 provenance tables; idempotent |
 
 Optional validators (read-only / dry-run):
@@ -47,15 +53,15 @@ Optional validators (read-only / dry-run):
 |----|------|-------------|
 | RLSE-001 | Version MUST be CalVer (`YYYY.MM.patch`) per ADR-065 — never SemVer. | `cleo release plan` rejects non-CalVer; exit 53. |
 | RLSE-002 | `CHANGELOG.md` MUST be updated before the tag — always-write is the default behaviour of `cleo release plan` (T9784 deleted the manual changelog verb). | Plan envelope refuses to advance to `pr-opened` if the changeset directory is unparseable (T10105). |
-| RLSE-003 | All per-task evidence gates MUST be recorded via `cleo verify <task> --gate <g> --evidence …` BEFORE `cleo complete`. The legacy `cleo release verify` batch verb was deleted in T9540. | ADR-051 per-task evidence ritual. |
-| RLSE-004 | The release MUST be tagged via the auto-tag GHA workflow — not a manual `git tag`. | T10104 closes the auto-tag gap. |
+| RLSE-003 | All per-task evidence gates MUST be recorded via `cleo verify <task> --gate <g> --evidence …` BEFORE `cleo complete`. The legacy `cleo release verify` batch verb was deleted in T9540. | ADR-051 per-task evidence ritual. | <!-- cleo-cmd: negative-example: release verify -->
+| RLSE-004 | The release MUST be tagged explicitly (`git tag -a v<ver>` + `git push origin v<ver>`) after the release PR merges. | Auto-tag was retired in T10434 / ADR-087: `GITHUB_TOKEN` tag pushes did not reliably trigger `release.yml`. |
 | RLSE-005 | Direct pushes to `main` are prohibited. Every release ships via a PR cut by `release-prepare.yml`. | ADR-065 + branch protection (see `docs/release/branch-protection-setup.md`). |
 | RLSE-006 | Version MUST be consistent across all workspace targets resolved by `resolveVersionBumpTargets` (root package.json + every workspace package + Cargo workspace). | Version-bump preflight in `release-prepare.yml`. |
 | RLSE-007 | Provenance reconcile MUST run within the release-publish workflow — never as a manual followup. | Invoked by `release-publish.yml`. |
 
 ## Integration
 
-Use the explicit two-verb invocation. **Do not** invoke `cleo release ship` — it was deleted in T10103.
+Use the explicit verbs. **Do not** invoke `cleo release ship` — it was deleted in T10103. <!-- cleo-cmd: negative-example: release ship -->
 
 ```bash
 # 1. Plan — build the canonical Release Plan envelope.
@@ -67,7 +73,11 @@ cleo release open v2026.6.0
 # 3. (Optional) Poll PR + CI status while the workflow runs.
 cleo release pr-status v2026.6.0
 
-# 4. Reconcile — runs automatically inside release-publish.yml.
+# 4. After the release PR merges, tag explicitly (auto-tag is retired).
+git tag -a v2026.6.0 -m "Release v2026.6.0"
+git push origin v2026.6.0
+
+# 5. Reconcile — runs automatically inside release-publish.yml.
 #    Run manually only if backfilling a historical release.
 cleo release reconcile v2026.6.0
 ```
@@ -88,7 +98,7 @@ Exit codes (canonical):
 - `0` — success.
 - `53` — version validation failed (e.g. not CalVer).
 - `54` — release-prepare workflow gate failed.
-- `56` — tag creation failed (auto-tag workflow).
+- `56` — tag creation failed.
 - `82` — `E_PLAN_NOT_FOUND` (plan envelope missing for the requested version).
 - `83` — `E_IVTR_INCOMPLETE` (per-task IVTR loops not released).
 - `88` — artifact publish failed.
@@ -97,9 +107,9 @@ Exit codes (canonical):
 
 | Pattern | Problem | Solution |
 |---------|---------|----------|
-| Running `cleo release ship` | The verb was deleted in T10103 — the command will exit with `Unknown command`. | Use `cleo release plan` + `cleo release open`. |
+| Running `cleo release ship` | The verb was deleted in T10103 — the command will exit with `Unknown command`. | Use `cleo release plan` + `cleo release open`. | <!-- cleo-cmd: negative-example: release ship -->
 | Manually invoking `gh workflow run release-prepare.yml` | Bypasses the plan envelope; `releases.status` stays at `planned`. | Always go through `cleo release open <ver>` — it tracks state in the `releases` table. |
-| Manually `git tag v<ver> && git push --tags` | Bypasses the auto-tag workflow (T10104) and skips provenance backfill. | Let `auto-tag-on-release-merge.yml` create the tag on PR merge. |
+| Tagging before the release PR merges, or `git push --tags` | Tags an unmerged commit, or pushes every local tag. | Tag the merged release commit and push that one tag: `git push origin v<ver>`. |
 | Hand-editing `CHANGELOG.md` for the new version | Drift between the changeset directory and the changelog. | `cleo release plan` always auto-writes the section (T10105). Use `cleo changeset add` to author entries. |
 | Pasting one verb into another's workflow file | Multi-step orchestration belongs in `ship-e2e-smoke`. | Use `cleo release ship-e2e-smoke … --execute` for end-to-end validation. |
 | Running the pipeline on a dirty worktree | Release commit scoops up unrelated changes. | The clean-tree gate refuses to advance. |
@@ -108,10 +118,10 @@ Exit codes (canonical):
 ## Critical Rules Summary
 
 1. The 4-verb pipeline — `plan`, `open`, `reconcile`, `rollback` — is the ONLY way to ship.
-2. The deprecated `cleo release ship` shim was DELETED in T10103. Do not invoke it.
+2. The deprecated `cleo release ship` shim was DELETED in T10103. Do not invoke it. <!-- cleo-cmd: negative-example: release ship -->
 3. CalVer (`YYYY.MM.patch`) is the only valid version scheme.
 4. `cleo release plan` always writes the CHANGELOG section unless `--no-changelog`.
-5. The tag is created by `auto-tag-on-release-merge.yml`, not by hand.
+5. The tag is created explicitly after the release PR merges; `auto-tag-on-release-merge.yml` is retired (T10434, ADR-087).
 6. Provenance reconcile is invoked by `release-publish.yml`, not manually (unless backfilling).
 7. Per-task evidence gates use `cleo verify --gate --evidence` per ADR-051 — not the deleted batch verb.
 8. Use `cleo release ship-e2e-smoke` to validate the full pipeline before a real ship.

package/skills/ct-release-orchestrator/references/composition.md

@@ -31,7 +31,7 @@ release → artifact-publish → provenance
 | 93 | provenance | `E_DIGEST_MISMATCH` |
 | 94 | provenance | `E_ATTESTATION_INVALID` |
 
-The parent MUST NOT remap sub-protocol exit codes. A caller reading `cleo release ship` output needs to know exactly which step failed.
+The parent MUST NOT remap sub-protocol exit codes. A caller reading `cleo release open` / `cleo release pr-status` output needs to know exactly which step failed.
 
 ## Rollback Semantics
 

package/skills/ct-release-orchestrator/references/release-types.md

@@ -18,8 +18,11 @@ No package is produced. Used for docs, spec updates, and internal code changes t
 ### Commands
 
 ```bash
-cleo release ship v2026.4.5 --bump-version --create-tag --push --no-artifacts
-cleo check protocol --protocolType release --version v2026.4.5 --hasChangelog true
+cleo release plan v2026.4.5 --epic T####
+cleo release open v2026.4.5
+# after the release PR merges:
+git tag -a v2026.4.5 -m "Release v2026.4.5" && git push origin v2026.4.5
+cleo check protocol release --version v2026.4.5 --has-changelog true
 ```
 
 ## npm-Package Release
@@ -38,11 +41,14 @@ Publishes one or more npm packages from the monorepo. Uses `npm publish --proven
 ### Commands
 
 ```bash
-cleo release ship v2026.4.5 --bump-version --create-tag --push
+cleo release plan v2026.4.5 --epic T####
+cleo release open v2026.4.5
+# after the release PR merges:
+git tag -a v2026.4.5 -m "Release v2026.4.5" && git push origin v2026.4.5
 # CI handles the publish + attestation; the skill records the result.
-cleo check protocol --protocolType release --version v2026.4.5 --hasChangelog true
-cleo check protocol --protocolType artifact-publish --artifactType npm-package --buildPassed true
-cleo check protocol --protocolType provenance --hasAttestation true --hasSbom true
+cleo check protocol release --version v2026.4.5 --has-changelog true
+cleo check protocol artifact-publish --artifact-type npm-package --build-passed true
+cleo check protocol provenance --has-attestation true --has-sbom true
 ```
 
 ## docker-image Release
@@ -61,10 +67,13 @@ Builds and pushes a container image to GHCR or another OCI registry, signs with
 ### Commands
 
 ```bash
-cleo release ship v2026.4.5 --bump-version --create-tag --push
+cleo release plan v2026.4.5 --epic T####
+cleo release open v2026.4.5
+# after the release PR merges:
+git tag -a v2026.4.5 -m "Release v2026.4.5" && git push origin v2026.4.5
 # CI runs: docker build → cosign sign → cosign attest → syft sbom → push
-cleo check protocol --protocolType artifact-publish --artifactType docker-image --buildPassed true
-cleo check protocol --protocolType provenance --hasAttestation true --hasSbom true
+cleo check protocol artifact-publish --artifact-type docker-image --build-passed true
+cleo check protocol provenance --has-attestation true --has-sbom true
 ```
 
 ## cargo-crate Release
@@ -82,9 +91,12 @@ Publishes one or more crates from the Rust workspace to crates.io.
 ### Commands
 
 ```bash
-cleo release ship v2026.4.5 --bump-version --create-tag --push
+cleo release plan v2026.4.5 --epic T####
+cleo release open v2026.4.5
+# after the release PR merges:
+git tag -a v2026.4.5 -m "Release v2026.4.5" && git push origin v2026.4.5
 # CI runs: cargo test → cargo publish --dry-run → cargo publish
-cleo check protocol --protocolType artifact-publish --artifactType cargo-crate --buildPassed true
+cleo check protocol artifact-publish --artifact-type cargo-crate --build-passed true
 ```
 
 ## github-tarball Release
@@ -101,9 +113,12 @@ Creates a source tarball and attaches it to a GitHub Release. Optional cosign si
 ### Commands
 
 ```bash
-cleo release ship v2026.4.5 --bump-version --create-tag --push
+cleo release plan v2026.4.5 --epic T####
+cleo release open v2026.4.5
+# after the release PR merges:
+git tag -a v2026.4.5 -m "Release v2026.4.5" && git push origin v2026.4.5
 # gh release create runs in CI with the tarball attached
-cleo check protocol --protocolType artifact-publish --artifactType github-release --buildPassed true
+cleo check protocol artifact-publish --artifact-type github-release --build-passed true
 ```
 
 ## Multi-Artifact Release
@@ -120,9 +135,12 @@ A release with more than one artifact type — typical for a major version that
 ### Commands
 
 ```bash
-cleo release ship v2026.4.5 --bump-version --create-tag --push
+cleo release plan v2026.4.5 --epic T####
+cleo release open v2026.4.5
+# after the release PR merges:
+git tag -a v2026.4.5 -m "Release v2026.4.5" && git push origin v2026.4.5
 # CI orchestrates all publishes; skill records the unified chain
-cleo check protocol --protocolType release --version v2026.4.5 --hasChangelog true
+cleo check protocol release --version v2026.4.5 --has-changelog true
 ```
 
 ## Which Checklist Wins?

package/skills/ct-research-agent/SKILL.md

@@ -1,12 +1,8 @@
 ---
 name: ct-research-agent
 description: Multi-source research and investigation combining web search, documentation lookup via Context7, and codebase analysis. Synthesizes findings into actionable recommendations with proper citation and task traceability. Use when conducting research, investigating best practices, gathering technical information, or analyzing existing implementations. Triggers on research tasks, investigation needs, or information discovery requests.
-version: 2.0.0
-tier: 2
-core: false
-category: recommended
+version: 2.0.4
 protocol: research
-loomStage: research
 adrRefs:
   - ADR-023
   - ADR-070
@@ -20,6 +16,16 @@ compatibility:
   - windsurf
   - gemini-cli
 license: MIT
+metadata:
+  version: 2.0.4
+  tier: on-demand
+  install: harness
+  covers:
+    - packages/core/src/validation/protocols/cant/research.cant
+    - packages/core/src/validation/protocols/protocols-markdown/research.md
+  loomStage: research
+  lastReviewed: 2026-09-28
+  stability: stable
 ---
 
 # Research Context Injection
@@ -70,8 +76,8 @@ Context injection for research and investigation tasks spawned via cleo-subagent
 1. Read task: `{{TASK_SHOW_CMD}} {{TASK_ID}}`
 2. Focus already set by orchestrator (skip if working standalone, set if needed)
 3. Conduct research (see Methodology below)
-4. Write output: `{{OUTPUT_DIR}}/{{DATE}}_{{TOPIC_SLUG}}.md`
-5. Append manifest: `{{MANIFEST_PATH}}`
+4. Record output: `cleo docs add {{TASK_ID}} --content - --type research --slug {{TOPIC_SLUG}}`
+5. Record the manifest entry: `cleo manifest append --task {{TASK_ID}} --type research --content "<one-paragraph summary>"`
 6. Complete task: `{{TASK_COMPLETE_CMD}} {{TASK_ID}}`
 7. Return summary message
 
@@ -109,8 +115,8 @@ Context injection for research and investigation tasks spawned via cleo-subagent
 
 ### Output Requirements
 
-1. MUST write findings to: `{{OUTPUT_DIR}}/{{DATE}}_{{TOPIC_SLUG}}.md`
-2. MUST append ONE line to: `{{MANIFEST_PATH}}`
+1. MUST record findings with `cleo docs add {{TASK_ID}} --content - --type research --slug {{TOPIC_SLUG}}` (never a raw file under `.cleo/agent-outputs/`)
+2. MUST record ONE manifest entry: `cleo manifest append --entry '<entry JSON>'` (the flat manifest file is retired, ADR-027)
 3. MUST return ONLY: "Research complete. Manifest appended to pipeline_manifest."
 4. MUST NOT return research content in response
 
@@ -118,7 +124,7 @@ Context injection for research and investigation tasks spawned via cleo-subagent
 
 ## Output File Format
 
-Write to `{{OUTPUT_DIR}}/{{DATE}}_{{TOPIC_SLUG}}.md`:
+Record it with `cleo docs add {{TASK_ID}} --content - --type research --slug {{TOPIC_SLUG}}`, using this body:
 
 ```markdown
 # {{RESEARCH_TITLE}}
@@ -159,7 +165,7 @@ Write to `{{OUTPUT_DIR}}/{{DATE}}_{{TOPIC_SLUG}}.md`:
 
 ## Manifest Entry Format
 
-Append ONE entry via `cleo manifest append <json>` (writes to pipeline_manifest table per ADR-027):
+Append ONE entry via `cleo manifest append --entry '<json>'` (writes to pipeline_manifest table per ADR-027):
 
 ```json
 {"id":"{{TOPIC_SLUG}}-{{DATE}}","file":"{{DATE}}_{{TOPIC_SLUG}}.md","title":"{{RESEARCH_TITLE}}","date":"{{DATE}}","status":"complete","agent_type":"research","topics":{{TOPICS_JSON}},"key_findings":["Finding 1","Finding 2","Finding 3"],"actionable":true,"needs_followup":[],"linked_tasks":["{{EPIC_ID}}","{{TASK_ID}}"]}
@@ -181,7 +187,7 @@ Append ONE entry via `cleo manifest append <json>` (writes to pipeline_manifest
 - [ ] Task details read via `{{TASK_SHOW_CMD}}`
 - [ ] Research conducted across multiple sources
 - [ ] Findings synthesized with recommendations
-- [ ] Output file written to `{{OUTPUT_DIR}}/`
+- [ ] Output recorded with `cleo docs add` (slug in the return message)
 - [ ] Manifest entry appended (single line, valid JSON)
 - [ ] Task completed via `{{TASK_COMPLETE_CMD}}`
 - [ ] Response is ONLY the summary message

package/skills/ct-research-agent/references/triggers-and-routing.md

@@ -38,12 +38,12 @@ to sibling skills that have narrower context budgets and stricter contracts.
 | "write the spec for X" | `ct-spec-writer` |
 | "validate this implementation against the spec" | `ct-validator` |
 | "decompose this epic into tasks" | `ct-epic-architect` |
-| "look up Next.js 15 middleware API" | `ct-docs-lookup` (single-library fetch) |
+| "look up Next.js 15 middleware API" | the Context7 MCP (single-library fetch) |
 | "decide between A and B" (no investigation needed) | `ct-consensus-voter` |
 | "explain this function" | (no skill — direct read suffices) |
 
 A useful heuristic: if the user already knows the answer and just wants it
-written down, route to `ct-spec-writer` or `ct-docs-write`. Research is for
+written down, route to `ct-spec-writer` or `ct-documentor` (`references/writing.md`). Research is for
 when the answer is not yet known.
 
 ## Routing to Downstream Skills
@@ -68,11 +68,11 @@ Research outputs typically feed one of these next stages. The manifest
 
 ```
 Is the answer already known and just needs documentation?
-├── YES → ct-docs-write
+├── YES → the writing guide (`ct-documentor/references/writing.md`)
 └── NO → continue
     │
     Is this a single-library API question?
-    ├── YES → ct-docs-lookup
+    ├── YES → the Context7 MCP
     └── NO → ct-research-agent (this skill)
         │
         After research, do findings produce requirements?

package/skills/{ct-skill-creator → ct-skill-author}/SKILL.md

@@ -1,12 +1,20 @@
 ---
-name: ct-skill-creator
-description: Guide for creating effective skills. This skill should be used when users want to create a new skill (or update an existing skill) that extends Claude's capabilities with specialized knowledge, workflows, or tool integrations.
+name: ct-skill-author
+description: Create, improve and validate CLEO skills. Use when writing a new skill or updating an existing one (structure, frontmatter, progressive disclosure, trigger descriptions, evals), and when auditing a skill folder against the CLEO standard before it ships (structural, ecosystem-fit and quality validation with an HTML report). Internal to CLEO development — not installed to harnesses.
 license: MIT
+metadata:
+  version: 2.0.1
+  tier: internal
+  install: internal
+  lastReviewed: 2026-09-28
+  stability: stable
 ---
 
-# Skill Creator
+# Skill Author
 
-This skill provides guidance for creating effective skills.
+Guidance for creating effective skills, and the validation loop that checks them.
+This skill merges the former ct-skill-creator and ct-skill-validator (T12649, D11157).
+For validation, load `references/validating.md`; its scripts live in `scripts/`.
 
 ## About Skills
 

package/skills/{ct-skill-validator → ct-skill-author}/agents/ecosystem-checker.md

@@ -93,7 +93,7 @@ Save to the path specified in your prompt (default: `ecosystem-check.json` in th
 
 ```json
 {
-  "skill_name": "ct-skill-validator",
+  "skill_name": "ct-skill-author",
   "verdict": "PASS|PASS_WITH_WARNINGS|FAIL",
   "rules": [
     {

package/skills/{ct-skill-validator → ct-skill-author}/evals/quality_evals.json

@@ -1,12 +1,12 @@
 {
-  "skill_name": "ct-skill-validator",
+  "skill_name": "ct-skill-author",
   "evals": [
     {
       "id": 1,
-      "prompt": "Validate the ct-skill-creator skill against the v2 standard and show me a full report",
-      "expected_output": "A complete tier-by-tier validation report showing pass/fail/warn status for ct-skill-creator, with an HTML report opened in the browser",
+      "prompt": "Validate the ct-skill-author skill against the v2 standard and show me a full report",
+      "expected_output": "A complete tier-by-tier validation report showing pass/fail/warn status for ct-skill-author, with an HTML report opened in the browser",
       "expectations": [
-        "Claude runs validate.py against ct-skill-creator",
+        "Claude runs validate.py against ct-skill-author",
         "The output shows results for all 5 tiers",
         "Claude runs generate_validation_report.py to produce an HTML report",
         "Claude tells the user the report path or opens it in the browser",
@@ -27,20 +27,20 @@
     },
     {
       "id": 3,
-      "prompt": "Audit the ct-skill-validator skill itself — run all checks and give me a full findings report",
-      "expected_output": "Full self-audit of ct-skill-validator including validate gauntlet and audit_body, with HTML report",
+      "prompt": "Audit the ct-skill-author skill itself — run all checks and give me a full findings report",
+      "expected_output": "Full self-audit of ct-skill-author including validate gauntlet and audit_body, with HTML report",
       "expectations": [
-        "Claude runs validate.py against ct-skill-validator",
+        "Claude runs validate.py against ct-skill-author",
         "Claude runs audit_body.py for the deep body quality audit",
         "An HTML report combining all findings is generated",
         "Claude opens or links the HTML report for the user",
-        "The result correctly reflects ct-skill-validator's actual compliance status"
+        "The result correctly reflects ct-skill-author's actual compliance status"
       ]
     },
     {
       "id": 4,
-      "prompt": "Run the manifest alignment check for ct-skill-validator against the CLEO manifest",
-      "expected_output": "Manifest alignment results showing whether ct-skill-validator is registered correctly in manifest.json and dispatch-config.json",
+      "prompt": "Run the manifest alignment check for ct-skill-author against the CLEO manifest",
+      "expected_output": "Manifest alignment results showing whether ct-skill-author is registered correctly in manifest.json",
       "expectations": [
         "Claude passes --manifest to validate.py (Tier 4 check)",
         "The manifest.json path is correctly resolved",

package/skills/{ct-skill-validator → ct-skill-author}/evals/trigger_queries.json

@@ -2,7 +2,7 @@
   {"query": "validate my skill against v2 standard", "should_trigger": true},
   {"query": "check if this skill folder is v2 compliant", "should_trigger": true},
   {"query": "audit the skill structure and frontmatter", "should_trigger": true},
-  {"query": "run v2 compliance check on ct-skill-creator", "should_trigger": true},
+  {"query": "run v2 compliance check on ct-skill-author", "should_trigger": true},
   {"query": "is my SKILL.md missing required fields", "should_trigger": true},
   {"query": "verify skill passes all CLEO validation tiers", "should_trigger": true},
   {"query": "prepare skill for distribution, check for issues", "should_trigger": true},