maestro-flow 0.5.2 → 0.5.31

package/.claude/commands/maestro-milestone-release.md

@@ -1,145 +1,136 @@
----
-name: maestro-milestone-release
-description: Bump version, generate changelog, tag milestone
-argument-hint: "[<version>] [--bump patch|minor|major] [--dry-run] [--no-tag] [--no-push]"
-allowed-tools:
-  - Read
-  - Write
-  - Edit
-  - Bash
-  - Glob
-  - Grep
-  - Agent
-  - AskUserQuestion
----
-
-<purpose>
-Package a completed milestone into a releasable version. Bumps the project version (e.g. `package.json`, `pyproject.toml`, or language-specific manifest), generates or appends a changelog entry from phase/milestone summaries and git log, creates an annotated git tag, and optionally pushes to the remote. Runs after `/maestro-milestone-complete` has archived the milestone; serves as the final delivery step in the SDLC loop.
-
-Pipeline position: downstream of `/maestro-milestone-complete` (consumes archived milestone + audit verdict). Terminal command — no downstream consumer.
-</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.
-
-**High-level flow:**
-1. Validate preconditions (milestone completed, clean tree, audit PASS)
-2. Resolve target version from `<version>` or `--bump` against current manifest
-3. Collect changes since last release tag: milestone summary + phase summaries + git log between tags
-4. Generate `CHANGELOG.md` entry (grouped by phase / change type)
-5. Write version to manifest file(s) + commit with message `chore(release): v{version}`
-6. Create annotated git tag `v{version}` with release notes body (unless `--no-tag`)
-7. Push commit + tag to remote (unless `--no-push`)
-
-For `--dry-run`, print the 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>
+---
+name: maestro-milestone-release
+description: Bump version, generate changelog, tag milestone
+argument-hint: "[<version>] [--bump patch|minor|major] [--dry-run] [--no-tag] [--no-push]"
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Glob
+  - Grep
+  - Agent
+  - AskUserQuestion
+---
+
+<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>