handoff-mcp-server 0.10.0 → 0.12.0

package/src/mcp/handlers/referrals.rs

@@ -4,7 +4,7 @@ use serde_json::Value;
 use super::resolve_project_dir;
 use crate::storage::ensure_handoff_exists;
 use crate::storage::referrals::{
-    change_referral_status, is_valid_referral_status, read_referral_summaries,
+    change_referral_status, is_valid_referral_status, read_referral_by_id, read_referral_summaries,
 };
 
 pub fn handle_list(arguments: &Value) -> Result<String> {
@@ -32,6 +32,25 @@ pub fn handle_list(arguments: &Value) -> Result<String> {
     serde_json::to_string_pretty(&result).context("Failed to serialize referrals")
 }
 
+pub fn handle_get(arguments: &Value) -> Result<String> {
+    let project_dir = resolve_project_dir(arguments)?;
+    let handoff = ensure_handoff_exists(&project_dir)?;
+    let referrals_dir = handoff.join("referrals");
+
+    let referral_id = arguments
+        .get("referral_id")
+        .and_then(|v| v.as_str())
+        .ok_or_else(|| anyhow::anyhow!("'referral_id' is required"))?;
+
+    let (data, status) = read_referral_by_id(&referrals_dir, referral_id)?
+        .ok_or_else(|| anyhow::anyhow!("Referral not found: {referral_id}"))?;
+
+    let mut result = serde_json::to_value(&data).context("Failed to serialize referral")?;
+    result["status"] = Value::String(status);
+
+    serde_json::to_string_pretty(&result).context("Failed to serialize referral")
+}
+
 pub fn handle_update(arguments: &Value) -> Result<String> {
     let project_dir = resolve_project_dir(arguments)?;
     let handoff = ensure_handoff_exists(&project_dir)?;

package/src/mcp/handlers/update_session.rs

@@ -179,7 +179,7 @@ fn write_active_session_data(
         }
 
         let updated = serde_json::to_string_pretty(data).context("Failed to serialize session")?;
-        std::fs::write(entry.path(), updated)
+        crate::storage::atomic_write(entry.path(), updated.as_bytes())
             .with_context(|| format!("Failed to write session: {}", entry.path().display()))?;
         return Ok(());
     }

package/src/mcp/handlers/update_task.rs

@@ -1,8 +1,11 @@
+use std::collections::HashMap;
+
 use anyhow::{Context, Result};
 use chrono::Utc;
 use serde_json::Value;
 
 use super::resolve_project_dir;
+use crate::storage::config::read_config;
 use crate::storage::ensure_handoff_exists;
 use crate::storage::tasks::*;
 
@@ -12,6 +15,10 @@ pub fn handle(arguments: &Value) -> Result<String> {
     let handoff = ensure_handoff_exists(&project_dir)?;
     let tasks_dir = handoff.join("tasks");
 
+    let require_estimate_hours = read_config(&handoff.join("config.toml"))
+        .map(|c| c.settings.require_estimate_hours)
+        .unwrap_or(true);
+
     let task_val = arguments
         .get("task")
         .ok_or_else(|| anyhow::anyhow!("'task' parameter is required"))?;
@@ -25,9 +32,15 @@ pub fn handle(arguments: &Value) -> Result<String> {
         }
         let task_exists = find_task_dir_by_id(&tasks_dir, existing_id)?.is_some();
         if task_exists {
-            return handle_update(&tasks_dir, existing_id, task_val);
+            return handle_update(&tasks_dir, existing_id, task_val, require_estimate_hours);
         }
-        return handle_upsert_create(&tasks_dir, existing_id, task_val, arguments);
+        return handle_upsert_create(
+            &tasks_dir,
+            existing_id,
+            task_val,
+            arguments,
+            require_estimate_hours,
+        );
     }
 
     let title = task_val
@@ -35,7 +48,13 @@ pub fn handle(arguments: &Value) -> Result<String> {
         .and_then(|v| v.as_str())
         .ok_or_else(|| anyhow::anyhow!("'task.title' is required for new tasks"))?;
 
-    handle_create(&tasks_dir, title, task_val, arguments)
+    handle_create(
+        &tasks_dir,
+        title,
+        task_val,
+        arguments,
+        require_estimate_hours,
+    )
 }
 
 fn handle_create(
@@ -43,6 +62,7 @@ fn handle_create(
     title: &str,
     task_val: &Value,
     arguments: &Value,
+    require_estimate_hours: bool,
 ) -> Result<String> {
     let parent_id = arguments.get("parent_id").and_then(|v| v.as_str());
 
@@ -103,8 +123,21 @@ fn handle_create(
             .get("order")
             .and_then(|v| v.as_u64())
             .map(|v| v as u32),
+        assignee: task_val
+            .get("assignee")
+            .and_then(|v| v.as_str())
+            .map(String::from),
+        extra: HashMap::new(),
     };
 
+    // A newly created task is always a leaf (no children yet).
+    validate_estimate_required(
+        require_estimate_hours,
+        status,
+        false,
+        data.schedule.as_ref(),
+    )?;
+
     write_task(&task_dir, status, &data)?;
 
     Ok(format!("Created task {new_id}: {title} [{status}]"))
@@ -115,6 +148,7 @@ fn handle_upsert_create(
     task_id: &str,
     task_val: &Value,
     arguments: &Value,
+    require_estimate_hours: bool,
 ) -> Result<String> {
     let title = task_val
         .get("title")
@@ -181,14 +215,32 @@ fn handle_upsert_create(
             .get("order")
             .and_then(|v| v.as_u64())
             .map(|v| v as u32),
+        assignee: task_val
+            .get("assignee")
+            .and_then(|v| v.as_str())
+            .map(String::from),
+        extra: HashMap::new(),
     };
 
+    // Upsert-create: a brand-new task is a leaf.
+    validate_estimate_required(
+        require_estimate_hours,
+        status,
+        false,
+        data.schedule.as_ref(),
+    )?;
+
     write_task(&task_dir, status, &data)?;
 
     Ok(format!("Created task {task_id}: {title} [{status}]"))
 }
 
-fn handle_update(tasks_dir: &std::path::Path, task_id: &str, task_val: &Value) -> Result<String> {
+fn handle_update(
+    tasks_dir: &std::path::Path,
+    task_id: &str,
+    task_val: &Value,
+    require_estimate_hours: bool,
+) -> Result<String> {
     let task_dir = find_task_dir_by_id(tasks_dir, task_id)?
         .ok_or_else(|| anyhow::anyhow!("Task not found: {task_id}"))?;
 
@@ -214,8 +266,32 @@ fn handle_update(tasks_dir: &std::path::Path, task_id: &str, task_val: &Value) -
     if task_val.get("done_criteria").is_some() {
         data.done_criteria = extract_done_criteria(task_val);
     }
-    if task_val.get("schedule").is_some() {
-        data.schedule = extract_schedule(task_val);
+    if let Some(sched_val) = task_val.get("schedule") {
+        // Field-level merge (not full replacement) so that fields not present in
+        // the patch — e.g. actual_hours/remaining_hours accrued by the VSCode timer —
+        // are preserved. Mirrors bulk_update_tasks. (referral ref-20260623-232823)
+        let schedule = data.schedule.get_or_insert_with(Default::default);
+        if let Some(sd) = sched_val.get("start_date").and_then(|v| v.as_str()) {
+            schedule.start_date = Some(sd.to_string());
+        }
+        if let Some(dd) = sched_val.get("due_date").and_then(|v| v.as_str()) {
+            schedule.due_date = Some(dd.to_string());
+        }
+        if let Some(eh) = sched_val.get("estimate_hours").and_then(|v| v.as_f64()) {
+            schedule.estimate_hours = Some(eh);
+        }
+        if let Some(ah) = sched_val.get("actual_hours").and_then(|v| v.as_f64()) {
+            schedule.actual_hours = Some(ah);
+        }
+        if let Some(rh) = sched_val.get("remaining_hours").and_then(|v| v.as_f64()) {
+            schedule.remaining_hours = Some(rh);
+        }
+        if let Some(ms) = sched_val.get("milestone").and_then(|v| v.as_str()) {
+            schedule.milestone = Some(ms.to_string());
+        }
+        if let Some(p) = sched_val.get("pinned").and_then(|v| v.as_bool()) {
+            schedule.pinned = Some(p);
+        }
     }
     if task_val.get("dependencies").is_some() {
         let new_deps = extract_string_array(task_val, "dependencies");
@@ -227,6 +303,12 @@ fn handle_update(tasks_dir: &std::path::Path, task_id: &str, task_val: &Value) -
     if let Some(order) = task_val.get("order").and_then(|v| v.as_u64()) {
         data.order = Some(order as u32);
     }
+    if task_val.get("assignee").is_some() {
+        data.assignee = task_val
+            .get("assignee")
+            .and_then(|v| v.as_str())
+            .map(String::from);
+    }
 
     let new_status = task_val
         .get("status")
@@ -246,6 +328,15 @@ fn handle_update(tasks_dir: &std::path::Path, task_id: &str, task_val: &Value) -
         validate_skipped_transition(&task_dir, &data)?;
     }
 
+    // Parent tasks (with children) are exempt; only leaf tasks need an estimate.
+    let has_children = task_has_children(&task_dir)?;
+    validate_estimate_required(
+        require_estimate_hours,
+        new_status,
+        has_children,
+        data.schedule.as_ref(),
+    )?;
+
     data.updated_at = Some(Utc::now().to_rfc3339());
 
     if let Some((old_path, _)) = find_task_file(&task_dir)? {
@@ -335,9 +426,11 @@ fn extract_schedule(val: &Value) -> Option<Schedule> {
             .map(String::from),
         estimate_hours: sched.get("estimate_hours").and_then(|v| v.as_f64()),
         actual_hours: sched.get("actual_hours").and_then(|v| v.as_f64()),
+        remaining_hours: sched.get("remaining_hours").and_then(|v| v.as_f64()),
         milestone: sched
             .get("milestone")
             .and_then(|v| v.as_str())
             .map(String::from),
+        pinned: sched.get("pinned").and_then(|v| v.as_bool()),
     })
 }

package/src/mcp/tools.rs

@@ -175,7 +175,7 @@ pub fn all_tool_definitions() -> Vec<ToolDefinition> {
         },
         ToolDefinition {
             name: "handoff_list_tasks".to_string(),
-            description: "List all tasks for the current project with optional status filter.".to_string(),
+            description: "List all tasks for the current project with optional filters.".to_string(),
             input_schema: json!({
                 "type": "object",
                 "properties": {
@@ -185,8 +185,25 @@ pub fn all_tool_definitions() -> Vec<ToolDefinition> {
                     },
                     "status_filter": {
                         "type": "string",
-                        "description": "Filter by status",
+                        "description": "Filter by status.",
                         "enum": ["todo", "in_progress", "review", "done", "blocked", "skipped"]
+                    },
+                    "assignee_filter": {
+                        "type": "string",
+                        "description": "Filter by assignee key."
+                    },
+                    "milestone_filter": {
+                        "type": "string",
+                        "description": "Filter by milestone name."
+                    },
+                    "priority_filter": {
+                        "type": "string",
+                        "description": "Filter by priority.",
+                        "enum": ["low", "medium", "high"]
+                    },
+                    "label_filter": {
+                        "type": "string",
+                        "description": "Filter by label (task must contain this label)."
                     }
                 }
             }),
@@ -286,7 +303,9 @@ pub fn all_tool_definitions() -> Vec<ToolDefinition> {
                                     "due_date": { "type": "string", "description": "YYYY-MM-DD" },
                                     "estimate_hours": { "type": "number" },
                                     "actual_hours": { "type": "number" },
-                                    "milestone": { "type": "string" }
+                                    "remaining_hours": { "type": "number", "description": "Hours remaining. Auto-decremented by handoff_log_time." },
+                                    "milestone": { "type": "string" },
+                                    "pinned": { "type": "boolean", "description": "If true, dates are locked and auto-scheduler skips this task." }
                                 }
                             },
                             "dependencies": {
@@ -297,6 +316,10 @@ pub fn all_tool_definitions() -> Vec<ToolDefinition> {
                             "order": {
                                 "type": "integer",
                                 "description": "Display order among siblings. 0-based, lower = higher priority."
+                            },
+                            "assignee": {
+                                "type": "string",
+                                "description": "Assignee key (matches config.toml [assignees.<key>])."
                             }
                         },
                     },
@@ -621,6 +644,24 @@ pub fn all_tool_definitions() -> Vec<ToolDefinition> {
                 }
             }),
         },
+        ToolDefinition {
+            name: "handoff_get_referral".to_string(),
+            description: "Get the full details of a single incoming referral by ID (summary, details, tasks with done_criteria, priority, context, status). Use this instead of reading .handoff/referrals/*.json directly.".to_string(),
+            input_schema: json!({
+                "type": "object",
+                "properties": {
+                    "project_dir": {
+                        "type": "string",
+                        "description": "Project directory path. Defaults to current working directory."
+                    },
+                    "referral_id": {
+                        "type": "string",
+                        "description": "ID of the referral to retrieve (full id or a unique prefix)."
+                    }
+                },
+                "required": ["referral_id"]
+            }),
+        },
         ToolDefinition {
             name: "handoff_update_referral".to_string(),
             description: "Update the status of an incoming referral (open -> acknowledged -> resolved).".to_string(),
@@ -703,9 +744,322 @@ pub fn all_tool_definitions() -> Vec<ToolDefinition> {
                 }
             }),
         },
+        ToolDefinition {
+            name: "handoff_log_time".to_string(),
+            description: "Log hours worked on a task. Adds to actual_hours and deducts from remaining_hours atomically.".to_string(),
+            input_schema: json!({
+                "type": "object",
+                "properties": {
+                    "project_dir": {
+                        "type": "string",
+                        "description": "Project directory path. Defaults to current working directory."
+                    },
+                    "task_id": {
+                        "type": "string",
+                        "description": "Task ID to log time against."
+                    },
+                    "hours": {
+                        "type": "number",
+                        "description": "Hours worked (e.g. 0.5 for 30 minutes)."
+                    }
+                },
+                "required": ["task_id", "hours"]
+            }),
+        },
+        ToolDefinition {
+            name: "handoff_get_metrics".to_string(),
+            description: "Get project metrics: completion %, effort tracking, overdue tasks, budget status, and milestone breakdown.".to_string(),
+            input_schema: json!({
+                "type": "object",
+                "properties": {
+                    "project_dir": {
+                        "type": "string",
+                        "description": "Project directory path. Defaults to current working directory."
+                    },
+                    "assignee": {
+                        "type": "string",
+                        "description": "Filter metrics to a specific assignee."
+                    }
+                }
+            }),
+        },
+        ToolDefinition {
+            name: "handoff_list_sessions".to_string(),
+            description: "List all sessions (open, active, paused, closed) with summary info. Use handoff_get_session for full detail.".to_string(),
+            input_schema: json!({
+                "type": "object",
+                "properties": {
+                    "project_dir": {
+                        "type": "string",
+                        "description": "Project directory path. Defaults to current working directory."
+                    },
+                    "status_filter": {
+                        "type": "string",
+                        "enum": ["open", "active", "paused", "closed"],
+                        "description": "Filter sessions by status."
+                    },
+                    "limit": {
+                        "type": "integer",
+                        "description": "Max sessions to return (default 20)."
+                    }
+                }
+            }),
+        },
+        ToolDefinition {
+            name: "handoff_list_assignees".to_string(),
+            description: "List all team members/assignees from config.toml with their task counts and effort stats.".to_string(),
+            input_schema: json!({
+                "type": "object",
+                "properties": {
+                    "project_dir": {
+                        "type": "string",
+                        "description": "Project directory path. Defaults to current working directory."
+                    }
+                }
+            }),
+        },
+        ToolDefinition {
+            name: "handoff_bulk_update_tasks".to_string(),
+            description: "Update multiple tasks in one call. Useful for applying auto-schedule results or bulk status/assignee changes.".to_string(),
+            input_schema: json!({
+                "type": "object",
+                "properties": {
+                    "project_dir": {
+                        "type": "string",
+                        "description": "Project directory path. Defaults to current working directory."
+                    },
+                    "updates": {
+                        "type": "array",
+                        "description": "Array of task updates to apply.",
+                        "items": {
+                            "type": "object",
+                            "properties": {
+                                "task_id": { "type": "string", "description": "Task ID to update." },
+                                "status": { "type": "string", "enum": ["todo", "in_progress", "review", "done", "blocked", "skipped"] },
+                                "priority": { "type": "string", "enum": ["low", "medium", "high"] },
+                                "assignee": { "type": "string" },
+                                "schedule": {
+                                    "type": "object",
+                                    "properties": {
+                                        "start_date": { "type": "string" },
+                                        "due_date": { "type": "string" },
+                                        "estimate_hours": { "type": "number" },
+                                        "actual_hours": { "type": "number" },
+                                        "remaining_hours": { "type": "number" },
+                                        "milestone": { "type": "string" },
+                                        "pinned": { "type": "boolean" }
+                                    }
+                                }
+                            },
+                            "required": ["task_id"]
+                        }
+                    }
+                },
+                "required": ["updates"]
+            }),
+        },
+        ToolDefinition {
+            name: "handoff_get_session".to_string(),
+            description: "Get full detail of a specific session by ID. Returns decisions, checklist, handoff notes, context pointers, etc.".to_string(),
+            input_schema: json!({
+                "type": "object",
+                "properties": {
+                    "project_dir": {
+                        "type": "string",
+                        "description": "Project directory path. Defaults to current working directory."
+                    },
+                    "session_id": {
+                        "type": "string",
+                        "description": "Session ID to retrieve."
+                    }
+                },
+                "required": ["session_id"]
+            }),
+        },
+        ToolDefinition {
+            name: "handoff_get_capacity".to_string(),
+            description: "Get work capacity for a date range. Shows available hours per day based on calendar config, and allocated hours from scheduled tasks.".to_string(),
+            input_schema: json!({
+                "type": "object",
+                "properties": {
+                    "project_dir": {
+                        "type": "string",
+                        "description": "Project directory path. Defaults to current working directory."
+                    },
+                    "start_date": {
+                        "type": "string",
+                        "description": "Start date (YYYY-MM-DD)."
+                    },
+                    "end_date": {
+                        "type": "string",
+                        "description": "End date (YYYY-MM-DD)."
+                    },
+                    "assignee": {
+                        "type": "string",
+                        "description": "Filter capacity to a specific assignee's calendar."
+                    }
+                },
+                "required": ["start_date", "end_date"]
+            }),
+        },
+        ToolDefinition {
+            name: "handoff_auto_schedule".to_string(),
+            description: "Run auto-scheduler to compute optimal task dates based on dependencies, estimates, and calendar capacity. Returns change diff; applies changes unless dry_run=true.".to_string(),
+            input_schema: json!({
+                "type": "object",
+                "properties": {
+                    "project_dir": {
+                        "type": "string",
+                        "description": "Project directory path. Defaults to current working directory."
+                    },
+                    "dry_run": {
+                        "type": "boolean",
+                        "description": "If true (default), return computed spans without writing. If false, apply changes to task files."
+                    },
+                    "assignee_filter": {
+                        "type": "string",
+                        "description": "Only schedule tasks assigned to this assignee."
+                    },
+                    "start_date": {
+                        "type": "string",
+                        "description": "Anchor date YYYY-MM-DD for the earliest task. Defaults to today (UTC)."
+                    }
+                }
+            }),
+        },
+        ToolDefinition {
+            name: "handoff_add_assignee".to_string(),
+            description: "Add a team member to config.toml [assignees.<key>]. Fails if the key already exists.".to_string(),
+            input_schema: assignee_write_schema(true),
+        },
+        ToolDefinition {
+            name: "handoff_update_assignee".to_string(),
+            description: "Update an existing [assignees.<key>] entry. Only provided fields change; pass null to clear a field.".to_string(),
+            input_schema: assignee_write_schema(false),
+        },
+        ToolDefinition {
+            name: "handoff_remove_assignee".to_string(),
+            description: "Remove a team member from config.toml and unassign them from every task.".to_string(),
+            input_schema: json!({
+                "type": "object",
+                "properties": {
+                    "project_dir": { "type": "string", "description": "Project directory path. Defaults to current working directory." },
+                    "key": { "type": "string", "description": "Assignee key to remove." }
+                },
+                "required": ["key"]
+            }),
+        },
+        ToolDefinition {
+            name: "handoff_list_milestones".to_string(),
+            description: "List all milestones defined in config.toml [milestones.*].".to_string(),
+            input_schema: json!({
+                "type": "object",
+                "properties": {
+                    "project_dir": { "type": "string", "description": "Project directory path. Defaults to current working directory." }
+                }
+            }),
+        },
+        ToolDefinition {
+            name: "handoff_add_milestone".to_string(),
+            description: "Add a milestone to config.toml [milestones.<name>]. Fails if it already exists.".to_string(),
+            input_schema: milestone_write_schema(),
+        },
+        ToolDefinition {
+            name: "handoff_update_milestone".to_string(),
+            description: "Update an existing [milestones.<name>] entry. Pass null to clear a field.".to_string(),
+            input_schema: milestone_write_schema(),
+        },
+        ToolDefinition {
+            name: "handoff_remove_milestone".to_string(),
+            description: "Remove a milestone from config.toml.".to_string(),
+            input_schema: json!({
+                "type": "object",
+                "properties": {
+                    "project_dir": { "type": "string", "description": "Project directory path. Defaults to current working directory." },
+                    "name": { "type": "string", "description": "Milestone name to remove." }
+                },
+                "required": ["name"]
+            }),
+        },
+        ToolDefinition {
+            name: "handoff_update_calendar".to_string(),
+            description: "Patch the project [calendar] section (work hours, closed days, day_hours, schedule_mode). Only provided fields change.".to_string(),
+            input_schema: json!({
+                "type": "object",
+                "properties": {
+                    "project_dir": { "type": "string", "description": "Project directory path. Defaults to current working directory." },
+                    "work_hours_per_day": { "type": "number", "description": "Default working hours per day." },
+                    "closed_weekdays": { "type": "array", "description": "Non-working weekdays (0=Sun..6=Sat, or names like \"sat\").", "items": {} },
+                    "closed_dates": { "type": "array", "description": "Non-working YYYY-MM-DD dates.", "items": { "type": "string" } },
+                    "open_dates": { "type": "array", "description": "Working YYYY-MM-DD dates that override closed weekdays.", "items": { "type": "string" } },
+                    "day_hours": { "type": "object", "description": "Per-weekday-name or per-date hour overrides, e.g. {\"fri\": 4, \"2026-07-01\": 0}.", "additionalProperties": { "type": "number" } },
+                    "schedule_mode": { "type": "string", "description": "\"manual\" or \"auto\"." },
+                    "overwork_limit_percent": { "type": "number" },
+                    "max_utilization": { "type": "number" }
+                }
+            }),
+        },
+        ToolDefinition {
+            name: "handoff_update_labels".to_string(),
+            description: "Set the project-level label vocabulary (top-level labels array in config.toml).".to_string(),
+            input_schema: json!({
+                "type": "object",
+                "properties": {
+                    "project_dir": { "type": "string", "description": "Project directory path. Defaults to current working directory." },
+                    "labels": { "type": "array", "description": "Full replacement list of project labels.", "items": { "type": "string" } }
+                },
+                "required": ["labels"]
+            }),
+        },
+        ToolDefinition {
+            name: "handoff_start_project".to_string(),
+            description: "Set the project started_at date and optionally shift all task dates so the earliest start aligns to it.".to_string(),
+            input_schema: json!({
+                "type": "object",
+                "properties": {
+                    "project_dir": { "type": "string", "description": "Project directory path. Defaults to current working directory." },
+                    "start_date": { "type": "string", "description": "Project start date YYYY-MM-DD. Defaults to today (UTC)." },
+                    "shift_dates": { "type": "boolean", "description": "If true, shift every task's start/due dates so the earliest start lands on start_date." }
+                }
+            }),
+        },
     ]
 }
 
+/// Shared input schema for add/update assignee. `key` is required either way.
+fn assignee_write_schema(_is_add: bool) -> Value {
+    json!({
+        "type": "object",
+        "properties": {
+            "project_dir": { "type": "string", "description": "Project directory path. Defaults to current working directory." },
+            "key": { "type": "string", "description": "Stable assignee key (used as [assignees.<key>])." },
+            "display_name": { "type": "string", "description": "Human-readable name." },
+            "color": { "type": "string", "description": "Display color (hex or name)." },
+            "work_hours_per_day": { "type": "number", "description": "This member's daily working hours." },
+            "closed_weekdays": { "type": "array", "description": "Non-working weekdays (0=Sun..6=Sat or names).", "items": {} },
+            "closed_dates": { "type": "array", "description": "Non-working YYYY-MM-DD dates.", "items": { "type": "string" } },
+            "open_dates": { "type": "array", "description": "Working YYYY-MM-DD override dates.", "items": { "type": "string" } },
+            "day_hours": { "type": "object", "description": "Per-weekday/date hour overrides.", "additionalProperties": { "type": "number" } }
+        },
+        "required": ["key"]
+    })
+}
+
+/// Shared input schema for add/update milestone. `name` is required.
+fn milestone_write_schema() -> Value {
+    json!({
+        "type": "object",
+        "properties": {
+            "project_dir": { "type": "string", "description": "Project directory path. Defaults to current working directory." },
+            "name": { "type": "string", "description": "Milestone name (used as [milestones.<name>])." },
+            "date": { "type": "string", "description": "Target date YYYY-MM-DD." },
+            "color": { "type": "string", "description": "Display color." },
+            "description": { "type": "string", "description": "Free-form description." }
+        },
+        "required": ["name"]
+    })
+}
+
 pub fn all_resource_definitions() -> Vec<Value> {
     vec![
         json!({