handoff-mcp-server 0.22.1 → 0.23.0

package/Cargo.lock

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

package/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "handoff-mcp"
-version = "0.22.1"
+version = "0.23.0"
 edition = "2021"
 description = "MCP server that gives AI coding agents persistent memory across sessions"
 license = "MIT"

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.1",
+  "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/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;
@@ -110,6 +111,7 @@ pub fn handle_tool_call(name: &str, arguments: &Value) -> JsonRpcResponse {
         "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}")),
     };
 

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" },
@@ -1429,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"]
+            }),
+        },
     ]
 }
 

package/src/storage/docs/mod.rs

@@ -207,6 +207,34 @@ pub fn find_doc_by_id(handoff_dir: &Path, doc_id: &str) -> Result<Option<DocMeta
     Ok(docs.into_iter().find(|d| d.id == doc_id))
 }
 
+/// Resolve every `link_type == "doc"` entry in `task_links` to its
+/// [`DocMetadata`], in one pass over `docs/` (via [`read_all_docs`]) rather
+/// than one [`find_doc_by_id`] scan per link. `task_links[].target` holds the
+/// document's stable `id` (see `crate::storage::tasks::sync_doc_task_links`),
+/// so lookup is by `id`, not `slug`. Links whose target doesn't resolve to an
+/// existing document (stale/dangling link) are silently skipped — callers
+/// that need to detect that should compare the input link count against the
+/// output length themselves.
+pub fn batch_resolve_docs(
+    handoff_dir: &Path,
+    task_links: &[crate::storage::tasks::TaskLink],
+) -> Result<Vec<DocMetadata>> {
+    let doc_ids: Vec<&str> = task_links
+        .iter()
+        .filter(|l| l.link_type == "doc")
+        .map(|l| l.target.as_str())
+        .collect();
+    if doc_ids.is_empty() {
+        return Ok(Vec::new());
+    }
+
+    let all_docs = read_all_docs(handoff_dir)?;
+    Ok(doc_ids
+        .iter()
+        .filter_map(|id| all_docs.iter().find(|d| &d.id == id).cloned())
+        .collect())
+}
+
 /// Delete a document's metadata file by exact slug. Returns `Ok(false)` when
 /// the file does not exist. Does not touch the document's body file —
 /// callers that want a full delete should also call [`delete_doc_body`].
@@ -475,4 +503,95 @@ mod tests {
         write_doc_body(&h, "my-slug", "body").unwrap();
         assert!(docs_dir(&h).exists());
     }
+
+    #[test]
+    fn batch_resolve_docs_resolves_doc_links_by_id() {
+        use crate::storage::tasks::TaskLink;
+
+        let tmp = TempDir::new().unwrap();
+        let h = handoff(&tmp);
+        write_doc(&h, &sample_doc("doc-1", "doc-one")).unwrap();
+        write_doc(&h, &sample_doc("doc-2", "doc-two")).unwrap();
+
+        let links = vec![
+            TaskLink {
+                target: "doc-1".to_string(),
+                link_type: "doc".to_string(),
+                label: None,
+            },
+            TaskLink {
+                target: "doc-2".to_string(),
+                link_type: "doc".to_string(),
+                label: None,
+            },
+        ];
+
+        let resolved = batch_resolve_docs(&h, &links).unwrap();
+        assert_eq!(resolved.len(), 2);
+        let ids: Vec<&str> = resolved.iter().map(|d| d.id.as_str()).collect();
+        assert!(ids.contains(&"doc-1"));
+        assert!(ids.contains(&"doc-2"));
+    }
+
+    #[test]
+    fn batch_resolve_docs_ignores_non_doc_link_types() {
+        use crate::storage::tasks::TaskLink;
+
+        let tmp = TempDir::new().unwrap();
+        let h = handoff(&tmp);
+        write_doc(&h, &sample_doc("doc-1", "doc-one")).unwrap();
+
+        let links = vec![
+            TaskLink {
+                target: "doc-1".to_string(),
+                link_type: "doc".to_string(),
+                label: None,
+            },
+            TaskLink {
+                target: "https://example.com".to_string(),
+                link_type: "url".to_string(),
+                label: None,
+            },
+        ];
+
+        let resolved = batch_resolve_docs(&h, &links).unwrap();
+        assert_eq!(resolved.len(), 1);
+        assert_eq!(resolved[0].id, "doc-1");
+    }
+
+    #[test]
+    fn batch_resolve_docs_skips_dangling_links() {
+        use crate::storage::tasks::TaskLink;
+
+        let tmp = TempDir::new().unwrap();
+        let h = handoff(&tmp);
+        write_doc(&h, &sample_doc("doc-1", "doc-one")).unwrap();
+
+        let links = vec![
+            TaskLink {
+                target: "doc-1".to_string(),
+                link_type: "doc".to_string(),
+                label: None,
+            },
+            TaskLink {
+                target: "doc-missing".to_string(),
+                link_type: "doc".to_string(),
+                label: None,
+            },
+        ];
+
+        let resolved = batch_resolve_docs(&h, &links).unwrap();
+        assert_eq!(resolved.len(), 1);
+        assert_eq!(resolved[0].id, "doc-1");
+    }
+
+    #[test]
+    fn batch_resolve_docs_empty_links_is_empty_without_reading_docs_dir() {
+        let tmp = TempDir::new().unwrap();
+        let h = tmp.path().join(".handoff");
+        std::fs::create_dir_all(&h).unwrap();
+        // docs/ dir does not exist at all — must not error.
+        assert!(!docs_dir(&h).exists());
+        assert!(batch_resolve_docs(&h, &[]).unwrap().is_empty());
+    }
 }

package/src/storage/tasks.rs

@@ -786,10 +786,13 @@ pub fn task_has_children(task_dir: &Path) -> Result<bool> {
 }
 
 /// Whether a task in the given status requires an effort estimate.
-/// Parent tasks (with children) and blocked/skipped tasks are exempt;
-/// this only covers the status dimension.
+/// Parent tasks (with children) and blocked/skipped/todo tasks are exempt;
+/// this only covers the status dimension. `todo` is exempt so that parent
+/// tasks can be created before their children exist (the children turn the
+/// parent from a leaf into a parent, removing the estimate requirement).
+/// The estimate is enforced when the task moves to `in_progress` or later.
 pub fn status_requires_estimate(status: &str) -> bool {
-    matches!(status, "todo" | "in_progress" | "review" | "done")
+    matches!(status, "in_progress" | "review" | "done")
 }
 
 /// Validate that a leaf task carries an `estimate_hours` when the project
@@ -839,7 +842,7 @@ pub fn validate_estimate_required(
              Resend with, for example:\n  \
              {example}\n\
              Exempt from this rule: parent tasks (any task with children), and \
-             tasks in status 'blocked' or 'skipped'.\n\
+             tasks in status 'todo', 'blocked', or 'skipped'.\n\
              To disable this requirement project-wide, set \
              settings.require_estimate_hours = false."
         );