Revert -- Git-Aware Undo

Safely revert implementation work at track, phase, or task granularity. Updates plan state to reflect the rollback.

Arguments

$ARGUMENTS

• <track>: Track name or ID (optional -- if omitted, enter Guided Selection)
• --phase <N>: Revert only phase N (optional)
• --task <name>: Revert only a specific task (optional)
• No scope flag: revert the entire track

---

Step 1: Parse Target Scope

Determine what to revert:

• Track-level: No --phase or --task flag. Revert all commits in the track.
• Phase-level: --phase N specified. Revert commits from phase N only.
• Task-level: --task <name> specified. Revert a single task's commit.

If no <track> argument, proceed to Guided Selection.

Step 1a: Guided Selection (when no track argument)

Read .maestro/tracks.md and recent maestro git history (git log --oneline --since="7 days ago" --grep="maestro").

Present a menu grouped by track showing ID, description, status, and completed task count. If user provides a custom track ID, use that.

Step 2: Locate Track

Match track argument against IDs and descriptions in .maestro/tracks.md. If not found: report and stop.

Step 3: Resolve Commit SHAs

If metadata.json has beads_epic_id: use br list --status closed --parent {epic_id} --all --json and parse close_reason for SHAs (sha:{7char}), scoped by labels for --phase/--task. Otherwise: extract SHAs from plan.md. See reference/git-operations.md for full SHA resolution protocol (steps 3a-3c).

Step 4: Git Reconciliation

Verify each SHA exists, detect merge commits and cherry-pick duplicates. See reference/git-operations.md for reconciliation protocol (steps 4a-4b).

Step 5: Present Execution Plan

Show exactly what will be reverted with commit list, affected files, and plan updates. See reference/confirmation-and-plan.md for the plan format.

Step 6: Multi-Step Confirmation

Two-phase confirmation with optional plan revision loop. See reference/confirmation-and-plan.md for the confirmation protocol.

Step 7: Execute Reverts

Revert in reverse chronological order. Handle merge commits and conflicts. See reference/git-operations.md for execution protocol (step 7).

Steps 8-10: Update Plan State, Registry, and Verify

Reset plan markers, update registry status, run test suite. See reference/git-operations.md for details (steps 8-10).

If metadata.json has beads_epic_id, also reopen BR issues: br update {issue_id} --status open --json.

Step 11: Summary

Display revert summary with scope, commit counts, test results, and next steps. See reference/confirmation-and-plan.md for the summary format.

---

Relationship to Other Commands

Recommended workflow:

• /maestro:setup -- Scaffold project context (run first)
• /maestro:new-track -- Create a feature/bug track with spec and plan
• /maestro:implement -- Execute the implementation
• /maestro:review -- Verify implementation correctness
• /maestro:status -- Check progress across all tracks
• /maestro:revert -- You are here. Undo implementation if needed
• /maestro:note -- Capture decisions and context to persistent notepad

Revert is the safety valve for /maestro:implement. It undoes commits and resets plan state so you can re-implement with /maestro:implement. Use /maestro:status after reverting to confirm the track state is correct. Revert depends on atomic commits from implementation -- the cleaner the commit history, the more precise the revert.