handoff-mcp-server 0.24.5 → 0.25.0

package/src/mcp/handlers/docs_query.rs

@@ -333,9 +333,9 @@ pub fn handle_doc_query(arguments: &Value) -> Result<String> {
         .map_err(|_| anyhow::anyhow!("doc corpus cache mutex poisoned"))?;
     let corpus = cache.get_or_build_corpus(&doc_texts);
 
-    let mut query_tokens = lexsim::tokenize(&text);
+    let mut query_tokens = lexsim::tokenize_weighted(&text);
     for p in &file_paths {
-        query_tokens.extend(lexsim::tokenize(&basename(p)));
+        query_tokens.extend(lexsim::tokenize_weighted(&basename(p)));
     }
 
     let scope_paths: Vec<Vec<String>> = candidates
@@ -344,6 +344,7 @@ pub fn handle_doc_query(arguments: &Value) -> Result<String> {
         .collect();
     let rank_config = RankConfig {
         min_score: DOC_QUERY_MIN_SCORE,
+        relative_threshold: 0.0,
         scope_path_bonus: SCOPE_PATH_BONUS,
         limit: candidates.len(),
     };
@@ -957,8 +958,7 @@ pub fn handle_doc_import(arguments: &Value) -> Result<String> {
         doc.source.original_path = Some(file.clone());
         doc.has_bom = split_doc.has_bom;
         doc.line_ending = split_doc.line_ending.to_string();
-        doc.source.frontmatter = split_doc.frontmatter.map(str::to_string);
-        doc.source.frontmatter_trailing_eol = split_doc.frontmatter_trailing_eol;
+        doc.split_level = DEFAULT_SPLIT_LEVEL;
 
         let body_after_strip: String = split_doc.fragments.iter().map(|f| f.body).collect();
         write_doc_body(&handoff, &slug, &body_after_strip)?;

package/src/mcp/handlers/memory.rs

@@ -96,6 +96,7 @@ pub fn handle_save(arguments: &Value) -> Result<String> {
     }
 
     let tags = string_array(arguments, "tags");
+    let keywords = string_array(arguments, "keywords");
     let scope_paths = string_array(arguments, "scope_paths");
     let force = arguments
         .get("force")
@@ -112,6 +113,7 @@ pub fn handle_save(arguments: &Value) -> Result<String> {
             text,
             kind,
             tags,
+            keywords,
             scope_paths,
         );
     }
@@ -130,7 +132,18 @@ pub fn handle_save(arguments: &Value) -> Result<String> {
     // (3) Near-duplicate: hand both bodies back for AI-driven merge.
     if !force {
         let dup_threshold = settings.memory_dup_threshold;
-        let new_set = lexsim::token_set(&text);
+        // Build the new memory's index text (body + tags + keywords),
+        // matching MemoryEntry::index_text() for symmetric Jaccard comparison.
+        let mut new_index = text.clone();
+        if !tags.is_empty() {
+            new_index.push(' ');
+            new_index.push_str(&tags.join(" "));
+        }
+        if !keywords.is_empty() {
+            new_index.push(' ');
+            new_index.push_str(&keywords.join(" "));
+        }
+        let new_set = lexsim::token_set(&new_index);
         let mut similar: Vec<Value> = Vec::new();
         for m in &existing {
             let score = lexsim::jaccard_sets(&new_set, &lexsim::token_set(&m.index_text()));
@@ -163,13 +176,22 @@ pub fn handle_save(arguments: &Value) -> Result<String> {
 
     // (4) New memory.
     let id = new_memory_id();
-    let entry = MemoryEntry::new(id.clone(), text, kind, tags, scope_paths, now_rfc3339());
+    let entry = MemoryEntry::new(
+        id.clone(),
+        text,
+        kind,
+        tags,
+        keywords,
+        scope_paths,
+        now_rfc3339(),
+    );
     write_memory(&handoff, &entry)?;
     Ok(to_json(&json!({ "status": "saved", "id": id })))
 }
 
 /// Commit an AI-driven merge: overwrite `merge_into` with the merged text and
 /// delete the absorbed memories, recording them in `superseded_ids`.
+#[allow(clippy::too_many_arguments)]
 fn commit_merge(
     handoff: &std::path::Path,
     merge_into: &str,
@@ -177,6 +199,7 @@ fn commit_merge(
     text: String,
     kind: String,
     tags: Vec<String>,
+    keywords: Vec<String>,
     scope_paths: Vec<String>,
 ) -> Result<String> {
     let mut target = read_memory_by_id(handoff, merge_into)?
@@ -188,6 +211,9 @@ fn commit_merge(
     if !tags.is_empty() {
         target.tags = tags;
     }
+    if !keywords.is_empty() {
+        target.keywords = keywords;
+    }
     if !scope_paths.is_empty() {
         target.scope_paths = scope_paths;
     }
@@ -200,8 +226,24 @@ fn commit_merge(
         if raw == &target_id {
             continue; // never absorb the target into itself
         }
-        // Resolve to a concrete id (supports prefixes), then delete it.
         if let Some(m) = read_memory_by_id(handoff, raw)? {
+            // Fold the absorbed memory's metadata into the target before
+            // deleting, so keywords/tags/scope_paths are not lost.
+            for kw in &m.keywords {
+                if !target.keywords.contains(kw) {
+                    target.keywords.push(kw.clone());
+                }
+            }
+            for t in &m.tags {
+                if !target.tags.contains(t) {
+                    target.tags.push(t.clone());
+                }
+            }
+            for s in &m.scope_paths {
+                if !target.scope_paths.contains(s) {
+                    target.scope_paths.push(s.clone());
+                }
+            }
             if delete_memory(handoff, &m.id)? {
                 absorbed.push(m.id);
             }
@@ -265,24 +307,28 @@ pub fn handle_query(arguments: &Value) -> Result<String> {
         return Ok(to_json(&json!({ "memories": [], "injected_count": 0 })));
     }
 
-    // Build the BM25 corpus over each memory's index text (body + tags).
-    let docs: Vec<String> = memories.iter().map(|m| m.index_text()).collect();
-    let corpus = lexsim::Corpus::build(&docs);
+    // Build the weighted BM25 corpus from per-memory weighted tokens.
+    // Keywords get doc-side TF boost (weight 2.0) via build_weighted_tokens;
+    // stopwords and CL-CnG trigrams from stopword-only context are excluded.
+    let doc_tokens: Vec<Vec<lexsim::WeightedToken>> =
+        memories.iter().map(|m| m.index_weighted_tokens()).collect();
+    let corpus = lexsim::Corpus::build_weighted_tokens(&doc_tokens);
 
     // Query = prompt text + tool name + file basenames (so a PreToolUse hook
     // that only passes a file path still matches name-related memories).
-    let mut query_tokens = lexsim::tokenize(&text);
+    let mut query_tokens = lexsim::tokenize_weighted(&text);
     if let Some(tn) = tool_name {
-        query_tokens.extend(lexsim::tokenize(tn));
+        query_tokens.extend(lexsim::tokenize_weighted(tn));
     }
     for p in &file_paths {
-        query_tokens.extend(lexsim::tokenize(&basename(p)));
+        query_tokens.extend(lexsim::tokenize_weighted(&basename(p)));
     }
 
     // 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,
+        relative_threshold: settings.memory_query_relative_threshold,
         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.
@@ -314,15 +360,27 @@ pub fn handle_query(arguments: &Value) -> Result<String> {
         .iter()
         .map(|item| {
             let m = &memories[item.index];
-            json!({
+            let mut entry = json!({
                 "id": m.id,
                 "text": m.text,
                 "kind": m.kind,
                 "score": round2(item.score),
-            })
+            });
+            if !m.keywords.is_empty() {
+                entry["keywords"] = json!(m.keywords);
+            }
+            entry
         })
         .collect();
 
+    // Warn about returned memories that have no keywords — these get weaker
+    // BM25 signal and would benefit from `memory_save` with explicit keywords.
+    let missing_kw: Vec<&str> = fresh
+        .iter()
+        .filter(|item| memories[item.index].keywords.is_empty())
+        .map(|item| memories[item.index].id.as_str())
+        .collect();
+
     // Bookkeeping: record survivors in the sidecar and bump usage stats. Only
     // when we have a session id and marking is enabled (the hook's normal path).
     if mark_injected && !fresh.is_empty() {
@@ -331,10 +389,21 @@ pub fn handle_query(arguments: &Value) -> Result<String> {
         }
     }
 
-    Ok(to_json(&json!({
+    let mut result = json!({
         "memories": out,
         "injected_count": out.len(),
-    })))
+    });
+    if !missing_kw.is_empty() {
+        result["warnings"] = json!([
+            format!(
+                "{} injected memories have no keywords — add keywords via memory_save(merge_into=<id>) to improve match precision: {}",
+                missing_kw.len(),
+                missing_kw.join(", ")
+            )
+        ]);
+    }
+
+    Ok(to_json(&result))
 }
 
 /// Append the freshly-injected memories to the session sidecar and bump each
@@ -530,6 +599,11 @@ fn merge_exact_duplicates(handoff: &std::path::Path, now: &str) -> Result<usize>
                     keeper.tags.push(t.clone());
                 }
             }
+            for kw in &dup.keywords {
+                if !keeper.keywords.contains(kw) {
+                    keeper.keywords.push(kw.clone());
+                }
+            }
             for s in &dup.scope_paths {
                 if !keeper.scope_paths.contains(s) {
                     keeper.scope_paths.push(s.clone());
@@ -804,6 +878,7 @@ mod tests {
             "lesson".to_string(),
             vec![],
             vec![],
+            vec![],
             created.to_string(),
         );
         m.last_referenced_at = last_ref.map(str::to_string);

package/src/mcp/handlers/mod.rs

@@ -99,6 +99,7 @@ pub fn handle_tool_call(name: &str, arguments: &Value) -> JsonRpcResponse {
         "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_update_section" => docs::handle_doc_update_section(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),

package/src/mcp/handlers/save_context.rs

@@ -130,11 +130,16 @@ pub fn handle(arguments: &Value) -> Result<String> {
         if let Some(active_session) = target {
             let sid = active_session.id.clone().unwrap_or_default();
             if keep_active {
-                let updated_path = update_active_session(&sessions_dir, &sid, &handoff_updates)?;
+                let updated_path =
+                    update_active_session(&sessions_dir, &sid, &handoff_updates, Some(arguments))?;
                 (0, updated_path, Some(sid))
             } else {
-                let closed_path =
-                    update_and_close_active_session(&sessions_dir, &sid, &handoff_updates)?;
+                let closed_path = update_and_close_active_session(
+                    &sessions_dir,
+                    &sid,
+                    &handoff_updates,
+                    Some(arguments),
+                )?;
                 (
                     if closed_path.is_some() { 1 } else { 0 },
                     closed_path,

package/src/mcp/handlers/task_checklist.rs

@@ -314,7 +314,12 @@ fn item_is_stale(doc: &DocMetadata, item: &VerificationItem) -> bool {
     let Some(hash_at_verify) = &item.content_hash_at_verify else {
         return false;
     };
-    match doc.sections.iter().find(|s| s.seq == item.fragment_seq) {
+    let Some(fragment_seq) = item.fragment_seq else {
+        // Freeform items (v2, fragment_seq=None) are never stale: they are
+        // not tied to any section's content_hash.
+        return false;
+    };
+    match doc.sections.iter().find(|s| s.seq == fragment_seq) {
         Some(section) => &section.content_hash != hash_at_verify,
         None => true,
     }
@@ -470,10 +475,17 @@ fn suggested_actions_json(data: &TaskData, docs: &[DocMetadata]) -> Vec<String>
         for item in &v.items {
             let resolved = item.status == "verified" || item.status == "skipped";
             if !resolved || item_is_stale(doc, item) {
-                actions.push(format!(
-                    "handoff_doc_verify(doc_id=\"{}\", action=\"check\", fragment_seq={}) — \"{}\" のレビュー完了時",
-                    doc.id, item.fragment_seq, item.heading
-                ));
+                let action = match item.fragment_seq {
+                    Some(seq) => format!(
+                        "handoff_doc_verify(doc_id=\"{}\", action=\"check\", fragment_seq={}) — \"{}\" のレビュー完了時",
+                        doc.id, seq, item.heading
+                    ),
+                    None => format!(
+                        "handoff_doc_verify(doc_id=\"{}\", action=\"check\", fragment_seq=null, label=\"{}\") — \"{}\" のレビュー完了時 (フリーフォーム項目)",
+                        doc.id, item.label.as_deref().unwrap_or(&item.heading), item.heading
+                    ),
+                };
+                actions.push(action);
             }
         }
     }

package/src/mcp/handlers/update_session.rs

@@ -153,11 +153,13 @@ pub fn handle(arguments: &Value) -> Result<String> {
     Ok(msg)
 }
 
-fn truncate(s: &str, max: usize) -> String {
-    if s.len() <= max {
-        s.to_string()
+fn truncate(s: &str, max_chars: usize) -> String {
+    let mut chars = s.chars();
+    let truncated: String = chars.by_ref().take(max_chars).collect();
+    if chars.next().is_some() {
+        format!("{truncated}...")
     } else {
-        format!("{}...", &s[..max])
+        truncated
     }
 }
 

package/src/mcp/tools.rs

@@ -1080,6 +1080,7 @@ pub fn all_tool_definitions() -> Vec<ToolDefinition> {
                     "text": { "type": "string", "description": "The memory body (any language). Required, non-empty." },
                     "kind": { "type": "string", "description": "Memory kind.", "enum": ["lesson", "rule", "convention", "gotcha"], "default": "lesson" },
                     "tags": { "type": "array", "items": { "type": "string" }, "description": "Optional tags; also indexed for similarity." },
+                    "keywords": { "type": "array", "items": { "type": "string" }, "description": "Subject keywords — nouns, technical terms, proper nouns that identify what this memory is about. These are weighted higher than body text in BM25 relevance scoring. Distinct from tags (classification labels)." },
                     "scope_paths": { "type": "array", "items": { "type": "string" }, "description": "Path prefixes this memory applies to (e.g. 'src/storage/'). Boosts relevance when a query touches a matching file." },
                     "merge_into": { "type": "string", "description": "Commit an AI merge: overwrite this memory id with `text` and absorb `absorb_ids`." },
                     "absorb_ids": { "type": "array", "items": { "type": "string" }, "description": "Memory ids to delete and record as superseded when merging." },
@@ -1259,6 +1260,21 @@ pub fn all_tool_definitions() -> Vec<ToolDefinition> {
                 }
             }),
         },
+        ToolDefinition {
+            name: "handoff_doc_update_section".to_string(),
+            description: "Replace a single section of a document by its seq number, without re-sending the whole document body. new_content is the replacement Markdown (including the section's own heading line); an empty string deletes the section. Sections are computed on-demand from the current body (same as doc_get/doc_save), so seq must match the document's current section numbering. expected_hash is an optional optimistic lock: when given, it must match the section's current content_hash or the call errors with the actual current hash (for retry) and makes no change. Updates the document's updated_at and content_hash, and — if a verification matrix item exists at this fragment_seq — surfaces a warning that it is now stale (its content_hash_at_verify no longer matches). Returns a JSON string {doc_id,seq,heading,content_hash,updated_at,section_count,warnings?:[…]}.".to_string(),
+            input_schema: json!({
+                "type": "object",
+                "properties": {
+                    "project_dir": { "type": "string", "description": "Project directory path. Defaults to current working directory." },
+                    "doc_id": { "type": "string", "description": "Document id or slug to update." },
+                    "seq": { "type": "integer", "description": "Section sequence number to replace (0 = preamble)." },
+                    "new_content": { "type": "string", "description": "Replacement Markdown text for this section, including its own heading line. An empty string deletes the section." },
+                    "expected_hash": { "type": "string", "description": "Optimistic lock: the section's expected current content_hash. If it does not match, the update is rejected with the actual current hash." }
+                },
+                "required": ["doc_id", "seq", "new_content"]
+            }),
+        },
         ToolDefinition {
             name: "handoff_doc_get".to_string(),
             description: "Read a document by doc_id or slug. format='full' returns the original Markdown body (read directly from _doc.<slug>.md) plus metadata; 'meta' returns metadata only (no body, cheap for graph traversal); 'section' returns one section's body (byte-sliced from the document body, requires seq). Returns a JSON string.".to_string(),
@@ -1329,17 +1345,21 @@ pub fn all_tool_definitions() -> Vec<ToolDefinition> {
         },
         ToolDefinition {
             name: "handoff_doc_verify".to_string(),
-            description: "Operate on a document's verification matrix (wiki/140-verification-matrix.md): generate (create a matrix from the document's current sections, error if one already exists), check (mark fragment_seq verified, recording verified_at/reviewer/notes/content_hash_at_verify), skip (mark fragment_seq skipped), sync (re-sync the matrix with the document's current sections — adds new sections as pending, removes deleted ones, preserves existing item status), or set_refs (update impl_refs/test_refs for fragment_seq). Overall verification_status is recomputed after every mutation: 'pending' if all items pending, 'verified' if all verified/skipped, else 'in_review'. Returns a JSON string {doc_id,verification_status,checked,skipped,pending,total,stale}.".to_string(),
+            description: "Operate on a document's verification matrix (wiki/140-verification-matrix.md): generate (create a matrix from the document's current sections, error if one already exists), check (mark fragment_seq — or its sub_item_index — verified, recording verified_at/reviewer/notes/content_hash_at_verify — fragment_seq may be a single section seq or an array of seqs to verify in one call), check_all (verify every section and sub_item in the matrix in one call, error if no matrix exists yet), skip (mark fragment_seq — or its sub_item_index — skipped), sync (re-sync the matrix with the document's current sections — adds new sections as pending, removes deleted ones, preserves existing item status), set_refs (update impl_refs/test_refs for fragment_seq), add_item (v2, spec §7.2: with fragment_seq given, append a SubItem — description required — to that section's sub_items; with fragment_seq omitted, append a new freeform top-level item not tied to any section — label required), or suggest_refs (t124.6: read-only — scans the document's scope_paths for source/test files whose fn/struct/impl/mod definitions or test functions fuzzy-match each verification item's heading, and returns candidate impl_refs/test_refs per item for the caller to review and apply via set_refs; errors if no matrix exists yet). Overall verification_status is recomputed after every mutation: 'pending' if all items pending, 'verified' if all verified/skipped, else 'in_review'. Returns a JSON string {doc_id,verification_status,checked,skipped,pending,total,stale} for mutating actions, or {doc_id,suggestions:[{fragment_seq,heading,suggested_impl_refs,suggested_test_refs}]} for suggest_refs.".to_string(),
             input_schema: json!({
                 "type": "object",
                 "properties": {
                     "project_dir": { "type": "string", "description": "Project directory path. Defaults to current working directory." },
                     "doc_id": { "type": "string", "description": "Document id or slug to operate on." },
-                    "action": { "type": "string", "description": "Verification matrix action.", "enum": ["generate", "check", "skip", "sync", "set_refs"] },
+                    "action": { "type": "string", "description": "Verification matrix action.", "enum": ["generate", "check", "check_all", "skip", "sync", "set_refs", "add_item", "suggest_refs"] },
                     "skip_seqs": { "type": "array", "items": { "type": "integer" }, "description": "generate only: section seqs to create as 'skipped' instead of 'pending'." },
-                    "fragment_seq": { "type": "integer", "description": "check/skip/set_refs: the section seq (VerificationItem.fragment_seq) to operate on." },
-                    "reviewer": { "type": "string", "description": "check: who verified it.", "enum": ["ai", "user"] },
-                    "notes": { "type": "string", "description": "check: optional free-text note." },
+                    "fragment_seq": { "description": "skip/set_refs: the section seq (VerificationItem.fragment_seq) to operate on. check: a single section seq, or an array of section seqs to verify in one call. add_item: the section seq to attach a new sub_item to; omit to add a freeform top-level item instead.", "oneOf": [ { "type": "integer" }, { "type": "array", "items": { "type": "integer" } } ] },
+                    "sub_item_index": { "type": "integer", "description": "check/skip: the 0-based SubItem.index within fragment_seq's sub_items to operate on, instead of the parent item itself." },
+                    "description": { "type": "string", "description": "add_item (fragment_seq given): the new sub_item's description. Required in this form." },
+                    "label": { "type": "string", "description": "add_item (fragment_seq omitted): the new freeform top-level item's label. Required in this form." },
+                    "category": { "type": "string", "description": "add_item: item/sub_item category (free-extensible, e.g. 'requirement', 'visual', 'regression', 'manual'). Defaults to 'requirement' for sub_items, 'visual' for freeform items." },
+                    "reviewer": { "type": "string", "description": "check/check_all: who verified it.", "enum": ["ai", "user"] },
+                    "notes": { "type": "string", "description": "check/check_all: optional free-text note." },
                     "impl_refs": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "lines": { "type": "string" }, "label": { "type": "string" } }, "required": ["path"] }, "description": "set_refs: implementation code references to attach to fragment_seq." },
                     "test_refs": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "lines": { "type": "string" }, "label": { "type": "string" } }, "required": ["path"] }, "description": "set_refs: test code references to attach to fragment_seq." }
                 },
@@ -1348,13 +1368,14 @@ pub fn all_tool_definitions() -> Vec<ToolDefinition> {
         },
         ToolDefinition {
             name: "handoff_doc_verify_status".to_string(),
-            description: "Get a document's verification matrix status: overall verification_status, progress counts (checked/skipped/pending/total/stale/percentage), and (when include_items=true) every item with a computed stale flag (its content_hash_at_verify no longer matches the section's current content_hash — spec §3.5). Errors if the document has no verification matrix yet (use handoff_doc_verify(action='generate') first). Returns a JSON string {doc_id,title,verification_status,progress:{…},items?:[…]}.".to_string(),
+            description: "Get a document's verification matrix status: overall verification_status, progress counts (checked/skipped/pending/total/stale/percentage — v2: counts leaf items, i.e. sub_items and freeform items, spec §7.4), and (when include_items=true) every item with a computed stale flag (its content_hash_at_verify no longer matches the section's current content_hash — spec §3.5). Errors if the document has no verification matrix yet (use handoff_doc_verify(action='generate') first). Returns a JSON string {doc_id,title,verification_status,progress:{…},items?:[…]} by default, or (format='checklist') a Markdown checklist rendering (spec §7.3) instead.".to_string(),
             input_schema: json!({
                 "type": "object",
                 "properties": {
                     "project_dir": { "type": "string", "description": "Project directory path. Defaults to current working directory." },
                     "doc_id": { "type": "string", "description": "Document id or slug to read verification status for." },
-                    "include_items": { "type": "boolean", "description": "Include the full per-item list (with stale detection).", "default": false }
+                    "include_items": { "type": "boolean", "description": "Include the full per-item list (with stale detection).", "default": false },
+                    "format": { "type": "string", "description": "Output format: 'json' (default, structured payload) or 'checklist' (Markdown checklist rendering with headings, sub_item checkboxes, refs, and categories).", "enum": ["json", "checklist"], "default": "json" }
                 },
                 "required": ["doc_id"]
             }),