maestro-flow 0.3.37 → 0.3.39

package/.claude/commands/maestro-learn.md

@@ -1,140 +1,140 @@
----
-name: maestro-learn
-description: Learning coordinator — route intent to learn commands, execute single or multi-step chains
-argument-hint: "\"intent text\" [-y] [--dry-run] [--chain <name>]"
-allowed-tools:
-  - Read
-  - Write
-  - Bash
-  - Glob
-  - Grep
-  - Agent
-  - AskUserQuestion
----
-<purpose>
-Route learning requests to the optimal learn command or multi-step chain. Supports direct chain selection via `--chain` or intent-based routing via keyword matching.
-
-Executes commands sequentially via Skill() with session tracking.
-</purpose>
-
-<context>
-$ARGUMENTS — user learning intent text, or flags.
-
-**Flags:**
-- `-y` / `--yes` — Auto mode: skip confirmation
-- `--dry-run` — Show planned chain without executing
-- `--chain <name>` — Force a specific chain (bypass intent detection)
-
-**Available learn commands:**
-| Command | Purpose |
-|---------|---------|
-| `learn-follow` | Guided reading with forcing questions, pattern extraction |
-| `learn-investigate` | Hypothesis-driven question investigation |
-| `learn-decompose` | 4-dimension parallel pattern extraction |
-| `learn-second-opinion` | Multi-perspective review/challenge/consult |
-| `learn-retro` | Unified retrospective (git metrics + decision evaluation) |
-
-**Available chains:**
-| Chain | Steps | Use when |
-|-------|-------|----------|
-| `follow` | learn-follow | Read/understand code or docs |
-| `investigate` | learn-investigate | Answer a "how/why" question |
-| `decompose` | learn-decompose | Catalog patterns in a module |
-| `second-opinion` | learn-second-opinion | Get review/challenge on code |
-| `retro` | learn-retro --lens all | Full retrospective (git + decisions) |
-| `deep-understand` | follow → decompose → second-opinion | Thorough module analysis |
-| `pattern-catalog` | decompose --save-spec --save-wiki → second-opinion --mode review | Full pattern extraction + review |
-
-**Storage:**
-- `.workflow/learning/.maestro-learn/{session_id}/status.json` — Session tracking
-- All learn command outputs go to `.workflow/learning/`
-</context>
-
-<execution>
-
-### Step 1: Parse & Route
-
-Parse flags (`-y`, `--dry-run`, `--chain`). Extract intent text.
-
-**If `--chain` specified:** validate against known chains, jump to Step 2.
-
-**Intent routing table** (match first token or keywords):
-
-| Keywords | Route |
-|----------|-------|
-| File path (contains `/` or `\`) | `follow` |
-| Wiki ID (`type-slug` pattern) | `follow` |
-| read, follow, walk through, understand, 阅读, 跟读 | `follow` |
-| why, how, what if, investigate, 为什么, 怎么 | `investigate` |
-| pattern, decompose, catalog, 分解, 模式 | `decompose` |
-| opinion, review, challenge, consult, 评审, 挑战 | `second-opinion` |
-| retro, git, commit, decision, 回顾 | `retro` |
-| thorough, deep, 全面, 深入 | `deep-understand` |
-
-**If no match:** present menu via AskUserQuestion:
-```
-What would you like to do?
-1. Read through code/docs → follow
-2. Investigate a question → investigate
-3. Find patterns in code → decompose
-4. Get a second opinion → second-opinion
-5. Retrospective → retro
-```
-
-Max 1 clarification round. If still unclear: error.
-
-### Step 2: Resolve Target & Build Args
-
-- File path → pass directly
-- Wiki ID → pass directly
-- Topic string → pass as quoted argument
-- Extract any flags (--depth, --days, --lens, --mode, --scope, etc.)
-
-**Chain → command mapping:**
-```
-follow          → Skill("learn-follow", "{target} {flags}")
-investigate     → Skill("learn-investigate", "\"{target}\" {flags}")
-decompose       → Skill("learn-decompose", "{target} {flags}")
-second-opinion  → Skill("learn-second-opinion", "{target} {flags}")
-retro           → Skill("learn-retro", "{flags}")
-deep-understand → [learn-follow --depth deep, learn-decompose --save-spec, learn-second-opinion --mode challenge]
-pattern-catalog → [learn-decompose --save-spec --save-wiki, learn-second-opinion --mode review]
-```
-
-### Step 3: Confirm & Execute
-
-**If `--dry-run`:** display chain plan and exit.
-
-**If not `-y`:** show plan, ask for confirmation.
-
-**Execute:**
-1. Create session dir: `.workflow/learning/.maestro-learn/learn-{timestamp}/`
-2. Write `status.json` with chain steps
-3. Execute each step via `Skill()`:
-   - On success: mark completed, continue
-   - On failure (interactive): ask retry/skip/abort
-   - On failure (auto): skip and continue
-4. Display session summary with artifact list and next-step suggestion
-
-</execution>
-
-<error_codes>
-| Code | Severity | Description | Recovery |
-|------|----------|-------------|----------|
-| E001 | error | No intent provided | Provide a learning goal or use --chain |
-| E002 | error | Cannot determine intent after clarification | Rephrase or use --chain directly |
-| E003 | error | Chain step failed + user chose abort | Partial progress saved in status.json |
-| E005 | error | Invalid --chain name | Show valid chains |
-| W001 | warning | Intent ambiguous between commands | Present options |
-| W002 | warning | Chain step completed with warnings | Log and continue |
-</error_codes>
-
-<success_criteria>
-- [ ] Intent routed to correct chain (or --chain validated)
-- [ ] Target resolved and arguments assembled
-- [ ] Session directory created with status.json
-- [ ] All chain steps executed via Skill()
-- [ ] Error handling: retry/skip/abort per step
-- [ ] Session summary displayed with next-step routing
-- [ ] No files modified outside `.workflow/learning/`
-</success_criteria>
+---
+name: maestro-learn
+description: Route learning intent to learn-* commands
+argument-hint: "\"intent text\" [-y] [--dry-run] [--chain <name>]"
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - Glob
+  - Grep
+  - Agent
+  - AskUserQuestion
+---
+<purpose>
+Route learning requests to the optimal learn command or multi-step chain. Supports direct chain selection via `--chain` or intent-based routing via keyword matching.
+
+Executes commands sequentially via Skill() with session tracking.
+</purpose>
+
+<context>
+$ARGUMENTS — user learning intent text, or flags.
+
+**Flags:**
+- `-y` / `--yes` — Auto mode: skip confirmation
+- `--dry-run` — Show planned chain without executing
+- `--chain <name>` — Force a specific chain (bypass intent detection)
+
+**Available learn commands:**
+| Command | Purpose |
+|---------|---------|
+| `learn-follow` | Guided reading with forcing questions, pattern extraction |
+| `learn-investigate` | Hypothesis-driven question investigation |
+| `learn-decompose` | 4-dimension parallel pattern extraction |
+| `learn-second-opinion` | Multi-perspective review/challenge/consult |
+| `learn-retro` | Unified retrospective (git metrics + decision evaluation) |
+
+**Available chains:**
+| Chain | Steps | Use when |
+|-------|-------|----------|
+| `follow` | learn-follow | Read/understand code or docs |
+| `investigate` | learn-investigate | Answer a "how/why" question |
+| `decompose` | learn-decompose | Catalog patterns in a module |
+| `second-opinion` | learn-second-opinion | Get review/challenge on code |
+| `retro` | learn-retro --lens all | Full retrospective (git + decisions) |
+| `deep-understand` | follow → decompose → second-opinion | Thorough module analysis |
+| `pattern-catalog` | decompose --save-spec --save-wiki → second-opinion --mode review | Full pattern extraction + review |
+
+**Storage:**
+- `.workflow/learning/.maestro-learn/{session_id}/status.json` — Session tracking
+- All learn command outputs go to `.workflow/learning/`
+</context>
+
+<execution>
+
+### Step 1: Parse & Route
+
+Parse flags (`-y`, `--dry-run`, `--chain`). Extract intent text.
+
+**If `--chain` specified:** validate against known chains, jump to Step 2.
+
+**Intent routing table** (match first token or keywords):
+
+| Keywords | Route |
+|----------|-------|
+| File path (contains `/` or `\`) | `follow` |
+| Wiki ID (`type-slug` pattern) | `follow` |
+| read, follow, walk through, understand, 阅读, 跟读 | `follow` |
+| why, how, what if, investigate, 为什么, 怎么 | `investigate` |
+| pattern, decompose, catalog, 分解, 模式 | `decompose` |
+| opinion, review, challenge, consult, 评审, 挑战 | `second-opinion` |
+| retro, git, commit, decision, 回顾 | `retro` |
+| thorough, deep, 全面, 深入 | `deep-understand` |
+
+**If no match:** present menu via AskUserQuestion:
+```
+What would you like to do?
+1. Read through code/docs → follow
+2. Investigate a question → investigate
+3. Find patterns in code → decompose
+4. Get a second opinion → second-opinion
+5. Retrospective → retro
+```
+
+Max 1 clarification round. If still unclear: error.
+
+### Step 2: Resolve Target & Build Args
+
+- File path → pass directly
+- Wiki ID → pass directly
+- Topic string → pass as quoted argument
+- Extract any flags (--depth, --days, --lens, --mode, --scope, etc.)
+
+**Chain → command mapping:**
+```
+follow          → Skill("learn-follow", "{target} {flags}")
+investigate     → Skill("learn-investigate", "\"{target}\" {flags}")
+decompose       → Skill("learn-decompose", "{target} {flags}")
+second-opinion  → Skill("learn-second-opinion", "{target} {flags}")
+retro           → Skill("learn-retro", "{flags}")
+deep-understand → [learn-follow --depth deep, learn-decompose --save-spec, learn-second-opinion --mode challenge]
+pattern-catalog → [learn-decompose --save-spec --save-wiki, learn-second-opinion --mode review]
+```
+
+### Step 3: Confirm & Execute
+
+**If `--dry-run`:** display chain plan and exit.
+
+**If not `-y`:** show plan, ask for confirmation.
+
+**Execute:**
+1. Create session dir: `.workflow/learning/.maestro-learn/learn-{timestamp}/`
+2. Write `status.json` with chain steps
+3. Execute each step via `Skill()`:
+   - On success: mark completed, continue
+   - On failure (interactive): ask retry/skip/abort
+   - On failure (auto): skip and continue
+4. Display session summary with artifact list and next-step suggestion
+
+</execution>
+
+<error_codes>
+| Code | Severity | Description | Recovery |
+|------|----------|-------------|----------|
+| E001 | error | No intent provided | Provide a learning goal or use --chain |
+| E002 | error | Cannot determine intent after clarification | Rephrase or use --chain directly |
+| E003 | error | Chain step failed + user chose abort | Partial progress saved in status.json |
+| E005 | error | Invalid --chain name | Show valid chains |
+| W001 | warning | Intent ambiguous between commands | Present options |
+| W002 | warning | Chain step completed with warnings | Log and continue |
+</error_codes>
+
+<success_criteria>
+- [ ] Intent routed to correct chain (or --chain validated)
+- [ ] Target resolved and arguments assembled
+- [ ] Session directory created with status.json
+- [ ] All chain steps executed via Skill()
+- [ ] Error handling: retry/skip/abort per step
+- [ ] Session summary displayed with next-step routing
+- [ ] No files modified outside `.workflow/learning/`
+</success_criteria>

package/.claude/commands/maestro-link-coordinate.md

@@ -1,6 +1,6 @@
 ---
 name: maestro-link-coordinate
-description: Step-mode graph coordinator via maestro coordinate endpoint — executes chain nodes one by one with session tracking
+description: Execute command chain nodes step by step
 argument-hint: "\"intent text\" [--list] [-c [sessionId]] [--chain <name>] [--tool <tool>] [-y]"
 allowed-tools:
   - Read

package/.claude/commands/maestro-merge.md

@@ -1,61 +1,61 @@
----
-name: maestro-merge
-description: Two-phase merge of milestone worktree branch back — git merge first, scratch artifact sync only on success
-argument-hint: "-m <milestone-number> [--force] [--dry-run] [--no-cleanup] [--continue]"
-allowed-tools:
-  - Read
-  - Write
-  - Edit
-  - Bash
-  - Glob
-  - Grep
-  - Agent
-  - AskUserQuestion
----
-<purpose>
-Merge a completed milestone worktree branch back into the main branch, sync scratch artifacts, and reconcile the artifact registry. Uses a two-phase approach: git merge first (source code), artifact sync second (only after git succeeds). This prevents partial state corruption when merge conflicts occur.
-
-Includes registry health check, pre-merge rebase (pull main into worktree to minimize conflicts), and atomic state reconciliation (merge artifact entries, don't overwrite).
-</purpose>
-
-<required_reading>
-@~/.maestro/workflows/merge.md
-</required_reading>
-
-<context>
-$ARGUMENTS -- milestone number and optional flags.
-
-Flags (`-m`, `--force`, `--dry-run`, `--no-cleanup`, `--continue`), merge sequence, artifact sync detail, and conflict handling are defined in workflow `merge.md`.
-</context>
-
-<execution>
-Follow '~/.maestro/workflows/merge.md' completely.
-
-**Next-step routing on completion:**
-- View dashboard → Skill({ skill: "manage-status" })
-- Audit milestone → Skill({ skill: "maestro-milestone-audit" })
-</execution>
-
-<error_codes>
-| Code | Severity | Condition | Recovery |
-|------|----------|-----------|----------|
-| E001 | error | Running inside a worktree | Run from main worktree |
-| E002 | error | No worktree registry found | Nothing to merge |
-| E003 | error | --continue but no merge state | Start fresh merge |
-| E004 | error | No milestone number provided | Provide `-m <N>` |
-| W001 | warning | Stale registry entries found | Auto-cleaned |
-| W002 | warning | Incomplete artifacts (without --force) | Confirm or use --force |
-| W003 | warning | Conflict pulling main into worktree | Resolve in worktree first |
-</error_codes>
-
-<success_criteria>
-- [ ] Registry health check passed (stale entries cleaned)
-- [ ] Pre-merge rebase successful (worktree has latest main)
-- [ ] Git merge completed without conflicts (or conflicts resolved via --continue)
-- [ ] All scratch artifacts synced to main `.workflow/scratch/`
-- [ ] `state.json.artifacts[]` reconciled (worktree entries merged into main)
-- [ ] Milestone `"forked"` flag removed in `state.json.milestones[]`
-- [ ] `roadmap.md` completed phases marked
-- [ ] Worktree removed and branch deleted (unless --no-cleanup)
-- [ ] `worktrees.json` registry updated (entry removed)
-</success_criteria>
+---
+name: maestro-merge
+description: Merge milestone worktree branch back to main
+argument-hint: "-m <milestone-number> [--force] [--dry-run] [--no-cleanup] [--continue]"
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Glob
+  - Grep
+  - Agent
+  - AskUserQuestion
+---
+<purpose>
+Merge a completed milestone worktree branch back into the main branch, sync scratch artifacts, and reconcile the artifact registry. Uses a two-phase approach: git merge first (source code), artifact sync second (only after git succeeds). This prevents partial state corruption when merge conflicts occur.
+
+Includes registry health check, pre-merge rebase (pull main into worktree to minimize conflicts), and atomic state reconciliation (merge artifact entries, don't overwrite).
+</purpose>
+
+<required_reading>
+@~/.maestro/workflows/merge.md
+</required_reading>
+
+<context>
+$ARGUMENTS -- milestone number and optional flags.
+
+Flags (`-m`, `--force`, `--dry-run`, `--no-cleanup`, `--continue`), merge sequence, artifact sync detail, and conflict handling are defined in workflow `merge.md`.
+</context>
+
+<execution>
+Follow '~/.maestro/workflows/merge.md' completely.
+
+**Next-step routing on completion:**
+- View dashboard → Skill({ skill: "manage-status" })
+- Audit milestone → Skill({ skill: "maestro-milestone-audit" })
+</execution>
+
+<error_codes>
+| Code | Severity | Condition | Recovery |
+|------|----------|-----------|----------|
+| E001 | error | Running inside a worktree | Run from main worktree |
+| E002 | error | No worktree registry found | Nothing to merge |
+| E003 | error | --continue but no merge state | Start fresh merge |
+| E004 | error | No milestone number provided | Provide `-m <N>` |
+| W001 | warning | Stale registry entries found | Auto-cleaned |
+| W002 | warning | Incomplete artifacts (without --force) | Confirm or use --force |
+| W003 | warning | Conflict pulling main into worktree | Resolve in worktree first |
+</error_codes>
+
+<success_criteria>
+- [ ] Registry health check passed (stale entries cleaned)
+- [ ] Pre-merge rebase successful (worktree has latest main)
+- [ ] Git merge completed without conflicts (or conflicts resolved via --continue)
+- [ ] All scratch artifacts synced to main `.workflow/scratch/`
+- [ ] `state.json.artifacts[]` reconciled (worktree entries merged into main)
+- [ ] Milestone `"forked"` flag removed in `state.json.milestones[]`
+- [ ] `roadmap.md` completed phases marked
+- [ ] Worktree removed and branch deleted (unless --no-cleanup)
+- [ ] `worktrees.json` registry updated (entry removed)
+</success_criteria>

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

@@ -1,96 +1,96 @@
----
-name: maestro-milestone-release
-description: Version bump, changelog generation, and git tag for a completed 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.
-</purpose>
-
-<required_reading>
-@~/.maestro/workflows/milestone-release.md
-</required_reading>
-
-<context>
-$ARGUMENTS -- optional explicit version string and flags.
-
-**Flags:**
-- `<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 (default: `minor`)
-- `--dry-run` -- compute the next version, changelog diff, and tag name without writing files or creating tags
-- `--no-tag` -- skip git tag creation (version bump + changelog only)
-- `--no-push` -- skip `git push --follow-tags` after tagging
-
-**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>
-
-<execution>
-Follow '~/.maestro/workflows/release.md' completely.
-
-**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`)
-
-**Report format on completion:**
-```
-=== 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
-
-Next steps:
-  /maestro-plan {next_phase}   -- Start next milestone's first phase
-  /manage-status               -- View project dashboard
-```
-
-For `--dry-run`, print the computed version, changelog diff, and tag name without side effects.
-</execution>
-
-<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. 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.
+</purpose>
+
+<required_reading>
+@~/.maestro/workflows/milestone-release.md
+</required_reading>
+
+<context>
+$ARGUMENTS -- optional explicit version string and flags.
+
+**Flags:**
+- `<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 (default: `minor`)
+- `--dry-run` -- compute the next version, changelog diff, and tag name without writing files or creating tags
+- `--no-tag` -- skip git tag creation (version bump + changelog only)
+- `--no-push` -- skip `git push --follow-tags` after tagging
+
+**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>
+
+<execution>
+Follow '~/.maestro/workflows/release.md' completely.
+
+**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`)
+
+**Report format on completion:**
+```
+=== 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
+
+Next steps:
+  /maestro-plan {next_phase}   -- Start next milestone's first phase
+  /manage-status               -- View project dashboard
+```
+
+For `--dry-run`, print the computed version, changelog diff, and tag name without side effects.
+</execution>
+
+<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>