Ijfw Milestone Summary

Produce an onboarding doc for someone joining mid-stream. Output: .planning/<milestone>/SUMMARY.md.

Domain-agnostic: "what shipped" means chapters drafted for a book, launches that landed for a campaign, features released for software, episodes recorded for a podcast. Adapt the noun to the project type.

Step 1 -- Resolve milestone

Argument is the milestone slug (e.g. 1.5.0, q2-launch, book-draft-2). If absent:

1. Read .ijfw/state/workflow.json -- use the current milestone field.
2. Else read .planning/ROADMAP.md -- pick the active milestone.
3. Else list directories under .planning/ and ask which one.

Set MS="<resolved-slug>". Set OUT=".planning/${MS}/SUMMARY.md".

Step 2 -- Inventory artifacts

Read whatever exists, skip whatever doesn't. Missing files are normal -- the doc adapts.

• .planning/ROADMAP.md -- scope, dates, status of each item.
• .planning/${MS}/SUMMARY.md -- prior version (overwrite guard, see Step 6).
• .planning/${MS}/**/SUMMARY.md -- per-item outcomes.
• .planning/${MS}/**/LEARNINGS.md -- per-item decisions (written by ijfw-extract-learnings / C06).
• .planning/${MS}/**/VERIFICATION.md -- gaps, deferred items.
• CHANGELOG.md -- the ${MS} entry if present.
• Git log for the milestone tag range:
  • If v${MS} tag exists: git log --oneline v${MS} and git log v${MS}~1..v${MS} --stat.
  • Else: git log --since="<earliest .planning/${MS}/ commit date>" --oneline.
  • Else: skip git stats.

Step 3 -- Synthesize

Compose the doc with these six sections in this order. Plain English. No jargon a new contributor wouldn't know.

What shipped

One paragraph, 3-5 sentences. Lead with the user-visible outcome ("v1.5.0 shipped runtime honesty + pluggability completion -- the workflow now self-audits, dispatches parallel subagents, and runs cross-model critique unattended"). Avoid implementation detail. Adapt the noun:

• software: features shipped
• book: chapters drafted, edits landed
• campaign: launches that landed, channels lit up
• podcast: episodes recorded and published
• research: papers drafted, experiments concluded

Scope shipped

Table of items in the milestone -> outcome. Pull item names from ROADMAP.md scope list; pull outcomes from per-item SUMMARY.md one_liner (fall back to first H1 sentence). Status column: done | partial | deferred.

| Item   | Outcome                          | Status   |
|--------|----------------------------------|----------|
| <name> | <one-liner>                      | done     |

Scope deferred

List items that were planned but cut. For each: name, one-line rationale (from LEARNINGS.md "deferred" sections, RETROSPECTIVE.md, or VERIFICATION.md gaps), and where it lives next (v<next> backlog, indefinitely parked, etc.).

If nothing was deferred: say so in one line. Do not pad.

Key decisions

Aggregate from per-item LEARNINGS.md. For each decision: one-line restatement + link to the source file. Format:

- **<decision>** -- <one-line rationale>. See [<phase>/LEARNINGS.md](<relative-path>).

Top 5-7 only. If LEARNINGS.md files are absent (C06 hasn't run), fall back to CONTEXT.md or SUMMARY.md "decisions" sections; if neither, list the empty section with a one-line note "decisions log not captured for this milestone".

Known gaps / followups

From VERIFICATION.md gaps, RETROSPECTIVE.md "what to improve", and any open issues tagged with the milestone. Each item: one line, with severity if obvious (blocking | annoying | nice-to-have).