kryptobaseddev/ct-release-orchestrator

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.

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:

# 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.