handoff-mcp-server 0.19.1 → 0.22.0

package/src/mcp/handlers/get_task.rs

@@ -22,6 +22,14 @@ pub fn handle(arguments: &Value) -> Result<String> {
     let (data, status) = read_task(&task_dir)?
         .ok_or_else(|| anyhow::anyhow!("Task file not found in {}", task_dir.display()))?;
 
+    // `links` stays the legacy `Vec<String>` for backward compatibility with
+    // existing clients (skills / VSCode extension). `task_links` is an
+    // additive field carrying the normalized, deduplicated view from the
+    // `links()` accessor (wiki/130-document-management.md §9.1), so callers
+    // that understand typed links (doc/url/file/task) can read them without
+    // re-deriving the merge themselves.
+    let normalized_links = data.links();
+
     let result = serde_json::json!({
         "id": data.id,
         "title": data.title,
@@ -33,6 +41,7 @@ pub fn handle(arguments: &Value) -> Result<String> {
         "completed_at": data.completed_at,
         "labels": data.labels,
         "links": data.links,
+        "task_links": normalized_links,
         "done_criteria": data.done_criteria,
         "schedule": data.schedule,
         "dependencies": data.dependencies,

package/src/mcp/handlers/import_context.rs

@@ -30,16 +30,46 @@ pub fn handle(arguments: &Value) -> Result<String> {
         .and_then(|v| v.as_str())
         .unwrap_or("other");
 
+    let require_estimate_hours = read_config(&config_path)
+        .map(|c| c.settings.require_estimate_hours)
+        .unwrap_or(true);
+
     let mut tasks_created: u32 = 0;
     let mut top_level_count: u32 = 0;
     let mut nested_count: u32 = 0;
 
     if let Some(tasks) = arguments.get("tasks").and_then(|v| v.as_array()) {
+        // Validate the whole payload before creating anything. Import writes many
+        // tasks in one call, so a rejection discovered mid-tree would otherwise
+        // leave a half-written forest behind and burn task IDs —
+        // `next_top_level_id` counts directories, not task files.
+        //
+        // Nothing is created yet, so `next_top_level_id` keeps returning the same
+        // value; project the IDs the writing pass below will assign, purely so the
+        // rejection names the task the caller sent.
+        let first_id = next_top_level_id(&tasks_dir)?;
+        let first_n: u32 = first_id
+            .strip_prefix('t')
+            .and_then(|n| n.parse().ok())
+            .with_context(|| format!("Unexpected task id form: {first_id}"))?;
+        let mut pending_deps: Vec<(String, Vec<String>)> = Vec::new();
+        for (i, task_val) in tasks.iter().enumerate() {
+            let projected_id = format!("t{}", first_n + i as u32);
+            validate_task_recursive(
+                &projected_id,
+                task_val,
+                require_estimate_hours,
+                &mut pending_deps,
+            )?;
+        }
+
+        // Check the dependency graph once, with every task in this payload already
+        // in it. Task-at-a-time checking would both reject a valid dependency on a
+        // sibling still unwritten and miss a cycle confined to the payload.
+        validate_dependencies_batch(&tasks_dir, &pending_deps)?;
+
         for task_val in tasks {
-            let title = task_val
-                .get("title")
-                .and_then(|v| v.as_str())
-                .ok_or_else(|| anyhow::anyhow!("Each task requires a 'title'"))?;
+            let title = task_title(task_val)?;
 
             let task_id = next_top_level_id(&tasks_dir)?;
             let count = create_task_recursive(&tasks_dir, &task_id, None, title, task_val)?;
@@ -204,6 +234,84 @@ pub fn handle(arguments: &Value) -> Result<String> {
     Ok(msg)
 }
 
+// The validating pass and the writing pass must read the payload identically, or
+// a task could pass validation and then be written as something else. These three
+// accessors are the single source of truth for the fields the estimate rule keys
+// on; both passes go through them rather than reaching into `task_val` directly.
+
+fn task_title(task_val: &Value) -> Result<&str> {
+    task_val
+        .get("title")
+        .and_then(|v| v.as_str())
+        .ok_or_else(|| anyhow::anyhow!("Each task requires a 'title'"))
+}
+
+fn task_status(task_val: &Value) -> &str {
+    task_val
+        .get("status")
+        .and_then(|v| v.as_str())
+        .unwrap_or("todo")
+}
+
+fn task_children(task_val: &Value) -> Option<&Vec<Value>> {
+    task_val.get("children").and_then(|v| v.as_array())
+}
+
+/// Check one task subtree against the rules `create_task_recursive` would
+/// otherwise only discover after writing earlier siblings to disk.
+///
+/// `has_children` is read from the payload, not the filesystem: at this point the
+/// child directories do not exist, so a filesystem probe would call every parent
+/// a leaf and demand an estimate it is exempt from.
+fn validate_task_recursive(
+    task_id: &str,
+    task_val: &Value,
+    require_estimate_hours: bool,
+    pending_deps: &mut Vec<(String, Vec<String>)>,
+) -> Result<()> {
+    let title = task_title(task_val)?;
+
+    let status = task_status(task_val);
+    if !is_valid_status(status) {
+        anyhow::bail!("Invalid status: {status}");
+    }
+
+    validate_priority(task_val.get("priority").and_then(|v| v.as_str()))?;
+
+    let children = task_children(task_val);
+    // An empty `children` array creates no child tasks, so such a task is a leaf
+    // and owes an estimate — matching what the writing pass will produce.
+    let has_children = children.is_some_and(|c| !c.is_empty());
+
+    // import only ever creates, so `is_create` is true and the resend example
+    // carries `title` — the caller has no stored task to preserve it.
+    validate_estimate_required(
+        require_estimate_hours,
+        task_id,
+        title,
+        status,
+        has_children,
+        true,
+        extract_schedule(task_val).as_ref(),
+    )?;
+
+    // Record this task's edges under the ID the writing pass will give it, so the
+    // batch cycle check below sees the graph as it will exist after the import.
+    pending_deps.push((
+        task_id.to_string(),
+        extract_string_array_from(task_val, "dependencies"),
+    ));
+
+    if let Some(children) = children {
+        for (i, child_val) in children.iter().enumerate() {
+            let child_id = format!("{task_id}.{}", i + 1);
+            validate_task_recursive(&child_id, child_val, require_estimate_hours, pending_deps)?;
+        }
+    }
+
+    Ok(())
+}
+
 fn create_task_recursive(
     tasks_dir: &std::path::Path,
     task_id: &str,
@@ -220,11 +328,12 @@ fn create_task_recursive(
         .with_context(|| format!("Failed to create task dir: {}", task_dir.display()))?;
 
     let now = Utc::now().to_rfc3339();
-    let status = task_val
-        .get("status")
-        .and_then(|v| v.as_str())
-        .unwrap_or("todo");
+    let status = task_status(task_val);
 
+    // `validate_task_recursive` has already passed on this payload, so these two
+    // cannot fail here. They stay as defense-in-depth: this function writes to
+    // disk, and a future caller that forgets the pre-pass must not slip an
+    // invalid status or priority through unchecked.
     if !is_valid_status(status) {
         anyhow::bail!("Invalid status: {status}");
     }
@@ -251,6 +360,7 @@ fn create_task_recursive(
         completed_at,
         labels: extract_string_array_from(task_val, "labels"),
         links: extract_string_array_from(task_val, "links"),
+        task_links: Vec::new(),
         done_criteria: extract_done_criteria(task_val),
         schedule: extract_schedule(task_val),
         dependencies: extract_string_array_from(task_val, "dependencies"),
@@ -269,12 +379,9 @@ fn create_task_recursive(
 
     let mut count: u32 = 1;
 
-    if let Some(children) = task_val.get("children").and_then(|v| v.as_array()) {
+    if let Some(children) = task_children(task_val) {
         for (i, child_val) in children.iter().enumerate() {
-            let child_title = child_val
-                .get("title")
-                .and_then(|v| v.as_str())
-                .ok_or_else(|| anyhow::anyhow!("Each child task requires a 'title'"))?;
+            let child_title = task_title(child_val)?;
 
             let child_id = format!("{task_id}.{}", i + 1);
             count += create_task_recursive(

package/src/mcp/handlers/memory.rs

@@ -11,6 +11,7 @@ use serde_json::{json, Value};
 use std::path::Path;
 
 use super::resolve_project_dir;
+use crate::context::injection::{filter_already_injected, rank_by_bm25_and_scope, RankConfig};
 use crate::storage::config::{read_config, SettingsConfig};
 use crate::storage::ensure_handoff_exists;
 use crate::storage::memory::{
@@ -277,49 +278,47 @@ pub fn handle_query(arguments: &Value) -> Result<String> {
     for p in &file_paths {
         query_tokens.extend(lexsim::tokenize(&basename(p)));
     }
-    let scores = corpus.bm25_scores_tokens(&query_tokens);
 
-    // Score + scope-path bonus, then threshold and rank.
-    let mut ranked: Vec<(usize, f64)> = memories
-        .iter()
-        .enumerate()
-        .map(|(i, m)| {
-            let mut s = scores[i];
-            if scope_matches(&m.scope_paths, &file_paths) {
-                s += SCOPE_PATH_BONUS;
-            }
-            (i, s)
-        })
-        .filter(|(_, s)| *s >= settings.memory_query_min_score)
-        .collect();
-    ranked.sort_by(|a, b| b.1.partial_cmp(&a.1).unwrap_or(std::cmp::Ordering::Equal));
+    // Score + scope-path bonus, then threshold and rank (shared with doc_query).
+    let scope_paths: Vec<Vec<String>> = memories.iter().map(|m| m.scope_paths.clone()).collect();
+    let rank_config = RankConfig {
+        min_score: settings.memory_query_min_score,
+        scope_path_bonus: SCOPE_PATH_BONUS,
+        // Rank without truncating yet — the session diff below needs the full
+        // ranked order so it can backfill past already-injected memories.
+        limit: memories.len(),
+    };
+    let ranked = rank_by_bm25_and_scope(
+        &corpus,
+        &query_tokens,
+        &scope_paths,
+        &file_paths,
+        &rank_config,
+    );
 
     // Per-session diff: drop memories already injected this session at the same
     // hash. The `limit` is applied to the *fresh* set so the caller still gets up
     // to `limit` new memories even when earlier prompts already consumed some.
     let now = now_rfc3339();
     let injected_set = session_id.map(|sid| read_injected_set(&handoff, sid, &now));
-    let fresh: Vec<(usize, f64)> = ranked
-        .into_iter()
-        .filter(|(i, _)| match &injected_set {
-            Some(set) => {
-                let m = &memories[*i];
-                !set.already_injected(&m.id, &m.content_hash)
-            }
-            None => true,
-        })
-        .take(limit)
-        .collect();
+    let already_injected = |i: usize| match &injected_set {
+        Some(set) => {
+            let m = &memories[i];
+            set.already_injected(&m.id, &m.content_hash)
+        }
+        None => false,
+    };
+    let fresh = filter_already_injected(ranked, already_injected, limit);
 
     let out: Vec<Value> = fresh
         .iter()
-        .map(|(i, s)| {
-            let m = &memories[*i];
+        .map(|item| {
+            let m = &memories[item.index];
             json!({
                 "id": m.id,
                 "text": m.text,
                 "kind": m.kind,
-                "score": round2(*s),
+                "score": round2(item.score),
             })
         })
         .collect();
@@ -352,13 +351,13 @@ fn mark_injected_memories(
     handoff: &std::path::Path,
     session_id: &str,
     memories: &[MemoryEntry],
-    fresh: &[(usize, f64)],
+    fresh: &[crate::context::injection::RankItem],
     now: &str,
 ) -> Result<()> {
     let mut set = read_injected_set(handoff, session_id, now);
     set.updated_at = now.to_string();
-    for (i, _) in fresh {
-        let m = &memories[*i];
+    for item in fresh {
+        let m = &memories[item.index];
         set.mark(&m.id, &m.content_hash);
     }
     // (1) Persist the suppression record first — this is the correctness-critical
@@ -369,8 +368,8 @@ fn mark_injected_memories(
     // concurrent edit's other fields. A failure here is non-fatal: the sidecar
     // already recorded the injection, so the worst case is a slightly stale
     // hit_count — never a re-spam or a double count.
-    for (i, _) in fresh {
-        let m = &memories[*i];
+    for item in fresh {
+        let m = &memories[item.index];
         if let Ok(Some(mut entry)) = read_memory_by_id(handoff, &m.id) {
             entry.hit_count = entry.hit_count.saturating_add(1);
             entry.last_referenced_at = Some(now.to_string());
@@ -742,16 +741,6 @@ impl UnionFind {
     }
 }
 
-/// True if any `scope` prefix matches any `file` path.
-fn scope_matches(scopes: &[String], files: &[String]) -> bool {
-    if scopes.is_empty() || files.is_empty() {
-        return false;
-    }
-    scopes
-        .iter()
-        .any(|scope| files.iter().any(|f| f.contains(scope.as_str())))
-}
-
 /// Last path component of `p` (handles both `/` and `\` separators).
 fn basename(p: &str) -> String {
     p.rsplit(['/', '\\']).next().unwrap_or(p).to_string()
@@ -796,15 +785,6 @@ mod tests {
         assert_eq!(basename("plain.rs"), "plain.rs");
     }
 
-    #[test]
-    fn scope_matches_prefix() {
-        let scopes = vec!["src/storage/".to_string()];
-        let files = vec!["/repo/src/storage/mod.rs".to_string()];
-        assert!(scope_matches(&scopes, &files));
-        let files2 = vec!["/repo/src/mcp/mod.rs".to_string()];
-        assert!(!scope_matches(&scopes, &files2));
-    }
-
     #[test]
     fn string_array_parsing() {
         let v = json!({ "tags": ["a", "b", 3, "c"] });

package/src/mcp/handlers/mod.rs

@@ -7,6 +7,8 @@ pub mod check_criterion;
 pub mod config;
 pub mod config_crud;
 pub mod dashboard;
+pub mod docs;
+pub mod docs_query;
 pub mod fork_session;
 pub mod get_session;
 pub mod get_task;
@@ -95,6 +97,17 @@ pub fn handle_tool_call(name: &str, arguments: &Value) -> JsonRpcResponse {
         "handoff_timer_start" => timer::handle_start(arguments),
         "handoff_timer_stop" => timer::handle_stop(arguments),
         "handoff_timer_get_time" => timer::handle_get_time(arguments),
+        "handoff_doc_save" => docs::handle_doc_save(arguments),
+        "handoff_doc_get" => docs::handle_doc_get(arguments),
+        "handoff_doc_list" => docs::handle_doc_list(arguments),
+        "handoff_doc_delete" => docs::handle_doc_delete(arguments),
+        "handoff_doc_reassemble" => docs::handle_doc_reassemble(arguments),
+        "handoff_doc_tree" => docs::handle_doc_tree(arguments),
+        "handoff_doc_verify" => docs::handle_doc_verify(arguments),
+        "handoff_doc_verify_status" => docs::handle_doc_verify_status(arguments),
+        "handoff_doc_query" => docs_query::handle_doc_query(arguments),
+        "handoff_doc_analyze" => docs_query::handle_doc_analyze(arguments),
+        "handoff_doc_import" => docs_query::handle_doc_import(arguments),
         _ => Err(anyhow::anyhow!("Tool not implemented: {name}")),
     };
 

package/src/mcp/handlers/update_task.rs

@@ -82,8 +82,6 @@ fn handle_create(
     let slug = title_to_slug(title);
     let dir_name = format!("{new_id}-{slug}");
     let task_dir = parent_dir.join(&dir_name);
-    std::fs::create_dir_all(&task_dir)
-        .with_context(|| format!("Failed to create task dir: {}", task_dir.display()))?;
 
     let now = Utc::now().to_rfc3339();
     let status = task_val
@@ -116,6 +114,7 @@ fn handle_create(
         completed_at: None,
         labels: extract_string_array(task_val, "labels"),
         links: extract_string_array(task_val, "links"),
+        task_links: Vec::new(),
         done_criteria: extract_done_criteria(task_val),
         schedule: extract_schedule(task_val),
         dependencies,
@@ -133,11 +132,20 @@ fn handle_create(
     // A newly created task is always a leaf (no children yet).
     validate_estimate_required(
         require_estimate_hours,
+        &new_id,
+        title,
         status,
         false,
+        true,
         data.schedule.as_ref(),
     )?;
 
+    // Create the directory only once every validation has passed. A rejected
+    // create must leave nothing behind: an orphan dir would burn the task ID,
+    // because `next_top_level_id` counts directories, not task files.
+    std::fs::create_dir_all(&task_dir)
+        .with_context(|| format!("Failed to create task dir: {}", task_dir.display()))?;
+
     write_task(&task_dir, status, &data)?;
 
     Ok(format!("Created task {new_id}: {title} [{status}]"))
@@ -169,8 +177,6 @@ fn handle_upsert_create(
     let slug = title_to_slug(title);
     let dir_name = format!("{task_id}-{slug}");
     let task_dir = parent_dir.join(&dir_name);
-    std::fs::create_dir_all(&task_dir)
-        .with_context(|| format!("Failed to create task dir: {}", task_dir.display()))?;
 
     let now = Utc::now().to_rfc3339();
     let status = task_val
@@ -203,6 +209,7 @@ fn handle_upsert_create(
         completed_at: None,
         labels: extract_string_array(task_val, "labels"),
         links: extract_string_array(task_val, "links"),
+        task_links: Vec::new(),
         done_criteria: extract_done_criteria(task_val),
         schedule: extract_schedule(task_val),
         dependencies,
@@ -220,11 +227,19 @@ fn handle_upsert_create(
     // Upsert-create: a brand-new task is a leaf.
     validate_estimate_required(
         require_estimate_hours,
+        task_id,
+        title,
         status,
         false,
+        true,
         data.schedule.as_ref(),
     )?;
 
+    // Create the directory only once every validation has passed, so a rejected
+    // upsert-create leaves no orphan dir shadowing the requested ID.
+    std::fs::create_dir_all(&task_dir)
+        .with_context(|| format!("Failed to create task dir: {}", task_dir.display()))?;
+
     write_task(&task_dir, status, &data)?;
 
     Ok(format!("Created task {task_id}: {title} [{status}]"))
@@ -336,8 +351,11 @@ fn handle_update(
     let has_children = task_has_children(&task_dir)?;
     validate_estimate_required(
         require_estimate_hours,
+        task_id,
+        &data.title,
         new_status,
         has_children,
+        false,
         data.schedule.as_ref(),
     )?;