handoff-mcp-server 0.22.0 → 0.23.0

package/src/mcp/handlers/task_checklist.rs

@@ -0,0 +1,495 @@
+//! `handoff_task_checklist` — pure-view aggregation of a task's
+//! `done_criteria` and its linked documents' verification matrices
+//! (doc-20260712-191142-602891 §3.1/§3.2, "タスク×ドキュメント連携チェックシート
+//! — 改訂仕様 (v2)"). Phase 1 implements `action="view"`; Phase 2 adds
+//! `action="generate"` (doc-20260712-191142-602891 §3.2), which turns a
+//! linked spec/design document's level-2 section headings into
+//! `done_criteria` items (hardcoded defaults, no config template — spec §3.2
+//! "ハードコードデフォルト (config 不要)").
+//!
+//! `view` writes nothing back to disk: it is a computed view over existing
+//! `TaskData.task_links` (`link_type == "doc"`) and each linked document's
+//! `DocMetadata.verification` matrix. `generate` also reads only
+//! `DocMetadata.sections` (never writes to the document); it writes to the
+//! task's `done_criteria` only in `append`/`replace` mode (never in the
+//! default `preview` mode).
+
+use anyhow::Result;
+use serde_json::{json, Value};
+
+use super::resolve_project_dir;
+use crate::storage::docs::{
+    batch_resolve_docs, find_doc_by_id, read_doc, DocMetadata, SectionIndex, VerificationItem,
+};
+use crate::storage::ensure_handoff_exists;
+use crate::storage::tasks::{
+    find_task_dir_by_id, read_modify_write_task, read_task, suggest_task_id, DoneCriterion,
+    TaskData,
+};
+
+/// `handoff_task_checklist` entry point: dispatches on `action`
+/// (`"view"` default, or `"generate"`).
+pub fn handle(arguments: &Value) -> Result<String> {
+    let project_dir = resolve_project_dir(arguments)?;
+    let handoff = ensure_handoff_exists(&project_dir)?;
+    let tasks_dir = handoff.join("tasks");
+
+    let task_id = arguments
+        .get("task_id")
+        .and_then(|v| v.as_str())
+        .ok_or_else(|| anyhow::anyhow!("'task_id' is required"))?;
+    let action = arguments
+        .get("action")
+        .and_then(|v| v.as_str())
+        .unwrap_or("view");
+
+    match action {
+        "view" => handle_view(arguments, &handoff, &tasks_dir, task_id),
+        "generate" => handle_generate(arguments, &handoff, &tasks_dir, task_id),
+        other => anyhow::bail!("Unknown action '{other}'; expected 'view' or 'generate'."),
+    }
+}
+
+fn handle_view(
+    _arguments: &Value,
+    handoff: &std::path::Path,
+    tasks_dir: &std::path::Path,
+    task_id: &str,
+) -> Result<String> {
+    let task_dir = find_task_dir_by_id(tasks_dir, task_id)?
+        .ok_or_else(|| anyhow::anyhow!("{}", suggest_task_id(tasks_dir, task_id)))?;
+    let (data, _status) = read_task(&task_dir)?
+        .ok_or_else(|| anyhow::anyhow!("Task file not found in {}", task_dir.display()))?;
+
+    let doc_links: Vec<_> = data
+        .links()
+        .into_iter()
+        .filter(|l| l.link_type == "doc")
+        .collect();
+
+    if doc_links.is_empty() {
+        return Ok(to_json(&json!({
+            "task_id": data.id,
+            "title": data.title,
+            "no_linked_docs": true,
+        })));
+    }
+
+    let docs = batch_resolve_docs(handoff, &doc_links)?;
+
+    let done_criteria = done_criteria_json(&data);
+    let documents: Vec<Value> = docs.iter().map(doc_coverage_json).collect();
+    let overall = overall_progress_json(&docs);
+    let combined_readiness = combined_readiness_json(&data, &docs);
+    let suggested_actions = suggested_actions_json(&data, &docs);
+
+    Ok(to_json(&json!({
+        "task_id": data.id,
+        "title": data.title,
+        "no_linked_docs": false,
+        "done_criteria": done_criteria,
+        "verification_coverage": {
+            "documents": documents,
+            "overall": overall,
+        },
+        "combined_readiness": combined_readiness,
+        "suggested_actions": suggested_actions,
+    })))
+}
+
+/// Resolve a document by either its file-naming `slug` or its stable `id`
+/// (mirrors the private `resolve_doc` helper in `docs.rs`, duplicated here
+/// rather than made `pub` there to avoid growing that module's public
+/// surface for a single two-line lookup used by only one other handler).
+fn resolve_doc_by_slug_or_id(
+    handoff: &std::path::Path,
+    slug_or_id: &str,
+) -> Result<Option<DocMetadata>> {
+    if let Some(doc) = read_doc(handoff, slug_or_id)? {
+        return Ok(Some(doc));
+    }
+    find_doc_by_id(handoff, slug_or_id)
+}
+
+/// Only `level == 2` sections are eligible for generation (spec §3.2
+/// "ハードコードデフォルトルール: level 2 の見出しのみ対象"). `skip_seqs` is the
+/// fully-resolved exclusion set built by the caller (`handle_generate`'s
+/// `skipped_seqs`), which always includes seq=0 (the preamble) by default
+/// plus any caller-supplied `skip_seqs` param values.
+fn eligible_sections<'a>(
+    sections: &'a [SectionIndex],
+    skip_seqs: &[usize],
+) -> Vec<&'a SectionIndex> {
+    sections
+        .iter()
+        .filter(|s| s.level == 2 && !skip_seqs.contains(&s.seq))
+        .collect()
+}
+
+/// Fixed checklist items appended alongside the generated per-section
+/// criteria, keyed by `doc_type` (spec §3.2 "ハードコードデフォルト").
+fn fixed_items_for_doc_type(doc_type: &str) -> Vec<&'static str> {
+    match doc_type {
+        "spec" => vec![
+            "仕様書の全セクションがカバーされていることを確認",
+            "仕様変更があれば doc_save で更新済み",
+        ],
+        "design" => vec!["設計と実装の乖離がないことを確認"],
+        _ => vec![],
+    }
+}
+
+fn handle_generate(
+    arguments: &Value,
+    handoff: &std::path::Path,
+    tasks_dir: &std::path::Path,
+    task_id: &str,
+) -> Result<String> {
+    let task_dir = find_task_dir_by_id(tasks_dir, task_id)?
+        .ok_or_else(|| anyhow::anyhow!("{}", suggest_task_id(tasks_dir, task_id)))?;
+    let (data, _status) = read_task(&task_dir)?
+        .ok_or_else(|| anyhow::anyhow!("Task file not found in {}", task_dir.display()))?;
+
+    let doc = match arguments.get("doc_id").and_then(|v| v.as_str()) {
+        Some(doc_id) => resolve_doc_by_slug_or_id(handoff, doc_id)?
+            .ok_or_else(|| anyhow::anyhow!("Document not found: {doc_id}"))?,
+        None => {
+            let doc_links: Vec<_> = data
+                .links()
+                .into_iter()
+                .filter(|l| l.link_type == "doc")
+                .collect();
+            let docs = batch_resolve_docs(handoff, &doc_links)?;
+            docs.into_iter()
+                .find(|d| d.doc_type == "spec" || d.doc_type == "design")
+                .ok_or_else(|| {
+                    anyhow::anyhow!(
+                        "No 'doc_id' given and task {task_id} has no linked document with doc_type 'spec' or 'design'; pass 'doc_id' explicitly."
+                    )
+                })?
+        }
+    };
+
+    let mode = arguments
+        .get("mode")
+        .and_then(|v| v.as_str())
+        .unwrap_or("preview");
+    if !["preview", "append", "replace"].contains(&mode) {
+        anyhow::bail!("Unknown mode '{mode}'; expected 'preview', 'append', or 'replace'.");
+    }
+
+    let caller_skip_seqs: Vec<usize> = arguments
+        .get("skip_seqs")
+        .and_then(|v| v.as_array())
+        .map(|arr| {
+            arr.iter()
+                .filter_map(|v| v.as_u64())
+                .map(|n| n as usize)
+                .collect()
+        })
+        .unwrap_or_default();
+    let mut skipped_seqs: Vec<usize> = std::iter::once(0).chain(caller_skip_seqs).collect();
+    skipped_seqs.sort_unstable();
+    skipped_seqs.dedup();
+
+    let generated_criteria: Vec<Value> = eligible_sections(&doc.sections, &skipped_seqs)
+        .into_iter()
+        .map(|s| {
+            json!({
+                "item": format!("[{}§{}] {}", doc.doc_type, s.seq, s.heading),
+                "fragment_seq": s.seq,
+            })
+        })
+        .collect();
+    let fixed_items = fixed_items_for_doc_type(&doc.doc_type);
+
+    let applied = match mode {
+        "preview" => false,
+        "append" => {
+            apply_generated_criteria(&task_dir, &generated_criteria, false)?;
+            true
+        }
+        "replace" => {
+            apply_generated_criteria(&task_dir, &generated_criteria, true)?;
+            true
+        }
+        _ => unreachable!("mode already validated above"),
+    };
+
+    Ok(to_json(&json!({
+        "task_id": data.id,
+        "generated_criteria": generated_criteria,
+        "applied": applied,
+        "skipped_seqs": skipped_seqs,
+        "fixed_items": fixed_items,
+    })))
+}
+
+/// Writes `generated_criteria` into the task's `done_criteria`: appends when
+/// `replace` is `false`, overwrites entirely when `true`. Uses
+/// `read_modify_write_task` for optimistic-concurrency safety (mirrors
+/// `log_time.rs`), since this is a write path shared with other tools that
+/// mutate the same task file (e.g. `handoff_check_criterion`).
+fn apply_generated_criteria(
+    task_dir: &std::path::Path,
+    generated_criteria: &[Value],
+    replace: bool,
+) -> Result<()> {
+    let new_items: Vec<DoneCriterion> = generated_criteria
+        .iter()
+        .map(|c| DoneCriterion {
+            item: c["item"].as_str().unwrap_or_default().to_string(),
+            checked: false,
+        })
+        .collect();
+
+    read_modify_write_task(task_dir, |data, status| {
+        if replace {
+            data.done_criteria = new_items.clone();
+        } else {
+            data.done_criteria.extend(new_items.clone());
+        }
+        data.updated_at = Some(chrono::Utc::now().to_rfc3339());
+        Ok(status.to_string())
+    })
+}
+
+fn done_criteria_json(data: &TaskData) -> Value {
+    let items: Vec<Value> = data
+        .done_criteria
+        .iter()
+        .enumerate()
+        .map(|(index, c)| {
+            json!({
+                "index": index,
+                "item": c.item,
+                "checked": c.checked,
+            })
+        })
+        .collect();
+    let checked = data.done_criteria.iter().filter(|c| c.checked).count();
+    let total = data.done_criteria.len();
+    let percentage = if total == 0 {
+        0.0
+    } else {
+        checked as f64 / total as f64 * 100.0
+    };
+    json!({
+        "items": items,
+        "progress": { "checked": checked, "total": total, "percentage": percentage },
+    })
+}
+
+/// Priority order (highest first): stale > skipped > verified > implemented
+/// > in_progress > untouched (doc-20260712-191142-602891 §3.1 table).
+fn visual_state(doc: &DocMetadata, item: &VerificationItem) -> &'static str {
+    if item_is_stale(doc, item) {
+        return "stale";
+    }
+    match item.status.as_str() {
+        "skipped" => "skipped",
+        "verified" => "verified",
+        "pending" => {
+            let has_impl = !item.impl_refs.is_empty();
+            let has_test = !item.test_refs.is_empty();
+            if has_impl && has_test {
+                "implemented"
+            } else if has_impl {
+                "in_progress"
+            } else {
+                "untouched"
+            }
+        }
+        _ => "untouched",
+    }
+}
+
+/// An item is stale when it was verified at a content_hash that no longer
+/// matches its section's current content_hash. Mirrors
+/// `crate::mcp::handlers::docs::item_is_stale` (not reused directly since
+/// that helper is private to `docs.rs`; duplicated here rather than exposed
+/// publicly to avoid growing that already-1492-line file's public surface
+/// for a single one-line predicate).
+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) {
+        Some(section) => &section.content_hash != hash_at_verify,
+        None => true,
+    }
+}
+
+fn doc_coverage_json(doc: &DocMetadata) -> Value {
+    let empty_items: Vec<VerificationItem> = Vec::new();
+    let items = doc
+        .verification
+        .as_ref()
+        .map(|v| &v.items)
+        .unwrap_or(&empty_items);
+
+    let items_json: Vec<Value> = items
+        .iter()
+        .map(|i| {
+            json!({
+                "fragment_seq": i.fragment_seq,
+                "heading": i.heading,
+                "status": i.status,
+                "stale": item_is_stale(doc, i),
+                "visual_state": visual_state(doc, i),
+                "impl_refs": i.impl_refs,
+                "test_refs": i.test_refs,
+            })
+        })
+        .collect();
+
+    let verified = items.iter().filter(|i| i.status == "verified").count();
+    let pending = items.iter().filter(|i| i.status == "pending").count();
+    let skipped = items.iter().filter(|i| i.status == "skipped").count();
+    let stale = items.iter().filter(|i| item_is_stale(doc, i)).count();
+    let total = items.len();
+    let percentage = if total == 0 {
+        0.0
+    } else {
+        (verified + skipped) as f64 / total as f64 * 100.0
+    };
+
+    json!({
+        "doc_id": doc.id,
+        "slug": doc.slug,
+        "title": doc.title,
+        "doc_type": doc.doc_type,
+        "items": items_json,
+        "progress": {
+            "verified": verified,
+            "pending": pending,
+            "skipped": skipped,
+            "stale": stale,
+            "total": total,
+            "percentage": percentage,
+        },
+    })
+}
+
+fn overall_progress_json(docs: &[DocMetadata]) -> Value {
+    let mut verified = 0;
+    let mut pending = 0;
+    let mut stale = 0;
+    let mut total = 0;
+    for doc in docs {
+        if let Some(v) = &doc.verification {
+            verified += v.items.iter().filter(|i| i.status == "verified").count();
+            pending += v.items.iter().filter(|i| i.status == "pending").count();
+            stale += v.items.iter().filter(|i| item_is_stale(doc, i)).count();
+            total += v.items.len();
+        }
+    }
+    let percentage = if total == 0 {
+        0.0
+    } else {
+        verified as f64 / total as f64 * 100.0
+    };
+    json!({ "verified": verified, "pending": pending, "stale": stale, "total": total, "percentage": percentage })
+}
+
+/// Typed blockers (doc-20260712-191142-602891 §3.1 M7: "blockers は typed
+/// objects"): one entry per unchecked done_criteria item
+/// (`{type:"criteria", index, item}`), one per non-verified/non-skipped
+/// verification item (`{type:"verification", doc_id, doc_slug, fragment_seq,
+/// heading}`), and one per linked doc that has no verification matrix at all
+/// (`{type:"verification_missing", doc_id, doc_slug}` — mirrors
+/// `handle_doc_verify_status`'s hard error on the same condition, so a doc
+/// that never had `action="generate"` run cannot silently count as ready).
+fn combined_readiness_json(data: &TaskData, docs: &[DocMetadata]) -> Value {
+    let mut blockers = Vec::new();
+
+    for (index, c) in data.done_criteria.iter().enumerate() {
+        if !c.checked {
+            blockers.push(json!({ "type": "criteria", "index": index, "item": c.item }));
+        }
+    }
+
+    for doc in docs {
+        let Some(v) = &doc.verification else {
+            blockers.push(json!({
+                "type": "verification_missing",
+                "doc_id": doc.id,
+                "doc_slug": doc.slug,
+            }));
+            continue;
+        };
+        for item in &v.items {
+            let resolved = item.status == "verified" || item.status == "skipped";
+            if !resolved || item_is_stale(doc, item) {
+                blockers.push(json!({
+                    "type": "verification",
+                    "doc_id": doc.id,
+                    "doc_slug": doc.slug,
+                    "fragment_seq": item.fragment_seq,
+                    "heading": item.heading,
+                }));
+            }
+        }
+    }
+
+    let done_criteria_met =
+        !data.done_criteria.is_empty() && data.done_criteria.iter().all(|c| c.checked);
+    let verification_complete = docs.iter().all(|d| match &d.verification {
+        None => false,
+        Some(v) => v
+            .items
+            .iter()
+            .all(|i| (i.status == "verified" || i.status == "skipped") && !item_is_stale(d, i)),
+    });
+    let ready = done_criteria_met && verification_complete;
+
+    json!({
+        "done_criteria_met": done_criteria_met,
+        "verification_complete": verification_complete,
+        "ready": ready,
+        "blockers": blockers,
+    })
+}
+
+/// Advisory next-action hints (doc-20260712-191142-602891 §3.1 / §2.3: no
+/// auto-sync, `suggested_actions` presents next steps for the caller to run
+/// itself). One suggestion per unresolved verification item, one per doc
+/// with no verification matrix yet, and one per unchecked done_criteria
+/// item, each naming the concrete tool call to make.
+fn suggested_actions_json(data: &TaskData, docs: &[DocMetadata]) -> Vec<String> {
+    let mut actions = Vec::new();
+
+    for doc in docs {
+        let Some(v) = &doc.verification else {
+            actions.push(format!(
+                "handoff_doc_verify(doc_id=\"{}\", action=\"generate\") — \"{}\" の検証マトリクスがまだ存在しない",
+                doc.id, doc.title
+            ));
+            continue;
+        };
+        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
+                ));
+            }
+        }
+    }
+
+    for (index, c) in data.done_criteria.iter().enumerate() {
+        if !c.checked {
+            actions.push(format!(
+                "handoff_check_criterion(task_id=\"{}\", criterion_index={}) — \"{}\" 完了時",
+                data.id, index, c.item
+            ));
+        }
+    }
+
+    actions
+}
+
+fn to_json(v: &Value) -> String {
+    serde_json::to_string_pretty(v).unwrap_or_else(|_| v.to_string())
+}

package/src/mcp/tools.rs

@@ -275,7 +275,7 @@ pub fn all_tool_definitions() -> Vec<ToolDefinition> {
         },
         ToolDefinition {
             name: "handoff_update_task".to_string(),
-            description: "Add, update, or move a task. Manages the tasks/ directory structure. When creating a leaf task, always include task.schedule.estimate_hours (raw human-effort hours, > 0); it is rejected without one unless the task is a parent or is blocked/skipped.".to_string(),
+            description: "Add, update, or move a task. Manages the tasks/ directory structure. Include task.schedule.estimate_hours (raw human-effort hours, > 0) when moving a leaf task to in_progress/review/done; it is rejected without one unless the task is a parent, todo, blocked, or skipped.".to_string(),
             input_schema: json!({
                 "type": "object",
                 "properties": {
@@ -285,7 +285,7 @@ pub fn all_tool_definitions() -> Vec<ToolDefinition> {
                     },
                     "task": {
                         "type": "object",
-                        "description": "The task to add or update. When creating a leaf task (status todo/in_progress/review/done), schedule.estimate_hours is REQUIRED and the call is rejected without it. Omit it only for parent tasks (any task with children) or status blocked/skipped.",
+                        "description": "The task to add or update. schedule.estimate_hours is REQUIRED when a leaf task is in status in_progress/review/done. Omit it for parent tasks (any task with children) or status todo/blocked/skipped.",
                         "properties": {
                             "id": { "type": "string", "description": "Task ID. Omit for auto-generated ID. If provided and task exists, updates it. If provided and task does not exist, creates a new task with that ID (upsert)." },
                             "title": { "type": "string", "description": "Required for new tasks. Optional when updating (id present)." },
@@ -320,11 +320,11 @@ pub fn all_tool_definitions() -> Vec<ToolDefinition> {
                             },
                             "schedule": {
                                 "type": "object",
-                                "description": "Schedule and effort tracking. Supply this with estimate_hours whenever creating a leaf task.",
+                                "description": "Schedule and effort tracking. Supply estimate_hours when a leaf task enters in_progress/review/done.",
                                 "properties": {
                                     "start_date": { "type": "string", "description": "YYYY-MM-DD" },
                                     "due_date": { "type": "string", "description": "YYYY-MM-DD" },
-                                    "estimate_hours": { "type": "number", "description": "REQUIRED for leaf tasks (status todo/in_progress/review/done); the call is rejected without it. Omit only for parent tasks (any task with children) or status blocked/skipped. Raw human-effort hours, > 0 — do not pre-multiply by settings.ai_estimate_multiplier, which is applied at aggregation time." },
+                                    "estimate_hours": { "type": "number", "description": "REQUIRED for leaf tasks in status in_progress/review/done; the call is rejected without it. Omit for parent tasks (any task with children) or status todo/blocked/skipped. Raw human-effort hours, > 0 — do not pre-multiply by settings.ai_estimate_multiplier, which is applied at aggregation time." },
                                     "actual_hours": { "type": "number", "description": "Hours actually spent. Prefer handoff_log_time, which adds to this and decrements remaining_hours atomically." },
                                     "remaining_hours": { "type": "number", "description": "Hours remaining. Auto-decremented by handoff_log_time." },
                                     "milestone": { "type": "string" },
@@ -864,7 +864,7 @@ pub fn all_tool_definitions() -> Vec<ToolDefinition> {
         },
         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. Enforces the same estimate rule as handoff_update_task: a leaf task left in status todo/in_progress/review/done must carry schedule.estimate_hours (> 0). Offending updates are rejected individually and reported in errors[]; the rest still apply.".to_string(),
+            description: "Update multiple tasks in one call. Useful for applying auto-schedule results or bulk status/assignee changes. Enforces the same estimate rule as handoff_update_task: a leaf task in status in_progress/review/done must carry schedule.estimate_hours (> 0). Offending updates are rejected individually and reported in errors[]; the rest still apply.".to_string(),
             input_schema: json!({
                 "type": "object",
                 "properties": {
@@ -874,12 +874,12 @@ pub fn all_tool_definitions() -> Vec<ToolDefinition> {
                     },
                     "updates": {
                         "type": "array",
-                        "description": "Array of task updates to apply. Each is validated on its own: if an update would leave a leaf task in status todo/in_progress/review/done without schedule.estimate_hours, that update is rejected and listed in errors[] while the others still apply. Supply estimate_hours in the same update to move an estimateless task out of blocked/skipped.",
+                        "description": "Array of task updates to apply. Each is validated on its own: if an update would leave a leaf task in status in_progress/review/done without schedule.estimate_hours, that update is rejected and listed in errors[] while the others still apply. Supply estimate_hours in the same update to move an estimateless task out of blocked/skipped or todo.",
                         "items": {
                             "type": "object",
                             "properties": {
                                 "task_id": { "type": "string", "description": "Task ID to update." },
-                                "status": { "type": "string", "enum": ["todo", "in_progress", "review", "done", "blocked", "skipped"], "description": "Moving a leaf task into todo/in_progress/review/done requires schedule.estimate_hours to be present or supplied in the same update. Parent tasks (any task with children) and the statuses blocked/skipped are exempt." },
+                                "status": { "type": "string", "enum": ["todo", "in_progress", "review", "done", "blocked", "skipped"], "description": "Moving a leaf task into in_progress/review/done requires schedule.estimate_hours to be present or supplied in the same update. Parent tasks (any task with children) and the statuses todo/blocked/skipped are exempt." },
                                 "priority": { "type": "string", "enum": ["low", "medium", "high"] },
                                 "assignee": { "type": "string" },
                                 "notes": { "type": "string", "description": "Replace task notes." },
@@ -890,7 +890,7 @@ pub fn all_tool_definitions() -> Vec<ToolDefinition> {
                                     "properties": {
                                         "start_date": { "type": "string", "description": "YYYY-MM-DD" },
                                         "due_date": { "type": "string", "description": "YYYY-MM-DD" },
-                                        "estimate_hours": { "type": "number", "description": "REQUIRED for a leaf task left in status todo/in_progress/review/done; the update is rejected without it. Omit only for parent tasks (any task with children) or status blocked/skipped. Raw human-effort hours, > 0 — do not pre-multiply by settings.ai_estimate_multiplier, which is applied at aggregation time." },
+                                        "estimate_hours": { "type": "number", "description": "REQUIRED for a leaf task in status in_progress/review/done; the update is rejected without it. Omit for parent tasks (any task with children) or status todo/blocked/skipped. Raw human-effort hours, > 0 — do not pre-multiply by settings.ai_estimate_multiplier, which is applied at aggregation time." },
                                         "actual_hours": { "type": "number", "description": "Hours actually spent. Prefer handoff_log_time, which adds to this and decrements remaining_hours atomically." },
                                         "remaining_hours": { "type": "number", "description": "Hours remaining. Auto-decremented by handoff_log_time." },
                                         "milestone": { "type": "string" },
@@ -1358,6 +1358,31 @@ pub fn all_tool_definitions() -> Vec<ToolDefinition> {
                 "required": ["doc_id"]
             }),
         },
+        ToolDefinition {
+            name: "handoff_doc_graph".to_string(),
+            description: "Build a graph of every document in the project: nodes (one per document, with id/slug/title/doc_type/tags/task_ids/section_count/updated_at, plus verification_progress {total,verified} when include_verification=true and a matrix exists), edges (explicit parent_id -> type='parent_child'/direction='down', explicit related[] -> type=<rel>/direction='forward', and — when include_implicit=true — implicit shared_task edges for documents sharing task_ids and shared_scope edges for documents sharing scope_paths), and layers (doc ids grouped by doc_type). Intended for graph-visualization UIs. Returns a JSON string {nodes:[…],edges:[…],layers:{…}}.".to_string(),
+            input_schema: json!({
+                "type": "object",
+                "properties": {
+                    "project_dir": { "type": "string", "description": "Project directory path. Defaults to current working directory." },
+                    "include_implicit": { "type": "boolean", "description": "Also emit shared_task/shared_scope implicit edges.", "default": true },
+                    "include_verification": { "type": "boolean", "description": "Attach verification_progress {total,verified} to each node that has a verification matrix.", "default": false }
+                }
+            }),
+        },
+        ToolDefinition {
+            name: "handoff_doc_trace".to_string(),
+            description: "Trace a document's family-tree lineage from doc_id (id or slug): direction='up' walks the child->parent chain to the root; 'down' walks parent->children (DFS); 'both' (default) merges the up chain, the target doc, and the down chain into one ordered chain (root to leaf). related (implements/references/etc.) documents encountered along the chain are appended as detour entries. Multi-child forks encountered in the down direction are additionally reported in branches[] (one entry per fork, {fork_from,docs:[…]}). Cycle-safe: a visited set skips any document already seen in the traversal. Returns a JSON string {chain:[{id,title,doc_type,rel}…],branches:[{fork_from,docs:[…]}…]}.".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 trace from." },
+                    "direction": { "type": "string", "description": "Traversal direction.", "enum": ["up", "down", "both"], "default": "both" }
+                },
+                "required": ["doc_id"]
+            }),
+        },
         ToolDefinition {
             name: "handoff_doc_query".to_string(),
             description: "Inject document sections relevant to the current prompt/file/task (hook-driven context injection, mirrors memory_query at section granularity). Ranks by BM25 relevance + scope_paths match + task_id affinity, then stages each result as 'full' (whole section body, when its token estimate is within the inline threshold) or 'outline' (heading + sibling table of contents only, for larger sections — fetch the body via doc_get(format='section')). With session_id, already-injected sections (same content_hash) are skipped this session; mark_injected (default true) records survivors. suppress_doc_ids excludes given documents from this call's results; combined with suppress_until_changed=true (requires session_id), the suppression is recorded in the session's injected sidecar and persists across future calls until that document's content_hash changes. Returns a JSON string {documents:[…],injected_count}.".to_string(),
@@ -1404,6 +1429,22 @@ pub fn all_tool_definitions() -> Vec<ToolDefinition> {
                 "required": ["analyzed"]
             }),
         },
+        ToolDefinition {
+            name: "handoff_task_checklist".to_string(),
+            description: "action=\"view\" (default): pure-view aggregation of a task's done_criteria and its linked documents' verification matrices. No new data is written — reads task_links (link_type=\"doc\") and each linked document's verification matrix, computed fresh on every call. Returns {task_id,title,no_linked_docs:true} as a fast-path response when the task has no linked documents. Otherwise returns {task_id,title,no_linked_docs:false,done_criteria:{items:[…],progress:{…}},verification_coverage:{documents:[{doc_id,slug,title,doc_type,items:[{fragment_seq,heading,status,stale,visual_state,impl_refs,test_refs}],progress:{…}}],overall:{…}},combined_readiness:{done_criteria_met,verification_complete,ready,blockers:[{type:\"criteria\"|\"verification\",…}]},suggested_actions:[…]}. Each item's visual_state is computed in priority order stale > skipped > verified > implemented (pending+impl_refs+test_refs) > in_progress (pending+impl_refs only) > untouched. action=\"generate\": turns a linked spec/design document's level-2 section headings into done_criteria items using hardcoded defaults (no config template) — format '[{doc_type}§{seq}] {heading}', seq=0 (preamble) plus any skip_seqs excluded. doc_id defaults to the first linked document with doc_type 'spec' or 'design' when omitted. mode=\"preview\" (default) returns the generated items without writing; \"append\" adds them to the task's existing done_criteria; \"replace\" overwrites done_criteria entirely — both writes go through the same optimistic-concurrency path as handoff_check_criterion. Returns {task_id,generated_criteria:[{item,fragment_seq}],applied,skipped_seqs,fixed_items}, where fixed_items is a doc_type-specific list of non-section checklist items (spec: 2 items; design: 1 item; other doc_types: []).".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 build the checklist for (e.g. 't1', 't1.2')." },
+                    "action": { "type": "string", "description": "Checklist action.", "enum": ["view", "generate"], "default": "view" },
+                    "doc_id": { "type": "string", "description": "generate only: document id or slug to generate from. Defaults to the first task-linked document with doc_type 'spec' or 'design'." },
+                    "mode": { "type": "string", "description": "generate only: 'preview' returns items without writing, 'append' adds to existing done_criteria, 'replace' overwrites done_criteria entirely.", "enum": ["preview", "append", "replace"], "default": "preview" },
+                    "skip_seqs": { "type": "array", "items": { "type": "integer" }, "description": "generate only: additional section seqs to exclude, beyond the always-skipped seq=0 preamble." }
+                },
+                "required": ["task_id"]
+            }),
+        },
     ]
 }