handoff-mcp-server 0.19.1 → 0.22.0

package/Cargo.lock

@@ -37,9 +37,9 @@ checksum = "72f5acc6cb2ba439de613abc23857ec3d78374d8ed5ac84e9d11336e87da8649"
 
 [[package]]
 name = "cc"
-version = "1.2.65"
+version = "1.2.67"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "e228eec9be7c17ccb640b59b36a5cd805ea2a564a4c5e162c2f659fea30d3b96"
+checksum = "e17dd265a7d0f31ef544e1b20e03add05d3b45b491b633b10d67145d2acc1a38"
 dependencies = [
  "find-msvc-tools",
  "shlex",
@@ -123,6 +123,15 @@ dependencies = [
  "slab",
 ]
 
+[[package]]
+name = "getopts"
+version = "0.2.24"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "cfe4fbac503b8d1f88e6676011885f34b7174f46e59956bba534ba83abded4df"
+dependencies = [
+ "unicode-width",
+]
+
 [[package]]
 name = "getrandom"
 version = "0.4.3"
@@ -136,11 +145,12 @@ dependencies = [
 
 [[package]]
 name = "handoff-mcp"
-version = "0.19.1"
+version = "0.22.0"
 dependencies = [
  "anyhow",
  "chrono",
  "lexsim",
+ "pulldown-cmark",
  "serde",
  "serde_json",
  "tempfile",
@@ -208,9 +218,9 @@ dependencies = [
 
 [[package]]
 name = "lexsim"
-version = "0.4.0"
+version = "0.6.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "14b08f26a4b07325e83c0211adb36d0223fae644534dacd4eae72153c1ccd873"
+checksum = "b64f48de8c9d203c0ed3ac8c68e9ba1072206d5072551c08889a4bbae9d84677"
 dependencies = [
  "unicode-normalization",
  "unicode-segmentation",
@@ -236,9 +246,9 @@ checksum = "0ceec5bc11778974d1bcb055b18002eba7f4b3518b6a0081b3af5f21666da9ad"
 
 [[package]]
 name = "memchr"
-version = "2.8.2"
+version = "2.8.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "88904434abc2901f197fe8cc55f0445e7ded921dba5911dad2e2b39b48e663c4"
+checksum = "cf8baf1c55e62ffcace7a9f06f4bd9cd3f0c4beb022d3b367256b91b87513d98"
 
 [[package]]
 name = "num-traits"
@@ -270,6 +280,25 @@ dependencies = [
  "unicode-ident",
 ]
 
+[[package]]
+name = "pulldown-cmark"
+version = "0.13.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e9f068eba8e7071c5f9511831b44f32c740d5adf574e990f946ddb53db2f314e"
+dependencies = [
+ "bitflags",
+ "getopts",
+ "memchr",
+ "pulldown-cmark-escape",
+ "unicase",
+]
+
+[[package]]
+name = "pulldown-cmark-escape"
+version = "0.11.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "007d8adb5ddab6f8e3f491ac63566a7d5002cc7ed73901f72057943fa71ae1ae"
+
 [[package]]
 name = "quote"
 version = "1.0.46"
@@ -300,9 +329,9 @@ dependencies = [
 
 [[package]]
 name = "rustversion"
-version = "1.0.22"
+version = "1.0.23"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "b39cdef0fa800fc44525c84ccb54a029961a8215f9619753635a9c0d2538d46d"
+checksum = "cf54715a573b99ac80df0bc206da022bcd442c974952c7b9720069370852e21f"
 
 [[package]]
 name = "serde"
@@ -415,9 +444,9 @@ dependencies = [
 
 [[package]]
 name = "tinyvec"
-version = "1.11.0"
+version = "1.12.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "3e61e67053d25a4e82c844e8424039d9745781b3fc4f32b8d55ed50f5f667ef3"
+checksum = "bb4ebadaa0af04fab11ae01eb5f9fdb5f9c5b875506e210e71c07873528baa7f"
 dependencies = [
  "tinyvec_macros",
 ]
@@ -469,6 +498,12 @@ version = "0.1.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "5d99f8c9a7727884afe522e9bd5edbfc91a3312b36a77b5fb8926e4c31a41801"
 
+[[package]]
+name = "unicase"
+version = "2.9.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "dbc4bc3a9f746d862c45cb89d705aa10f187bb96c76001afab07a0d35ce60142"
+
 [[package]]
 name = "unicode-ident"
 version = "1.0.24"
@@ -490,6 +525,12 @@ version = "1.13.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "c6f5d3c3b1bf09027a88a6bc961fc00497d651009560b5463668dc81b0fa87a8"
 
+[[package]]
+name = "unicode-width"
+version = "0.2.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b4ac048d71ede7ee76d585517add45da530660ef4390e49b098733c6e897f254"
+
 [[package]]
 name = "wasm-bindgen"
 version = "0.2.126"

package/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "handoff-mcp"
-version = "0.19.1"
+version = "0.22.0"
 edition = "2021"
 description = "MCP server that gives AI coding agents persistent memory across sessions"
 license = "MIT"
@@ -21,6 +21,7 @@ chrono = { version = "0.4", features = ["serde"] }
 anyhow = "1"
 thiserror = "2"
 lexsim = ">=0.1.0, <1.0.0"
+pulldown-cmark = "0.13"
 
 [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
 
@@ -313,6 +419,26 @@ rename) so a concurrent reader never sees a partially-written file.
 For usage best practices (granularity, scope_paths, conflict handling, cleanup), see `skills/handoff-memory/SKILL.md`.
 See [Project Memory](#project-memory-1) below for what it is and how to wire automatic injection.
 
+### Document Management
+
+| Tool | Purpose |
+|------|---------|
+| `handoff_doc_save` | Create or update a document (auto-splits into fragments) |
+| `handoff_doc_get` | Read a document — full, meta, or single fragment |
+| `handoff_doc_list` | List/search documents with BM25 and filters |
+| `handoff_doc_delete` | Delete a document and its fragments |
+| `handoff_doc_reassemble` | Reconstruct original Markdown from fragments |
+| `handoff_doc_tree` | Walk family tree (ancestors/descendants/related) |
+| `handoff_doc_query` | Context injection — staged full/outline, hook-driven |
+| `handoff_doc_analyze` | Read-only heuristic scan (import step 1) |
+| `handoff_doc_import` | Atomic bulk write after analysis (import step 3) |
+
+Documents live in `.handoff/docs/` (`_doc.*.json` metadata + `_frag.*.{json,md}`
+fragments). Large Markdown is split into fragments on save; `handoff_doc_reassemble`
+reconstructs the original with drift detection, and `handoff_doc_query` feeds
+staged (outline-first, then full-text) context to the agent — the same mechanism
+that powers the hook-driven injection described below.
+
 ### Task Data Model
 
 Tasks are stored as a directory tree with status encoded in filenames:
@@ -478,14 +604,23 @@ what the agent intends, call `handoff_memory_query`, and inject the matching mem
 the same memory is **not injected twice in one session** — and an *edited* memory
 (new content hash) is re-injected.
 
+The same hooks also call `handoff_doc_query`, so relevant documents (saved via
+`handoff_doc_save`) are staged into context alongside memories — outline first,
+then full text as relevance/budget allows.
+
 | Event | Calls | Effect |
 |-------|-------|--------|
-| `UserPromptSubmit` | `handoff_memory_query` (prompt text) | Inject memories relevant to the prompt |
-| `PreToolUse` (`Edit\|Write\|MultiEdit`) | `handoff_memory_query` (file path) | Inject memories scoped to the file being edited |
+| `UserPromptSubmit` | `handoff_memory_query` (prompt text), `handoff_doc_query` (prompt text) | Inject memories and documents relevant to the prompt |
+| `PreToolUse` (`Edit\|Write\|MultiEdit`) | `handoff_memory_query` (file path), `handoff_doc_query` (file path) | Inject memories and documents scoped to the file being edited |
 
 `handoff_memory_cleanup` (merge exact duplicates, gc old sidecars) is not wired
 to a hook — call it manually or from a CLI/cron job when you want housekeeping.
 
+> The bundled `plugin-hooks/hooks/hooks.json` (used by the "Handoff MCP — Memory
+> & Document Hooks" plugin) already wires both `handoff_memory_query` and
+> `handoff_doc_query` on `UserPromptSubmit` and `PreToolUse`; the JSON examples
+> below show the equivalent hand-written config for non-plugin setups.
+
 > **Wire hooks in your *user/global* settings, not in the repo.** Hooks are a
 > personal workflow choice; the handoff-mcp repo does not ship a `.claude/`
 > hooks config, and you should not commit one into a shared project. Put the
@@ -569,8 +704,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.1",
+  "version": "0.22.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-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,35 @@ 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.
+
+### Document Management
+
+For structured, multi-section documents (specs, designs, ADRs, guides) that
+are too large for a single memory entry, use the doc tools instead — see the
+`handoff-docs` skill for full parameter details and workflows:
+
+| Tool | Purpose |
+|---|---|
+| `handoff_doc_save` | Create/update a document — auto-splits `body` into fragments at `##` (configurable via `split_level`) |
+| `handoff_doc_get` | Read a document — `full` (reassembled), `meta` (manifest only), or `fragment` (one section) |
+| `handoff_doc_list` | List/search documents (BM25), filter by `doc_type`/`tags`/`task_id` |
+| `handoff_doc_delete` | Delete a document and its fragments (also unlinks it from tasks) |
+| `handoff_doc_reassemble` | Reconstruct the original Markdown from fragments, with drift detection |
+| `handoff_doc_tree` | Traverse the family tree — parent/child (structural) + related (semantic: `supersedes`/`references`/`implements`/`extends`/`conflicts`) |
+| `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_doc_save(task_ids: [...])` creates a **bidirectional** doc↔task
+link: the document gains a `task_ids` entry and each linked task gains a
+`TaskLink` in its `task_links`. Look it up from either side with
+`handoff_doc_list(task_id: ...)` (docs linked to a task) or
+`handoff_get_task(id: ...)` (inspect `task_links` on the task record).
 
 ### Configuration Management