From f6a7b9f497ddf40d8a849faa6a7f92d18f9c5399 Mon Sep 17 00:00:00 2001 From: Tom Boucher Date: Tue, 7 Apr 2026 17:26:33 -0400 Subject: [PATCH] fix(milestone): prevent data loss and Backlog drop on milestone completion (#1940) - Reorder reorganize_roadmap_and_delete_originals to commit archive files as a safety checkpoint BEFORE removing any originals (fixes #1913) - Use overwrite-in-place for ROADMAP.md instead of delete-then-recreate - Use git rm for REQUIREMENTS.md to stage deletion atomically with history - Add 3-step Backlog preservation protocol: extract before rewrite, re-append after, skip silently if absent (fixes #1914) - Update success_criteria and archival_behavior to reflect new ordering --- get-shit-done/workflows/complete-milestone.md | 53 +++++++++++++------ 1 file changed, 38 insertions(+), 15 deletions(-) diff --git a/get-shit-done/workflows/complete-milestone.md b/get-shit-done/workflows/complete-milestone.md index 170cab139..d0d91e3b3 100644 --- a/get-shit-done/workflows/complete-milestone.md +++ b/get-shit-done/workflows/complete-milestone.md @@ -20,8 +20,8 @@ When a milestone completes: 1. Extract full milestone details to `.planning/milestones/v[X.Y]-ROADMAP.md` 2. Archive requirements to `.planning/milestones/v[X.Y]-REQUIREMENTS.md` -3. Update ROADMAP.md — replace milestone details with one-line summary -4. Delete REQUIREMENTS.md (fresh one for next milestone) +3. Update ROADMAP.md — overwrite in place with milestone grouping (preserve Backlog section) +4. Safety commit archive files + updated ROADMAP.md, then `git rm REQUIREMENTS.md` (fresh for next milestone) 5. Perform full PROJECT.md evolution review 6. Offer to create next milestone inline 7. Archive UI artifacts (`*-UI-SPEC.md`, `*-UI-REVIEW.md`) alongside other phase documents @@ -400,18 +400,29 @@ Verify: `✅ Phase directories archived to .planning/milestones/v[X.Y]-phases/` If "Skip": Phase directories remain in `.planning/phases/` as raw execution history. Use `/gsd-cleanup` later to archive retroactively. After archival, the AI still handles: -- Reorganizing ROADMAP.md with milestone grouping (requires judgment) +- Reorganizing ROADMAP.md with milestone grouping (requires judgment) — overwrite in place after extracting Backlog section - Full PROJECT.md evolution review (requires understanding) -- Deleting original ROADMAP.md and REQUIREMENTS.md +- Safety commit of archive files + updated ROADMAP.md, then `git rm .planning/REQUIREMENTS.md` - These are NOT fully delegated because they require AI interpretation of content -After `milestone complete` has archived, reorganize ROADMAP.md with milestone groupings, then delete originals: +After `milestone complete` has archived, reorganize ROADMAP.md with milestone groupings, then commit archives as a safety checkpoint before removing originals. -**Reorganize ROADMAP.md** — group completed milestone phases: +**Backlog preservation — do this FIRST before rewriting ROADMAP.md:** + +Extract the Backlog section from the current ROADMAP.md before making any changes: + +```bash +# Extract lines under ## Backlog through end of file (or next ## section) +BACKLOG_SECTION=$(awk '/^## Backlog/{found=1} found{print}' .planning/ROADMAP.md) +``` + +If `$BACKLOG_SECTION` is empty, there is no Backlog section — skip silently. + +**Reorganize ROADMAP.md** — overwrite in place (do NOT delete first) with milestone groupings: ```markdown # Roadmap: [Project Name] @@ -432,11 +443,22 @@ After `milestone complete` has archived, reorganize ROADMAP.md with milestone gr ``` -**Then delete originals:** +**Re-append Backlog section after the rewrite** (only if `$BACKLOG_SECTION` was non-empty): + +Append the extracted Backlog content verbatim to the end of the newly written ROADMAP.md. This ensures 999.x backlog items are never silently dropped during milestone reorganization. + +**Safety commit — commit archive files BEFORE deleting any originals:** ```bash -rm .planning/ROADMAP.md -rm .planning/REQUIREMENTS.md +node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" commit "chore: archive v[X.Y] milestone files" --files .planning/milestones/v[X.Y]-ROADMAP.md .planning/milestones/v[X.Y]-REQUIREMENTS.md .planning/milestones/v[X.Y]-MILESTONE-AUDIT.md .planning/MILESTONES.md .planning/PROJECT.md .planning/STATE.md .planning/ROADMAP.md +``` + +This creates a durable checkpoint in git history. If anything fails after this point, the working tree can be reconstructed from git. + +**Remove REQUIREMENTS.md via git rm** (preserves history, stages deletion atomically): + +```bash +git rm .planning/REQUIREMENTS.md ``` @@ -686,14 +708,13 @@ git push origin v[X.Y] -Commit milestone completion. +Commit the REQUIREMENTS.md deletion (archive files and ROADMAP.md were already committed in the safety commit in `reorganize_roadmap_and_delete_originals`). ```bash -node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" commit "chore: complete v[X.Y] milestone" --files .planning/milestones/v[X.Y]-ROADMAP.md .planning/milestones/v[X.Y]-REQUIREMENTS.md .planning/milestones/v[X.Y]-MILESTONE-AUDIT.md .planning/MILESTONES.md .planning/PROJECT.md .planning/STATE.md -``` +git commit -m "chore: remove REQUIREMENTS.md for v[X.Y] milestone" ``` -Confirm: "Committed: chore: complete v[X.Y] milestone" +Confirm: "Committed: chore: remove REQUIREMENTS.md for v[X.Y] milestone" @@ -759,10 +780,12 @@ Milestone completion is successful when: - [ ] PROJECT.md full evolution review completed - [ ] All shipped requirements moved to Validated in PROJECT.md - [ ] Key Decisions updated with outcomes -- [ ] ROADMAP.md reorganized with milestone grouping +- [ ] ROADMAP.md Backlog section extracted before rewrite, re-appended after (skipped if absent) +- [ ] ROADMAP.md reorganized with milestone grouping (overwritten in place, not deleted) - [ ] Roadmap archive created (milestones/v[X.Y]-ROADMAP.md) - [ ] Requirements archive created (milestones/v[X.Y]-REQUIREMENTS.md) -- [ ] REQUIREMENTS.md deleted (fresh for next milestone) +- [ ] Safety commit made (archive files + updated ROADMAP.md) BEFORE deleting REQUIREMENTS.md +- [ ] REQUIREMENTS.md removed via `git rm` (fresh for next milestone, history preserved) - [ ] STATE.md updated with fresh project reference - [ ] Git tag created (v[X.Y]) - [ ] Milestone commit made (includes archive files and deletion)