handoff-mcp-server 0.11.0 → 0.12.0

package/Cargo.lock

@@ -144,7 +144,7 @@ dependencies = [
 
 [[package]]
 name = "handoff-mcp"
-version = "0.11.0"
+version = "0.12.0"
 dependencies = [
  "anyhow",
  "chrono",

package/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "handoff-mcp"
-version = "0.11.0"
+version = "0.12.0"
 edition = "2021"
 description = "MCP server that gives AI coding agents persistent memory across sessions"
 license = "MIT"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "handoff-mcp-server",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "description": "MCP server that gives AI coding agents persistent memory across sessions",
   "license": "MIT",
   "author": "AlphaElements <66808803+alphaelements@users.noreply.github.com>",

package/skills/handoff/SKILL.md

@@ -54,6 +54,13 @@ description: "Session handoff — load context at start, save at end, track task
   user that their input is needed before proceeding.
 - Create new tasks as work is discovered. Always include `done_criteria` with
   verifiable items so completion can be tracked.
+- **Always set `schedule.estimate_hours`** (raw human-effort hours, > 0) on every
+  leaf task. It is required by default — `handoff_update_task` rejects creating or
+  updating a leaf task without it (parent tasks and `blocked`/`skipped` tasks are
+  exempt). Enter the raw human-effort estimate; the AI-effort multiplier
+  (`settings.ai_estimate_multiplier`, default 0.2) is applied automatically at
+  aggregation time by `handoff_get_metrics`/`handoff_get_capacity`. To turn the
+  requirement off, set `settings.require_estimate_hours = false`.
 
 ### Progressive done_criteria Checking
 - **Check off `done_criteria` immediately as each item is verified** — do not
@@ -91,7 +98,7 @@ description: "Session handoff — load context at start, save at end, track task
 Use `handoff_log_time` to record hours worked on a task:
 - Atomically adds to `schedule.actual_hours` and deducts from `schedule.remaining_hours`.
 - Never overwrite `actual_hours` directly — always use the additive `handoff_log_time` tool.
-- Set `schedule.estimate_hours` on task creation so metrics can show estimate vs actual.
+- Set `schedule.estimate_hours` on task creation (required by default) so metrics can show estimate vs actual.
 - When the handoff-vscode time tracker is enabled, the extension also logs time
   automatically — the AI does not need to log time manually for extension-tracked tasks.
 - `handoff_update_task`'s `schedule` field **merges** (partial update): passing

package/src/mcp/handlers/capacity.rs

@@ -4,6 +4,7 @@ use serde_json::{json, Value};
 use toml_edit::DocumentMut;
 
 use super::resolve_project_dir;
+use crate::storage::config::read_config;
 use crate::storage::ensure_handoff_exists;
 use crate::storage::tasks::{build_task_index, is_terminal_status, TaskIndex};
 
@@ -54,9 +55,12 @@ pub fn handle(arguments: &Value) -> Result<String> {
     }
 
     // Calculate allocated hours from tasks
+    let multiplier = read_config(&config_path)
+        .map(|c| c.settings.ai_estimate_multiplier)
+        .unwrap_or(0.2);
     if tasks_dir.exists() {
         let (tree, _) = build_task_index(&tasks_dir, u32::MAX)?;
-        allocate_task_hours(&tree, assignee_filter, &start, &end, &mut days);
+        allocate_task_hours(&tree, assignee_filter, &start, &end, &mut days, multiplier);
     }
 
     let allocated_hours: f64 = days
@@ -260,6 +264,7 @@ fn allocate_task_hours(
     start: &NaiveDate,
     end: &NaiveDate,
     days: &mut [Value],
+    multiplier: f64,
 ) {
     for node in tree {
         if is_terminal_status(&node.status) {
@@ -278,10 +283,13 @@ fn allocate_task_hours(
                         NaiveDate::parse_from_str(sd, "%Y-%m-%d"),
                         NaiveDate::parse_from_str(dd, "%Y-%m-%d"),
                     ) {
-                        let est = sched
-                            .remaining_hours
-                            .or(sched.estimate_hours)
-                            .unwrap_or(0.0);
+                        // remaining_hours is already actual AI-effort progress, so it
+                        // is used as-is; the raw estimate is human-effort and gets the
+                        // AI multiplier applied to derive AI-effort allocation.
+                        let est = match sched.remaining_hours {
+                            Some(rem) => rem,
+                            None => sched.estimate_hours.unwrap_or(0.0) * multiplier,
+                        };
                         let overlap_start = (*start).max(task_start);
                         let overlap_end = (*end).min(task_end);
                         if overlap_start <= overlap_end {
@@ -311,6 +319,13 @@ fn allocate_task_hours(
             }
         }
 
-        allocate_task_hours(&node.children, assignee_filter, start, end, days);
+        allocate_task_hours(
+            &node.children,
+            assignee_filter,
+            start,
+            end,
+            days,
+            multiplier,
+        );
     }
 }

package/src/mcp/handlers/config.rs

@@ -44,6 +44,8 @@ pub fn handle_update(arguments: &Value) -> Result<String> {
         "settings.history_limit",
         "settings.done_task_limit",
         "settings.auto_git_summary",
+        "settings.require_estimate_hours",
+        "settings.ai_estimate_multiplier",
         "settings.context_files",
         "dashboard.scan_dirs",
         "dashboard.exclude_patterns",
@@ -87,6 +89,21 @@ pub fn handle_update(arguments: &Value) -> Result<String> {
                         applied.push(format!("settings.auto_git_summary = {b}"));
                     }
                 }
+                "settings.require_estimate_hours" => {
+                    if let Some(b) = value.as_bool() {
+                        config.settings.require_estimate_hours = b;
+                        applied.push(format!("settings.require_estimate_hours = {b}"));
+                    }
+                }
+                "settings.ai_estimate_multiplier" => {
+                    if let Some(n) = value.as_f64() {
+                        if n < 0.0 {
+                            anyhow::bail!("settings.ai_estimate_multiplier must be >= 0");
+                        }
+                        config.settings.ai_estimate_multiplier = n;
+                        applied.push(format!("settings.ai_estimate_multiplier = {n}"));
+                    }
+                }
                 "settings.context_files" => {
                     if let Some(arr) = value.as_array() {
                         config.settings.context_files = arr

package/src/mcp/handlers/metrics.rs

@@ -5,6 +5,7 @@ use chrono::Utc;
 use serde_json::{json, Value};
 
 use super::resolve_project_dir;
+use crate::storage::config::read_config;
 use crate::storage::ensure_handoff_exists;
 use crate::storage::tasks::{build_task_index, is_terminal_status, TaskIndex};
 
@@ -50,6 +51,13 @@ pub fn handle(arguments: &Value) -> Result<String> {
 
     let budget = read_budget(&handoff);
 
+    // AI-effort multiplier: the raw estimate is the human-effort estimate;
+    // multiplying by ai_estimate_multiplier yields the expected AI-effort hours.
+    // Raw estimates are preserved; only the adjusted view is derived here.
+    let multiplier = read_config(&handoff.join("config.toml"))
+        .map(|c| c.settings.ai_estimate_multiplier)
+        .unwrap_or(0.2);
+
     let milestone_list: Vec<Value> = milestones
         .into_iter()
         .map(|(name, (done, ms_total, est, act))| {
@@ -58,6 +66,7 @@ pub fn handle(arguments: &Value) -> Result<String> {
                 "done": done,
                 "total": ms_total,
                 "estimate_hours": est,
+                "adjusted_estimate_hours": est * multiplier,
                 "actual_hours": act,
             })
         })
@@ -68,6 +77,8 @@ pub fn handle(arguments: &Value) -> Result<String> {
         "by_status": by_status,
         "completion_percent": (completion_percent * 10.0).round() / 10.0,
         "total_estimate_hours": estimate_sum,
+        "ai_estimate_multiplier": multiplier,
+        "total_adjusted_estimate_hours": estimate_sum * multiplier,
         "total_actual_hours": actual_sum,
         "total_remaining_hours": remaining_sum,
         "overdue_count": overdue_tasks.len(),

package/src/mcp/handlers/mod.rs

@@ -53,6 +53,7 @@ pub fn handle_tool_call(name: &str, arguments: &Value) -> JsonRpcResponse {
         "handoff_import_context" => import_context::handle(arguments),
         "handoff_refer" => refer::handle(arguments),
         "handoff_list_referrals" => referrals::handle_list(arguments),
+        "handoff_get_referral" => referrals::handle_get(arguments),
         "handoff_update_referral" => referrals::handle_update(arguments),
         "handoff_update_session" => update_session::handle(arguments),
         "handoff_log_time" => log_time::handle(arguments),

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_task.rs

@@ -5,6 +5,7 @@ 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::*;
 
@@ -14,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"))?;
@@ -27,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
@@ -37,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(
@@ -45,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());
 
@@ -112,6 +130,14 @@ fn handle_create(
         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}]"))
@@ -122,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")
@@ -195,12 +222,25 @@ fn handle_upsert_create(
         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}"))?;
 
@@ -288,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)? {

package/src/mcp/tools.rs

@@ -644,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(),

package/src/storage/config.rs

@@ -49,6 +49,13 @@ pub struct SettingsConfig {
     pub done_task_limit: u32,
     #[serde(default = "default_auto_git_summary")]
     pub auto_git_summary: bool,
+    /// Require `estimate_hours` when creating/updating leaf tasks. Default true.
+    #[serde(default = "default_require_estimate_hours")]
+    pub require_estimate_hours: bool,
+    /// Multiplier applied to AI-entered `estimate_hours` to derive the
+    /// adjusted (AI-effort) estimate at aggregation time. Default 0.2.
+    #[serde(default = "default_ai_estimate_multiplier")]
+    pub ai_estimate_multiplier: f64,
     #[serde(default)]
     pub context_files: Vec<String>,
     #[serde(default)]
@@ -190,6 +197,14 @@ fn default_auto_git_summary() -> bool {
     true
 }
 
+fn default_require_estimate_hours() -> bool {
+    true
+}
+
+fn default_ai_estimate_multiplier() -> f64 {
+    0.2
+}
+
 fn default_scan_dirs() -> Vec<String> {
     vec!["~/pro/".to_string()]
 }
@@ -200,6 +215,8 @@ impl Default for SettingsConfig {
             history_limit: default_history_limit(),
             done_task_limit: default_done_task_limit(),
             auto_git_summary: default_auto_git_summary(),
+            require_estimate_hours: default_require_estimate_hours(),
+            ai_estimate_multiplier: default_ai_estimate_multiplier(),
             context_files: Vec::new(),
             custom_fields: HashMap::new(),
         }

package/src/storage/referrals.rs

@@ -160,6 +160,44 @@ pub fn change_referral_status(
     Ok(())
 }
 
+/// Read a single referral's full data by ID, returning the data and its status.
+/// Searches every status (open / acknowledged / resolved). Matches by exact ID
+/// first, then falls back to a unique prefix match for convenience.
+pub fn read_referral_by_id(
+    referrals_dir: &Path,
+    referral_id: &str,
+) -> Result<Option<(ReferralData, String)>> {
+    if !referrals_dir.exists() {
+        return Ok(None);
+    }
+
+    let mut prefix_matches: Vec<(ReferralData, String)> = Vec::new();
+
+    for entry in std::fs::read_dir(referrals_dir)? {
+        let entry = entry?;
+        let name = entry.file_name().to_string_lossy().to_string();
+        if let Some(status) = parse_referral_status(&name) {
+            let content = std::fs::read_to_string(entry.path())?;
+            if let Ok(data) = serde_json::from_str::<ReferralData>(&content) {
+                if data.id == referral_id {
+                    return Ok(Some((data, status)));
+                }
+                if data.id.starts_with(referral_id) {
+                    prefix_matches.push((data, status));
+                }
+            }
+        }
+    }
+
+    match prefix_matches.len() {
+        0 => Ok(None),
+        1 => Ok(Some(prefix_matches.into_iter().next().unwrap())),
+        n => anyhow::bail!(
+            "Ambiguous referral id prefix '{referral_id}' matches {n} referrals; use the full id"
+        ),
+    }
+}
+
 pub fn find_referral_file(
     referrals_dir: &Path,
     referral_id: &str,

package/src/storage/tasks.rs

@@ -590,6 +590,61 @@ pub fn validate_skipped_transition(task_dir: &Path, data: &TaskData) -> Result<(
     Ok(())
 }
 
+/// Returns true if the task directory contains at least one child task
+/// (a non-`_`/`.`-prefixed subdirectory holding a task file).
+pub fn task_has_children(task_dir: &Path) -> Result<bool> {
+    if !task_dir.exists() {
+        return Ok(false);
+    }
+    for entry in std::fs::read_dir(task_dir)? {
+        let entry = entry?;
+        if !entry.file_type()?.is_dir() {
+            continue;
+        }
+        let name = entry.file_name().to_string_lossy().to_string();
+        if name.starts_with('_') || name.starts_with('.') {
+            continue;
+        }
+        if find_task_file(&entry.path())?.is_some() {
+            return Ok(true);
+        }
+    }
+    Ok(false)
+}
+
+/// Whether a task in the given status requires an effort estimate.
+/// Parent tasks (with children) and blocked/skipped tasks are exempt;
+/// this only covers the status dimension.
+pub fn status_requires_estimate(status: &str) -> bool {
+    matches!(status, "todo" | "in_progress" | "review" | "done")
+}
+
+/// Validate that a leaf task carries an `estimate_hours` when the project
+/// requires it. `has_children` lets the caller skip parent tasks.
+/// Returns an error guiding the caller to add an estimate.
+pub fn validate_estimate_required(
+    require_estimate_hours: bool,
+    status: &str,
+    has_children: bool,
+    schedule: Option<&Schedule>,
+) -> Result<()> {
+    if !require_estimate_hours || has_children || !status_requires_estimate(status) {
+        return Ok(());
+    }
+    let has_estimate = schedule
+        .and_then(|s| s.estimate_hours)
+        .is_some_and(|h| h > 0.0);
+    if !has_estimate {
+        anyhow::bail!(
+            "Task requires an effort estimate: set schedule.estimate_hours (hours, > 0) \
+             when creating or updating a leaf task in status '{status}'. \
+             Estimate the human-effort hours for this task. \
+             To disable this requirement project-wide, set settings.require_estimate_hours = false."
+        );
+    }
+    Ok(())
+}
+
 fn check_children_terminal(task_dir: &Path, parent_id: &str) -> Result<()> {
     if !task_dir.exists() {
         return Ok(());