ijfw-complete-milestone

name	ijfw-complete-milestone
description	Use when a milestone is shipping and you need to archive its artifacts, generate a summary, and seed the next milestone. Trigger: 'milestone complete', 'ship milestone', 'wrap milestone', 'complete milestone <id>', /ijfw-complete-milestone.
since	1.5.0

Archive a completed milestone, capture what shipped, and surface the next milestone. Domain-agnostic -- a milestone may be a software release, a book part, a campaign wave, a design-system tier, or any other top-level project unit defined in .planning/ROADMAP.md.

Inputs

• Milestone identifier (e.g. 1.5.0, part-two, wave-3). If the user did not name one, ask once: Which milestone are we wrapping? Accept any string that appears as a milestone heading in .planning/ROADMAP.md.

Process

1. Verify completion.

   • Read .planning/ROADMAP.md. Find the milestone block for <id>.
   • List every phase under that milestone. For each phase, check that it is marked complete (e.g. [x], status: complete, shipped, or has a SUMMARY.md in .planning/<milestone>/<phase>/).
   • If any phase is incomplete: surface the gap and ask Proceed anyway and treat the open phase as deferred? (y / fix first). Do not auto-advance.

2. Extract learnings (dispatch agent).

   • Dispatch ijfw-extract-learnings with the milestone scope. The agent reads every SUMMARY.md, RETRO.md, and commit message in .planning/<milestone>/** and writes .planning/<milestone>/LEARNINGS.md (decisions, surprises, patterns, lessons).
   • If the agent is unavailable in this runtime, write a stub LEARNINGS.md with _pending: dispatch ijfw-extract-learnings when available_ and surface the gap.

3. Generate milestone summary (dispatch skill).

   • Dispatch ijfw-milestone-summary with <id>. The skill writes .planning/<milestone>/SUMMARY.md -- stats, accomplishments, timeline, contributors -- suitable for a release post, book-part wrap, campaign retro, or design-tier handoff.
   • Paste the summary's first 6 lines in-chat so the user sees what landed.

4. Confirm with user.

   • Show: milestone id, phase count, days elapsed (first → last commit in scope), first line of SUMMARY.md, first 3 LEARNINGS entries.
   • Ask: Archive and seed next milestone? (yes / show full summary / hold).
   • On hold: stop. The artifacts remain in place; the user can re-run later.

5. Archive artifacts.

   • Move .planning/<milestone>/ → .planning/_archive/<milestone>/. Preserve full directory tree. Create .planning/_archive/ if absent.
   • Leave SUMMARY.md and LEARNINGS.md discoverable at .planning/_archive/<milestone>/SUMMARY.md and .planning/_archive/<milestone>/LEARNINGS.md.
   • Never delete -- only move. Archive is the historical record.

6. Update ROADMAP.md.

   • Collapse the milestone block to a single line:

     - [x] <id> -- shipped <YYYY-MM-DD>. See `.planning/_archive/<id>/SUMMARY.md`.
     

   • If a next milestone is already drafted in ROADMAP.md, mark it [ ] <next-id> -- next so it is visually surfaced.
   • If no next milestone exists, append:

     - [ ] _next milestone_ -- run `/ijfw-workflow` or `/gsd-new-milestone` to define.
     

7. Write memory entry.

   • Call ijfw_memory_store with:
     • key: milestone_<id>_shipped
     • value: first 200 chars of SUMMARY.md plus the line count of LEARNINGS.md
     • tags: ['milestone', 'shipped', <id>]
   • If the MCP tool is unavailable, append the same entry to .ijfw/memory/MEMORY.md under a ## Milestones Shipped section.

8. Tag the commit (optional, with confirmation).

   • Ask: Tag this commit as 'milestone-<id>'? (y / custom / skip).
   • On y: run git tag -a milestone-<id> -m "<first line of SUMMARY.md>".
   • On custom: accept the user's tag string, then tag.
   • On skip: continue without tagging.
   • Never push the tag automatically. Surface the push command: git push origin milestone-<id>.

9. Commit the archive + roadmap change.

   • Stage .planning/_archive/<milestone>/, .planning/ROADMAP.md, and .ijfw/memory/MEMORY.md (if touched).
   • Commit message:

     chore(milestone): archive <id> + seed next milestone
     
     - LEARNINGS.md captured (<N> entries)
     - SUMMARY.md captured (<M> lines)
     - ROADMAP.md collapsed to one-line entry
     - Memory: milestone_<id>_shipped
     

   • Surface the SHA back to the user.

10. Closer.

    • One-line receipt:

      You went from <id> open with <N> phases to archived with summary, learnings, memory, and tag in <M> minutes.

    • Suggest the next move: Run /ijfw-workflow to plan the next milestone, or /gsd-new-milestone for the full questioning loop.

Critical rules

• Archive before mutating. Always move .planning/<milestone>/ to .planning/_archive/<milestone>/ before collapsing ROADMAP.md. If the archive move fails, abort the roadmap edit.
• One-line ROADMAP entry. Collapsed milestones must be a single line with a link to the archive. This keeps ROADMAP.md constant-size as the project grows.
• No silent skips. If a phase is incomplete, the user must say proceed -- never assume.
• Memory is mandatory. A shipped milestone the next session can't recall is a workflow failure. If ijfw_memory_store is unavailable, fall back to the markdown append; never skip.
• Tags are user-gated. Never tag without explicit y. Never push tags.
• Domain agnostic. Phases in a book milestone (chapters), a campaign milestone (channels), or a design-system milestone (tiers) all use the same archive path and lifecycle -- do not hardcode software vocabulary.

Output contract

Final message to the user, in this order:

1. Receipt line (You went from ...).
2. Archive path (.planning/_archive/<id>/).
3. Commit SHA.
4. Tag (if created) and the push command.
5. Suggested next move.