maestro-milestone-release

<purpose>
Package a completed milestone into a releasable version: version bump → changelog → tag → push.

Pipeline position: downstream of `/maestro-milestone-complete`. Terminal command.
</purpose>

<required_reading>
@~/.maestro/workflows/milestone-release.md
</required_reading>

<context>
$ARGUMENTS -- optional explicit version string and flags.

**Flags:**

| Flag | Effect | Default |
|------|--------|---------|
| `<version>` | Explicit version (e.g. `1.2.0`). If omitted, version is derived from `--bump` or prompted | — |
| `--bump patch\|minor\|major` | Semver bump relative to the current version | `minor` |
| `--dry-run` | Compute the next version, changelog diff, and tag name without writing files or creating tags | `false` |
| `--no-tag` | Skip git tag creation (version bump + changelog only) | `false` |
| `--no-push` | Skip `git push --follow-tags` after tagging | `false` |

**State files:**
- `.workflow/state.json` -- current_milestone, previous release version
- `.workflow/milestones/{milestone}/summary.md` -- milestone summary (from `maestro-milestone-complete`)
- `.workflow/milestones/{milestone}/audit-report.md` -- audit verdict (must be PASS)
- `CHANGELOG.md` -- release notes file (created if missing)
- Version manifest -- `package.json` / `pyproject.toml` / `Cargo.toml` / etc. (auto-detected)

**Preconditions:**
- Current milestone must be completed (audit PASS + `/maestro-milestone-complete` run)
- Working tree must be clean (no uncommitted changes) unless `--dry-run`
</context>

<interview_protocol>
Follows @~/.maestro/workflows/interview-mechanics.md standard.

**Decision points**: version bump type (major / minor / patch / custom), changelog review and confirmation
**Scope guard**: only release decisions; do not prejudge next milestone scope
</interview_protocol>

<execution>
Follow '~/.maestro/workflows/milestone-release.md' completely.

### Phase Gates (MANDATORY, BLOCKING)

**GATE 1: Validation → Version Bump**
- REQUIRED: Current milestone completed (audit PASS + milestone-complete run). E001 if not.
- REQUIRED: Working tree clean (no uncommitted changes). E003 if dirty.

**GATE 2: Version Bump → Changelog**
- REQUIRED: Target version computed and greater than previous (E005 if not).
- REQUIRED: Version manifest file(s) identified and accessible.

**GATE 3: Changelog → Tag/Push**
- REQUIRED: CHANGELOG.md entry written with milestone summary + grouped changes.
- REQUIRED: Release commit created with conventional message.

**GATE 4: Tag → Completion**
- REQUIRED: Annotated git tag created (unless --no-tag).
- REQUIRED: state.json updated with last_release_version + last_release_at.

For `--dry-run`: print computed version, changelog diff, and tag name without side effects.
</execution>

<completion>
### Standalone report

```
=== RELEASE COMPLETE ===
Version:   v{previous} → v{new}
Milestone: {milestone_name}
Tag:       v{new} {pushed|local-only}
Changelog: {N} entries written to CHANGELOG.md
Manifest:  {file_path} updated
```

### Ralph-invoked completion

End the step by calling the CLI (no text block output):
```
maestro ralph complete <idx> --status {STATUS} [--evidence {path}]
```

Status verdicts:
- **DONE** — Normal completion
- **DONE_WITH_CONCERNS** — Completed with caveats; pass `--concerns`
- **NEEDS_RETRY** — Tooling error / transient issue; ralph will retry
- **BLOCKED** — External hard blocker; pass `--reason`

### Next-step routing

| Condition | Suggestion |
|-----------|-----------|
| Release successful, starting next milestone | `/maestro-plan {next_phase}` |
| Want to view project dashboard | `/manage-status` |
</completion>

<error_codes>
| Code | Severity | Condition | Recovery |
|------|----------|-----------|----------|
| E001 | error | Current milestone not completed (no milestone-complete run) | Run `/maestro-milestone-complete` first |
| E002 | error | Audit verdict not PASS | Re-run `/maestro-milestone-audit` and resolve findings |
| E003 | error | Working tree not clean (uncommitted changes) | Commit or stash changes, then retry |
| E004 | error | Version manifest not found / unsupported | Add supported manifest or pass `<version>` explicitly with `--no-tag` |
| E005 | error | Target version not greater than current (would break semver monotonicity) | Choose a higher version or run with explicit `<version>` |
| W001 | warning | No changes detected since last release tag | Confirm whether release is still desired |
| W002 | warning | Remote push failed (network / auth) | Retry manually with `git push --follow-tags` |
</error_codes>

<success_criteria>
- [ ] Preconditions validated (milestone complete, audit PASS, clean tree)
- [ ] Target version computed and greater than previous
- [ ] Version manifest(s) updated with new version
- [ ] CHANGELOG.md contains new entry with milestone summary + grouped changes
- [ ] Release commit created with conventional message
- [ ] Annotated git tag created (unless `--no-tag`)
- [ ] Commit + tag pushed to remote (unless `--no-push` or push failed → W002)
- [ ] state.json updated with last_release_version + last_release_at timestamp
</success_criteria>