@cleocode/cleo 2026.3.2 → 2026.3.6

package/packages/ct-skills/protocols/release.md

@@ -1,635 +0,0 @@
-# Release Protocol
-
-**Provenance**: @task T3155, @epic T3147
-**Version**: 2.1.0
-**Type**: Conditional Protocol
-**Max Active**: 3 protocols (including base)
-
----
-
-## Trigger Conditions
-
-This protocol activates when the task involves:
-
-| Trigger | Keywords | Context |
-|---------|----------|---------|
-| Version | "release", "version", "v1.x.x" | Version management |
-| Publish | "publish", "deploy", "ship" | Distribution |
-| Changelog | "changelog", "release notes" | Documentation |
-| Tag | "tag", "milestone", "GA" | Version marking |
-
-**Explicit Override**: `--protocol release` flag on task creation.
-
----
-
-## Requirements (RFC 2119)
-
-### MUST
-
-| Requirement | Description |
-|-------------|-------------|
-| RLSE-001 | MUST follow semantic versioning (semver) |
-| RLSE-002 | MUST update changelog with all changes |
-| RLSE-003 | MUST pass all validation gates before release |
-| RLSE-004 | MUST tag release in version control |
-| RLSE-005 | MUST document breaking changes with migration path |
-| RLSE-006 | MUST verify version consistency across files |
-| RLSE-007 | MUST set `agent_type: "documentation"` in manifest |
-
-### SHOULD
-
-| Requirement | Description |
-|-------------|-------------|
-| RLSE-010 | SHOULD include upgrade instructions |
-| RLSE-011 | SHOULD verify documentation is current |
-| RLSE-012 | SHOULD test installation process |
-| RLSE-013 | SHOULD create backup before release |
-| RLSE-014 | SHOULD run test suite for major/minor releases (use `--run-tests`) |
-| RLSE-015 | SHOULD verify tests pass before tagging (opt-in to avoid timeout) |
-
-### MAY
-
-| Requirement | Description |
-|-------------|-------------|
-| RLSE-020 | MAY include performance benchmarks |
-| RLSE-021 | MAY announce on communication channels |
-| RLSE-022 | MAY batch minor fixes into single release |
-
----
-
-## State Machine
-
-```
-create → planned → active → released (immutable)
-```
-
-| Transition | Trigger | Condition |
-|------------|---------|-----------|
-| (none) → planned | `cleo release create <version>` | User action |
-| planned → active | `cleo release ship <version>` (automatic) | Ship begins execution |
-| active → released | `cleo release ship <version>` (automatic) | All steps complete |
-
-The `active` state is automatic and transitional -- it is set internally during `ship` execution. Agents interact with `create` (→ planned) and `ship` (→ released). The `plan` command works on releases in `planned` or `active` status. Once `released`, the entry is **immutable** -- no task additions, no metadata changes.
-
----
-
-## Release Schema
-
-Releases are stored as an array in `todo.json` under `project.releases`:
-
-```json
-{
-  "releaseDefinition": {
-    "required": ["version", "status", "createdAt"],
-    "properties": {
-      "version": { "type": "string", "pattern": "^v\\d+\\.\\d+\\.\\d+(-[a-z0-9.-]+)?$" },
-      "status": { "enum": ["planned", "active", "released"] },
-      "name": { "type": ["string", "null"], "maxLength": 100 },
-      "description": { "type": ["string", "null"], "maxLength": 500 },
-      "tasks": { "type": "array", "items": { "pattern": "^T\\d{3,}$" } },
-      "createdAt": { "format": "date-time" },
-      "targetDate": { "format": "date" },
-      "releasedAt": { "format": "date-time" },
-      "gitTag": { "type": ["string", "null"] },
-      "changelog": { "type": ["string", "null"] },
-      "notes": { "type": "array", "items": { "maxLength": 500 } }
-    }
-  }
-}
-```
-
----
-
-## CLI Commands (8 subcommands)
-
-### `create`
-
-Create a new planned release.
-
-```bash
-cleo release create <version> [--target-date DATE] [--tasks T001,T002] [--notes "text"]
-```
-
-| Flag | Type | Default | Description |
-|------|------|---------|-------------|
-| `--target-date` | DATE (YYYY-MM-DD) | null | Target release date |
-| `--tasks` | string (comma-separated) | [] | Tasks to include |
-| `--notes` | string | null | Release notes |
-
-**Exit codes**: 0 (success), 51 (`E_RELEASE_EXISTS`), 53 (`E_INVALID_VERSION`)
-
-**Behavior**: Creates a new release entry with status `planned`. Validates version is valid semver and doesn't already exist. Tasks are stored as an array; target date and notes are optional metadata.
-
----
-
-### `plan`
-
-Add or remove tasks from a release.
-
-```bash
-cleo release plan <version> [--tasks T001,T002] [--remove T003] [--notes "text"]
-```
-
-| Flag | Type | Default | Description |
-|------|------|---------|-------------|
-| `--tasks` | string (comma-separated) | — | Tasks to add (appends, deduplicates) |
-| `--remove` | string | — | Task to remove |
-| `--notes` | string | — | Update release notes |
-
-**Exit codes**: 0 (success), 50 (`E_RELEASE_NOT_FOUND`), 52 (`E_RELEASE_LOCKED`)
-
-**Behavior**: Modifies an existing release in `planned` or `active` status. The `--tasks` flag appends to existing tasks and deduplicates automatically. Calling `plan --tasks T001` then `plan --tasks T002` results in both tasks being included. Released entries are immutable and reject modification.
-
----
-
-### `ship`
-
-Mark a release as released. This is the primary release workflow command.
-
-```bash
-cleo release ship <version> [FLAGS]
-```
-
-| Flag | Type | Default | Description |
-|------|------|---------|-------------|
-| `--bump-version` | boolean | false | Bump VERSION file via `dev/bump-version.sh` |
-| `--create-tag` | boolean | false | Create annotated git tag |
-| `--force-tag` | boolean | false | Overwrite existing git tag (requires `--create-tag`) |
-| `--push` | boolean | false | Push commits and tag to remote |
-| `--no-changelog` | boolean | false | Skip changelog generation |
-| `--no-commit` | boolean | false | Skip git commit (update files only) |
-| `--run-tests` | boolean | false | Run test suite during validation (opt-in, slow) |
-| `--skip-validation` | boolean | false | Skip all validation gates (emergency releases) |
-| `--dry-run` | boolean | false | Preview what would happen without making changes |
-| `--notes` | string | "" | Release notes |
-| `--output` | string | CHANGELOG.md | Changelog output file |
-
-**Exit codes**: 0 (success), 50 (`E_RELEASE_NOT_FOUND`), 52 (`E_RELEASE_LOCKED`), 54 (`E_VALIDATION_FAILED`), 55 (`E_VERSION_BUMP_FAILED`), 56 (`E_TAG_CREATION_FAILED`), 57 (`E_CHANGELOG_GENERATION_FAILED`), 58 (`E_TAG_EXISTS`)
-
-**Ship Workflow** (10 steps):
-
-```
- 1. Auto-populate release tasks (date window + label matching from todo.json)
- 2. Bump version (if --bump-version)
- 3. Ensure [Unreleased] section exists in CHANGELOG.md (creates if missing)
- 4. Generate changelog from task metadata via lib/changelog.sh (unless --no-changelog)
- 5. Validate changelog content is not empty (unless --no-changelog)
- 6. Append to CHANGELOG.md + generate platform-specific outputs (if configured)
- 7. Run validation gates (tests opt-in, schema, version, changelog)
- 8. Create release commit staging VERSION, README, CHANGELOG.md, platform docs, todo.json (unless --no-commit)
- 9. Create annotated tag with changelog/commit/description fallback (if --create-tag)
-10. Push to remote (if --push)
-11. Update release status to "released" in todo.json with releasedAt timestamp
-```
-
-Steps 2-6 are conditional on flags. Step 7 is skippable with `--skip-validation`. The `--dry-run` flag previews all steps without executing.
-
-**`changelog` vs `ship`**: The `changelog` subcommand generates and previews changelog content without modifying release state. The `ship` subcommand performs the full release workflow including changelog generation, git operations, and status transition.
-
----
-
-### `changelog`
-
-Generate changelog from release tasks without shipping.
-
-```bash
-cleo release changelog <version> [--output FILE]
-```
-
-| Flag | Type | Default | Description |
-|------|------|---------|-------------|
-| `--output` | string | — | Write changelog to file |
-
-**Exit codes**: 0 (success), 50 (`E_RELEASE_NOT_FOUND`), 53 (`E_INVALID_VERSION`)
-
-**Behavior**: Generates changelog content from task metadata (title, description, labels) for the specified release. Outputs to stdout by default. Use `--output` to write to a file. Does not modify release status. Useful for previewing changelog before shipping.
-
----
-
-### `list`
-
-List all releases.
-
-```bash
-cleo release list [--status STATUS] [--format FORMAT]
-```
-
-| Flag | Type | Default | Description |
-|------|------|---------|-------------|
-| `--status` | string | — | Filter by status (planned, active, released) |
-| `--format` | text\|json | auto | Output format |
-
-**Exit codes**: 0 (success)
-
-**Behavior**: Lists all releases with version, status, target date, task count, and released timestamp. Supports JSON and text output. Color-coded by status: yellow=planned, cyan=active, green=released.
-
----
-
-### `show`
-
-Show details of a specific release.
-
-```bash
-cleo release show <version> [--format FORMAT]
-```
-
-| Flag | Type | Default | Description |
-|------|------|---------|-------------|
-| `--format` | text\|json | auto | Output format |
-
-**Exit codes**: 0 (success), 50 (`E_RELEASE_NOT_FOUND`), 53 (`E_INVALID_VERSION`)
-
-**Behavior**: Displays full details for a release including version, status, dates, tasks, notes, git tag, and changelog content.
-
----
-
-### `init-ci`
-
-Initialize CI/CD workflow configuration for automated releases.
-
-```bash
-cleo release init-ci [--platform PLATFORM] [--force] [--dry-run]
-```
-
-| Flag | Type | Default | Description |
-|------|------|---------|-------------|
-| `--platform` | string | from config | CI platform: `github-actions`, `gitlab-ci`, `circleci` |
-| `--force` | boolean | false | Overwrite existing CI config file |
-| `--dry-run` | boolean | false | Preview without writing files |
-
-**Exit codes**: 0 (success), 72 (`E_CI_INIT_FAILED`)
-
-**Behavior**: Generates CI/CD workflow configuration files from templates in `lib/release-ci.sh`. Platform is auto-detected from config or specified via `--platform`. Use `--force` to overwrite existing configuration files.
-
----
-
-### `validate`
-
-Validate release protocol compliance for a task.
-
-```bash
-cleo release validate <task-id> [--strict] [--format FORMAT]
-```
-
-| Flag | Type | Default | Description |
-|------|------|---------|-------------|
-| `--strict` | boolean | false | Enable strict validation mode |
-| `--format` | text\|json | auto | Output format |
-
-**Exit codes**: 0 (valid), 4 (`E_NOT_FOUND` -- manifest or task not found), 66 (protocol violation in strict mode)
-
-**Behavior**: Validates a task's manifest entry against the release protocol. Checks for required fields, correct `agent_type`, semver compliance, and changelog presence. The `--strict` flag enforces stricter checks (e.g., all SHOULD requirements become violations). Outputs validation score (0-100) and violation details.
-
----
-
-## Task Discovery (6-Filter Pipeline)
-
-During `cleo release ship`, tasks are auto-discovered via `populate_release_tasks()`:
-
-| Filter | Purpose |
-|--------|---------|
-| 1. `completedAt` | Must have completion timestamp |
-| 2. Date window | Completed between previous and current release |
-| 3. `status == "done"` | Must be done (not pending/active/blocked) |
-| 4. `type != "epic"` | Excludes organizational epics |
-| 5. Label match | Has version label, `changelog`, or `release` label |
-| 6. Version exclusivity | Tasks with explicit version labels aren't claimed by other releases |
-
-Tasks are also included if explicitly assigned via `cleo release plan --tasks T001,T002`.
-
----
-
-## Validation Gates
-
-| Gate | Check | Required | Notes |
-|------|-------|----------|-------|
-| Tests | All tests pass | SHOULD | Opt-in with `--run-tests` flag to avoid timeout |
-| Schema | All schemas valid | MUST | Always enforced via `cleo validate` |
-| Version | Version bumped correctly | MUST | If `--bump-version` used |
-| Changelog | Entry for new version | MUST | Unless `--no-changelog` |
-| Docs | Documentation current | SHOULD | Manual verification |
-| Install | Installation works | SHOULD | Manual verification |
-
-Use `--skip-validation` to bypass all gates for emergency releases. Use `--run-tests` to opt into running the full test suite (slow, disabled by default to avoid ship timeout).
-
----
-
-## Tag Annotation Fallback (v0.83.0+)
-
-When `--create-tag` is used, the tag annotation is populated from a fallback chain:
-
-1. **CHANGELOG.md section** -- extracted via `extract_changelog_section()`
-2. **Git commit notes** -- generated via `generate_changelog_from_commits()` from previous tag
-3. **Release description** -- from `release.notes` field in todo.json
-
-This ensures tags always have meaningful content for GitHub Actions, even when `--no-changelog` skips CHANGELOG.md generation.
-
----
-
-## Platform Changelog Configuration (v0.84.0+)
-
-Platform-specific changelog generation is controlled by `.cleo/config.json`:
-
-```json
-{
-  "release": {
-    "changelog": {
-      "outputs": [
-        { "platform": "mintlify", "enabled": true, "path": "docs/changelog/overview.mdx" }
-      ]
-    }
-  }
-}
-```
-
-Supported platforms: `mintlify`, `docusaurus`, `github`, `gitbook`, `plain`, `custom`.
-Default for fresh installs: no platforms configured (only CHANGELOG.md generated).
-GitHub URLs in generated output are resolved dynamically from `git remote origin`.
-
----
-
-## CI/CD Integration
-
-| Event | Workflow | Action |
-|-------|----------|--------|
-| Tag push `v*.*.*` | `release.yml` | Build tarball, generate release notes, create GitHub Release |
-| Tag push `v*.*.*` | `npm-publish.yml` | Build, test, and publish `@cleocode/mcp-server` to npm |
-| CHANGELOG.md changed on main | `docs-update.yml` | Safety net: regenerate platform docs if missed by ship flow |
-| docs/** changed on main | `mintlify-deploy.yml` | Validate Mintlify docs (deployment via Mintlify dashboard) |
-
----
-
-## MCP Server Publishing
-
-The MCP server npm package (`@cleocode/mcp-server`) is automatically published when a release is shipped:
-
-1. `cleo release ship` bumps VERSION file via `dev/bump-version.sh`
-2. `dev/sync-mcp-version.sh` is called automatically to sync `mcp-server/package.json` version
-3. Release commit includes the synced `mcp-server/package.json`
-4. Git tag push triggers `.github/workflows/npm-publish.yml`
-5. GitHub Action builds, tests, and publishes to npm
-
-### Required Setup
-
-- GitHub secret `NPM_TOKEN` must be configured with npm publish access
-- npm package `@cleocode/mcp-server` must exist on the registry
-- The `dev/sync-mcp-version.sh` script must be present in the repository
-
-### Version Sync Details
-
-The version sync is integrated into `dev/bump-version.sh` as step 6. It runs after all other version updates (VERSION file, README badge, template tags, plugin.json). If the sync script is missing or fails, the bump continues with a warning -- it does not block the release.
-
----
-
-## Error Codes (50-59)
-
-| Code | Constant | Meaning | Recovery |
-|------|----------|---------|----------|
-| 50 | `E_RELEASE_NOT_FOUND` | Release version not found | `cleo release list` |
-| 51 | `E_RELEASE_EXISTS` | Version already exists | Use different version |
-| 52 | `E_RELEASE_LOCKED` | Released = immutable | Create hotfix version |
-| 53 | `E_INVALID_VERSION` | Bad semver format | Use `v{major}.{minor}.{patch}` |
-| 54 | `E_VALIDATION_FAILED` | Validation gate failed | Fix validation errors |
-| 55 | `E_VERSION_BUMP_FAILED` | bump-version.sh failed | Check VERSION file |
-| 56 | `E_TAG_CREATION_FAILED` | Git tag/commit failed | Check git status, existing tags |
-| 57 | `E_CHANGELOG_GENERATION_FAILED` | Changelog failed | Check lib/changelog.sh |
-| 58 | `E_TAG_EXISTS` | Git tag already exists | Use `--force-tag` to overwrite |
-| 59 | `E_TASKS_INCOMPLETE` | Incomplete tasks | Complete or remove from release |
-
----
-
-## Output Format
-
-### Semantic Versioning
-
-| Version Part | When to Increment | Example |
-|--------------|-------------------|---------|
-| Major (X.0.0) | Breaking changes | 1.0.0 → 2.0.0 |
-| Minor (X.Y.0) | New features, backward compatible | 1.0.0 → 1.1.0 |
-| Patch (X.Y.Z) | Bug fixes, backward compatible | 1.0.0 → 1.0.1 |
-
-### Changelog Format
-
-```markdown
-# Changelog
-
-All notable changes to this project will be documented in this file.
-
-The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
-and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
-
-## [Unreleased]
-
-### Added
-- New features
-
-### Changed
-- Changes in existing functionality
-
-### Deprecated
-- Soon-to-be removed features
-
-### Removed
-- Removed features
-
-### Fixed
-- Bug fixes
-
-### Security
-- Security fixes
-
-## [X.Y.Z] - YYYY-MM-DD
-
-### Added
-- {Feature description} (T####)
-
-### Fixed
-- {Bug fix description} (T####)
-
-### Changed
-- {Change description} (T####)
-
-### Breaking Changes
-- {Breaking change with migration path}
-```
-
-### Release Checklist
-
-```markdown
-## Release Checklist: vX.Y.Z
-
-### Pre-Release
-
-- [ ] All features complete and merged
-- [ ] Tests passing (recommended: ./tests/run-all-tests.sh)
-- [ ] Version bumped (./dev/bump-version.sh X.Y.Z)
-- [ ] Version consistency verified (./dev/validate-version.sh)
-- [ ] Changelog updated
-- [ ] Documentation current
-- [ ] Breaking changes documented
-- [ ] For major/minor: Run `cleo release ship --run-tests` to validate
-
-### Release
-
-- [ ] Create release commit
-- [ ] Tag release (git tag vX.Y.Z)
-- [ ] Push to remote (git push && git push --tags)
-- [ ] Create GitHub release (if applicable)
-
-### Post-Release
-
-- [ ] Verify installation works
-- [ ] Update any dependent projects
-- [ ] Announce release (if applicable)
-- [ ] Archive completed tasks (cleo archive)
-```
-
-### File Output
-
-```markdown
-# Release: vX.Y.Z
-
-**Task**: T####
-**Date**: YYYY-MM-DD
-**Status**: complete|partial|blocked
-**Agent Type**: documentation
-
----
-
-## Release Summary
-
-{2-3 sentence summary of this release}
-
-## Version Information
-
-| Field | Value |
-|-------|-------|
-| Version | X.Y.Z |
-| Previous | X.Y.W |
-| Type | Major/Minor/Patch |
-| Tag | vX.Y.Z |
-
-## Changes in This Release
-
-### Features
-
-| Feature | Task | Description |
-|---------|------|-------------|
-| {Name} | T#### | {Description} |
-
-### Bug Fixes
-
-| Fix | Task | Description |
-|-----|------|-------------|
-| {Name} | T#### | {Description} |
-
-### Breaking Changes
-
-| Change | Migration |
-|--------|-----------|
-| {Change} | {How to migrate} |
-
-## Validation Results
-
-| Gate | Status | Notes |
-|------|--------|-------|
-| Tests | PASS | 142 tests, 0 failures |
-| Lint | PASS | No warnings |
-| Version | PASS | Consistent across files |
-| Changelog | PASS | Entry present |
-
-## Release Commands
-
-```bash
-# Tag and push
-git tag -a vX.Y.Z -m "Release vX.Y.Z"
-git push origin main --tags
-
-# Verify
-git describe --tags
-```
-
-## Post-Release Tasks
-
-- [ ] Verify GitHub release created
-- [ ] Update documentation site
-- [ ] Notify stakeholders
-```
-
-### Manifest Entry
-
-@skills/_shared/manifest-operations.md
-
-Use `cleo research add` to create the manifest entry:
-
-```bash
-cleo research add \
-  --title "Release: vX.Y.Z" \
-  --file "YYYY-MM-DD_release-vXYZ.md" \
-  --topics "release,version,changelog" \
-  --findings "Version X.Y.Z released,3 features added,2 bugs fixed" \
-  --status complete \
-  --task T#### \
-  --not-actionable \
-  --agent-type documentation
-```
-
----
-
-## Integration Points
-
-### Base Protocol
-
-- Inherits task lifecycle (start, execute, complete)
-- Inherits manifest append requirement
-- Inherits error handling patterns
-
-### Protocol Interactions
-
-| Combined With | Behavior |
-|---------------|----------|
-| contribution | Contributions feed changelog |
-| implementation | Implementation changes tracked |
-| specification | Spec changes documented |
-
----
-
-## Example
-
-**Task**: Release CLEO v0.70.0
-
-**Manifest Entry Command**:
-```bash
-cleo research add \
-  --title "Release: v0.70.0" \
-  --file "2026-01-26_release-v0700.md" \
-  --topics "release,v0.70.0,changelog" \
-  --findings "Multi-agent support added,12 new commands,Full test coverage" \
-  --status complete \
-  --task T2350 \
-  --epic T2308 \
-  --not-actionable \
-  --agent-type documentation
-```
-
-**Return Message**:
-```
-Release complete. See MANIFEST.jsonl for summary.
-```
-
----
-
-## Anti-Patterns
-
-| Pattern | Why Avoid |
-|---------|-----------|
-| Skipping version bump | Version confusion |
-| Missing changelog entry | Lost history |
-| Undocumented breaking changes | User frustration |
-| No release tag | Cannot reference version |
-| Incomplete checklist | Missed steps |
-| Major releases without `--run-tests` | Quality risk for breaking changes |
-
----
-
-*Protocol Version 2.1.0 - Canonical release reference (consolidated from RELEASE-MANAGEMENT.mdx)*