handoff-mcp-server 0.22.0 → 0.23.0

package/Cargo.lock

@@ -145,7 +145,7 @@ dependencies = [
 
 [[package]]
 name = "handoff-mcp"
-version = "0.22.0"
+version = "0.23.0"
 dependencies = [
  "anyhow",
  "chrono",

package/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "handoff-mcp"
-version = "0.22.0"
+version = "0.23.0"
 edition = "2021"
 description = "MCP server that gives AI coding agents persistent memory across sessions"
 license = "MIT"
@@ -10,7 +10,7 @@ readme = "README.md"
 keywords = ["mcp", "ai", "claude", "handoff", "context"]
 categories = ["command-line-utilities", "development-tools"]
 rust-version = "1.85"
-exclude = ["lefthook.yml", "tmp/", "wiki/", "docs/", ".claude/", ".vscode/"]
+exclude = ["lefthook.yml", "tmp/", "wiki/", ".claude/", ".vscode/"]
 
 [dependencies]
 serde = { version = "1", features = ["derive"] }

package/README.md

@@ -556,10 +556,10 @@ handoff-mcp distinguishes the **raw human-effort estimate** you record on a task
 from the **AI-effort hours** used in scheduling and metrics:
 
 - **`require_estimate_hours`** (default `true`) — `handoff_update_task` rejects
-  creating or updating a *leaf* task (in `todo` / `in_progress` / `review` /
-  `done`) without `schedule.estimate_hours > 0`. Parent tasks (with children) and
-  `blocked` / `skipped` tasks are exempt, and an estimate already on the task
-  satisfies the requirement. Set to `false` to opt out.
+  creating or updating a *leaf* task in `in_progress` / `review` / `done` without
+  `schedule.estimate_hours > 0`. Parent tasks (with children) and tasks in `todo` /
+  `blocked` / `skipped` are exempt, and an estimate already on the task satisfies
+  the requirement. Set to `false` to opt out.
 - **`ai_estimate_multiplier`** (default `0.2`) — the factor applied to raw
   estimates to model how long the work takes when an AI agent does it. Always
   record the *raw human-effort* estimate; the multiplier is applied at

package/package.json

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

package/skills/handoff/SKILL.md

@@ -54,10 +54,11 @@ description: "Session handoff — load context at start, save at end, track task
   user that their input is needed before proceeding.
 - Create new tasks as work is discovered. Always include `done_criteria` with
   verifiable items so completion can be tracked.
-- **Always set `schedule.estimate_hours`** (raw human-effort hours, > 0) on every
-  leaf task. It is required by default — `handoff_update_task` rejects creating or
-  updating a leaf task without it (parent tasks and `blocked`/`skipped` tasks are
-  exempt). Enter the raw human-effort estimate; the AI-effort multiplier
+- **Set `schedule.estimate_hours`** (raw human-effort hours, > 0) on leaf tasks
+  when moving them to `in_progress`/`review`/`done`. It is required by default —
+  `handoff_update_task` rejects leaf tasks in those statuses without it. Tasks in
+  `todo`/`blocked`/`skipped` and parent tasks (with children) are exempt. Enter the
+  raw human-effort estimate; the AI-effort multiplier
   (`settings.ai_estimate_multiplier`, default 0.2) is applied automatically at
   aggregation time by `handoff_get_metrics`/`handoff_get_capacity`. To turn the
   requirement off, set `settings.require_estimate_hours = false`.
@@ -70,7 +71,7 @@ missing `estimate_hours` is refused, costing a round trip.
 - [ ] `title` — present (required for any new task)
 - [ ] `done_criteria` — verifiable items, not restatements of the title
 - [ ] `schedule.estimate_hours` — **> 0, raw human-effort hours.** Skip only if
-      the task is a parent (has children) or its status is `blocked`/`skipped`
+      the task is a parent (has children) or its status is `todo`/`blocked`/`skipped`
 - [ ] `priority` — `low` / `medium` / `high`
 - [ ] `labels` — at least one, so the task is findable by filter
 - [ ] `assignee` — matches a key in `config.toml [assignees.<key>]`
@@ -234,10 +235,10 @@ Use `handoff_bulk_update_tasks` for:
 - Batch assignee changes (e.g., reassigning a team member's tasks).
 - Each task update is independent — failures on one task don't roll back others.
 - The `estimate_hours` rule applies here too: an update leaving a leaf task in
-  `todo`/`in_progress`/`review`/`done` without `schedule.estimate_hours` is
-  rejected and reported in `errors[]`. Supply the estimate in the same update
-  when moving a task out of `blocked`/`skipped`. Parent tasks and the statuses
-  `blocked`/`skipped` are exempt.
+  `in_progress`/`review`/`done` without `schedule.estimate_hours` is rejected and
+  reported in `errors[]`. Supply the estimate in the same update when moving a
+  task out of `todo`/`blocked`/`skipped`. Parent tasks and the statuses
+  `todo`/`blocked`/`skipped` are exempt.
 
 ### Document Management
 
@@ -256,6 +257,7 @@ are too large for a single memory entry, use the doc tools instead — see the
 | `handoff_doc_query` | Context injection (hook-driven) — staged `full`/`outline` results by fragment size |
 | `handoff_doc_analyze` | Read-only heuristic scan of a file/directory — step 1 of importing existing docs |
 | `handoff_doc_import` | Atomic bulk write of analyzed + AI-reviewed documents — step 3 of importing existing docs |
+| `handoff_task_checklist` | Combined readiness view for a task — aggregates `done_criteria` with the verification matrices of its linked documents (`action="view"`, read-only); `action="generate"` builds `done_criteria` from a linked spec's sections |
 
 `handoff_doc_save(task_ids: [...])` creates a **bidirectional** doc↔task
 link: the document gains a `task_ids` entry and each linked task gains a

package/skills/handoff-docs/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: handoff-docs
-description: "Document management — save, read, search, import, and traverse structured project documents (specs, designs, ADRs, guides, notes). Triggers on 'ドキュメント保存', '仕様書を管理', '設計書をインポート', 'save this doc', 'import specs', 'document management', or when the user asks to persist/organize/search multi-section markdown that is too structured for a single memory entry."
+description: "Document management — save, read, search, import, and traverse structured project documents (specs, designs, ADRs, guides, notes). Triggers on 'ドキュメント保存', '仕様書を管理', '設計書をインポート', 'save this doc', 'import specs', 'document management', 'タスク開始', 'spec registration', '仕様登録', 'verification check', or when the user asks to persist/organize/search multi-section markdown that is too structured for a single memory entry, or when the AI writes a spec/design document during development."
 ---
 
 # Handoff Docs Skill
@@ -17,6 +17,32 @@ If the knowledge is a short, standalone lesson/rule/convention/gotcha (< 1 page,
 no internal sections), use `handoff-memory` instead — see "Memory vs Documents"
 in `skills/handoff-memory/SKILL.md` for the boundary.
 
+## Development Flow Integration
+
+Document management is NOT just for explicit user requests. It activates
+automatically during the standard development cycle:
+
+### When writing a spec or design
+After writing/updating a specification or finishing a `/design-review` session
+(wiki/ or tmp/), immediately:
+1. Start from a template (see "Templates" below) instead of a blank document.
+2. `handoff_doc_save(title=..., body=..., doc_type="spec", task_ids=[...])`
+3. `handoff_doc_verify(doc_id=..., action="generate")` to create the verification matrix
+
+### When starting a task
+Before implementation, fetch related specs:
+- `handoff_doc_query(task_id="<task-id>")` — surfaces linked documents automatically
+- Review the verification matrix: `handoff_doc_verify_status(doc_id=...)`
+
+### When implementation is complete
+Mark verified sections:
+- `handoff_doc_verify(doc_id=..., action="check", fragment_seq=N)` for each completed section
+- `handoff_doc_verify(doc_id=..., action="set_refs", fragment_seq=N, impl_refs=[...])` to record implementation locations
+
+### When reviewing
+Check readiness:
+- `handoff_task_checklist(task_id=..., action="view")` — combined readiness view
+
 ## The 9 Doc Tools
 
 | Tool | Purpose |
@@ -231,3 +257,31 @@ only be validated when every file is visible at once.
 `spec` (requirements/behavior contracts) · `design` (architecture/design
 docs) · `adr` (architecture decision records) · `guide` (how-to/operational
 docs) · `note` (fallback — anything that doesn't fit the above).
+
+## Templates
+
+Three starter templates are registered as `doc_type="guide"` documents tagged
+`template` (plus a type-specific tag: `spec`, `design`, or `adr`). Fetch one
+with `handoff_doc_list(tags=["template"])` or `handoff_doc_get(doc_id=...)`
+before writing a new spec/design/ADR from scratch — copy its section
+structure rather than reinventing it:
+
+| Template | Tags | Structure |
+|---|---|---|
+| Specification Template (`specification-template`) | `template`, `spec` | 課題 / ゴール / 設計 / 実装計画 / 検証チェックリスト / 未決事項 |
+| Design Document Template (`design-doc-template`) | `template`, `design` | 概要 / 制約・前提 / 設計案（採用案・代替案）/ トレードオフ表 / 実装影響範囲 / リスク |
+| ADR Template (`adr-template`) | `template`, `adr` | コンテキスト / 決定 / 理由 / 結果 |
+
+Templates are registered with `auto_inject="none"` — they are reference
+material fetched on demand, not injected into every prompt.
+
+## Memory vs Documents
+
+| Criterion | Use Memory | Use Documents |
+|---|---|---|
+| Size | < 1 page, no sections | Multi-section, structured |
+| Lifecycle | Permanent lesson/rule | Versioned with the project |
+| Granularity | Single fact/convention | Sections need independent tracking |
+| Review tracking | Not needed | Verification matrix tracks per-section |
+| Task linkage | Not applicable | Bidirectional task_ids |
+| Example | "Always use SSH for git push" | "Authentication spec with 5 sections" |

package/src/mcp/handlers/bulk_update.rs

@@ -131,9 +131,8 @@ fn apply_single_update(
 
     // Guard the same invariant handoff_update_task enforces, or a bulk patch
     // becomes a way around it. The check is on the task as it would be written —
-    // status and schedule already merged — not on the patch: a date-only patch
-    // that leaves an estimateless leaf in `todo` is exactly the state
-    // update_task refuses to write. Parent tasks (with children) are exempt.
+    // status and schedule already merged — not on the patch. Parent tasks (with
+    // children) and tasks in todo/blocked/skipped are exempt.
     let has_children = task_has_children(&task_dir)?;
     validate_estimate_required(
         require_estimate_hours,

package/src/mcp/handlers/docs.rs

@@ -1002,6 +1002,323 @@ pub fn handle_doc_verify_status(arguments: &Value) -> Result<String> {
     Ok(to_json(&out))
 }
 
+/// `handoff_doc_graph` — build a graph of every document in the project:
+/// `nodes[]` (one per document, with optional verification progress),
+/// `edges[]` (explicit parent_child/related links, plus implicit
+/// shared_task/shared_scope links when `include_implicit=true`), and
+/// `layers` (doc ids grouped by `doc_type`).
+pub fn handle_doc_graph(arguments: &Value) -> Result<String> {
+    let project_dir = resolve_project_dir(arguments)?;
+    let handoff = ensure_handoff_exists(&project_dir)?;
+
+    let include_implicit = arguments
+        .get("include_implicit")
+        .and_then(|v| v.as_bool())
+        .unwrap_or(true);
+    let include_verification = arguments
+        .get("include_verification")
+        .and_then(|v| v.as_bool())
+        .unwrap_or(false);
+
+    let docs = read_all_docs(&handoff)?;
+
+    let nodes: Vec<Value> = docs
+        .iter()
+        .map(|d| doc_graph_node_json(d, include_verification))
+        .collect();
+
+    let mut edges = doc_graph_explicit_edges(&docs);
+    if include_implicit {
+        edges.extend(doc_graph_implicit_edges(&docs));
+    }
+
+    let mut layers: std::collections::BTreeMap<String, Vec<String>> =
+        std::collections::BTreeMap::new();
+    for d in &docs {
+        layers
+            .entry(d.doc_type.clone())
+            .or_default()
+            .push(d.id.clone());
+    }
+
+    Ok(to_json(&json!({
+        "nodes": nodes,
+        "edges": edges,
+        "layers": layers,
+    })))
+}
+
+/// Builds one `handoff_doc_graph` node: id/slug/title/doc_type/tags/task_ids
+/// /section_count/updated_at, plus `verification_progress` when requested
+/// (and the document has a verification matrix).
+fn doc_graph_node_json(doc: &DocMetadata, include_verification: bool) -> Value {
+    let mut node = json!({
+        "id": doc.id,
+        "slug": doc.slug,
+        "title": doc.title,
+        "doc_type": doc.doc_type,
+        "tags": doc.tags,
+        "task_ids": doc.task_ids,
+        "section_count": doc.sections.len(),
+        "updated_at": doc.updated_at,
+    });
+    if include_verification {
+        if let Some(v) = &doc.verification {
+            let total = v.items.len();
+            let verified = v.items.iter().filter(|i| i.status == "verified").count();
+            node["verification_progress"] = json!({ "total": total, "verified": verified });
+        }
+    }
+    node
+}
+
+/// Explicit edges: `parent_id` (`type="parent_child"`, `direction="down"`,
+/// from=parent to=child) and `related[]` (`type=<rel>`,
+/// `direction="forward"`, from=this doc to=related target). Related entries
+/// pointing at an id not present in `docs` are still emitted — the graph
+/// consumer is expected to render dangling links, not silently drop them.
+fn doc_graph_explicit_edges(docs: &[DocMetadata]) -> Vec<Value> {
+    let mut edges = Vec::new();
+    for d in docs {
+        if let Some(parent_id) = &d.parent_id {
+            edges.push(json!({
+                "from": parent_id,
+                "to": d.id,
+                "type": "parent_child",
+                "direction": "down",
+            }));
+        }
+        for r in &d.related {
+            edges.push(json!({
+                "from": d.id,
+                "to": r.id,
+                "type": r.rel,
+                "direction": "forward",
+            }));
+        }
+    }
+    edges
+}
+
+/// Implicit edges: `shared_task` (two documents sharing at least one
+/// `task_ids` entry — `task_ids` on the edge lists every id shared, not just
+/// the first) and `shared_scope` (two documents sharing at least one
+/// `scope_paths` entry). Both are unordered/undirected pairs, emitted once
+/// per pair (i<j) to avoid duplicating the same relationship in both
+/// directions.
+fn doc_graph_implicit_edges(docs: &[DocMetadata]) -> Vec<Value> {
+    let mut edges = Vec::new();
+    for i in 0..docs.len() {
+        for j in (i + 1)..docs.len() {
+            let a = &docs[i];
+            let b = &docs[j];
+
+            let shared_tasks: Vec<String> = a
+                .task_ids
+                .iter()
+                .filter(|t| b.task_ids.contains(t))
+                .cloned()
+                .collect();
+            if !shared_tasks.is_empty() {
+                edges.push(json!({
+                    "from": a.id,
+                    "to": b.id,
+                    "type": "shared_task",
+                    "task_ids": shared_tasks,
+                }));
+            }
+
+            let shares_scope = a.scope_paths.iter().any(|p| b.scope_paths.contains(p));
+            if shares_scope {
+                edges.push(json!({
+                    "from": a.id,
+                    "to": b.id,
+                    "type": "shared_scope",
+                }));
+            }
+        }
+    }
+    edges
+}
+
+/// One entry in a `handoff_doc_trace` `chain[]`/`branches[].docs[]`:
+/// `{id, title, doc_type, rel}`. `rel` describes how this doc relates to the
+/// previous entry in the chain ("parent", "child", or the `related[].rel`
+/// value for a related-doc detour); `None` for the trace's starting doc.
+fn doc_trace_item_json(doc: &DocMetadata, rel: Option<&str>) -> Value {
+    json!({
+        "id": doc.id,
+        "title": doc.title,
+        "doc_type": doc.doc_type,
+        "rel": rel,
+    })
+}
+
+/// Walks the child->parent chain starting at `doc` (exclusive — `doc` itself
+/// is not included), ordered from the immediate parent up to the root.
+/// `visited` prevents infinite loops on a cyclic `parent_id` graph; a doc
+/// already visited (including `doc` itself) stops the walk rather than
+/// erroring.
+fn doc_trace_walk_up(
+    handoff: &Path,
+    doc: &DocMetadata,
+    visited: &mut std::collections::HashSet<String>,
+) -> Result<Vec<Value>> {
+    let mut out = Vec::new();
+    let mut current = doc.clone();
+    while let Some(parent_id) = current.parent_id.clone() {
+        if visited.contains(&parent_id) {
+            break;
+        }
+        let Some(parent) = find_doc_by_id(handoff, &parent_id)? else {
+            break;
+        };
+        visited.insert(parent.id.clone());
+        out.push(doc_trace_item_json(&parent, Some("parent")));
+        current = parent;
+    }
+    out.reverse();
+    Ok(out)
+}
+
+/// Recursively walks parent->children (DFS) starting at `doc` (exclusive).
+/// Returns the primary descendant chain (first child at each level) plus any
+/// `branches` recorded for multi-child forks. `visited` prevents infinite
+/// loops on a cyclic `children` graph.
+fn doc_trace_walk_down(
+    handoff: &Path,
+    doc: &DocMetadata,
+    visited: &mut std::collections::HashSet<String>,
+    branches: &mut Vec<Value>,
+) -> Result<Vec<Value>> {
+    let mut children = Vec::new();
+    for child_id in &doc.children {
+        if visited.contains(child_id) {
+            continue;
+        }
+        if let Some(child) = find_doc_by_id(handoff, child_id)? {
+            children.push(child);
+        }
+    }
+
+    if children.is_empty() {
+        return Ok(Vec::new());
+    }
+
+    // Fork detection: more than one live (non-visited, resolvable) child at
+    // this level. Every child's own sub-chain is recorded under `branches`;
+    // the first child's sub-chain also becomes the primary continuation of
+    // the returned chain, so a single-child level still reads as a plain
+    // linear chain.
+    let is_fork = children.len() > 1;
+    let mut primary_chain = Vec::new();
+
+    for (idx, child) in children.iter().enumerate() {
+        if visited.contains(&child.id) {
+            continue;
+        }
+        visited.insert(child.id.clone());
+        let mut sub_chain = vec![doc_trace_item_json(child, Some("child"))];
+        sub_chain.extend(doc_trace_walk_down(handoff, child, visited, branches)?);
+
+        if is_fork {
+            branches.push(json!({
+                "fork_from": doc.id,
+                "docs": sub_chain,
+            }));
+        }
+        if idx == 0 {
+            primary_chain = sub_chain;
+        }
+    }
+
+    Ok(primary_chain)
+}
+
+/// Appends `related` (implements/references/etc.) detours for every document
+/// already present in `chain` (by id), skipping any related id already
+/// visited. Related docs are appended once, immediately, as a flat list — a
+/// "detour" from the main chain rather than a further recursive expansion.
+fn doc_trace_related_detours(
+    handoff: &Path,
+    chain_doc_ids: &[String],
+    visited: &mut std::collections::HashSet<String>,
+) -> Result<Vec<Value>> {
+    let mut out = Vec::new();
+    for doc_id in chain_doc_ids {
+        let Some(doc) = find_doc_by_id(handoff, doc_id)? else {
+            continue;
+        };
+        for r in &doc.related {
+            if visited.contains(&r.id) {
+                continue;
+            }
+            let Some(target) = find_doc_by_id(handoff, &r.id)? else {
+                continue;
+            };
+            visited.insert(target.id.clone());
+            out.push(doc_trace_item_json(&target, Some(&r.rel)));
+        }
+    }
+    Ok(out)
+}
+
+/// `handoff_doc_trace` — trace a document's family-tree lineage: `up` (walk
+/// child->parent), `down` (walk parent->children, DFS), or `both` (merge the
+/// up chain + the target + the down chain). `related` docs encountered along
+/// the primary chain are appended as detour entries. Multi-child forks in the
+/// `down` direction are additionally reported in `branches[]`.
+pub fn handle_doc_trace(arguments: &Value) -> Result<String> {
+    let project_dir = resolve_project_dir(arguments)?;
+    let handoff = ensure_handoff_exists(&project_dir)?;
+
+    let doc_id = arguments
+        .get("doc_id")
+        .and_then(|v| v.as_str())
+        .ok_or_else(|| anyhow::anyhow!("'doc_id' is required"))?;
+    let direction = arguments
+        .get("direction")
+        .and_then(|v| v.as_str())
+        .unwrap_or("both");
+
+    let doc = resolve_doc(&handoff, doc_id)?
+        .ok_or_else(|| anyhow::anyhow!("Document not found: {doc_id}"))?;
+
+    let mut visited: std::collections::HashSet<String> = std::collections::HashSet::new();
+    visited.insert(doc.id.clone());
+
+    let mut branches: Vec<Value> = Vec::new();
+    let mut chain: Vec<Value> = Vec::new();
+
+    if direction == "up" || direction == "both" {
+        chain.extend(doc_trace_walk_up(&handoff, &doc, &mut visited)?);
+    }
+    chain.push(doc_trace_item_json(&doc, None));
+    if direction == "down" || direction == "both" {
+        chain.extend(doc_trace_walk_down(
+            &handoff,
+            &doc,
+            &mut visited,
+            &mut branches,
+        )?);
+    }
+
+    let chain_doc_ids: Vec<String> = chain
+        .iter()
+        .filter_map(|v| v["id"].as_str().map(str::to_string))
+        .collect();
+    chain.extend(doc_trace_related_detours(
+        &handoff,
+        &chain_doc_ids,
+        &mut visited,
+    )?);
+
+    Ok(to_json(&json!({
+        "chain": chain,
+        "branches": branches,
+    })))
+}
+
 fn doc_metadata_json(doc: &DocMetadata) -> Value {
     json!({
         "id": doc.id,
@@ -1041,3 +1358,135 @@ fn string_array_value(v: &Value) -> Vec<String> {
 fn to_json(v: &Value) -> String {
     serde_json::to_string_pretty(v).unwrap_or_else(|_| v.to_string())
 }
+
+#[cfg(test)]
+mod graph_tests {
+    use super::*;
+
+    fn doc(id: &str, slug: &str, doc_type: &str) -> DocMetadata {
+        DocMetadata::new(
+            id.to_string(),
+            slug.to_string(),
+            format!("Title {id}"),
+            doc_type.to_string(),
+            "2026-07-12T00:00:00Z".to_string(),
+        )
+    }
+
+    #[test]
+    fn explicit_edges_include_parent_child_and_related() {
+        let mut parent = doc("doc-1", "parent", "spec");
+        let mut child = doc("doc-2", "child", "design");
+        child.parent_id = Some("doc-1".to_string());
+        parent.children = vec!["doc-2".to_string()];
+        child.related.push(DocRelation {
+            id: "doc-3".to_string(),
+            rel: "implements".to_string(),
+        });
+        let other = doc("doc-3", "other", "note");
+
+        let docs = vec![parent, child, other];
+        let edges = doc_graph_explicit_edges(&docs);
+
+        assert!(edges.iter().any(|e| e["type"] == "parent_child"
+            && e["from"] == "doc-1"
+            && e["to"] == "doc-2"
+            && e["direction"] == "down"));
+        assert!(edges.iter().any(|e| e["type"] == "implements"
+            && e["from"] == "doc-2"
+            && e["to"] == "doc-3"
+            && e["direction"] == "forward"));
+    }
+
+    #[test]
+    fn implicit_edges_detect_shared_task_ids() {
+        let mut a = doc("doc-1", "a", "spec");
+        let mut b = doc("doc-2", "b", "spec");
+        a.task_ids = vec!["t-1".to_string(), "t-2".to_string()];
+        b.task_ids = vec!["t-2".to_string(), "t-3".to_string()];
+        let docs = vec![a, b];
+
+        let edges = doc_graph_implicit_edges(&docs);
+        let shared_task_edge = edges
+            .iter()
+            .find(|e| e["type"] == "shared_task")
+            .expect("shared_task edge must be generated");
+        assert_eq!(shared_task_edge["from"], "doc-1");
+        assert_eq!(shared_task_edge["to"], "doc-2");
+        assert_eq!(shared_task_edge["task_ids"], json!(["t-2"]));
+    }
+
+    #[test]
+    fn implicit_edges_detect_shared_scope_paths() {
+        let mut a = doc("doc-1", "a", "spec");
+        let mut b = doc("doc-2", "b", "spec");
+        a.scope_paths = vec!["src/mcp/".to_string()];
+        b.scope_paths = vec!["src/mcp/".to_string(), "src/storage/".to_string()];
+        let docs = vec![a, b];
+
+        let edges = doc_graph_implicit_edges(&docs);
+        assert!(edges
+            .iter()
+            .any(|e| e["type"] == "shared_scope" && e["from"] == "doc-1" && e["to"] == "doc-2"));
+    }
+
+    #[test]
+    fn implicit_edges_absent_when_nothing_shared() {
+        let a = doc("doc-1", "a", "spec");
+        let b = doc("doc-2", "b", "spec");
+        let docs = vec![a, b];
+
+        let edges = doc_graph_implicit_edges(&docs);
+        assert!(edges.is_empty());
+    }
+
+    #[test]
+    fn graph_node_json_includes_verification_progress_when_requested() {
+        let mut d = doc("doc-1", "a", "spec");
+        d.verification = Some(Verification {
+            status: "in_review".to_string(),
+            created_at: "2026-07-12T00:00:00Z".to_string(),
+            updated_at: "2026-07-12T00:00:00Z".to_string(),
+            items: vec![
+                VerificationItem {
+                    fragment_seq: 0,
+                    heading: String::new(),
+                    status: "verified".to_string(),
+                    impl_refs: Vec::new(),
+                    test_refs: Vec::new(),
+                    reviewer: None,
+                    verified_at: None,
+                    notes: String::new(),
+                    content_hash_at_verify: None,
+                },
+                VerificationItem {
+                    fragment_seq: 1,
+                    heading: "H".to_string(),
+                    status: "pending".to_string(),
+                    impl_refs: Vec::new(),
+                    test_refs: Vec::new(),
+                    reviewer: None,
+                    verified_at: None,
+                    notes: String::new(),
+                    content_hash_at_verify: None,
+                },
+            ],
+        });
+
+        let with_verification = doc_graph_node_json(&d, true);
+        assert_eq!(
+            with_verification["verification_progress"],
+            json!({ "total": 2, "verified": 1 })
+        );
+
+        let without_verification = doc_graph_node_json(&d, false);
+        assert!(without_verification.get("verification_progress").is_none());
+    }
+
+    #[test]
+    fn graph_node_json_omits_verification_progress_when_no_matrix() {
+        let d = doc("doc-1", "a", "spec");
+        let node = doc_graph_node_json(&d, true);
+        assert!(node.get("verification_progress").is_none());
+    }
+}

package/src/mcp/handlers/mod.rs

@@ -25,6 +25,7 @@ pub mod milestones;
 pub mod refer;
 pub mod referrals;
 pub mod save_context;
+pub mod task_checklist;
 pub mod timer;
 pub mod update_session;
 pub mod update_task;
@@ -103,11 +104,14 @@ pub fn handle_tool_call(name: &str, arguments: &Value) -> JsonRpcResponse {
         "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_graph" => docs::handle_doc_graph(arguments),
+        "handoff_doc_trace" => docs::handle_doc_trace(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),
+        "handoff_task_checklist" => task_checklist::handle(arguments),
         _ => Err(anyhow::anyhow!("Tool not implemented: {name}")),
     };