@cleocode/skills 2026.4.4 → 2026.4.6

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

@@ -0,0 +1,161 @@
+---
+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."
+---
+
+# Provenance Keeper
+
+## Overview
+
+Sub-protocol of ct-artifact-publisher. Generates cryptographic evidence for every published artifact: SHA-256 digests, in-toto Statement v1 attestations, SBOMs (CycloneDX 1.5+ or SPDX 2.3+), and signatures via sigstore/cosign keyless or gpg. Records the full commit-to-registry chain in `.cleo/releases.json`, verifies chain integrity before publishing attestations, and refuses to bind an attestation to an artifact whose digest does not match.
+
+## Core Principle
+
+> Provenance is non-falsifiable or it is not provenance.
+
+## Immutable Constraints
+
+| ID | Rule | Enforcement |
+|----|------|-------------|
+| PROV-001 | Chain MUST be recorded from source commit to published artifact. | `record_release()` writes the full chain; missing links set `metadata.completeness: incomplete`. |
+| PROV-002 | SHA-256 digest MUST be computed for every produced artifact. | Digest binds to the in-toto subject; mismatch exits 93. |
+| PROV-003 | Attestation MUST be in in-toto Statement v1 format. | Validator rejects other schemas; exit 94. |
+| PROV-004 | SLSA Build Level MUST be recorded (L1 minimum). | Level stored in `releases.json`; L1 is the floor. |
+| PROV-005 | Provenance record MUST be stored in `.cleo/releases.json` via `record_release()`. | Missing record fails validation. |
+| PROV-006 | Chain integrity MUST be verified before publishing the attestation. | `verify_provenance_chain()` runs before emit. |
+| PROV-007 | Manifest entry MUST set `agent_type: "provenance"`. | Validator rejects any other value. |
+
+## SLSA Compliance Levels
+
+The skill records the achieved SLSA level in every provenance record. A minimum of L1 is mandatory; L3 is the target for npm + docker releases via OIDC keyless signing.
+
+| Level | Requirements | Typical achievement |
+|-------|--------------|---------------------|
+| L1 | Provenance exists, basic metadata recorded. | Any run of the skill produces at least L1. |
+| L2 | Signed provenance, build on a hosted platform. | Requires sigstore keyless OR gpg signing + CI build. |
+| L3 | Non-falsifiable provenance, hermetic build environment. | CI runs with isolated runners and OIDC-bound identity (this is the default for npm + docker releases). |
+| L4 | Reproducible builds, two-party review, all deps signed. | Rare; requires pinned dependencies and second-reviewer sign-off. |
+
+Full requirements and per-level checklists are in [references/slsa.md](references/slsa.md).
+
+## Signing Methods
+
+Three methods are supported; the skill selects based on `release.security.provenance.signing.method`:
+
+| Method | Command | Output | When to use |
+|--------|---------|--------|-------------|
+| `sigstore` (default, keyless) | `cosign sign-blob --yes --output-signature <sig> --output-certificate <cert> <artifact>` | `.sig` + `.pem` + Rekor transparency log entry | Default. Requires OIDC identity (CI). |
+| `sigstore` (key) | `cosign sign-blob --key <ref> <artifact>` | `.sig` | Offline or self-hosted without OIDC. |
+| `gpg` | `gpg --detach-sign --armor -u <key-id> <artifact>` | `.asc` | Legacy workflows, regulated environments. |
+| `none` | (skip) | (none) | SLSA L1 only; explicit opt-out. |
+
+The decision matrix, including `GPG_KEY_ID` and OIDC trusted-publisher setup, lives in [references/signing.md](references/signing.md).
+
+## Provenance Chain
+
+The skill walks and records the full chain for every release:
+
+```
+commit  -->  build  -->  artifact  -->  attestation  -->  registry
+  |           |            |               |                |
+  sha        log         digest        signature        published
+  |           |            |               |                |
+source    env capture   sha256 file    cert bundle        URL
+```
+
+Each link MUST reference the previous link's output. The chain is append-only in `releases.json`: no link is ever modified after creation. Missing links are recorded as `incomplete`, never elided. Offline verification MUST be possible — every digest is stored locally, not fetched per verification.
+
+## SBOM Generation
+
+SBOMs are mandatory for artifacts with runtime dependencies (docker images, npm packages) and recommended for standalone binaries.
+
+| Format | Spec | Use case |
+|--------|------|----------|
+| CycloneDX | 1.5+ | Default. Machine-readable JSON. |
+| SPDX | 2.3+ | Compliance-focused (FedRAMP, regulated environments). |
+
+Storage locations:
+
+- `.cleo/sbom/<artifact-name>-<version>.cdx.json` (CycloneDX)
+- `.cleo/sbom/<artifact-name>-<version>.spdx.json` (SPDX)
+- `<artifact>.sbom.json` (bundled alongside the artifact)
+
+Generate with `syft packages dir:. -o cyclonedx-json` or equivalent.
+
+## `.cleo/releases.json` Record Structure
+
+Each release appends a record in the following shape. The skill MUST populate every field that can be known; the remainder stay as explicit nulls (never absent).
+
+```json
+{
+  "version": "v2026.4.5",
+  "commitSha": "3a2f1e9c4b8d7e6a5f2c1d0e9f8a7b6c5d4e3f2a",
+  "gitTag": "v2026.4.5",
+  "buildInvocationId": "gh-actions-12345",
+  "builder": { "id": "https://github.com/actions/runner" },
+  "artifacts": [
+    {
+      "type": "npm-package",
+      "name": "@cleocode/core",
+      "sha256": "a1b2c3...",
+      "registry": "https://registry.npmjs.org",
+      "publishedAt": "2026-04-06T19:50:00Z",
+      "attestation": ".cleo/attestations/v2026.4.5-core.intoto.jsonl",
+      "signature": {
+        "method": "sigstore",
+        "keyless": true,
+        "transparencyLog": {
+          "index": "123456789",
+          "url": "https://rekor.sigstore.dev"
+        }
+      }
+    }
+  ],
+  "sbom": {
+    "format": "CycloneDX",
+    "specVersion": "1.5",
+    "path": ".cleo/sbom/cleocode-core-2026.4.5.cdx.json"
+  },
+  "slsaLevel": "SLSA_BUILD_LEVEL_3",
+  "chainVerified": true,
+  "recordedAt": "2026-04-06T19:51:00Z"
+}
+```
+
+## Integration
+
+Validate the provenance entry through `cleo check protocol`:
+
+```bash
+cleo check protocol \
+  --protocolType provenance \
+  --taskId T4902 \
+  --hasAttestation true \
+  --hasSbom 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.
+
+## Anti-Patterns
+
+| Pattern | Problem | Solution |
+|---------|---------|----------|
+| Skipping digest computation | Chain integrity cannot be verified (violates PROV-002) | Always compute SHA-256 for every artifact before attesting |
+| Hardcoding signing keys in config | Key exposure, credentials in VCS | Reference env vars by name; actual keys stay in the environment |
+| Generating attestation without matching digest | Attestation binds to the wrong artifact (violates PROV-006) | Compute the digest first, then attest; refuse to attest a mismatched pair |
+| Publishing artifact before signing | Cannot retrofit signatures after publish | Sign before push; the sub-protocol order is build → sign → publish |
+| Modifying provenance records after creation | Breaks immutability, corrupts the audit trail | `.cleo/releases.json` is append-only; never rewrite old entries |
+| Skipping SBOM for artifacts with dependencies | Hidden supply-chain risk | Generate CycloneDX for every artifact with runtime deps |
+| Using SHA-1 or MD5 for digests | Cryptographically broken; non-compliant with SLSA | SHA-256 is mandatory; SHA-512 is optional for high-security contexts |
+| Storing private keys inside `.cleo/` | Key compromise if the repo is leaked | Keys live in the keystore / OIDC / HSM — never in the worktree |
+
+## Critical Rules Summary
+
+1. Compute SHA-256 for every artifact; bind the attestation to the exact digest.
+2. Produce attestations in in-toto Statement v1 format only.
+3. Record the full chain in `.cleo/releases.json` via `record_release()`.
+4. Verify chain integrity before publishing the attestation.
+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`.

package/skills/ct-provenance-keeper/manifest-entry.json

@@ -0,0 +1,30 @@
+{
+  "_comment": "CLEO-only metadata -- add to packages/skills/skills/manifest.json",
+  "name": "ct-provenance-keeper",
+  "version": "1.0.0",
+  "tier": 2,
+  "token_budget": 6000,
+  "protocol": "provenance",
+  "capabilities": {
+    "inputs": ["built-artifacts", "commit-sha", "builder-identity"],
+    "outputs": ["in-toto-attestation", "sbom", "signature", "releases-json-entry"],
+    "dispatch_triggers": [
+      "generate provenance",
+      "sign artifacts",
+      "create attestation",
+      "record supply chain",
+      "run slsa attestation"
+    ],
+    "compatible_subagent_types": ["general-purpose"],
+    "chains_to": [],
+    "dispatch_keywords": {
+      "primary": ["provenance", "attestation", "sbom", "slsa"],
+      "secondary": ["sigstore", "cosign", "in-toto", "sign"]
+    }
+  },
+  "constraints": {
+    "max_context_tokens": 60000,
+    "requires_session": false,
+    "requires_epic": false
+  }
+}

package/skills/ct-provenance-keeper/references/signing.md

@@ -0,0 +1,188 @@
+# Signing Methods Reference
+
+This file documents the three supported signing methods and when to pick each. The default is `sigstore` keyless via OIDC, which is what every npm and docker release in this monorepo uses.
+
+## Method Decision Matrix
+
+| Method | Trust root | Requires | Use when |
+|--------|------------|----------|----------|
+| `sigstore` keyless | Rekor transparency log | OIDC identity (CI) | Default for every CI release; produces SLSA L3. |
+| `sigstore` keyed | Local or cloud key | Cosign key reference | Self-hosted CI without OIDC; produces SLSA L2. |
+| `gpg` | GPG key in the local keystore | `GPG_KEY_ID` env var | Legacy workflows, air-gapped environments. |
+| `none` | (no signing) | — | SLSA L1 only; explicit opt-out, never default. |
+
+## Sigstore Keyless (default)
+
+Cosign issues a short-lived certificate bound to an OIDC identity (GitHub Actions token, Google OAuth, etc.) and publishes the signature to Rekor for transparency.
+
+### Command
+
+```bash
+cosign sign-blob \
+  --yes \
+  --output-signature "${ARTIFACT}.sig" \
+  --output-certificate "${ARTIFACT}.pem" \
+  "${ARTIFACT}"
+```
+
+### Outputs
+
+- `<artifact>.sig` — detached signature.
+- `<artifact>.pem` — short-lived certificate from Fulcio.
+- Transparency log entry in Rekor (the command prints the index).
+
+### OIDC Trusted Publishing
+
+For npm, configure the trusted publisher in the npm registry settings:
+
+1. Go to the package page → Settings → Trusted Publishers.
+2. Add the GitHub repo and workflow file (`.github/workflows/release.yml`).
+3. Scope the trust to the `release` job.
+
+The workflow then runs `npm publish --provenance` without any token; npm exchanges the OIDC token for short-lived publish permission and produces the SLSA L3 attestation automatically.
+
+For GHCR (docker), the `GITHUB_TOKEN` in CI is already OIDC-bound; no extra setup is needed.
+
+### Verification
+
+```bash
+cosign verify-blob \
+  --certificate "${ARTIFACT}.pem" \
+  --signature "${ARTIFACT}.sig" \
+  --certificate-identity-regexp "^https://github.com/kryptobaseddev/cleocode/" \
+  --certificate-oidc-issuer "https://token.actions.githubusercontent.com" \
+  "${ARTIFACT}"
+```
+
+## Sigstore Keyed
+
+Use when OIDC is unavailable but cosign is still preferred.
+
+### Command
+
+```bash
+cosign sign-blob \
+  --key "cosign.key" \
+  --output-signature "${ARTIFACT}.sig" \
+  "${ARTIFACT}"
+```
+
+### Key storage
+
+- **Local**: `cosign.key` file (reference only the path, never the contents).
+- **Cloud KMS**: `cosign.key` reference like `awskms:///alias/cosign`.
+- **HashiCorp Vault**: `hashivault://<path>`.
+
+### Verification
+
+```bash
+cosign verify-blob \
+  --key cosign.pub \
+  --signature "${ARTIFACT}.sig" \
+  "${ARTIFACT}"
+```
+
+## GPG
+
+Use for air-gapped environments, regulated workflows, or legacy release lines that predate sigstore.
+
+### Command
+
+```bash
+gpg --detach-sign --armor -u "${GPG_KEY_ID}" "${ARTIFACT}"
+```
+
+### Requirements
+
+- `GPG_KEY_ID` environment variable set to the signing key identifier.
+- The private key loaded in the GPG keyring (`gpg --list-secret-keys`).
+- A corresponding public key published somewhere consumers can fetch.
+
+### Output
+
+- `<artifact>.asc` — ASCII-armored detached signature.
+
+### Verification
+
+```bash
+gpg --verify "${ARTIFACT}.asc" "${ARTIFACT}"
+```
+
+## None
+
+Explicit opt-out. Use only for internal pre-release builds that will never leave the build environment. Producing a `none` signing method downgrades the release to SLSA L1 automatically.
+
+```json
+{
+  "release": {
+    "security": {
+      "provenance": {
+        "enabled": true,
+        "framework": "slsa",
+        "level": "SLSA_BUILD_LEVEL_1",
+        "signing": { "method": "none" }
+      }
+    }
+  }
+}
+```
+
+The skill rejects any config that declares `signing.method: none` with a target level higher than L1.
+
+## Validation Decision Tree
+
+```
+signing.method configured?
++-- "sigstore" (default)
+|   +-- IS keyless enabled (default: true)?
+|       +-- YES -> cosign sign-blob --yes <artifact>
+|                  require OIDC identity in env
+|       +-- NO  -> cosign sign-blob --key <key-ref> <artifact>
+|                  require key reference resolvable
++-- "gpg"
+|   +-- GPG_KEY_ID set?
+|       +-- YES -> gpg --detach-sign --armor -u <key-id> <artifact>
+|       +-- NO  -> Exit 91 (E_SIGNING_KEY_MISSING)
++-- "none"
+    +-- Target level > L1?
+        +-- YES -> Exit 90 (E_PROVENANCE_CONFIG_INVALID)
+        +-- NO  -> Skip signing; record as unsigned
+```
+
+## Signing Metadata Record
+
+Every signed artifact appends a `signature` block to its entry in `releases.json`:
+
+```json
+{
+  "signature": {
+    "method": "sigstore",
+    "keyless": true,
+    "signed": true,
+    "signedAt": "2026-04-06T19:50:32Z",
+    "signature": ".cleo/attestations/cleocode-core-2026.4.5.sig",
+    "certificate": ".cleo/attestations/cleocode-core-2026.4.5.pem",
+    "transparencyLog": {
+      "index": "123456789",
+      "url": "https://rekor.sigstore.dev"
+    }
+  }
+}
+```
+
+For gpg:
+
+```json
+{
+  "signature": {
+    "method": "gpg",
+    "keyless": false,
+    "signed": true,
+    "signedAt": "2026-04-06T19:50:32Z",
+    "signature": ".cleo/attestations/cleocode-core-2026.4.5.asc",
+    "keyId": "0xDEADBEEFCAFEBABE"
+  }
+}
+```
+
+The skill MUST populate the method and signedAt fields on every signed record. Optional fields (transparency log, certificate) are filled when the signing method provides them.

package/skills/ct-provenance-keeper/references/slsa.md

@@ -0,0 +1,121 @@
+# SLSA Compliance Reference
+
+SLSA (Supply-chain Levels for Software Artifacts) defines four levels of build provenance rigor. This file lists the exact requirements per level and the concrete checklist this skill uses to determine which level a release achieved.
+
+## Level Matrix
+
+| Requirement | L1 | L2 | L3 | L4 |
+|-------------|:--:|:--:|:--:|:--:|
+| Provenance exists | MUST | MUST | MUST | MUST |
+| Provenance is signed | — | MUST | MUST | MUST |
+| Build on hosted platform | — | MUST | MUST | MUST |
+| Non-falsifiable provenance (isolated builder) | — | — | MUST | MUST |
+| All dependencies have provenance | — | — | — | MUST |
+| Two-party review | — | — | — | MUST |
+| Hermetic, reproducible build | — | — | — | MUST |
+
+## Level 1 Checklist
+
+- [ ] Provenance record exists in `.cleo/releases.json` for this release.
+- [ ] `commitSha` is populated.
+- [ ] `artifacts[].sha256` is populated for every artifact.
+- [ ] `builder.id` is a non-empty URI (local builder is fine).
+- [ ] `buildInvocationId` is recorded (can be a local uuid).
+
+If any of the above is missing, the release is L0 (non-compliant). The skill refuses to mark a release L0 — it raises the missing-field errors and asks for them to be populated.
+
+## Level 2 Checklist
+
+All L1 items plus:
+
+- [ ] Attestation is signed (sigstore keyless or gpg).
+- [ ] Signature verifies against the attestation subject digest.
+- [ ] Build ran on a hosted CI platform (GitHub Actions, GitLab CI, CircleCI, etc.).
+- [ ] `builder.id` points at the hosted runner's identity URI.
+
+The skill determines L2 compliance automatically by inspecting the `signature.method` field and the `builder.id` URL shape.
+
+## Level 3 Checklist
+
+All L2 items plus:
+
+- [ ] Provenance is non-falsifiable: the builder cannot forge attestations for builds it did not run.
+- [ ] Build runs on an isolated runner (no long-lived state from prior builds).
+- [ ] Signing identity is bound to the CI run via OIDC.
+- [ ] The attestation is published to a transparency log (Rekor for sigstore).
+
+In practice, L3 means: GitHub Actions with OIDC trusted publishing, sigstore keyless signing, and a Rekor transparency log entry. This is the default for npm + docker releases in this monorepo.
+
+## Level 4 Checklist
+
+All L3 items plus:
+
+- [ ] Every runtime dependency has its own provenance attestation.
+- [ ] The build is reproducible (same inputs produce identical output digests).
+- [ ] A second reviewer signed off on the build config change that produced this release.
+- [ ] The builder image is pinned to a digest, not a tag.
+
+L4 is rare outside regulated environments. The skill does not attempt to claim L4 automatically; a human reviewer MUST assert the two-party review and reproducibility checks before the skill records L4.
+
+## Configuration
+
+The desired level is declared in `.cleo/config.json`:
+
+```json
+{
+  "release": {
+    "security": {
+      "provenance": {
+        "enabled": true,
+        "framework": "slsa",
+        "level": "SLSA_BUILD_LEVEL_3"
+      }
+    }
+  }
+}
+```
+
+The skill attempts to achieve the declared level. If the environment cannot satisfy it (e.g., declared L3 but no OIDC identity available), the skill records the actual level achieved and flags the shortfall in the manifest entry. It does NOT silently downgrade.
+
+## Level Detection Decision Tree
+
+```
+HAS provenance record in releases.json?
++-- NO  -> Level 0 (non-compliant; error)
++-- YES
+    +-- IS signature.method in ["sigstore", "gpg"]?
+    |   +-- NO  -> Level 1
+    |   +-- YES
+    |       +-- IS builder.id a hosted CI runner URI?
+    |       |   +-- NO  -> Level 1 (key-based but local build)
+    |       |   +-- YES
+    |       |       +-- IS signature.transparencyLog populated (Rekor for sigstore) OR equivalent?
+    |       |       |   +-- NO  -> Level 2
+    |       |       |   +-- YES
+    |       |       |       +-- ALL deps have provenance AND build is reproducible AND two-party reviewed?
+    |       |       |       |   +-- NO  -> Level 3
+    |       |       |       |   +-- YES -> Level 4 (requires human assertion)
+```
+
+## Recording Level
+
+The detected level is written to `releases.json` as a string:
+
+```json
+{
+  "slsaLevel": "SLSA_BUILD_LEVEL_3"
+}
+```
+
+Valid values: `SLSA_BUILD_LEVEL_1`, `SLSA_BUILD_LEVEL_2`, `SLSA_BUILD_LEVEL_3`, `SLSA_BUILD_LEVEL_4`. Never write `L0` — that's a validation error that the skill surfaces before writing anything.
+
+## Verification
+
+A consumer can verify SLSA level claims by:
+
+1. Fetching the attestation from the registry or local store.
+2. Verifying the signature via `cosign verify-blob` or `gpg --verify`.
+3. Inspecting the `builder.id` in the predicate.
+4. Checking the Rekor transparency log for the entry.
+
+The skill provides `verify_provenance_chain()` for internal checks; consumers use the standard SLSA tooling.

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

@@ -0,0 +1,134 @@
+---
+name: ct-release-orchestrator
+description: "Orchestrates the full release pipeline: version bump, then changelog, then commit, then tag, then conditionally forks to artifact-publish and provenance based on release config. Parent protocol that composes ct-artifact-publisher and ct-provenance-keeper as sub-protocols: not every release publishes artifacts (source-only releases skip it), and artifact publishers delegate signing and attestation to provenance. Use when shipping a new version, running cleo release ship, or promoting a completed epic to released status."
+---
+
+# Release Orchestrator
+
+## Overview
+
+Owns the top of the release pipeline: semver bump, changelog, release commit, and git tag. Composes two sub-protocols conditionally — ct-artifact-publisher when the release config has enabled artifacts, and ct-provenance-keeper when signing or attestation is required. Source-only releases (docs, spec changes) stop after the tag and skip both sub-protocols.
+
+## Core Principle
+
+> Release is the parent protocol; artifact-publish and provenance are conditional sub-protocols.
+
+## Immutable Constraints
+
+| ID | Rule | Enforcement |
+|----|------|-------------|
+| RLSE-001 | Version MUST follow semantic versioning (`v{major}.{minor}.{patch}`). | `validateReleaseProtocol` rejects non-semver strings; exit 53. |
+| RLSE-002 | Changelog MUST be updated with all changes before the tag. | `hasChangelog: false` fails validation unless `--no-changelog` is explicit. |
+| RLSE-003 | All validation gates MUST pass before the release proceeds. | Ship halts on any gate failure; exit 54. |
+| RLSE-004 | Release MUST be tagged in version control. | Missing tag fails validation; exit 56. |
+| RLSE-005 | Breaking changes MUST be documented with a migration path. | Required section in the changelog entry. |
+| RLSE-006 | Version MUST be consistent across all files listed in `release.versionBump`. | Mismatched files fail validation; exit 55. |
+| RLSE-007 | Manifest entry MUST set `agent_type: "documentation"`. | Validator rejects any other value. |
+| RLSE-008 | Parent protocol MUST hand off to artifact-publish when `release.artifacts` is non-empty. | Composition invariant from ARTP-005. |
+| RLSE-009 | Provenance chain MUST be recorded for every signed release. | Composition invariant from PROV-005. |
+
+## Composition Pipeline
+
+The release parent protocol composes with the artifact-publish and provenance sub-protocols via explicit handoffs:
+
+```
+Release Protocol                        Artifact Publish Protocol
+---                                     ---
+1.  Version bump
+2.  Changelog generation
+3.  Validation gates
+4.  Git commit + tag
+5.  ---- HANDOFF ------------------> 6.  Load artifact config
+                                     7.  Pre-validate all artifacts
+                                     8.  Build all artifacts
+                                     9.  ---- HANDOFF ----> Provenance Protocol
+                                                             10. Compute digests
+                                                             11. Generate in-toto attestation
+                                                             12. Sign (sigstore keyless)
+                                                             13. Record chain in releases.json
+                                     14. <--- RETURN ----
+                                     15. Publish signed artifacts
+                                     16. Record provenance to releases.json
+17. <--- RETURN ---------------------- 
+18. Push to remote
+19. Update release status to "released"
+```
+
+Each handoff uses a distinct exit code:
+
+| Edge | Exit code | Meaning |
+|------|-----------|---------|
+| Release → artifact-publish | 65 (`HANDOFF_REQUIRED`) | Parent yields control to the sub-protocol |
+| artifact-publish → provenance | 65 (`HANDOFF_REQUIRED`) | Sub-protocol delegates signing |
+| provenance → artifact-publish | 0 on success | Return to parent sub-protocol |
+| artifact-publish → release | 0 on success, 88 on publish fail | Return to parent with result |
+| release → tag push | 0 on success, 56 on tag fail | Final commit |
+
+Partial-failure rollback semantics are documented in [references/composition.md](references/composition.md).
+
+## Conditional Trigger Matrix
+
+Not every release needs both sub-protocols. The parent decides based on `release.artifacts` and `release.security.provenance.enabled`:
+
+| Release type | Needs artifact-publish | Needs provenance |
+|--------------|:---------------------:|:----------------:|
+| `source-only` (docs, spec changes, code-only merges without a package) | no | no |
+| `npm-package` | yes | yes (SLSA L3 via npm `--provenance`) |
+| `docker-image` | yes | yes (cosign keyless attestation) |
+| `cargo-crate` | yes | yes (GPG or sigstore) |
+| `github-tarball` | yes | optional (MAY sign via cosign) |
+| `multi-artifact` (npm + docker + tarball combo) | yes | yes |
+
+The parent skill inspects `.cleo/config.json#release.artifacts[]`. If the array is empty or all entries are disabled, the release is `source-only` and the pipeline stops after the tag.
+
+## CI Integration
+
+The existing `.github/workflows/release.yml` uses `npm publish --provenance` with the repository's OIDC trust configuration, producing SLSA L3 keyless attestations automatically. This skill's responsibility is to ensure the resulting chain is recorded in the manifest entry and in `.cleo/releases.json`, not to re-implement the signing step. When CI has already produced an attestation, the skill MUST read its reference from the workflow output and record it verbatim.
+
+## Integration
+
+Invoke the parent pipeline via `cleo release ship`, then validate with `cleo check protocol`:
+
+```bash
+# Kick off the release pipeline.
+cleo release ship v2026.4.5 \
+  --epic T260 \
+  --bump-version \
+  --create-tag \
+  --push
+
+# Validate the parent protocol entry.
+cleo check protocol \
+  --protocolType release \
+  --taskId T4900 \
+  --version v2026.4.5 \
+  --hasChangelog true
+```
+
+Exit code 0 = release complete. Exit code 50 = release not found. Exit code 54 = validation gate failed. Exit code 55 = version bump failed. Exit code 56 = tag creation failed. Exit code 88 = artifact publish failed (bubbled from sub-protocol). Exit code 94 = attestation invalid (bubbled from provenance).
+
+For source-only releases, pass `--no-artifacts` to skip the artifact-publish handoff. Every other release type leaves the default behavior alone.
+
+## Anti-Patterns
+
+| Pattern | Problem | Solution |
+|---------|---------|----------|
+| Publishing artifacts before running validation gates | Can't roll back a successful publish on a failed build | Follow the pipeline order: gates → commit → tag → publish |
+| Pushing the git tag before publishing artifacts | Tag points to a commit whose packages never shipped | Push the tag after artifacts are live, or use the same job |
+| Skipping the dry-run phase | Irreversible registry state on first real attempt | ARTP-002 requires dry-run; the parent skill refuses to skip it |
+| Source-only releases triggering artifact-publish | Wasted CI time, false SLSA attestations | Check `release.artifacts` before handoff; skip if empty |
+| Not recording the provenance chain in releases.json | Canon loses the commit → build → artifact → attestation link | Parent MUST record even when CI generated the attestation |
+| Overusing `--force` to bypass epic completeness | Ships partial epics without review | Use the guard mode `warn` and address gaps explicitly |
+| Mutating a `released` entry after the fact | Canon must be immutable once shipped | Create a new release entry for the hotfix |
+| Running ship on a dirty worktree | Commits scoop up unrelated changes | Require a clean worktree before step 1 |
+
+## Critical Rules Summary
+
+1. Version MUST be valid semver; the parent skill refuses non-semver strings.
+2. The changelog MUST be updated before the tag — no exceptions beyond explicit `--no-changelog`.
+3. All validation gates MUST pass before the commit step.
+4. The pipeline composes with artifact-publish and provenance only when the release config calls for it.
+5. Exit codes bubble up unchanged: 88 from artifact-publish and 94 from provenance surface at the parent.
+6. `released` entries are immutable; hotfixes go into new entries.
+7. Manifest entry MUST set `agent_type: "documentation"` and record the full chain via `record_release()`.
+8. Always validate via `cleo check protocol --protocolType release` before declaring the release done.

package/skills/ct-release-orchestrator/manifest-entry.json

@@ -0,0 +1,30 @@
+{
+  "_comment": "CLEO-only metadata -- add to packages/skills/skills/manifest.json",
+  "name": "ct-release-orchestrator",
+  "version": "1.0.0",
+  "tier": 2,
+  "token_budget": 8000,
+  "protocol": "release",
+  "capabilities": {
+    "inputs": ["version", "epic-id", "release-config"],
+    "outputs": ["release-commit", "git-tag", "changelog-entry", "manifest-entry"],
+    "dispatch_triggers": [
+      "ship release",
+      "cut release",
+      "publish version",
+      "cleo release ship",
+      "promote epic to released"
+    ],
+    "compatible_subagent_types": ["general-purpose"],
+    "chains_to": ["ct-artifact-publisher", "ct-provenance-keeper"],
+    "dispatch_keywords": {
+      "primary": ["release", "ship", "version", "tag"],
+      "secondary": ["changelog", "semver", "bump", "publish"]
+    }
+  },
+  "constraints": {
+    "max_context_tokens": 60000,
+    "requires_session": false,
+    "requires_epic": true
+  }
+}