handoff-mcp-server 0.6.0 → 0.6.1

package/Cargo.lock

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

package/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "handoff-mcp"
-version = "0.6.0"
+version = "0.6.1"
 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.6.0",
+  "version": "0.6.1",
   "description": "MCP server that gives AI coding agents persistent memory across sessions",
   "license": "MIT",
   "author": "AlphaElements <66808803+alphaelements@users.noreply.github.com>",

package/src/mcp/handlers/refer.rs

@@ -93,10 +93,165 @@ pub fn handle(arguments: &Value) -> Result<String> {
         target_dir.to_string_lossy().to_string()
     };
 
-    Ok(format!(
+    let mut msg = format!(
         "Referral sent: {id}\n  From: {}\n  To: {target_name}\n  Type: {referral_type}\n  Summary: {summary}",
         source_config.project.name
-    ))
+    );
+
+    for w in collect_refer_warnings(&data, &source_project_dir, &target_dir) {
+        msg.push_str(&format!("\n{w}"));
+    }
+
+    Ok(msg)
+}
+
+fn collect_refer_warnings(
+    data: &ReferralData,
+    source_dir: &Path,
+    target_dir: &Path,
+) -> Vec<String> {
+    let mut warnings = Vec::new();
+
+    if data.details.is_none() {
+        warnings.push(
+            "Warning: No details. The target project won't know what specifically to do. \
+             Add a 'details' field describing the change, its impact, and what needs updating."
+                .to_string(),
+        );
+    }
+
+    if data.tasks.is_empty() {
+        warnings.push(
+            "Warning: No tasks. Consider adding suggested tasks with done_criteria \
+             so the target project has actionable items to work from."
+                .to_string(),
+        );
+    }
+
+    if let Some(ref ctx) = data.context {
+        let refs = collect_refs_from_value(ctx);
+        if refs.is_empty() {
+            warnings.push(
+                "Warning: context has no spec/doc references. Add 'spec_docs' with wiki paths, \
+                 MR URLs, or file paths so the target can find the authoritative specification."
+                    .to_string(),
+            );
+        } else {
+            for r in &refs {
+                if r.starts_with("http://") || r.starts_with("https://") {
+                    continue;
+                }
+                let clean = r.split(" — ").next().unwrap_or(r).trim();
+                let clean = clean.split('#').next().unwrap_or(clean).trim();
+                let p = Path::new(clean);
+                if p.is_absolute() {
+                    if !p.exists() {
+                        warnings.push(format!(
+                            "Warning: spec reference path does not exist: {clean}"
+                        ));
+                    }
+                } else {
+                    let in_source = source_dir.join(clean);
+                    let in_target = target_dir.join(clean);
+                    if !in_source.exists() && !in_target.exists() {
+                        warnings.push(format!(
+                            "Warning: spec reference path does not exist \
+                             in source or target project: {clean}"
+                        ));
+                    } else if !in_target.exists() {
+                        warnings.push(format!(
+                            "Warning: spec reference '{clean}' exists in source project \
+                             but not in target project. Use an absolute path or ensure \
+                             the target has this file."
+                        ));
+                    }
+                }
+            }
+        }
+    } else {
+        warnings.push(
+            "Warning: No context. Add a 'context' field with 'spec_docs' referencing the \
+             authoritative specification (wiki paths, MR URLs, source file paths)."
+                .to_string(),
+        );
+    }
+
+    if data.priority.is_none() {
+        warnings.push(
+            "Warning: No priority. Set 'priority' (low/medium/high) so the target project \
+             can triage this referral appropriately."
+                .to_string(),
+        );
+    }
+
+    for (i, task) in data.tasks.iter().enumerate() {
+        let has_criteria = task
+            .get("done_criteria")
+            .and_then(|v| v.as_array())
+            .is_some_and(|a| !a.is_empty());
+        if !has_criteria {
+            let title = task
+                .get("title")
+                .and_then(|v| v.as_str())
+                .unwrap_or("(untitled)");
+            warnings.push(format!(
+                "Warning: Task #{} '{}' has no done_criteria. \
+                 Add criteria so the target knows when the task is complete.",
+                i + 1,
+                title
+            ));
+        }
+    }
+
+    warnings
+}
+
+fn is_ref_string(s: &str) -> bool {
+    s.starts_with("http://")
+        || s.starts_with("https://")
+        || s.starts_with('/')
+        || s.starts_with("wiki/")
+        || s.starts_with("docs/")
+        || s.starts_with("src/")
+        || s.ends_with(".md")
+        || s.ends_with(".rs")
+        || s.ends_with(".ts")
+        || s.ends_with(".toml")
+}
+
+fn collect_refs_from_value(val: &Value) -> Vec<String> {
+    let mut refs = Vec::new();
+    match val {
+        Value::String(s) => {
+            if is_ref_string(s) {
+                refs.push(s.clone());
+            }
+        }
+        Value::Array(arr) => {
+            for item in arr {
+                refs.extend(collect_refs_from_value(item));
+            }
+        }
+        Value::Object(map) => {
+            for (key, v) in map {
+                if key == "spec_docs"
+                    || key == "source_wiki"
+                    || key == "source_data_model"
+                    || key.contains("spec")
+                    || key.contains("doc")
+                    || key.contains("wiki")
+                {
+                    refs.extend(collect_refs_from_value(v));
+                } else if let Value::String(s) = v {
+                    if is_ref_string(s) {
+                        refs.push(s.clone());
+                    }
+                }
+            }
+        }
+        _ => {}
+    }
+    refs
 }
 
 fn resolve_target(arguments: &Value, scan_dirs: &[String]) -> Result<PathBuf> {

package/src/mcp/handlers/save_context.rs

@@ -1,3 +1,5 @@
+use std::path::Path;
+
 use anyhow::Result;
 use chrono::Utc;
 use serde_json::Value;
@@ -95,14 +97,14 @@ pub fn handle(arguments: &Value) -> Result<String> {
         ));
     }
 
-    for w in collect_save_warnings(&data) {
+    for w in collect_save_warnings(&data, &project_dir) {
         msg.push_str(&format!("\n{w}"));
     }
 
     Ok(msg)
 }
 
-fn collect_save_warnings(data: &SessionData) -> Vec<String> {
+fn collect_save_warnings(data: &SessionData, project_dir: &Path) -> Vec<String> {
     let mut warnings = Vec::new();
 
     if data.checklist.is_empty() {
@@ -169,6 +171,51 @@ fn collect_save_warnings(data: &SessionData) -> Vec<String> {
             "Warning: No references. Consider adding links to relevant docs, issues, or MRs."
                 .to_string(),
         );
+    } else {
+        for r in &data.references {
+            let uri = r.get("uri").and_then(|v| v.as_str()).unwrap_or("");
+            if uri.is_empty() {
+                continue;
+            }
+            if uri.starts_with("http://") || uri.starts_with("https://") {
+                continue;
+            }
+            if uri.starts_with("ref-") {
+                continue;
+            }
+            let resolved = if Path::new(uri).is_absolute() {
+                std::path::PathBuf::from(uri)
+            } else {
+                project_dir.join(uri)
+            };
+            let check_path = resolved
+                .to_string_lossy()
+                .split('#')
+                .next()
+                .unwrap_or("")
+                .to_string();
+            if !Path::new(&check_path).exists() {
+                let label = r.get("label").and_then(|v| v.as_str()).unwrap_or("");
+                warnings.push(format!(
+                    "Warning: reference '{label}' path does not exist: {uri}"
+                ));
+            }
+        }
+    }
+
+    for cp in &data.context_pointers {
+        let p = cp.get("path").and_then(|v| v.as_str()).unwrap_or("");
+        if p.is_empty() {
+            continue;
+        }
+        let resolved = if Path::new(p).is_absolute() {
+            std::path::PathBuf::from(p)
+        } else {
+            project_dir.join(p)
+        };
+        if !resolved.exists() {
+            warnings.push(format!("Warning: context_pointer path does not exist: {p}"));
+        }
     }
 
     warnings

package/tests/tool_referrals.rs

@@ -440,3 +440,165 @@ fn no_referrals_dir_is_graceful() {
     let parsed: Value = serde_json::from_str(&text).unwrap();
     assert_eq!(parsed["total"], 0);
 }
+
+#[test]
+fn refer_warns_on_missing_details() {
+    let (_base, proj_a, proj_b) = setup_two_projects();
+
+    let resp = call_tool(
+        "handoff_refer",
+        json!({
+            "project_dir": proj_a.to_string_lossy(),
+            "target_project_dir": proj_b.to_string_lossy(),
+            "summary": "Minimal referral"
+        }),
+    );
+
+    assert!(!is_error(&resp), "error: {}", get_text(&resp));
+    let text = get_text(&resp);
+    assert!(text.contains("Referral sent"));
+    let warning_count = text.matches("Warning").count();
+    assert!(
+        warning_count >= 3,
+        "should have at least 3 warnings (details, tasks, context), got {warning_count}: {text}"
+    );
+    assert!(
+        text.contains("details"),
+        "should warn about missing details: {text}"
+    );
+    assert!(
+        text.contains("tasks"),
+        "should warn about missing tasks: {text}"
+    );
+    assert!(
+        text.contains("context"),
+        "should warn about missing context: {text}"
+    );
+}
+
+#[test]
+fn refer_warns_on_tasks_without_done_criteria() {
+    let (_base, proj_a, proj_b) = setup_two_projects();
+
+    let resp = call_tool(
+        "handoff_refer",
+        json!({
+            "project_dir": proj_a.to_string_lossy(),
+            "target_project_dir": proj_b.to_string_lossy(),
+            "summary": "Referral with bare tasks",
+            "details": "Some details here",
+            "priority": "high",
+            "context": { "branch": "main" },
+            "tasks": [
+                { "title": "Task without criteria" },
+                { "title": "Task with criteria", "done_criteria": [{"item": "check", "checked": false}] }
+            ]
+        }),
+    );
+
+    assert!(!is_error(&resp), "error: {}", get_text(&resp));
+    let text = get_text(&resp);
+    assert!(
+        text.contains("Task #1 'Task without criteria' has no done_criteria"),
+        "should warn about task without criteria: {text}"
+    );
+    assert!(
+        !text.contains("Task #2"),
+        "should NOT warn about task with criteria: {text}"
+    );
+}
+
+#[test]
+fn refer_no_warnings_when_complete() {
+    let (_base, proj_a, proj_b) = setup_two_projects();
+
+    let resp = call_tool(
+        "handoff_refer",
+        json!({
+            "project_dir": proj_a.to_string_lossy(),
+            "target_project_dir": proj_b.to_string_lossy(),
+            "summary": "Complete referral",
+            "referral_type": "request",
+            "priority": "high",
+            "details": "Full description of what needs to happen",
+            "context": {
+                "branch": "feat/x",
+                "commit": "abc123",
+                "spec_docs": [
+                    format!("{}/.handoff/config.toml", proj_a.to_string_lossy()),
+                    "https://gitlab.example.com/project/-/merge_requests/1"
+                ]
+            },
+            "tasks": [
+                {
+                    "title": "Do the thing",
+                    "done_criteria": [{"item": "Thing is done", "checked": false}]
+                }
+            ]
+        }),
+    );
+
+    assert!(!is_error(&resp), "error: {}", get_text(&resp));
+    let text = get_text(&resp);
+    assert!(text.contains("Referral sent"));
+    assert!(
+        !text.contains("Warning"),
+        "should have no warnings when fully specified: {text}"
+    );
+}
+
+#[test]
+fn refer_warns_on_context_without_spec_docs() {
+    let (_base, proj_a, proj_b) = setup_two_projects();
+
+    let resp = call_tool(
+        "handoff_refer",
+        json!({
+            "project_dir": proj_a.to_string_lossy(),
+            "target_project_dir": proj_b.to_string_lossy(),
+            "summary": "Has context but no spec refs",
+            "details": "Description",
+            "priority": "medium",
+            "context": { "branch": "main", "commit": "abc123" },
+            "tasks": [
+                { "title": "Task", "done_criteria": [{"item": "check", "checked": false}] }
+            ]
+        }),
+    );
+
+    assert!(!is_error(&resp), "error: {}", get_text(&resp));
+    let text = get_text(&resp);
+    assert!(
+        text.contains("spec/doc references"),
+        "should warn about missing spec references in context: {text}"
+    );
+}
+
+#[test]
+fn refer_warns_on_nonexistent_spec_path() {
+    let (_base, proj_a, proj_b) = setup_two_projects();
+
+    let resp = call_tool(
+        "handoff_refer",
+        json!({
+            "project_dir": proj_a.to_string_lossy(),
+            "target_project_dir": proj_b.to_string_lossy(),
+            "summary": "Spec path does not exist",
+            "details": "Description",
+            "priority": "medium",
+            "context": {
+                "spec_docs": ["/nonexistent/path/to/spec.md"]
+            },
+            "tasks": [
+                { "title": "Task", "done_criteria": [{"item": "check", "checked": false}] }
+            ]
+        }),
+    );
+
+    assert!(!is_error(&resp), "error: {}", get_text(&resp));
+    let text = get_text(&resp);
+    assert!(
+        text.contains("does not exist"),
+        "should warn about nonexistent spec path: {text}"
+    );
+}

package/tests/tool_sessions.rs

@@ -583,13 +583,13 @@ fn save_context_no_warnings_when_valid() {
                 { "note": "Next: implement feature Y", "category": "suggestion" }
             ],
             "context_pointers": [
-                { "path": "src/main.rs", "reason": "Entry point" }
+                { "path": ".handoff/config.toml", "reason": "Entry point" }
             ],
             "decisions": [
                 { "decision": "Use approach A", "confidence": "confirmed" }
             ],
             "references": [
-                { "label": "Design doc", "uri": "docs/design.md", "type": "doc" }
+                { "label": "Config", "uri": ".handoff/config.toml", "type": "doc" }
             ]
         }),
     );