handoff-mcp-server 0.22.1 → 0.24.0

package/Cargo.lock

@@ -145,7 +145,7 @@ dependencies = [
 
 [[package]]
 name = "handoff-mcp"
-version = "0.22.1"
+version = "0.24.0"
 dependencies = [
  "anyhow",
  "chrono",
@@ -655,6 +655,6 @@ dependencies = [
 
 [[package]]
 name = "zmij"
-version = "1.0.21"
+version = "1.0.22"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "b8848ee67ecc8aedbaf3e4122217aff892639231befc6a1b58d29fff4c2cabaa"
+checksum = "bd2f034a4bebf216c9e4b7083603e024cf930873fd67830cfb083c9fa33129d9"

package/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "handoff-mcp"
-version = "0.22.1"
+version = "0.24.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.24.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,49 @@ 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
+
+## Document Creation Rules
+
+1. **One document = one complete document**
+   - Always start with a `# Title` (h1 heading)
+   - Group related content of the same category (ADR, spec, design, etc.) into a single document
+   - Example: ADR-001 through ADR-005 belong inside `# Architecture Decision Records`
+     as `## ADR-001: Redis Session` through `## ADR-005: ...` sections
+
+2. **Use `append_body` to add sections**
+   - When adding a section to an existing document, use `append_body` instead of rewriting the whole body
+   - Example: `doc_save(doc_id="doc-...", append_body="## ADR-006: ...\n\n...")`
+
+3. **MCP handles splitting internally**
+   - There is no need for the AI to split content into separate documents manually
+   - MCP automatically computes a section index at each h2 heading boundary
+   - Use `doc_get(format="section", seq=N)` to retrieve individual sections on demand
+
 ## The 9 Doc Tools
 
 | Tool | Purpose |
@@ -231,3 +274,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

@@ -61,12 +61,21 @@ pub fn handle_doc_save(arguments: &Value) -> Result<String> {
     let handoff = ensure_handoff_exists(&project_dir)?;
     ensure_docs_dir(&handoff)?;
 
-    let body = arguments
-        .get("body")
-        .and_then(|v| v.as_str())
-        .ok_or_else(|| anyhow::anyhow!("'body' is required"))?;
+    let body_arg = arguments.get("body").and_then(|v| v.as_str());
+    let append_body_arg = arguments.get("append_body").and_then(|v| v.as_str());
+    if body_arg.is_some() && append_body_arg.is_some() {
+        anyhow::bail!("'body' and 'append_body' are mutually exclusive");
+    }
+    if body_arg.is_none() && append_body_arg.is_none() {
+        anyhow::bail!("either 'body' or 'append_body' is required");
+    }
 
     let doc_id = arguments.get("doc_id").and_then(|v| v.as_str());
+    if append_body_arg.is_some() && doc_id.is_none() {
+        anyhow::bail!(
+            "'append_body' requires 'doc_id' (appending to a new document is not meaningful)"
+        );
+    }
     let existing = match doc_id {
         Some(id) => Some(
             find_doc_by_id(&handoff, id)?
@@ -75,6 +84,31 @@ pub fn handle_doc_save(arguments: &Value) -> Result<String> {
         None => None,
     };
 
+    // `append_body`: join the appended text onto the existing document's
+    // stripped body (read_doc_body — NOT read_full_body, whose
+    // BOM/frontmatter restoration would otherwise get re-detected and
+    // double-persisted by `split()` below). No separator is inserted when
+    // the existing body is empty/missing (spec §3.1 edge case).
+    let joined_body: String;
+    let body: &str = if let Some(append_body) = append_body_arg {
+        let existing_doc = existing
+            .as_ref()
+            .expect("append_body requires doc_id, checked above, so existing is Some");
+        let existing_body = read_doc_body(&handoff, &existing_doc.slug)?.unwrap_or_default();
+        let separator = arguments
+            .get("separator")
+            .and_then(|v| v.as_str())
+            .unwrap_or("\n\n");
+        joined_body = if existing_body.is_empty() {
+            append_body.to_string()
+        } else {
+            format!("{existing_body}{separator}{append_body}")
+        };
+        &joined_body
+    } else {
+        body_arg.expect("body_arg is Some in this branch, checked above")
+    };
+
     // slug: required for new documents, taken from the existing document on
     // update (the `slug` argument is ignored on update — renaming a
     // document's file-naming slug is out of scope for `doc_save`).
@@ -185,6 +219,12 @@ pub fn handle_doc_save(arguments: &Value) -> Result<String> {
     // it, computed fresh on every save (no stale-fragment cleanup needed —
     // there is nothing left on disk to clean up per section).
     let body_after_strip: String = split_doc.fragments.iter().map(|f| f.body).collect();
+    if !body_after_strip.starts_with("# ") {
+        warnings.push(
+            "body does not start with a level-1 heading — consider adding one for readability"
+                .to_string(),
+        );
+    }
     write_doc_body(&handoff, &slug, &body_after_strip)?;
     doc.sections = compute_sections(&split_doc);
 

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" },
@@ -1237,15 +1237,17 @@ pub fn all_tool_definitions() -> Vec<ToolDefinition> {
         // ---- Document management tools (P1-6a, v5 rearchitecture: wiki/130-document-management.md §3.1) ----
         ToolDefinition {
             name: "handoff_doc_save".to_string(),
-            description: "Create or update a document from a full Markdown body. The body is stored verbatim at _doc.<slug>.md and split in-memory into a `sections` byte-offset index (no per-section files), syncing the bidirectional task<->doc link when task_ids is given. Omit doc_id to create a new document (slug is then required and must be unique); pass an existing doc_id to update it (slug is taken from the existing document — it cannot be renamed via doc_save). Returns a JSON string {doc_id,slug,title,doc_type,section_count,content_hash,warnings:[…]} — warnings lists any task_ids that could not be resolved.".to_string(),
+            description: "Save a complete document. The body MUST be a whole, human-readable Markdown document starting with a level-1 heading (e.g. `# Authentication Spec`) — group related content into ONE document (for example, all ADRs belong in a single `# Architecture Decision Records` document with each ADR as an `## ADR-001: ...` section, NOT as separate documents). MCP handles section-level indexing internally, so do not pre-split content yourself. To append a new section to an existing document (e.g. adding ADR-003) without rewriting the whole body, pass `append_body` with just the new section instead of `body` — `body` and `append_body` are mutually exclusive, and `append_body` requires an existing `doc_id` (there is nothing to append to when creating a new document). The body (or, for append_body, the resulting combined body) is stored verbatim at _doc.<slug>.md and split in-memory into a `sections` byte-offset index (no per-section files), syncing the bidirectional task<->doc link when task_ids is given. Omit doc_id to create a new document (slug is then required and must be unique); pass an existing doc_id to update it (slug is taken from the existing document — it cannot be renamed via doc_save). Returns a JSON string {doc_id,slug,title,doc_type,section_count,content_hash,warnings:[…]} — warnings lists any task_ids that could not be resolved, and includes a soft notice when the saved body does not start with a level-1 heading (the save is never rejected for this).".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": "Existing document id to update. Omit to create a new document." },
+                    "doc_id": { "type": "string", "description": "Existing document id to update. Omit to create a new document. Required when append_body is given." },
                     "slug": { "type": "string", "description": "Human-readable file-naming slug ([a-z0-9-], max 60 chars), used to name _doc.<slug>.json/.md. Required when creating; ignored on update (the existing document's slug is kept)." },
-                    "title": { "type": "string", "description": "Document title. Required when creating; optional on update (defaults to the existing title)." },
-                    "body": { "type": "string", "description": "Full Markdown body. Required." },
+                    "title": { "type": "string", "description": "Document title. Required when creating; optional on update or append (defaults to the existing title)." },
+                    "body": { "type": "string", "description": "Full Markdown document, starting with a level-1 heading. Mutually exclusive with append_body; one of the two is required." },
+                    "append_body": { "type": "string", "description": "New section(s) to append to an existing document's body (e.g. `## ADR-003: ...`). Joined onto the existing body with `separator` before the usual split/save. Requires doc_id. Mutually exclusive with body; one of the two is required. Use the same line-ending style as the existing document." },
+                    "separator": { "type": "string", "description": "append_body only: text inserted between the existing body and append_body.", "default": "\n\n" },
                     "doc_type": { "type": "string", "description": "Document type.", "enum": ["spec", "design", "adr", "guide", "note"], "default": "note" },
                     "tags": { "type": "array", "items": { "type": "string" }, "description": "Tags for filtering/search." },
                     "scope_paths": { "type": "array", "items": { "type": "string" }, "description": "Path prefixes this document applies to; boosts relevance in doc_list(query=...) when a file path matches." },
@@ -1254,8 +1256,7 @@ pub fn all_tool_definitions() -> Vec<ToolDefinition> {
                     "related": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "rel": { "type": "string", "enum": ["supersedes", "references", "implements", "extends", "conflicts"] } }, "required": ["id", "rel"] }, "description": "Sibling/relative relationships to other documents." },
                     "split_level": { "type": "integer", "description": "ATX heading level at/above which the body is split into sections.", "default": 2 },
                     "auto_inject": { "type": "string", "description": "Auto-injection control.", "enum": ["auto", "full", "outline", "none"], "default": "auto" }
-                },
-                "required": ["body"]
+                }
             }),
         },
         ToolDefinition {
@@ -1417,7 +1418,7 @@ pub fn all_tool_definitions() -> Vec<ToolDefinition> {
         },
         ToolDefinition {
             name: "handoff_doc_import".to_string(),
-            description: "Bulk-write an analyzed payload (from handoff_doc_analyze, with the AI's overrides applied) as new documents. Each analyzed.auto_resolved entry must carry its file's full Markdown 'body' (doc_import writes from the payload, it does not re-read the filesystem). Each document's slug is taken from its override's 'slug' if given, else its suggested_slug, disambiguated with a numeric suffix on collision. Persists every file as a document, applies proposed_tree parent/children relationships, links task_ids to every imported document (bidirectionally), and invalidates the doc corpus cache. Returns a JSON string {imported_count,documents:[{doc_id,slug,title,section_count}],warnings:[…]}.".to_string(),
+            description: "Bulk-import pre-existing Markdown files. Each file becomes ONE document in .handoff/docs/ — the file's content is stored as-is, including its h1 heading. Do NOT split a single source file into multiple documents; MCP indexes sections internally. Writes an analyzed payload (from handoff_doc_analyze, with the AI's overrides applied) as new documents. Each analyzed.auto_resolved entry must carry its file's full Markdown 'body' (doc_import writes from the payload, it does not re-read the filesystem). Each document's slug is taken from its override's 'slug' if given, else its suggested_slug, disambiguated with a numeric suffix on collision. Persists every file as a document, applies proposed_tree parent/children relationships, links task_ids to every imported document (bidirectionally), and invalidates the doc corpus cache. Returns a JSON string {imported_count,documents:[{doc_id,slug,title,section_count}],warnings:[…]}.".to_string(),
             input_schema: json!({
                 "type": "object",
                 "properties": {
@@ -1429,6 +1430,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."
         );