Milestone Management

Milestones group tasks by iteration, version, or release cycle and are the core tool for tracking phase progress and planning roadmaps. Backlog.md stores milestone data as Markdown files in backlog/milestones/, under version control alongside task files.

Creating Milestones

Milestones can be created through the CLI, Web interface, or MCP.

CLI Creation

backlog milestone add "M3 - Web UI"

# Set description, dates, and linked documents in one command
backlog milestone add "M3 - Web UI" \
  --description "UI and interaction goals for this phase" \
  --due-date 2026-07-31 --planned-start 2026-07-01 --planned-end 2026-07-25 \
  --doc doc-5 --doc doc-8

--doc can be repeated to link multiple documents; empty values are rejected. created_date is written automatically on creation.

Web Interface Creation

1. Start the Web interface with backlog browser.
2. Click "Milestones" in the navigation bar to enter the milestone management page.
3. Click the "Add Milestone" button and enter the milestone name (for example M3 - Web UI).
4. The description field supports Markdown editing, Mermaid preview, and paste-upload images (images are automatically promoted to paste/ before saving).
5. Click save; the system generates the corresponding milestone file under backlog/milestones/.

Tip: AI agents can create milestones directly through the MCP milestone_add tool without opening the browser.

Editing Milestones

Edit a milestone's title, description, and date fields through the CLI:

backlog milestone edit M1 --title "M1 - Core CLI" --description "Phase 1 goals" \
  --due-date 2026-06-30 --planned-start 2026-05-01 --planned-end 2026-06-15 \
  --actual-start "2026-05-01 09:00" --actual-end "2026-06-10 18:00"

# Clear date fields
backlog milestone edit M1 --clear-due-date --clear-planned-end --clear-actual-start

• Milestones can be located by title or ID (fuzzy matching).
• Planned fields (dueDate / plannedStart / plannedEnd) use the format YYYY-MM-DD.
• Actual fields (actualStart / actualEnd) use the format YYYY-MM-DD HH:MM (UTC).
• Passing an empty string clears the corresponding field.

Milestones also support document links consistent with tasks:

# Overwrite linked documents
backlog milestone edit M1 --doc doc-5

# Append / remove by value / clear
backlog milestone edit M1 --add-doc doc-8
backlog milestone edit M1 --remove-doc doc-5
backlog milestone edit M1 --clear-docs

--doc (set) and --add-doc (append) are mutually exclusive in the same command, and --clear-docs cannot be combined with other document flags; the rules are identical to task list-type fields. Adding or removing document links is a substantive change and refreshes updated_date.

Milestone Date Editing in the Web UI

Click a milestone card on the milestone management page to open the edit popup:

• Due Date / Planned Start / Planned End — date inputs.
• Actual Start / Actual End — datetime-local inputs.
• Documentation — linked document entries can be previewed directly inside the popup: local (non-URL) entries open an in-app file preview (shared with the task popup) when you click the preview control; http(s) entries remain external links that open in a new tab. The preview resets automatically when switching milestones and does not persist after the popup closes.

A milestone's actualStart / actualEnd are automatically driven by status changes of its child tasks:

• When any task under the milestone changes to In Progress, if actualStart is empty it is automatically set to the current date and time.
• When the last non-terminal task under the milestone changes to Done, if actualEnd is empty it is automatically set to the current date and time.
• You can override these auto-filled values manually at any time.

Milestone List and Details

View all milestones and their completion status in the terminal:

backlog milestone list

Example output:

Active milestones (2):
  m-1: M1 - CLI (8/12 done)
  m-2: M2 - MCP Support (3/5 done)

Completed milestones (1):
  (collapsed, use --show-completed to list)

Each milestone shows the ratio of completed tasks to total tasks, making progress clear at a glance.

Milestone ID display style: Milestone IDs are uniformly displayed in uppercase M-N form across all interfaces, aligned with the TASK-9 style for task IDs—the Web list and detail popup use an em dash (M-9 — Title), while the TUI milestone row and CLI milestone list --plain section headings use a hyphen (M-9 - Title, ## M-9 - Title (n tasks)). This is a display-layer change only; storage format and alias resolution (m-2, 2, M2, etc.) are unaffected.

Viewing Completed Milestones

By default, completed milestones are collapsed to reduce noise. To expand them:

backlog milestone list --show-completed

Plain-text output (good for scripts):

backlog milestone list --plain

# Paging window: unit is milestone
backlog milestone list --max-count 10
backlog milestone list --max-count 10 --skip 10
backlog milestone list --count

--plain output is a Markdown grouped board fully consistent with backlog board -m: first the "No Milestone" section, then sections by milestone file order, with tasks grouped under ### <status> (count) subheadings. Tasks in the completed directory are excluded by default; --show-completed includes them. Empty status columns are automatically narrowed.

TUI Milestone Board

Run backlog milestones in a TTY to enter the interactive milestone board: the left pane lists milestones (Space to restrict scope, Enter to view metadata, N to create), and the right pane is an embedded task board. The milestone detail popup supports pressing E to edit dates and description. See TUI Board for details.

Assigning Tasks to Milestones

There are three ways to assign a task to a milestone:

1. Specify at Task Creation

backlog task create "Implement board drag-and-drop" -m "M2 - MCP Support"

The -m option supports fuzzy matching; the system automatically finds the closest milestone. You can also use the milestone ID (such as m-2) or a plain number (such as 2).

2. Edit an Existing Task

backlog task edit 7 --milestone "M2 - MCP Support"

3. Filter the Task List by Milestone ID

In the milestone filter of backlog task list, you can locate milestones in several forms:

# Numeric alias
backlog task list -m 2

# Canonical ID
backlog task list -m m-2

# Case variants
backlog task list -m "M2"

# Exact or partial title match
backlog task list -m "MCP Support"

Filter parsing supports numeric aliases, canonical IDs (m-N), case variants, and titles with punctuation. Behavior is consistent across the CLI, interactive task list, and MCP task_list active/draft paths. If the query matches no milestone, an empty list is returned.

4. Clear Milestone Assignment

backlog task edit 7 --clear-milestone

5. Web Interface Drag-and-Drop Assignment

On the Web milestone management page, the "Unassigned task pool" shows all tasks without a milestone. Drag a task card onto a target milestone card to assign it; drag in the opposite direction to remove it.

Milestone Completion Detection and Archiving

Automatic Completion Detection

When all tasks under a milestone enter the Done status, the system automatically marks the milestone as completed. In backlog milestone list, it moves from the "Active milestones" area to the "Completed milestones" area.

Archiving Milestones

Completed milestones that remain in the active list for a long time accumulate noise. You can archive them:

backlog milestone archive "M1 - CLI"

After archiving:

• The milestone is removed from the active milestone list.
• Its tasks automatically become "unassigned" (the tasks themselves are not deleted; only the milestone binding is removed).
• The file is moved into the archive area and its ID no longer participates in fuzzy matching.

Archiving supports locating the milestone by title or ID:

backlog milestone archive m-1
backlog milestone archive 1

Archiving does not modify any task files—tasks keep their reference to the milestone. If you want to clear or reassign the milestone field on tasks at the same time, use remove (see next section).

created_date and updated_date

Milestones automatically maintain two timestamps, just like tasks:

• created_date: written at creation time (UTC, YYYY-MM-DD HH:MM).
• updated_date: refreshed only on substantive changes—pure ordering adjustments do not refresh it, but adding or removing document links does.

backlog milestone list appends (updated ...) after each entry (falling back to (created ...) when there is no update record); MCP milestone_list shows Created: / Updated: labels. Historical files missing these fields do not cause errors; display falls back to created_date. The Web interface shows "Last updated" on milestone cards and "Created / Updated" in the detail popup header.

Removing a Milestone (remove)

In addition to archive, there is remove. Both move the milestone file into the archive directory; the difference is whether task files' milestone fields are processed:

# Default: clear the milestone field on matching tasks
backlog milestone remove "Release 1.0"

# Keep task milestone references
backlog milestone remove "Release 1.0" --task-handling keep

# Reassign to another active milestone
backlog milestone remove "Release 1.0" --task-handling reassign --reassign-to "Release 2.0"

Unassigned Task Pool

Tasks that do not belong to any active milestone form the "unassigned task pool". On the Web milestone page these tasks are shown together at the top of the page, making it easy to:

• Quickly review work items that have not yet been included in iteration planning.
• Batch drag-and-drop them to the right milestone.
• Identify omissions or tasks that need to be rescheduled.

In the terminal, unassigned tasks are not shown in backlog milestone list, but you can view them through filtering:

backlog task list --milestone ""

Grouping the Board by Milestone

Both the TUI board and Web board support milestone grouping mode:

# TUI board displays milestone swimlanes
backlog board --milestones

In this mode the board no longer only groups by status; instead, tasks in each column are arranged in horizontal swimlanes by milestone, helping you visually compare remaining work across iterations.