Release-Checklist Harness

# Release-Checklist Harness

A Claude Code project configuration for gating releases with a structured pre-flight checklist.

## What it does

When this harness is active, Claude Code acts as a release gatekeeper. Before any version
ships, it walks through every item on the checklist below, assigns a PASS or FAIL to each,
and delivers a go/no-go verdict. No release proceeds until all blocking items are green.

**Checklist items (in order):**

1. **Tests green** — the full test suite passes in CI on the release commit.
2. **Changelog updated** — a `CHANGELOG.md` or equivalent entry exists for this version,
   listing every user-visible change.
3. **Version bumped** — `package.json` (and any other version sources: `pyproject.toml`,
   `Cargo.toml`, etc.) agree on the new version and follow semver.
4. **Rollback plan documented** — a rollback procedure is written and reachable (inline
   comment, wiki page, or runbook) before deployment starts.
5. **Monitoring confirmed** — at least one alerting rule covers the release's key metrics;
   the on-call engineer is aware.

Any FAIL blocks the release. Claude reports which items need attention before asking you
to proceed.

## Files in this harness

| File | Purpose |
|------|---------|
| `README.md` | This guide — Claude reads it as its working instructions |
| `settings.json` | Claude Code project settings — copy to `.claude/settings.json` |

## Setup

1. Copy `settings.json` to `.claude/settings.json` in your project root.
2. Open your project in Claude Code.
3. Tell Claude the version you want to release and the deployment target, e.g.:
   "We are releasing v2.4.0 to production on Render."

Claude will run through the checklist and report status before taking any further action.

## Workflow reference

### Running a full release check
Tell Claude: "Run the release checklist for v2.4.0."

Claude will:
1. Run the test suite and confirm it is green on the release commit.
2. Check `CHANGELOG.md` for a v2.4.0 entry and flag it if missing.
3. Read `package.json` and any other version files and verify they all say `2.4.0`.
4. Ask you to confirm or provide a rollback procedure.
5. Ask whether monitoring is in place for this release.
6. Output the verdict table and — if all green — give an explicit go-ahead.

### Generating a rollback plan
Tell Claude: "Write a rollback plan for v2.4.0."

Claude will draft a numbered runbook: how to revert the deployment, what config changes
need to be undone, and how to verify the rollback succeeded.

### Bumping the version
Tell Claude: "Bump to v2.4.0."

Claude will update every version source consistently and prompt you to review the diff
before committing.

## Example output

```
Release checklist — v2.4.0
────────────────────────────────────────────
✓ Tests            all 312 tests pass on commit a3f9c1d
✓ Changelog        CHANGELOG.md entry found for v2.4.0
✓ Version bump     package.json, Dockerfile ARG — all say 2.4.0
✗ Rollback plan    no rollback procedure found — blocking
✓ Monitoring       Grafana alert "error-rate-high" covers /api/*

Overall verdict: NO-GO  (1 blocking item)
```

## Commands

- `/release-check <version>` — Run the full pre-release checklist for the given version
  and output a per-item PASS/FAIL table with an overall go/no-go verdict.
- `/rollback-plan <version>` — Draft a numbered rollback runbook for the release,
  covering deployment revert, config rollback, and verification steps.
- `/bump-version <version>` — Update every version source in the repo to the given
  version consistently, then show the diff for review.

## Allowed bash commands

The harness permits test runners, version inspection, and read-only git:

- `Bash(npm test*)`, `Bash(npx vitest*)`, `Bash(npx jest*)` — run the test suite
- `Bash(npx tsc*)` — typecheck before release
- `Bash(npm version*)` — bump version in package.json
- `Bash(git diff*)`, `Bash(git status*)`, `Bash(git log*)`, `Bash(git tag*)` — inspect state
- `Bash(cat*)` — read version files and changelog

Destructive commands and remote pushes are blocked.

## Known limitations

- The harness does not execute the deployment itself; it only gates the release.
- Monitoring confirmation is a human-in-the-loop step: Claude asks you to confirm rather
  than querying your alerting platform directly.

{
  "permissions": {
    "allow": [
      "Read(**)",
      "Write(**)",
      "Edit(**)",
      "Bash(npm test*)",
      "Bash(npx vitest*)",
      "Bash(npx jest*)",
      "Bash(npx tsc*)",
      "Bash(npm version*)",
      "Bash(git diff*)",
      "Bash(git status*)",
      "Bash(git log*)",
      "Bash(git tag*)",
      "Bash(cat*)"
    ],
    "deny": [
      "Bash(git push*)",
      "Bash(git reset --hard*)",
      "Bash(git restore*)",
      "Bash(git clean*)",
      "Bash(rm -rf*)"
    ]
  }
}