Release Readiness Gate Boshu2 Agentops

---
name: release-readiness-gate
description: |-
  Use when preparing releases with versioning, changelog, artifacts, smoke tests, tags, and go/no-go.
  Triggers:
practices:
- pragmatic-programmer
skill_api_version: 1
user-invocable: false
hexagonal_role: supporting
context:
  window: inherit
  intent:
    mode: task
metadata:
  tier: execution
  stability: stable
  category: engineering-quality
  maturity: source
  clean_room: true
  owner: agentops
  dependencies: []
  primary_artifacts:
  - release-readiness report
  - signed release artifacts
  - annotated version tag
output_contract: 'release_readiness_report with sections: version, changelog, artifacts, smoke, gates, decision.'
---

# Release Preparations

Use this skill to take a candidate build from "the work is merged" to a recorded
**go / no-go** decision, by running a fixed pre-release sequence and capturing
evidence at each step. The deliverable is a release-readiness report, not a vibe.

## ⚠️ Critical Constraints

- **Nothing leaves the building before the go decision.** No tag push, no
  artifact upload, no announcement until the decision section says GO.
  **Why:** a release is irreversible in practice — users pull it, mirrors cache
  it, downstreams pin it. Order is: decide, *then* publish.
  - WRONG: `git push --tags && gh release create` while smoke tests are running.
  - CORRECT: gates green + smoke green → record GO → then tag and publish.
- **The version comes from the change set, not the calendar.** Read what changed
  and apply semver: breaking → MAJOR, feature → MINOR, fix-only → PATCH.
  **Why:** a PATCH that hides a breaking change silently breaks every consumer
  who trusted the number when they pinned it.
  - WRONG: bumping `1.4.3 → 1.4.4` for a release that removed a CLI flag.
  - CORRECT: `1.4.3 → 2.0.0` because a public flag was removed.
- **Build and tag from a clean, committed tree.** No uncommitted edits, no local
  patches in the artifact. **Why:** an artifact built from a dirty tree is
  unreproducible — you can never rebuild the exact bytes you shipped.
  - WRONG: `git status` shows modified files, build anyway.
  - CORRECT: tree clean at the candidate commit, then build.
- **Every readiness claim cites a command + exit code.** "Tests pass" is not
  evidence; `go test ./... → exit 0` is. **Why:** self-report skims; the gate is
  the source of truth, and the report must be re-verifiable by the next person.

## Why This Exists

Releases fail not because the code was wrong but because a step was skipped under
the pressure of shipping: the version got bumped wrong, the changelog lagged, the
artifact was built dirty, a gate was assumed green. Each skip is invisible until
a user hits it. This skill makes the pre-release sequence the same every time, so
the decision rests on evidence and the failure modes are caught before publish,
not after. It is the discipline that turns "I think it's ready" into "here is why
it is ready, step by step."

## Quick Start

```bash
# From the candidate commit, with a clean tree:
git status --porcelain             # MUST be empty
git log --oneline LAST_TAG..HEAD   # the change set you are releasing
# Run validate.sh after authoring the report to self-check this skill:
bash scripts/validate.sh
```

Work the six phases below in order. Do not advance past a red phase — fix it or
record it as a blocker. Write the result of each phase into the readiness report.

## Workflow

### Phase 1 — Version (semver)
Read the change set since the last tag (`git log LAST_TAG..HEAD`, merged PRs,
closed issues). Classify the highest-impact change and bump accordingly:
- **MAJOR** — any breaking change (removed/renamed public API, flag, schema,
  changed default, dropped platform).
- **MINOR** — backward-compatible new capability.
- **PATCH** — backward-compatible fixes only.
Pre-1.0 (`0.y.z`): treat MINOR as the breaking lane. Record the chosen version
and the one change that forced it.
**Checkpoint:** the version is written down with its justifying change.

### Phase 2 — Changelog finalize
Move the `[Unreleased]` block into a dated, versioned section. Confirm entries
are user-facing (outcomes, not commit subjects), grouped (Added / Changed /
Fixed / Removed), and that any breaking change is flagged. The version heading
must equal the version chosen in Phase 1.
**Checkpoint:** changelog top section matches the chosen version and date.

### Phase 3 — Build & sign artifacts
Confirm the tree is clean and at the candidate commit, then build the release
artifacts with the project's release tooling. Generate checksums and sign per the
project's signing policy. Capture the build command and its exit code.
**Checkpoint:** artifacts exist, checksums computed, signatures verify.

### Phase 4 — Smoke tests
Exercise the built artifact the way a user would — install/run it, hit the
primary path, confirm `--version` reports the chosen version. Smoke tests run the
*shipped* artifact, not the source tree. Capture commands and exit codes.
**Checkpoint:** the artifact runs and reports the correct version.

### Phase 5 — Run the gates
Run the project's full gate suite (tests, lint, type-check, security scan, and
any repo-specific bundle — run the whole bundle or its script, not a remembered
subset). Record each gate's command and exit code. A non-zero exit is a blocker.
**Checkpoint:** every gate reported with command + exit code.

### Phase 6 — Tag & go/no-go
With all phases green, record the **GO** decision, then create the annotated tag
at the candidate commit (`git tag -a vX.Y.Z`). If any phase is red, record
**NO-GO** with the specific blocker and the fix needed. Publishing (tag push,
artifact upload, announcement) happens only after GO is recorded.
**Checkpoint:** the decision section names a verdict and, for NO-GO, the blocker.

## Output Specification

Write a `release-readiness report` (filename `RELEASE-READINESS.md` or inline in
the release issue) with these sections, in order:

- **version** — chosen `vX.Y.Z`, the bump level, and the change that forced it.
- **changelog** — confirmation the section is finalized and matches the version.
- **artifacts** — what was built/signed, checksums, the build command + exit.
- **smoke** — what was exercised on the artifact, commands + exit codes.
- **gates** — each gate, its command, and its exit code.
- **decision** — `GO` or `NO-GO`; NO-GO lists each blocker and its fix.

## Quality Rubric

- [ ] The version is justified by a named change and follows semver.
- [ ] Every gate and smoke result shows its command and a real exit code (no
      "passed" without evidence).
- [ ] The tree was clean and the tag points at the exact built commit.
- [ ] The decision is explicit; a NO-GO names blockers and their fixes.

## Examples

**GO (patch release).** Change set is two bug fixes → `1.4.3 → 1.4.4`. Changelog
`Fixed` section finalized. `make build && make sign` → exit 0, checksums verify.
`./dist/app --version` → `1.4.4`. `make test lint` → exit 0. Decision: **GO** →
`git tag -a v1.4.4`.

**NO-GO (caught at gates).** Feature release `2.1.0 → 2.2.0`, changelog ready,
artifact built. Smoke green, but `make security` → exit 1 (a new dependency has a
known CVE). Decision: **NO-GO** — blocker: vulnerable dependency in lockfile; fix:
bump or replace, re-run from Phase 3. No tag created.

## Troubleshooting

| Symptom | Cause | Fix |
|---|---|---|
| `git status` not empty at build | uncommitted edits | commit or stash, rebuild from clean tree |
| `--version` shows wrong number | version not propagated to build | wire version from the tag/source, rebuild |
| Gate "passed" but no exit code | self-report, not evidence | re-run the gate, capture the exit code |
| Breaking change in a PATCH | semver misread in Phase 1 | reclassify to MAJOR, redo version + changelog |
| Signature verify fails | wrong key / corrupted artifact | re-sign with the release key, recompute checksums |

## See Also

- `changelog-md-workmanship` — finalize the changelog block in Phase 2.
- `gh-actions` — automate the build/sign/publish steps once the decision is GO.