BACK-400 - Add milestone filter support to task list (CLI and MCP) (#552)

## Summary
- add CLI task list -m, --milestone <milestone> filter wiring
- extend shared TaskListFilter + core filtering for case-insensitive
exact milestone matching
- add MCP task_list milestone schema/handler support, including Draft
status path
- add/extend tests for CLI and MCP milestone filtering behavior

## Verification
- bun test src/test/cli-milestone-filter.test.ts
- bun test src/test/mcp-tasks.test.ts
- bun test src/test/cli-parent-filter.test.ts
- bun test src/test/mcp-tasks-local-filter.test.ts
- bunx tsc --noEmit
- bun run check .

## Scope
Solves #546

Author: MrLesk

backlog/tasks/back-400 - Add-milestone-filter-support-to-task-list-CLI-and-MCP.md

@@ -1,10 +1,11 @@
 ---
 id: BACK-400
 title: Add milestone filter support to task list (CLI and MCP)
-status: To Do
-assignee: []
+status: Done
+assignee:
+  - '@codex'
 created_date: '2026-03-01 20:26'
-updated_date: '2026-03-01 20:28'
+updated_date: '2026-03-01 20:43'
 labels:
   - cli
   - mcp
@@ -16,6 +17,7 @@ references:
   - /Users/alex/projects/Backlog.md/src/types/index.ts
   - /Users/alex/projects/Backlog.md/src/mcp/tools/tasks/schemas.ts
   - /Users/alex/projects/Backlog.md/src/mcp/tools/tasks/handlers.ts
+  - 'https://github.com/MrLesk/Backlog.md/issues/546'
 priority: medium
 ---
 
@@ -27,17 +29,102 @@ Enable users and MCP clients to filter tasks by milestone in listing workflows.
 
 ## Acceptance Criteria
 <!-- AC:BEGIN -->
-- [ ] #1 CLI `task list` supports `-m, --milestone <milestone>` and applies milestone filtering alongside existing filters.
-- [ ] #2 Core task filtering supports milestone matching as a case-insensitive exact match, consistent with existing status/priority filtering style.
-- [ ] #3 MCP `task_list` accepts a `milestone` parameter in its input schema without validation errors.
-- [ ] #4 MCP `task_list` applies the milestone filter and returns only tasks whose milestone matches the requested value.
-- [ ] #5 Automated tests cover CLI and MCP milestone filter behavior, including case-insensitive matching and combination with at least one existing filter.
-- [ ] #6 Existing task listing behavior is unchanged when no milestone filter is provided.
+- [x] #1 CLI `task list` supports `-m, --milestone <milestone>` and applies milestone filtering alongside existing filters.
+- [x] #2 Core task filtering supports milestone matching as a case-insensitive exact match, consistent with existing status/priority filtering style.
+- [x] #3 MCP `task_list` accepts a `milestone` parameter in its input schema without validation errors.
+- [x] #4 MCP `task_list` applies the milestone filter and returns only tasks whose milestone matches the requested value.
+- [x] #5 Automated tests cover CLI and MCP milestone filter behavior, including case-insensitive matching and combination with at least one existing filter.
+- [x] #6 Existing task listing behavior is unchanged when no milestone filter is provided.
 <!-- AC:END -->
 
+## Implementation Plan
+
+<!-- SECTION:PLAN:BEGIN -->
+1. Extend task list filter contract and core filtering.
+- Update `TaskListFilter` in `src/types/index.ts` to include optional `milestone`.
+- Add milestone filtering in `Core.applyTaskFilters` (`src/core/backlog.ts`) as a case-insensitive exact match, aligned with current status/priority filter semantics.
+- Keep behavior unchanged when `milestone` is not provided.
+
+2. Wire CLI `task list` milestone filter.
+- Add `-m, --milestone <milestone>` option to `task list` in `src/cli.ts`.
+- Include `options.milestone` in `baseFilters` passed to `core.queryTasks`.
+- Include milestone in active-filter display text and `runUnifiedView` filter payload so TUI header/filter state reflects the new flag.
+- Preserve existing parent/sort/error behavior.
+
+3. Wire MCP `task_list` milestone filter end-to-end.
+- Add `milestone` to `taskListSchema` in `src/mcp/tools/tasks/schemas.ts` so the tool accepts the field.
+- Extend `TaskListArgs` in `src/mcp/tools/tasks/handlers.ts` with optional `milestone`.
+- Add `filters.milestone` in the non-draft `task_list` handler before calling `core.queryTasks`.
+- Apply the same milestone filter in the draft branch for consistent `task_list` behavior when `status: Draft` is requested.
+
+4. Add automated coverage for CLI and MCP milestone filtering.
+- Add/extend CLI tests (likely new focused test file under `src/test/`) to verify:
+  - milestone filtering returns only matching tasks,
+  - matching is case-insensitive,
+  - milestone filter combines correctly with an existing filter (status),
+  - listing behavior remains unchanged without `--milestone`.
+- Add/extend MCP tests (likely `src/test/mcp-tasks.test.ts`) to verify:
+  - `task_list` accepts `milestone` without schema errors,
+  - milestone filtering works and is case-insensitive,
+  - milestone combines with at least one existing filter.
+
+5. Validate and regression-check.
+- Run targeted tests for changed CLI/MCP suites first.
+- Run `bunx tsc --noEmit` and scoped `bun test` for changed files; run broader checks if targeted results indicate regressions.
+- Confirm no output/behavior changes when milestone filter is omitted.
+<!-- SECTION:PLAN:END -->
+
+## Implementation Notes
+
+<!-- SECTION:NOTES:BEGIN -->
+TPM directive: treat GitHub issue #546 as authoritative scope anchor for this task.
+
+Implementation started after TPM approval. Proceeding with focused scope: CLI task list + MCP task_list + shared core filter path; raw milestone exact match (case-insensitive), including Draft task_list path.
+
+Implemented milestone filtering for task listing across CLI and MCP using the shared `TaskListFilter` + `Core.applyTaskFilters` path with case-insensitive exact raw milestone matching.
+
+CLI updates: added `task list -m, --milestone <milestone>`; wired milestone into `baseFilters`, active filter display text, and unified-view filter payload.
+
+MCP updates: `task_list` schema now accepts `milestone`; handler applies milestone filter in both regular and Draft status paths.
+
+Added automated coverage: new `src/test/cli-milestone-filter.test.ts` and new milestone-focused MCP integration tests in `src/test/mcp-tasks.test.ts` (including Draft path).
+
+Verification evidence: `bun test src/test/cli-milestone-filter.test.ts` (pass), `bun test src/test/mcp-tasks.test.ts` (pass), `bun test src/test/cli-parent-filter.test.ts` (pass regression), `bun test src/test/mcp-tasks-local-filter.test.ts` (pass regression), `bunx tsc --noEmit` (pass), `bun run check .` (pass after formatting).
+
+User-perspective verification: manual CLI run shows `task list --milestone RELEASE-1 --plain` returns only Release-1 tasks; `task list -m release-1 --status "To Do" --plain` returns only matching To Do task; `task list --plain` remains unchanged. Manual MCP call verifies `task_list` accepts `milestone` and filters both regular and Draft paths.
+<!-- SECTION:NOTES:END -->
+
+## Final Summary
+
+<!-- SECTION:FINAL_SUMMARY:BEGIN -->
+Implemented milestone filtering for task listing across CLI and MCP, aligned to issue #546 scope.
+
+What changed:
+- Added `milestone?: string` to `TaskListFilter` and implemented case-insensitive exact raw milestone matching in `Core.applyTaskFilters`.
+- Added CLI support for `task list -m, --milestone <milestone>` and wired it through task query filters, active filter labels, and unified-view filter state.
+- Extended MCP `task_list` schema to accept `milestone` and updated handler logic to apply milestone filtering in both regular task listing and Draft-status listing paths.
+- Added automated test coverage:
+  - New `src/test/cli-milestone-filter.test.ts` for CLI milestone filtering, case-insensitive matching, combined filter behavior, and no-filter regression behavior.
+  - Extended `src/test/mcp-tasks.test.ts` with milestone filtering tests for normal and Draft task_list paths.
+
+Verification run:
+- `bun test src/test/cli-milestone-filter.test.ts`
+- `bun test src/test/mcp-tasks.test.ts`
+- `bun test src/test/cli-parent-filter.test.ts`
+- `bun test src/test/mcp-tasks-local-filter.test.ts`
+- `bunx tsc --noEmit`
+- `bun run check .`
+
+Manual user-perspective verification:
+- CLI: `task list --milestone RELEASE-1 --plain` returned only Release-1 tasks.
+- CLI: `task list -m release-1 --status "To Do" --plain` returned only matching To Do task.
+- CLI: `task list --plain` remained unchanged when no milestone filter was provided.
+- MCP: direct tool calls confirmed `task_list` accepts `milestone` and filters in both regular and Draft paths.
+<!-- SECTION:FINAL_SUMMARY:END -->
+
 ## Definition of Done
 <!-- DOD:BEGIN -->
-- [ ] #1 bunx tsc --noEmit passes when TypeScript touched
-- [ ] #2 bun run check . passes when formatting/linting touched
-- [ ] #3 bun test (or scoped test) passes
+- [x] #1 bunx tsc --noEmit passes when TypeScript touched
+- [x] #2 bun run check . passes when formatting/linting touched
+- [x] #3 bun test (or scoped test) passes
 <!-- DOD:END -->

src/cli.ts

@@ -51,6 +51,7 @@ import { viewTaskEnhanced } from "./ui/task-viewer-with-search.ts";
 import { scrollableViewer } from "./ui/tui.ts";
 import { type AgentSelectionValue, processAgentSelection } from "./utils/agent-selection.ts";
 import { findBacklogRoot } from "./utils/find-backlog-root.ts";
+import { createMilestoneFilterValueResolver, resolveClosestMilestoneFilterValue } from "./utils/milestone-filter.ts";
 import { hasAnyPrefix } from "./utils/prefix-config.ts";
 import { type RuntimeCwdResolution, resolveRuntimeCwd } from "./utils/runtime-cwd.ts";
 import { formatValidStatuses, getCanonicalStatus, getValidStatuses } from "./utils/status.ts";
@@ -1755,6 +1756,7 @@ taskCmd
 	.description("list tasks grouped by status")
 	.option("-s, --status <status>", "filter tasks by status (case-insensitive)")
 	.option("-a, --assignee <assignee>", "filter tasks by assignee")
+	.option("-m, --milestone <milestone>", "filter tasks by milestone (closest match, case-insensitive)")
 	.option("-p, --parent <taskId>", "filter tasks by parent task ID")
 	.option("--priority <priority>", "filter tasks by priority (high, medium, low)")
 	.option("--sort <field>", "sort tasks by field (priority, id)")
@@ -1773,6 +1775,9 @@ taskCmd
 		if (options.assignee) {
 			baseFilters.assignee = options.assignee;
 		}
+		if (options.milestone) {
+			baseFilters.milestone = options.milestone;
+		}
 		if (options.priority) {
 			const priorityLower = options.priority.toLowerCase();
 			const validPriorities = ["high", "medium", "low"] as const;
@@ -1909,15 +1914,42 @@ taskCmd
 		if (options.parent) {
 			activeFilters.push(`Parent: ${normalizeTaskId(String(options.parent))}`);
 		}
+		if (options.milestone) activeFilters.push(`Milestone: ${options.milestone}`);
 		if (options.priority) activeFilters.push(`Priority: ${options.priority}`);
 		if (options.sort) activeFilters.push(`Sort: ${options.sort}`);
 
 		if (activeFilters.length > 0) {
 			filterDescription = activeFilters.join(", ");
 			title = `Tasks (${activeFilters.join(" • ")})`;
 		}
+		const initialUnifiedFilter: {
+			status?: string;
+			assignee?: string;
+			milestone?: string;
+			priority?: string;
+			sort?: string;
+			title?: string;
+			filterDescription?: string;
+			parentTaskId?: string;
+		} = {
+			status: options.status,
+			assignee: options.assignee,
+			milestone: options.milestone,
+			priority: options.priority,
+			sort: options.sort,
+			title,
+			filterDescription,
+			parentTaskId: parentId,
+		};
 
 		const { runUnifiedView } = await import("./ui/unified-view.ts");
+		const interactiveLoaderFilters: TaskListFilter = {};
+		if (options.assignee) {
+			interactiveLoaderFilters.assignee = options.assignee;
+		}
+		if (parentId) {
+			interactiveLoaderFilters.parentTaskId = parentId;
+		}
 		await runUnifiedView({
 			core,
 			initialView: "task-list",
@@ -1934,7 +1966,9 @@ taskCmd
 				// Now query with filters - this will use the already-populated ContentStore
 				updateProgress("Applying filters...");
 				const [tasks, allTasksForParentCheck] = await Promise.all([
-					core.queryTasks({ filters: baseFilters }),
+					core.queryTasks({
+						filters: Object.keys(interactiveLoaderFilters).length > 0 ? interactiveLoaderFilters : undefined,
+					}),
 					parentId ? core.queryTasks() : Promise.resolve(undefined),
 				]);
 
@@ -1962,20 +1996,30 @@ taskCmd
 					filtered = filtered.filter((task) => task.parentTaskId && taskIdsEqual(parentId, task.parentTaskId));
 				}
 
+				if (options.milestone && filtered.length > 0) {
+					const [activeMilestones, archivedMilestones] = await Promise.all([
+						core.filesystem.listMilestones(),
+						core.filesystem.listArchivedMilestones(),
+					]);
+					const resolveMilestoneFilterValue = createMilestoneFilterValueResolver([
+						...activeMilestones,
+						...archivedMilestones,
+					]);
+					const resolvedMilestone = resolveClosestMilestoneFilterValue(
+						options.milestone,
+						filtered.map((task) => resolveMilestoneFilterValue(task.milestone ?? "")),
+					);
+					if (resolvedMilestone) {
+						initialUnifiedFilter.milestone = resolvedMilestone;
+					}
+				}
+
 				return {
 					tasks: filtered,
 					statuses: config?.statuses || [],
 				};
 			},
-			filter: {
-				status: options.status,
-				assignee: options.assignee,
-				priority: options.priority,
-				sort: options.sort,
-				title,
-				filterDescription,
-				parentTaskId: parentId,
-			},
+			filter: initialUnifiedFilter,
 		});
 		cleanup();
 	});

src/core/backlog.ts

@@ -21,6 +21,11 @@ import {
 import { normalizeAssignee } from "../utils/assignee.ts";
 import { documentIdsEqual } from "../utils/document-id.ts";
 import { openInEditor } from "../utils/editor.ts";
+import {
+	createMilestoneFilterValueResolver,
+	normalizeMilestoneFilterValue,
+	resolveClosestMilestoneFilterValue,
+} from "../utils/milestone-filter.ts";
 import { buildIdRegex, extractAnyPrefix, getPrefixForType, normalizeId } from "../utils/prefix-config.ts";
 import {
 	getCanonicalStatus as resolveCanonicalStatus,
@@ -179,7 +184,11 @@ export class Core {
 		return this.searchService;
 	}
 
-	private applyTaskFilters(tasks: Task[], filters?: TaskListFilter): Task[] {
+	private applyTaskFilters(
+		tasks: Task[],
+		filters?: TaskListFilter,
+		resolveMilestoneFilterValue?: (milestoneValue: string) => string,
+	): Task[] {
 		if (!filters) {
 			return tasks;
 		}
@@ -196,6 +205,17 @@ export class Core {
 			const priorityLower = String(filters.priority).toLowerCase();
 			result = result.filter((task) => (task.priority ?? "").toLowerCase() === priorityLower);
 		}
+		if (filters.milestone) {
+			const milestoneFilter = resolveClosestMilestoneFilterValue(
+				filters.milestone,
+				result.map((task) => resolveMilestoneFilterValue?.(task.milestone ?? "") ?? task.milestone ?? ""),
+			);
+			result = result.filter(
+				(task) =>
+					normalizeMilestoneFilterValue(resolveMilestoneFilterValue?.(task.milestone ?? "") ?? task.milestone ?? "") ===
+					milestoneFilter,
+			);
+		}
 		if (filters.parentTaskId) {
 			const parentFilter = filters.parentTaskId;
 			result = result.filter((task) => task.parentTaskId && taskIdsEqual(parentFilter, task.parentTaskId));
@@ -287,9 +307,16 @@ export class Core {
 		const { filters, query, limit } = options;
 		const trimmedQuery = query?.trim();
 		const includeCrossBranch = options.includeCrossBranch ?? true;
-
-		const applyFiltersAndLimit = (collection: Task[]): Task[] => {
-			let filtered = this.applyTaskFilters(collection, filters);
+		const milestoneResolverPromise = filters?.milestone
+			? Promise.all([this.fs.listMilestones(), this.fs.listArchivedMilestones()]).then(
+					([activeMilestones, archivedMilestones]) =>
+						createMilestoneFilterValueResolver([...activeMilestones, ...archivedMilestones]),
+				)
+			: undefined;
+
+		const applyFiltersAndLimit = async (collection: Task[]): Promise<Task[]> => {
+			const resolveMilestoneFilterValue = milestoneResolverPromise ? await milestoneResolverPromise : undefined;
+			let filtered = this.applyTaskFilters(collection, filters, resolveMilestoneFilterValue);
 			if (!includeCrossBranch) {
 				filtered = this.filterLocalEditableTasks(filtered);
 			}
@@ -302,7 +329,7 @@ export class Core {
 		if (!trimmedQuery) {
 			const store = await this.getContentStore();
 			const tasks = store.getTasks();
-			return applyFiltersAndLimit(tasks);
+			return await applyFiltersAndLimit(tasks);
 		}
 
 		const searchService = await this.getSearchService();
@@ -337,7 +364,7 @@ export class Core {
 			tasks.push(task);
 		}
 
-		return applyFiltersAndLimit(tasks);
+		return await applyFiltersAndLimit(tasks);
 	}
 
 	async getTask(taskId: string): Promise<Task | null> {

src/mcp/tools/tasks/handlers.ts

@@ -7,6 +7,11 @@ import {
 	type TaskListFilter,
 } from "../../../types/index.ts";
 import type { TaskEditArgs, TaskEditRequest } from "../../../types/task-edit-args.ts";
+import {
+	createMilestoneFilterValueResolver,
+	normalizeMilestoneFilterValue,
+	resolveClosestMilestoneFilterValue,
+} from "../../../utils/milestone-filter.ts";
 import { buildTaskUpdateInput } from "../../../utils/task-edit-builder.ts";
 import { createTaskSearchIndex } from "../../../utils/task-search.ts";
 import { sortTasks } from "../../../utils/task-sorting.ts";
@@ -37,6 +42,7 @@ export type TaskCreateArgs = {
 export type TaskListArgs = {
 	status?: string;
 	assignee?: string;
+	milestone?: string;
 	labels?: string[];
 	search?: string;
 	limit?: number;
@@ -232,6 +238,24 @@ export class TaskHandlers {
 			if (args.assignee) {
 				drafts = drafts.filter((draft) => (draft.assignee ?? []).includes(args.assignee ?? ""));
 			}
+			if (args.milestone) {
+				const [activeMilestones, archivedMilestones] = await Promise.all([
+					this.core.filesystem.listMilestones(),
+					this.core.filesystem.listArchivedMilestones(),
+				]);
+				const resolveMilestoneFilterValue = createMilestoneFilterValueResolver([
+					...activeMilestones,
+					...archivedMilestones,
+				]);
+				const milestoneFilter = resolveClosestMilestoneFilterValue(
+					args.milestone,
+					drafts.map((draft) => resolveMilestoneFilterValue(draft.milestone ?? "")),
+				);
+				drafts = drafts.filter(
+					(draft) =>
+						normalizeMilestoneFilterValue(resolveMilestoneFilterValue(draft.milestone ?? "")) === milestoneFilter,
+				);
+			}
 
 			const labelFilters = args.labels ?? [];
 			if (labelFilters.length > 0) {
@@ -278,6 +302,9 @@ export class TaskHandlers {
 		if (args.assignee) {
 			filters.assignee = args.assignee;
 		}
+		if (args.milestone) {
+			filters.milestone = args.milestone;
+		}
 
 		const tasks = await this.core.queryTasks({
 			query: args.search,