Release

Release

SemVer-aware release readiness/communication. Prepares release evidence/docs; never tag, publish, upload, or force-push.

Input Schema

{
  "mode": "notes|prepare|audit|demo",
  "range": "optional git range, tag pair, or target version",
  "target_version": "optional SemVer version",
  "done_when": "release blockers, warnings, and required artifacts are explicit"
}

Workflow

01: Create run directory

Run create_run.py --skill release per ../../shared/helper-cli-contract.md.

02: Determine mode, range, and target version

• notes: draft release notes from git range.
• prepare: audit plus notes/changelog/migration-artifact checks.
• audit: readiness verdict only.
• demo: optional release-demo planning artifact; never required for non-feature releases.

Unknown mode/ambiguous range => fail before release docs.

03: Collect release evidence

Use supplied range; when absent, run git describe --tags --abbrev=0 as argv and form <printed-tag>..HEAD. Retain that literal release range in workflow state, run git log --oneline <release-range> as argv, and write stdout to <run-directory>/commits.txt. Record range or log collection failure instead of treating empty output as success.

When current GitHub release metadata is required, use python PLUGIN_ROOT/shared/github_read.py --out <run-directory>/github-release.json -- gh release view <tag-or-url> --json <fields>. It prefers gh; public HTTPS fallback is only for public REST resources and cannot supply private evidence. Never invoke gh directly. Apply full networked CLI approval and denial contract in ../../shared/native-skill-contract.md to this complete owning command. The operation-specific brief is: Action and purpose: collect current release metadata for selected tag or URL; External capability: read-only GitHub network access, with public HTTPS fallback only when eligible; Credential behavior: gh is opaque local credential broker and no credential output is retained; Filesystem and worktree effects: write github-release.json without changing worktree; Retry policy and safe denial outcome: stop turn on denial and record current release metadata as unavailable evidence.

Inspect python PLUGIN_ROOT/shared/collect_diff.py --help; collect commit scope for retained release range into <run-directory>/range. Collection failure is evidence gap, not empty release.

Write <run-directory>/change-table.md: change type, user impact, breaking status, docs need, verification evidence.

04: Verify release readiness

Required checks:

• SemVer classification matches observed API/user-visible changes.
• Breaking changes have migration guidance.
• Deprecations follow project policy and released before removal.
• CHANGELOG/release notes mention user-visible changes.
• Do not advertise reverted changes as live features.
• Call out security/dependency changes with source evidence.

Structural context (optional): for Python package release, also probe codemap-py once for undocumented public surface and externally-uncalled modules: python PLUGIN_ROOT/shared/codemap_adapter.py context --category audit --out <run-directory>/codemap-context.json. Per ../../shared/codemap-contract.md, absence/incompatibility is non-fatal — continue with checks above, using persisted evidence as additional readiness signal.

Write <run-directory>/release-readiness.md with:

• SemVer
• Migration
• Checks
• Blockers

For prepare/audit, read and apply ../../shared/specialist-orchestration.md only for public API changes, CI/release automation, security/dependency changes, docs/migration work, or broad verification risk; otherwise do not load it. Write <run-directory>/specialist-release-plan.md with narrow context packs for:

• oss-shepherd: SemVer, deprecation policy, maintainer readiness.
• cicd-steward: release workflow, publishing, CI status, artifact gates.
• doc-scribe: changelog, migration guide, README/examples.
• qa-specialist: verification matrix and test evidence.
• security-auditor: only when user expressly requests Sol or selects that role for security/dependency-sensitive changes; it returns bounded read-only evidence artifact to Terra parent/session for release acceptance.
• challenger: release-blocker downgrade or no-blocker conclusion.

Single-agent for notes on narrow low-risk range unless SemVer/migration impact ambiguous.

05: Run required checks from ../../shared/quality-gates.md

Inspect python PLUGIN_ROOT/shared/run_gates.py --help; run every project-required release gate with explicit commands/skip reasons.

06: Classify blockers and warnings

• critical: publish would ship known security/data-loss/API breakage without mitigation.
• high: SemVer, changelog, migration, or required-check gap blocks readiness.
• medium: incomplete docs, missing contributor notes, uncertain compatibility.
• low: wording, formatting, or optional artifact polish.

07: Decide gate result, write result.candidate.json, validate artifacts, and publish .reports/codex/release/<timestamp>/result.json

Follow ../../shared/helper-cli-contract.md and authoritative help. Write RELEASE_METADATA, validate as release, promote only validated candidate.

Fail-Fast Rules

1. Missing or invalid target range for notes/prepare/demo => fail.
2. Invalid SemVer target for prepare/audit => fail.
3. Breaking change without migration decision => fail.
4. Release blocker presented as warning => fail.
5. Publish/tag/upload action attempted by this skill => fail.
6. Missing release-readiness.md SemVer, Migration, Checks, or Blockers evidence => fail.
7. Result artifact validator failure => fail.
8. Result artifact missing => fail.

Quality Gates

Release readiness requires all five shared gates + shared artifact validator unless project has no executable package; record any skipped executable check as gap.

Calibration Hooks

On SemVer, deprecation, changelog, or release-blocker policy change, update calibration:

• behavioral cases: missing migration, wrong SemVer, unreleased API removal, artifact validator bypass, networked CLI owning-command approval
• benchmark patterns: release

Output Contract

Before writing result candidate, follow ../../shared/final-handoff-contract.md: render and bind final-handoff.json, final.md, and final-handoff.validation.json; after both validators and promotion pass, emit final.md verbatim.

Use ../../shared/quality-gates.md.

Final chat

Final chat follows shared ordered frame. Outcome is release-ready, blocked, or warning-only. Results has one material change or blocker per row and exactly Change | SemVer impact | Status / blocker | Evidence. Apply shared Verification, Remaining, Next steps, Confidence, and supplemental Artifact rules; include release gates and every blocker/warning with owner and closure action.

Minimum artifact payload template: result-template.json.