handoff-mcp-server 0.19.0 → 0.20.0

package/Cargo.lock

@@ -136,7 +136,7 @@ dependencies = [
 
 [[package]]
 name = "handoff-mcp"
-version = "0.19.0"
+version = "0.20.0"
 dependencies = [
  "anyhow",
  "chrono",
@@ -208,9 +208,9 @@ dependencies = [
 
 [[package]]
 name = "lexsim"
-version = "0.1.0"
+version = "0.4.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "579b9d7ab407540bead4688eaf1675410a198d77c237a30cda55597df98926e1"
+checksum = "14b08f26a4b07325e83c0211adb36d0223fae644534dacd4eae72153c1ccd873"
 dependencies = [
  "unicode-normalization",
  "unicode-segmentation",

package/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "handoff-mcp"
-version = "0.19.0"
+version = "0.20.0"
 edition = "2021"
 description = "MCP server that gives AI coding agents persistent memory across sessions"
 license = "MIT"
@@ -20,7 +20,7 @@ toml_edit = "0.22"
 chrono = { version = "0.4", features = ["serde"] }
 anyhow = "1"
 thiserror = "2"
-lexsim = "0.1.0"
+lexsim = ">=0.1.0, <1.0.0"
 
 [dev-dependencies]
 tempfile = "3.27.0"

package/README.md

@@ -115,6 +115,75 @@ version. Note that `install-local.sh` **only rebuilds the binary and refreshes
 the plugin cache** — it does not register the marketplace or enable the plugin,
 so steps 2 and 3 are a one-time bootstrap.
 
+### Updating
+
+If you installed handoff-mcp as a plugin, it updates along **two independent
+paths**, and you need both. The plugin does not bundle the binary:
+`plugin.json` registers the MCP server as `command: "handoff-mcp"`, which
+Claude Code resolves on your `PATH`. So the marketplace ships the skills and
+the plugin manifest, while npm or cargo ships the executable that actually
+implements the MCP tools.
+
+(Installed without the plugin, via `cargo install` or `npm install -g` alone?
+Then only step 1 and the restart apply.)
+
+Updating only the plugin leaves you on the old MCP tools. Updating only the
+binary leaves you on the old skills.
+
+```bash
+# 1. Binary — this is what implements the MCP tools
+npm install -g handoff-mcp-server@latest
+# or: cargo install handoff-mcp --force
+
+# 2. Marketplace catalog — fetch the new version list
+/plugin marketplace update handoff-mcp-marketplace
+
+# 3. Plugin — skills and manifest
+/plugin update handoff-mcp@handoff-mcp-marketplace
+
+# 4. Restart Claude Code
+```
+
+Update the optional plugins the same way if you installed them:
+
+```bash
+/plugin update handoff-task-loop@handoff-mcp-marketplace
+/plugin update handoff-mcp-hooks@handoff-mcp-marketplace
+```
+
+Steps 1 and 3 update different things, and neither substitutes for the other.
+`/plugin update` never touches the binary — it swaps the cached plugin directory,
+which contains no executable at all — so no amount of restarting will give you
+new MCP tools if you skipped step 1. Conversely, step 1 rewrites the file on disk
+but the MCP server Claude Code already spawned keeps running the old image, so
+you get the new tools only after step 4.
+
+Step 4 is therefore not optional, and `/reload-plugins` is not a substitute: it
+refreshes skills, not the MCP server process.
+
+Do not expect step 1 to take effect on its own. An installer that overwrites a
+*running* binary in place fails on Linux with `Text file busy`; installers that
+replace the file instead (unlink, then create — what `install-local.sh` does)
+succeed, and leave the already-running server executing the now-deleted old
+image until it restarts. Either way, the new tools appear only after step 4.
+
+Verify the update landed:
+
+```bash
+which handoff-mcp          # the binary Claude Code will actually run
+handoff-mcp --version
+claude plugin list         # plugin version, per marketplace
+```
+
+`claude plugin list` reports the version you actually have installed. Note that
+`claude plugin details` reads the marketplace source instead, so it shows the
+version on offer whether or not you have updated to it — don't use it to
+confirm an update.
+
+**Local development checkout**: `./scripts/install-local.sh` does both halves at
+once (rebuilds the binary into `~/.local/bin` and refreshes the plugin cache).
+Restart Claude Code afterwards.
+
 **Troubleshooting**
 
 - **Plugin or skills don't show up** — run `/reload-plugins`, or restart Claude
@@ -123,6 +192,43 @@ so steps 2 and 3 are a one-time bootstrap.
   `/plugin marketplace update handoff-mcp-marketplace`, then reinstall.
 - **MCP server won't start** — open `/plugin` → **Errors** tab, and confirm the
   binary is on your `PATH` (`which handoff-mcp`).
+- **You updated, but the MCP tools still behave like the old version** — you
+  almost certainly updated the plugin without updating the binary, or you
+  updated the binary but did not restart Claude Code. Work through the four
+  steps above in order.
+- **An older `handoff-mcp` earlier on your `PATH` shadows the new one.** This is
+  the most common cause of "I updated and nothing changed", because
+  `npm install -g` and `cargo install` write to *different* directories. List
+  every copy and see which one wins:
+
+  ```bash
+  type -a handoff-mcp                       # every match, in resolution order
+  for d in ${PATH//:/ }; do
+    [ -x "$d/handoff-mcp" ] && echo "$d -> $("$d/handoff-mcp" --version)"
+  done
+  ```
+
+  The first line is the one Claude Code runs. Remove the stale copies (e.g.
+  `cargo uninstall handoff-mcp`, or delete the old file), or put the directory
+  holding the current binary earlier on your `PATH`.
+
+- **`--version` says the right number but the behavior is old.** A version
+  string only changes when a release bumps it, so two builds of the *same*
+  version — a stale `cargo install` and a fresh one — report identically.
+  Compare the file itself rather than the version:
+
+  ```bash
+  ls -l "$(which handoff-mcp)"   # check the mtime
+  ```
+
+  When in doubt, reinstall the binary and restart Claude Code.
+
+- **Old versions pile up in the plugin cache.** Claude Code keeps each installed
+  version in its own directory under
+  `~/.claude/plugins/cache/handoff-mcp-marketplace/<plugin>/<version>/`. This is
+  harmless — the active version is recorded in
+  `~/.claude/plugins/installed_plugins.json` — but you can reclaim the space by
+  deleting the directories for versions you no longer use.
 
 ### cargo
 
@@ -569,8 +675,9 @@ If you already ran `handoff-mcp setup` before this change, migrate with
 - **Manual edit**: open `~/.claude/settings.json` and delete the
   `hooks.SessionStart` entry whose `tool` is `handoff_memory_cleanup` (remove
   the whole `SessionStart` key if that was its only entry).
-- **Plugin users**: `/plugin update` to pick up the new `hooks.json`, then
-  restart Claude Code.
+- **Plugin users**: `/plugin update handoff-mcp-hooks@handoff-mcp-marketplace`
+  to pick up the new `hooks.json`, then restart Claude Code. This one ships
+  inside the plugin, so no binary update is needed.
 
 Restart Claude Code after any of the above for the change to take effect.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "handoff-mcp-server",
-  "version": "0.19.0",
+  "version": "0.20.0",
   "description": "MCP server that gives AI coding agents persistent memory across sessions",
   "license": "MIT",
   "author": "AlphaElements <66808803+alphaelements@users.noreply.github.com>",
@@ -21,7 +21,10 @@
     "handoff-mcp": "./bin/handoff-mcp.js"
   },
   "scripts": {
-    "postinstall": "node scripts/postinstall.js"
+    "postinstall": "node scripts/postinstall.js",
+    "test:js": "node --test \"plugin-task-loop/workflows/lib/*.test.js\"",
+    "sync:workflow": "./scripts/sync-workflow-inline.sh",
+    "check:workflow": "./scripts/sync-workflow-inline.sh --check"
   },
   "files": [
     "bin/handoff-mcp.js",

package/scripts/sync-plugin-skills.sh

@@ -1,11 +1,33 @@
 #!/usr/bin/env bash
 # Sync skills/ -> plugin/skills/ for plugin distribution.
-# Run before release to ensure the plugin has the latest skills.
+#
+# plugin/skills/ is generated, but it is COMMITTED: the marketplace serves the
+# plugin straight from the repository, so a skill that is not committed there
+# never reaches an installed plugin. Run this after editing skills/, and commit
+# the result.
+#
+#   sync-plugin-skills.sh            sync skills/ -> plugin/skills/
+#   sync-plugin-skills.sh --check    exit non-zero if they differ (no writes)
 set -euo pipefail
 
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
 ROOT="$(dirname "$SCRIPT_DIR")"
 
+if [ "${1:-}" = "--check" ]; then
+  if [ ! -d "$ROOT/plugin/skills" ]; then
+    echo "ERROR: plugin/skills/ is missing. Run './scripts/sync-plugin-skills.sh'." >&2
+    exit 1
+  fi
+  if ! diff -rq "$ROOT/skills/" "$ROOT/plugin/skills/" >/dev/null 2>&1; then
+    echo "ERROR: plugin/skills/ is out of sync with skills/:" >&2
+    diff -rq "$ROOT/skills/" "$ROOT/plugin/skills/" >&2 || true
+    echo "Run './scripts/sync-plugin-skills.sh' and commit the result." >&2
+    exit 1
+  fi
+  echo "OK: plugin/skills/ is in sync with skills/."
+  exit 0
+fi
+
 rm -rf "$ROOT/plugin/skills"
 cp -a "$ROOT/skills" "$ROOT/plugin/skills"
 

package/scripts/sync-plugin-version.sh

@@ -0,0 +1,85 @@
+#!/usr/bin/env bash
+# Sync plugin/marketplace manifest versions to package.json's version.
+#
+# package.json is the source of truth (kept in sync with Cargo.toml manually
+# per CLAUDE.md "Version sync" rule). This script propagates that version to:
+#   - plugin/.claude-plugin/plugin.json
+#   - plugin-hooks/.claude-plugin/plugin.json
+#   - plugin-task-loop/.claude-plugin/plugin.json
+#   - .claude-plugin/marketplace.json (all three "version" entries)
+#
+# Uses regex line replacement (not json.dump) so untouched formatting in
+# these hand-maintained manifests is preserved byte-for-byte.
+#
+# Usage:
+#   ./scripts/sync-plugin-version.sh          # fix mismatches in place
+#   ./scripts/sync-plugin-version.sh --check  # exit 1 if anything is out of sync, fix nothing
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+ROOT="$(dirname "$SCRIPT_DIR")"
+cd "$ROOT"
+
+MODE="fix"
+if [ "${1:-}" = "--check" ]; then
+  MODE="check"
+fi
+
+python3 - "$MODE" <<'PYEOF'
+import json
+import re
+import sys
+
+mode = sys.argv[1]
+
+with open("package.json") as f:
+    root_version = json.load(f)["version"]
+
+version_line_re = re.compile(r'^(\s*"version"\s*:\s*)"[^"]*"(,?\s*(?:\r?\n)?)$')
+
+def sync_file(path, mismatches):
+    with open(path) as f:
+        lines = f.readlines()
+    changed = False
+    out = []
+    for line in lines:
+        m = version_line_re.match(line)
+        if m:
+            current = re.search(r'"version"\s*:\s*"([^"]*)"', line).group(1)
+            if current != root_version:
+                mismatches.append((path, current))
+                changed = True
+                line = f'{m.group(1)}"{root_version}"{m.group(2)}'
+        out.append(line)
+    if changed and mode == "fix":
+        with open(path, "w") as f:
+            f.writelines(out)
+    return changed
+
+mismatches = []
+plugin_files = [
+    "plugin/.claude-plugin/plugin.json",
+    "plugin-hooks/.claude-plugin/plugin.json",
+    "plugin-task-loop/.claude-plugin/plugin.json",
+    ".claude-plugin/marketplace.json",
+]
+
+for path in plugin_files:
+    sync_file(path, mismatches)
+
+if mode == "check":
+    if mismatches:
+        print(f"Version mismatch: package.json is {root_version}, but found:")
+        for path, version in mismatches:
+            print(f"  {path}: {version}")
+        print("Run ./scripts/sync-plugin-version.sh to fix.")
+        sys.exit(1)
+    print(f"All plugin/marketplace manifests match package.json ({root_version}).")
+else:
+    if mismatches:
+        print(f"Synced {len(mismatches)} version occurrence(s) to {root_version}:")
+        for path, old_version in mismatches:
+            print(f"  {path}: {old_version} -> {root_version}")
+    else:
+        print(f"Already in sync at version {root_version}. No changes made.")
+PYEOF

package/scripts/sync-workflow-inline.sh

@@ -0,0 +1,138 @@
+#!/usr/bin/env bash
+#
+# sync-workflow-inline.sh — keep workflow scripts self-contained.
+#
+# The Workflow runtime cannot `import` (probed: "import() is not available in
+# workflow scripts"; `require` is undefined), and workflow scripts have a
+# top-level `return` so Node cannot import *them* either. Neither side can reach
+# the other, yet we still want the shared logic unit-tested.
+#
+# Resolution: the pure logic lives in testable ES modules (the source of truth).
+# Each module's INLINE region is mirrored verbatim into the workflow script
+# between GENERATED markers. This script performs — or verifies — that mirror.
+#
+#   ./scripts/sync-workflow-inline.sh          # rewrite the generated blocks
+#   ./scripts/sync-workflow-inline.sh --check  # fail if out of sync (CI/hook)
+#
+# Mirrors the contract of scripts/sync-plugin-version.sh.
+
+set -euo pipefail
+
+REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+cd "$REPO_ROOT"
+
+TARGET="plugin-task-loop/workflows/session-execute.js"
+
+# Modules mirrored into TARGET, in the order they must appear.
+# Each entry is a bare module name; source is lib/<name>.js.
+#
+# Order is load-bearing where one module's inline region calls another's:
+# `context-injection` calls resolveProfile()/profileStages() from `profile`, so
+# `profile` must be mirrored ahead of it (const bindings are in the temporal dead
+# zone until their block is evaluated).
+# `task-graph` is self-contained (pure union-find over the assignment arrays), so
+# its position is free; it sits last to keep the dependency-ordered prefix intact.
+MODULES=(verdict-logic profile context-injection task-graph)
+
+CHECK_MODE=0
+if [ "${1:-}" = "--check" ]; then
+  CHECK_MODE=1
+elif [ $# -gt 0 ]; then
+  echo "usage: $0 [--check]" >&2
+  exit 2
+fi
+
+[ -f "$TARGET" ] || { echo "ERROR: missing $TARGET" >&2; exit 1; }
+
+count_marker() { grep -cFx "$1" "$2" || true; }
+
+WORK="$(mktemp -d)"
+trap 'rm -rf "$WORK"' EXIT
+
+# Start from the current target; each module rewrites its own block in turn.
+cp "$TARGET" "$WORK/rendered"
+
+for module in "${MODULES[@]}"; do
+  SOURCE="plugin-task-loop/workflows/lib/${module}.js"
+  [ -f "$SOURCE" ] || { echo "ERROR: missing $SOURCE" >&2; exit 1; }
+
+  SRC_BEGIN="// --- BEGIN INLINE: ${module} ---"
+  SRC_END="// --- END INLINE: ${module} ---"
+  DST_BEGIN="// --- BEGIN GENERATED: ${module} (source: lib/${module}.js) ---"
+  DST_END="// --- END GENERATED: ${module} ---"
+
+  for marker in "$SRC_BEGIN" "$SRC_END"; do
+    n=$(count_marker "$marker" "$SOURCE")
+    [ "$n" -eq 1 ] || { echo "ERROR: '$marker' appears $n time(s) in $SOURCE (want 1)" >&2; exit 1; }
+  done
+  for marker in "$DST_BEGIN" "$DST_END"; do
+    n=$(count_marker "$marker" "$WORK/rendered")
+    [ "$n" -eq 1 ] || { echo "ERROR: '$marker' appears $n time(s) in $TARGET (want 1)" >&2; exit 1; }
+  done
+
+  EXTRACTED="$WORK/${module}.body"
+  awk -v b="$SRC_BEGIN" -v e="$SRC_END" '
+    $0 == b { inblk = 1; next }
+    $0 == e { inblk = 0; next }
+    inblk   { print }
+  ' "$SOURCE" > "$EXTRACTED"
+
+  if [ ! -s "$EXTRACTED" ]; then
+    echo "ERROR: extracted inline region from $SOURCE is empty" >&2
+    exit 1
+  fi
+
+  # The mirrored region must be self-contained.
+  if grep -Eq '^[[:space:]]*(import|export)[[:space:]]' "$EXTRACTED"; then
+    echo "ERROR: the inline region of $SOURCE contains import/export." >&2
+    echo "       Workflow scripts cannot import. Keep those outside the markers." >&2
+    exit 1
+  fi
+
+  # A destination marker inside the copied body would corrupt the target — the
+  # awk pass would end the generated block early and duplicate the remainder,
+  # after which every --check fails with a confusing "appears 2 time(s)".
+  for marker in "$DST_BEGIN" "$DST_END"; do
+    if grep -qFx "$marker" "$EXTRACTED"; then
+      echo "ERROR: the inline region of $SOURCE contains the destination marker:" >&2
+      echo "       $marker" >&2
+      echo "       Remove it — it would corrupt $TARGET on the next sync." >&2
+      exit 1
+    fi
+  done
+
+  awk -v b="$DST_BEGIN" -v e="$DST_END" -v body="$EXTRACTED" -v src="$SOURCE" '
+    $0 == b {
+      print
+      print "// AUTO-GENERATED — DO NOT EDIT BY HAND."
+      print "// Source: " src
+      print "// Regenerate: ./scripts/sync-workflow-inline.sh"
+      while ((getline line < body) > 0) print line
+      close(body)
+      skip = 1
+      next
+    }
+    $0 == e { skip = 0; print; next }
+    !skip   { print }
+  ' "$WORK/rendered" > "$WORK/next"
+  mv "$WORK/next" "$WORK/rendered"
+done
+
+if [ "$CHECK_MODE" -eq 1 ]; then
+  if ! diff -u "$TARGET" "$WORK/rendered" > /dev/null 2>&1; then
+    echo "ERROR: $TARGET is out of sync with its source modules" >&2
+    echo "       Run ./scripts/sync-workflow-inline.sh to regenerate." >&2
+    echo >&2
+    diff -u "$TARGET" "$WORK/rendered" >&2 || true
+    exit 1
+  fi
+  echo "OK: $TARGET is in sync with ${MODULES[*]}"
+  exit 0
+fi
+
+if diff -q "$TARGET" "$WORK/rendered" > /dev/null 2>&1; then
+  echo "OK: $TARGET already in sync (no change)"
+else
+  cat "$WORK/rendered" > "$TARGET"
+  echo "Synced: ${MODULES[*]} -> $TARGET"
+fi

package/skills/handoff/SKILL.md

@@ -62,6 +62,38 @@ description: "Session handoff — load context at start, save at end, track task
   aggregation time by `handoff_get_metrics`/`handoff_get_capacity`. To turn the
   requirement off, set `settings.require_estimate_hours = false`.
 
+### Checklist before every `handoff_update_task` that creates a task
+
+Run through this as you write the call, not after it is rejected. A leaf task
+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`
+- [ ] `priority` — `low` / `medium` / `high`
+- [ ] `labels` — at least one, so the task is findable by filter
+- [ ] `assignee` — matches a key in `config.toml [assignees.<key>]`
+
+A minimal accepted payload:
+
+```json
+{
+  "task": {
+    "title": "Add retry to the upload path",
+    "status": "todo",
+    "priority": "high",
+    "labels": ["upload", "reliability"],
+    "assignee": "ai",
+    "schedule": { "estimate_hours": 2.0 },
+    "done_criteria": [{ "item": "Upload retries 3x on 5xx, then surfaces the error" }]
+  }
+}
+```
+
+When updating an existing task, you do **not** resend `estimate_hours` — the
+stored value satisfies the requirement. Send only the fields you are changing.
+
 ### Appending to Task Notes
 - Use `notes_append` (not `notes`) in `handoff_update_task` or
   `handoff_bulk_update_tasks` to add text to existing task notes without
@@ -201,6 +233,11 @@ Use `handoff_bulk_update_tasks` for:
 - Batch status changes (e.g., closing all review tasks).
 - 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.
 
 ### Configuration Management
 

package/src/mcp/handlers/bulk_update.rs

@@ -3,6 +3,7 @@ use chrono::Utc;
 use serde_json::{json, Value};
 
 use super::resolve_project_dir;
+use crate::storage::config::read_config;
 use crate::storage::ensure_handoff_exists;
 use crate::storage::tasks::*;
 
@@ -11,6 +12,10 @@ pub fn handle(arguments: &Value) -> Result<String> {
     let handoff = ensure_handoff_exists(&project_dir)?;
     let tasks_dir = handoff.join("tasks");
 
+    let require_estimate_hours = read_config(&handoff.join("config.toml"))
+        .map(|c| c.settings.require_estimate_hours)
+        .unwrap_or(true);
+
     let updates = arguments
         .get("updates")
         .and_then(|v| v.as_array())
@@ -28,7 +33,9 @@ pub fn handle(arguments: &Value) -> Result<String> {
             }
         };
 
-        if let Err(e) = apply_single_update(&tasks_dir, task_id, update) {
+        // A rejected update is reported per task and the rest still land: that is
+        // this tool's established `applied` + `errors[]` contract.
+        if let Err(e) = apply_single_update(&tasks_dir, task_id, update, require_estimate_hours) {
             errors.push(json!({"task_id": task_id, "error": e.to_string()}));
         } else {
             applied += 1;
@@ -43,7 +50,12 @@ pub fn handle(arguments: &Value) -> Result<String> {
     serde_json::to_string_pretty(&result).map_err(Into::into)
 }
 
-fn apply_single_update(tasks_dir: &std::path::Path, task_id: &str, update: &Value) -> Result<()> {
+fn apply_single_update(
+    tasks_dir: &std::path::Path,
+    task_id: &str,
+    update: &Value,
+    require_estimate_hours: bool,
+) -> Result<()> {
     let task_dir = find_task_dir_by_id(tasks_dir, task_id)?
         .ok_or_else(|| anyhow::anyhow!("{}", suggest_task_id(tasks_dir, task_id)))?;
 
@@ -117,6 +129,22 @@ fn apply_single_update(tasks_dir: &std::path::Path, task_id: &str, update: &Valu
         validate_skipped_transition(&task_dir, &data)?;
     }
 
+    // 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.
+    let has_children = task_has_children(&task_dir)?;
+    validate_estimate_required(
+        require_estimate_hours,
+        task_id,
+        &data.title,
+        new_status,
+        has_children,
+        false,
+        data.schedule.as_ref(),
+    )?;
+
     data.updated_at = Some(Utc::now().to_rfc3339());
 
     if let Some((old_path, _)) = find_task_file(&task_dir)? {

package/src/mcp/handlers/import_context.rs

@@ -30,16 +30,46 @@ pub fn handle(arguments: &Value) -> Result<String> {
         .and_then(|v| v.as_str())
         .unwrap_or("other");
 
+    let require_estimate_hours = read_config(&config_path)
+        .map(|c| c.settings.require_estimate_hours)
+        .unwrap_or(true);
+
     let mut tasks_created: u32 = 0;
     let mut top_level_count: u32 = 0;
     let mut nested_count: u32 = 0;
 
     if let Some(tasks) = arguments.get("tasks").and_then(|v| v.as_array()) {
+        // Validate the whole payload before creating anything. Import writes many
+        // tasks in one call, so a rejection discovered mid-tree would otherwise
+        // leave a half-written forest behind and burn task IDs —
+        // `next_top_level_id` counts directories, not task files.
+        //
+        // Nothing is created yet, so `next_top_level_id` keeps returning the same
+        // value; project the IDs the writing pass below will assign, purely so the
+        // rejection names the task the caller sent.
+        let first_id = next_top_level_id(&tasks_dir)?;
+        let first_n: u32 = first_id
+            .strip_prefix('t')
+            .and_then(|n| n.parse().ok())
+            .with_context(|| format!("Unexpected task id form: {first_id}"))?;
+        let mut pending_deps: Vec<(String, Vec<String>)> = Vec::new();
+        for (i, task_val) in tasks.iter().enumerate() {
+            let projected_id = format!("t{}", first_n + i as u32);
+            validate_task_recursive(
+                &projected_id,
+                task_val,
+                require_estimate_hours,
+                &mut pending_deps,
+            )?;
+        }
+
+        // Check the dependency graph once, with every task in this payload already
+        // in it. Task-at-a-time checking would both reject a valid dependency on a
+        // sibling still unwritten and miss a cycle confined to the payload.
+        validate_dependencies_batch(&tasks_dir, &pending_deps)?;
+
         for task_val in tasks {
-            let title = task_val
-                .get("title")
-                .and_then(|v| v.as_str())
-                .ok_or_else(|| anyhow::anyhow!("Each task requires a 'title'"))?;
+            let title = task_title(task_val)?;
 
             let task_id = next_top_level_id(&tasks_dir)?;
             let count = create_task_recursive(&tasks_dir, &task_id, None, title, task_val)?;
@@ -204,6 +234,84 @@ pub fn handle(arguments: &Value) -> Result<String> {
     Ok(msg)
 }
 
+// The validating pass and the writing pass must read the payload identically, or
+// a task could pass validation and then be written as something else. These three
+// accessors are the single source of truth for the fields the estimate rule keys
+// on; both passes go through them rather than reaching into `task_val` directly.
+
+fn task_title(task_val: &Value) -> Result<&str> {
+    task_val
+        .get("title")
+        .and_then(|v| v.as_str())
+        .ok_or_else(|| anyhow::anyhow!("Each task requires a 'title'"))
+}
+
+fn task_status(task_val: &Value) -> &str {
+    task_val
+        .get("status")
+        .and_then(|v| v.as_str())
+        .unwrap_or("todo")
+}
+
+fn task_children(task_val: &Value) -> Option<&Vec<Value>> {
+    task_val.get("children").and_then(|v| v.as_array())
+}
+
+/// Check one task subtree against the rules `create_task_recursive` would
+/// otherwise only discover after writing earlier siblings to disk.
+///
+/// `has_children` is read from the payload, not the filesystem: at this point the
+/// child directories do not exist, so a filesystem probe would call every parent
+/// a leaf and demand an estimate it is exempt from.
+fn validate_task_recursive(
+    task_id: &str,
+    task_val: &Value,
+    require_estimate_hours: bool,
+    pending_deps: &mut Vec<(String, Vec<String>)>,
+) -> Result<()> {
+    let title = task_title(task_val)?;
+
+    let status = task_status(task_val);
+    if !is_valid_status(status) {
+        anyhow::bail!("Invalid status: {status}");
+    }
+
+    validate_priority(task_val.get("priority").and_then(|v| v.as_str()))?;
+
+    let children = task_children(task_val);
+    // An empty `children` array creates no child tasks, so such a task is a leaf
+    // and owes an estimate — matching what the writing pass will produce.
+    let has_children = children.is_some_and(|c| !c.is_empty());
+
+    // import only ever creates, so `is_create` is true and the resend example
+    // carries `title` — the caller has no stored task to preserve it.
+    validate_estimate_required(
+        require_estimate_hours,
+        task_id,
+        title,
+        status,
+        has_children,
+        true,
+        extract_schedule(task_val).as_ref(),
+    )?;
+
+    // Record this task's edges under the ID the writing pass will give it, so the
+    // batch cycle check below sees the graph as it will exist after the import.
+    pending_deps.push((
+        task_id.to_string(),
+        extract_string_array_from(task_val, "dependencies"),
+    ));
+
+    if let Some(children) = children {
+        for (i, child_val) in children.iter().enumerate() {
+            let child_id = format!("{task_id}.{}", i + 1);
+            validate_task_recursive(&child_id, child_val, require_estimate_hours, pending_deps)?;
+        }
+    }
+
+    Ok(())
+}
+
 fn create_task_recursive(
     tasks_dir: &std::path::Path,
     task_id: &str,
@@ -220,11 +328,12 @@ fn create_task_recursive(
         .with_context(|| format!("Failed to create task dir: {}", task_dir.display()))?;
 
     let now = Utc::now().to_rfc3339();
-    let status = task_val
-        .get("status")
-        .and_then(|v| v.as_str())
-        .unwrap_or("todo");
+    let status = task_status(task_val);
 
+    // `validate_task_recursive` has already passed on this payload, so these two
+    // cannot fail here. They stay as defense-in-depth: this function writes to
+    // disk, and a future caller that forgets the pre-pass must not slip an
+    // invalid status or priority through unchecked.
     if !is_valid_status(status) {
         anyhow::bail!("Invalid status: {status}");
     }
@@ -269,12 +378,9 @@ fn create_task_recursive(
 
     let mut count: u32 = 1;
 
-    if let Some(children) = task_val.get("children").and_then(|v| v.as_array()) {
+    if let Some(children) = task_children(task_val) {
         for (i, child_val) in children.iter().enumerate() {
-            let child_title = child_val
-                .get("title")
-                .and_then(|v| v.as_str())
-                .ok_or_else(|| anyhow::anyhow!("Each child task requires a 'title'"))?;
+            let child_title = task_title(child_val)?;
 
             let child_id = format!("{task_id}.{}", i + 1);
             count += create_task_recursive(

package/src/mcp/handlers/update_task.rs

@@ -82,8 +82,6 @@ fn handle_create(
     let slug = title_to_slug(title);
     let dir_name = format!("{new_id}-{slug}");
     let task_dir = parent_dir.join(&dir_name);
-    std::fs::create_dir_all(&task_dir)
-        .with_context(|| format!("Failed to create task dir: {}", task_dir.display()))?;
 
     let now = Utc::now().to_rfc3339();
     let status = task_val
@@ -133,11 +131,20 @@ fn handle_create(
     // A newly created task is always a leaf (no children yet).
     validate_estimate_required(
         require_estimate_hours,
+        &new_id,
+        title,
         status,
         false,
+        true,
         data.schedule.as_ref(),
     )?;
 
+    // Create the directory only once every validation has passed. A rejected
+    // create must leave nothing behind: an orphan dir would burn the task ID,
+    // because `next_top_level_id` counts directories, not task files.
+    std::fs::create_dir_all(&task_dir)
+        .with_context(|| format!("Failed to create task dir: {}", task_dir.display()))?;
+
     write_task(&task_dir, status, &data)?;
 
     Ok(format!("Created task {new_id}: {title} [{status}]"))
@@ -169,8 +176,6 @@ fn handle_upsert_create(
     let slug = title_to_slug(title);
     let dir_name = format!("{task_id}-{slug}");
     let task_dir = parent_dir.join(&dir_name);
-    std::fs::create_dir_all(&task_dir)
-        .with_context(|| format!("Failed to create task dir: {}", task_dir.display()))?;
 
     let now = Utc::now().to_rfc3339();
     let status = task_val
@@ -220,11 +225,19 @@ fn handle_upsert_create(
     // Upsert-create: a brand-new task is a leaf.
     validate_estimate_required(
         require_estimate_hours,
+        task_id,
+        title,
         status,
         false,
+        true,
         data.schedule.as_ref(),
     )?;
 
+    // Create the directory only once every validation has passed, so a rejected
+    // upsert-create leaves no orphan dir shadowing the requested ID.
+    std::fs::create_dir_all(&task_dir)
+        .with_context(|| format!("Failed to create task dir: {}", task_dir.display()))?;
+
     write_task(&task_dir, status, &data)?;
 
     Ok(format!("Created task {task_id}: {title} [{status}]"))
@@ -336,8 +349,11 @@ fn handle_update(
     let has_children = task_has_children(&task_dir)?;
     validate_estimate_required(
         require_estimate_hours,
+        task_id,
+        &data.title,
         new_status,
         has_children,
+        false,
         data.schedule.as_ref(),
     )?;
 

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.".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(),
             input_schema: json!({
                 "type": "object",
                 "properties": {
@@ -285,6 +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.",
                         "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)." },
@@ -319,12 +320,12 @@ pub fn all_tool_definitions() -> Vec<ToolDefinition> {
                             },
                             "schedule": {
                                 "type": "object",
-                                "description": "Schedule and effort tracking.",
+                                "description": "Schedule and effort tracking. Supply this with estimate_hours whenever creating a leaf task.",
                                 "properties": {
                                     "start_date": { "type": "string", "description": "YYYY-MM-DD" },
                                     "due_date": { "type": "string", "description": "YYYY-MM-DD" },
-                                    "estimate_hours": { "type": "number" },
-                                    "actual_hours": { "type": "number" },
+                                    "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." },
+                                    "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" },
                                     "pinned": { "type": "boolean", "description": "If true, dates are locked and auto-scheduler skips this task." }
@@ -863,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.".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(),
             input_schema: json!({
                 "type": "object",
                 "properties": {
@@ -873,26 +874,27 @@ pub fn all_tool_definitions() -> Vec<ToolDefinition> {
                     },
                     "updates": {
                         "type": "array",
-                        "description": "Array of task updates to apply.",
+                        "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.",
                         "items": {
                             "type": "object",
                             "properties": {
                                 "task_id": { "type": "string", "description": "Task ID to update." },
-                                "status": { "type": "string", "enum": ["todo", "in_progress", "review", "done", "blocked", "skipped"] },
+                                "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." },
                                 "priority": { "type": "string", "enum": ["low", "medium", "high"] },
                                 "assignee": { "type": "string" },
                                 "notes": { "type": "string", "description": "Replace task notes." },
                                 "notes_append": { "type": "string", "description": "Append text to existing notes with a timestamp heading. If both notes and notes_append are provided, notes (replace) takes precedence." },
                                 "schedule": {
                                     "type": "object",
+                                    "description": "Schedule fields to merge. Omitted fields are preserved, not cleared.",
                                     "properties": {
-                                        "start_date": { "type": "string" },
-                                        "due_date": { "type": "string" },
-                                        "estimate_hours": { "type": "number" },
-                                        "actual_hours": { "type": "number" },
-                                        "remaining_hours": { "type": "number" },
+                                        "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." },
+                                        "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" },
-                                        "pinned": { "type": "boolean" }
+                                        "pinned": { "type": "boolean", "description": "If true, dates are locked and auto-scheduler skips this task." }
                                     }
                                 }
                             },

package/src/storage/tasks.rs

@@ -605,6 +605,38 @@ pub fn validate_dependencies(tasks_dir: &Path, task_id: &str, new_deps: &[String
     Ok(())
 }
 
+/// Validate dependencies for a whole batch of tasks that do not exist yet.
+///
+/// `validate_dependencies` adds one node to the on-disk graph, which is all an
+/// update needs. An import creates a tree in one call, so its tasks may depend on
+/// each other: checking them one at a time would reject a legitimate dependency
+/// on a sibling (not yet written) and miss a cycle that lives entirely inside the
+/// batch (neither end written). Merge every pending node in first, then search.
+///
+/// A dependency naming a task that exists nowhere is left alone — it contributes
+/// no edge, and `validate_dependencies` tolerates it too.
+pub fn validate_dependencies_batch(
+    tasks_dir: &Path,
+    pending: &[(String, Vec<String>)],
+) -> Result<()> {
+    let mut graph = build_dependency_graph(tasks_dir)?;
+    for (id, deps) in pending {
+        graph.insert(id.clone(), deps.clone());
+    }
+
+    for (id, deps) in pending {
+        let mut visited = HashSet::new();
+        let mut stack = HashSet::new();
+        if has_cycle(&graph, id, &mut visited, &mut stack) {
+            anyhow::bail!(
+                "Circular dependency detected: setting dependencies {deps:?} on task {id} would create a cycle"
+            );
+        }
+    }
+
+    Ok(())
+}
+
 fn build_dependency_graph(tasks_dir: &Path) -> Result<HashMap<String, Vec<String>>> {
     let mut graph = HashMap::new();
     build_dep_graph_recursive(tasks_dir, &mut graph)?;
@@ -712,11 +744,19 @@ pub fn status_requires_estimate(status: &str) -> bool {
 
 /// Validate that a leaf task carries an `estimate_hours` when the project
 /// requires it. `has_children` lets the caller skip parent tasks.
-/// Returns an error guiding the caller to add an estimate.
+///
+/// The rejection names the offending task and shows a ready-to-send payload,
+/// so a caller that forgot the estimate can fix it in one retry instead of
+/// discovering the required shape by trial and error. `is_create` tailors that
+/// payload: creating a task also needs `title`, whereas an update must not
+/// imply the stored title should be overwritten.
 pub fn validate_estimate_required(
     require_estimate_hours: bool,
+    id: &str,
+    title: &str,
     status: &str,
     has_children: bool,
+    is_create: bool,
     schedule: Option<&Schedule>,
 ) -> Result<()> {
     if !require_estimate_hours || has_children || !status_requires_estimate(status) {
@@ -726,11 +766,32 @@ pub fn validate_estimate_required(
         .and_then(|s| s.estimate_hours)
         .is_some_and(|h| h > 0.0);
     if !has_estimate {
+        // Mirror the rejected call, so the example can be resent as-is. Build it
+        // with serde_json rather than string formatting: a title carrying a quote,
+        // a backslash, or a control character must still serialize to valid JSON.
+        // A create also needs `title`; an update must not imply overwriting it.
+        let mut example = serde_json::Map::new();
+        example.insert("id".into(), Value::String(id.to_string()));
+        if is_create {
+            example.insert("title".into(), Value::String(title.to_string()));
+        }
+        example.insert(
+            "schedule".into(),
+            serde_json::json!({ "estimate_hours": 2.0 }),
+        );
+        let example = Value::Object(example);
         anyhow::bail!(
-            "Task requires an effort estimate: set schedule.estimate_hours (hours, > 0) \
-             when creating or updating a leaf task in status '{status}'. \
-             Estimate the human-effort hours for this task. \
-             To disable this requirement project-wide, set settings.require_estimate_hours = false."
+            "Task '{id}' ({title}) requires an effort estimate: \
+             schedule.estimate_hours (hours, > 0) is mandatory for a leaf task \
+             in status '{status}'.\n\
+             Estimate the raw human-effort hours — do not pre-multiply by the \
+             AI-effort multiplier; that is applied at aggregation time.\n\
+             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\
+             To disable this requirement project-wide, set \
+             settings.require_estimate_hours = false."
         );
     }
     Ok(())