handoff-mcp-server 0.20.0 → 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.20.0"
+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.20.0"
+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

@@ -419,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:
@@ -584,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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "handoff-mcp-server",
-  "version": "0.20.0",
+  "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>",

package/skills/handoff/SKILL.md

@@ -239,6 +239,30 @@ Use `handoff_bulk_update_tasks` for:
   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
 
 Use `handoff_update_config` to manage project settings via dot-notation keys:

package/skills/handoff-docs/SKILL.md

@@ -0,0 +1,233 @@
+---
+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."
+---
+
+# Handoff Docs Skill
+
+## When to use
+
+- The user asks to save a spec, design doc, ADR, guide, or note so it survives across sessions
+- The user wants to import an existing pile of Markdown files (e.g. a `wiki/` or `specs/` directory) into structured document management
+- You need to read a specific section of a large document without pulling the whole thing into context
+- You need to trace how documents relate to each other (parent/child hierarchy, or semantic links like "this design implements that spec")
+- A document should be linked to one or more tasks so it surfaces automatically while that task is being worked on
+
+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.
+
+## The 9 Doc Tools
+
+| Tool | Purpose |
+|---|---|
+| `handoff_doc_save` | Create or update a document. Splits `body` into fragments automatically. |
+| `handoff_doc_get` | Read a document — `full` (reassembled body), `meta` (manifest only), or `fragment` (one section). |
+| `handoff_doc_list` | List/search documents (BM25 over title + fragment bodies), filter by `doc_type`, `tags`, `task_id`. |
+| `handoff_doc_delete` | Delete a document and all its fragments; unlinks it from any linked tasks. |
+| `handoff_doc_reassemble` | Reconstruct the original Markdown from fragments, with drift detection. |
+| `handoff_doc_tree` | Walk the family tree (ancestors/descendants/related) for a document. |
+| `handoff_doc_query` | Context injection — hook-driven, staged `full`/`outline` results ranked by relevance. |
+| `handoff_doc_analyze` | Read-only heuristic scan of a file or directory — step 1 of the import flow. |
+| `handoff_doc_import` | Atomic bulk write of analyzed + AI-reviewed documents — step 3 of the import flow. |
+
+### `handoff_doc_save`
+
+| Param | Required | Description |
+|---|---|---|
+| `title` | yes | Document title |
+| `body` | yes | Full Markdown source — this is what gets split into fragments |
+| `doc_type` | no | One of `spec`, `design`, `adr`, `guide`, `note` |
+| `tags` | no | Free-form tags, folded into the BM25 index |
+| `scope_paths` | no | Path prefixes this doc applies to — boosts relevance in `doc_query` when the matching file is being edited |
+| `parent_id` | no | Places this document under a parent in the family tree |
+| `related` | no | Array of `{ id, rel }` — semantic links to other documents (see Family Tree below) |
+| `task_ids` | no | Task IDs to bidirectionally link (see Task Linking below) |
+| `split_level` | no | ATX heading level to split on (default: `2`, i.e. `##`) |
+| `auto_inject` | no | Injection hint: `auto` (default) \| `full` \| `outline` \| `none` |
+| `doc_id` | no | Provide to update an existing document; omit to create a new one |
+
+### `handoff_doc_get`
+
+| Param | Required | Description |
+|---|---|---|
+| `doc_id` | yes | Document to read |
+| `format` | no | `full` (default-equivalent reassembly) \| `meta` (manifest only, no body) \| `fragment` |
+| `seq` | when `format=fragment` | Fragment sequence number to return |
+
+Use `meta` when you only need to walk the graph (titles, tags, relations)
+without paying the token cost of fragment bodies. Use `fragment` with a `seq`
+from an outline injection (see Staged Injection) to fetch exactly the section
+you need.
+
+### `handoff_doc_list`
+
+| Param | Required | Description |
+|---|---|---|
+| `query` | no | BM25 search over title + fragment bodies |
+| `doc_type` | no | Filter by type |
+| `tags` | no | Filter by tags |
+| `task_id` | no | Documents linked to this task |
+| `include_body` | no | Default `false` — metadata-only listing |
+
+### `handoff_doc_delete`
+
+| Param | Required | Description |
+|---|---|---|
+| `doc_id` | yes | Document to delete, along with all its fragments |
+
+Deleting also removes the document from any linked task's `task_links`.
+
+### `handoff_doc_reassemble`
+
+| Param | Required | Description |
+|---|---|---|
+| `doc_id` | yes | Document to reconstruct |
+| `output_path` | no | If set, also writes the reassembled Markdown to this path |
+
+Fragments are concatenated in `seq` order with original heading markers
+preserved — `save(body) → reassemble()` is byte-identical. If a fragment was
+edited directly after the split, its `content_hash` no longer matches and
+`reassemble` reports the drift instead of silently returning stale content.
+
+### `handoff_doc_tree`
+
+| Param | Required | Description |
+|---|---|---|
+| `doc_id` | yes | Root of the traversal |
+| `depth` | no | How many parent/child levels to return |
+| `include_related` | no | Whether to also include semantically `related` documents |
+
+### `handoff_doc_query`
+
+| Param | Required | Description |
+|---|---|---|
+| `text` | no | Prompt/query text (BM25 relevance ranking) |
+| `file_paths` | no | Files being worked on — boosts documents whose `scope_paths` prefix-match |
+| `task_id` | no | Boosts documents linked to this task |
+| `session_id` | no | Enables per-session dedup — a fragment already injected this session is skipped unless its content changed |
+| `limit` | no | Max fragments to return |
+| `mark_injected` | no | Whether to record injection for dedup (default `true`) |
+| `suppress_doc_ids` | no | Document ids to exclude entirely from this call's results |
+| `suppress_until_changed` | no | With `suppress_doc_ids` and `session_id`: persists the suppression in the session sidecar so those documents stay excluded from future calls until their `content_hash` changes (default `false`) |
+
+This is the hook-driven tool — see Staged Injection below for how results are shaped.
+
+### `handoff_doc_analyze`
+
+| Param | Required | Description |
+|---|---|---|
+| `path` | yes | File or directory to scan |
+| `recursive` | no | Recurse into subdirectories |
+| `flatten` | no | Skip hierarchy inference (no `parent_id` guessing) |
+
+Read-only — writes nothing. Returns a conditioning report with
+`auto_resolved` entries (high-confidence `doc_type`/`tags`/`scope_paths`) and
+`needs_review` entries (broken links, missing relationships, near-duplicates)
+each carrying a concrete `suggestion` the AI can approve, edit, or reject.
+
+### `handoff_doc_import`
+
+| Param | Required | Description |
+|---|---|---|
+| `analyzed` | yes | The `handoff_doc_analyze` output (possibly after AI review) |
+| `overrides` | no | Per-file corrections (`doc_type`, relationship resolutions, etc.) |
+| `task_ids` | no | Link every imported document to these tasks |
+
+Writes all `_doc.*.json` + `_frag.*.{json,md}` atomically in one transaction,
+including any task links — matches the "validate whole tree, then write"
+pattern used by `handoff_import_context` for tasks.
+
+## Staged Injection (outline vs full)
+
+`handoff_doc_query` avoids flooding context with large documents:
+
+| Mode | When | What's injected |
+|---|---|---|
+| `full` | Fragment body <= `doc_inline_threshold` tokens (default 300) | Metadata + the entire fragment body |
+| `outline` | Fragment body > threshold | Metadata + heading list only — no body. Read a specific section with `handoff_doc_get(format="fragment", seq=N)` |
+
+This means short documents (ADRs, conventions, short notes) get pulled in
+ready-to-use, while long documents (full specs, design docs) only announce
+their structure — the AI decides which section is actually worth fetching.
+
+### `auto_inject` override
+
+Set on `handoff_doc_save` (or later via an update) to force behavior
+regardless of size:
+
+| Value | Effect |
+|---|---|
+| `auto` (default) | Size-based automatic choice between `full`/`outline` |
+| `full` | Always inject the full body |
+| `outline` | Always inject headings only, even if small |
+| `none` | Never auto-inject — only surfaced via explicit `handoff_doc_get` |
+
+## Family Tree
+
+Two distinct kinds of document relationship:
+
+- **parent/child** (`parent_id`) — structural hierarchy, e.g. a directory of
+  specs where each file's document is a child of the directory's document.
+- **related** (`related: [{ id, rel }]`) — semantic links between documents
+  that are not structurally nested. `rel` is one of:
+
+  | `rel` | Meaning |
+  |---|---|
+  | `supersedes` | Replaces the target (a version bump) |
+  | `references` | Loose cross-reference |
+  | `implements` | This document implements the spec the target describes |
+  | `extends` | Extends the target without replacing it |
+  | `conflicts` | Known contradiction that needs resolving |
+
+Use `handoff_doc_tree` to walk both kinds together (`include_related: true`)
+or just the structural hierarchy.
+
+## Task Linking
+
+`handoff_doc_save(task_ids: [...])` creates a **bidirectional** link:
+
+1. The document's own `task_ids` field is set.
+2. Each linked task gets a `TaskLink { target: doc_id, link_type: "doc", label: <doc title> }` entry in its `task_links`.
+3. Deleting the document removes it from the linked tasks' `task_links` automatically.
+
+Look up the relationship from either side:
+- `handoff_doc_list(task_id: "T-79")` — documents linked to a task.
+- `handoff_get_task(task_id: "T-79")` — inspect `task_links` on the task record to
+  see which documents (and other targets) it links to.
+
+Note: there is no dedicated `doc_id` filter on `handoff_list_tasks` — the
+`task_links` field is populated and readable per-task via `handoff_get_task`,
+but a document → "which tasks link to me" listing must be done by scanning
+`task_links` yourself, not via a built-in filter.
+
+## Fragment Granularity
+
+- Default split boundary: ATX heading level 2 (`##`).
+- Override per-call with `split_level` on `handoff_doc_save` (e.g. `1` to
+  split only on `#`, or `3` for finer-grained `###` sections).
+- Content before the first qualifying heading becomes fragment `seq: 0` (the
+  preamble). Nested headings below `split_level` stay inside their parent
+  fragment rather than becoming their own fragment.
+
+## Import Workflow (3 steps)
+
+Use this instead of calling `doc_save` file-by-file when bringing in an
+existing pile of Markdown — cross-document relationships and duplicates can
+only be validated when every file is visible at once.
+
+1. **`handoff_doc_analyze(path, recursive, flatten)`** — read-only scan.
+   Returns `auto_resolved` (confident guesses) and `needs_review` (broken
+   links, missing relationships, near-duplicates), each with a `suggestion`.
+2. **AI reviews the report** — approve `auto_resolved` entries as-is, and for
+   each `needs_review` item either accept the `suggestion`, correct it, or
+   reject it. Nothing is written yet.
+3. **`handoff_doc_import(analyzed, overrides, task_ids)`** — takes the
+   analyzed payload plus the AI's overrides and writes the whole tree
+   atomically, including task links.
+
+## `doc_type` Values
+
+`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).

package/skills/handoff-load/SKILL.md

@@ -33,5 +33,13 @@ user-invocable: true
    - **決定事項**: confidence が `unverified` のものを警告
    - **申し送り**: `caution` を最初に、`context` → `suggestion` の順
    - **コンテキストポインタ**: 次に読むべきファイル一覧
-6. ユーザーに現状サマリーを日本語で報告
-7. 次のアクションを提案（「何から始めますか？」）
+6. **関連ドキュメントの確認**:
+   - `in_progress` タスクにリンクされたドキュメントがあれば、フックの
+     `handoff_doc_query`（`UserPromptSubmit`/`PreToolUse`）が自動注入する
+     — セッション開始時点で明示的に呼ぶ必要はない
+   - 特定のセクションだけ読みたい場合は `handoff_doc_get(doc_id, format="fragment", seq=N)`
+     を手動で呼ぶ（outline 注入で見出し一覧だけ渡された場合など）
+   - ドキュメント管理の詳細（段階的注入・家系図・インポート手順）は
+     `handoff-docs` スキルを参照
+7. ユーザーに現状サマリーを日本語で報告
+8. 次のアクションを提案（「何から始めますか？」）

package/skills/handoff-memory/SKILL.md

@@ -137,3 +137,23 @@ JSON configuration.
 
 Rule changes: discover via memory → codify in skills/CLAUDE.md. Memory is the
 source of evidence; skills and CLAUDE.md are the source of authority.
+
+## Memory vs Documents
+
+| | Memory | Documents |
+|---|---|---|
+| Shape | Short, atomic lesson/rule/convention/gotcha | Structured, multi-section Markdown (specs, designs, ADRs, guides) |
+| Storage | One flat entry (`.handoff/memory/`) | Split into fragments with a family tree (`.handoff/docs/`) |
+| Relationships | None | parent/child (structural) + `related` (semantic: supersedes/references/implements/extends/conflicts) |
+| Task linking | Via `scope_paths` boost only | Bidirectional `task_ids` ↔ `task_links` |
+| Injection | Always inline (BM25 similarity) | Staged — `full` body for small fragments, `outline` (headings only) for large ones |
+
+**Boundary rule**: if it is a standalone piece of knowledge that fits in a
+paragraph or two (< 1 page, no internal sections), save it as a memory. If it
+has structure — sections, a hierarchy, cross-references to other documents —
+use document management (`handoff_doc_save`; see the `handoff-docs` skill).
+
+There is **no migration path** between the two stores — they are independent.
+If a memory grows into something that needs sections and cross-references,
+recreate it as a document with `handoff_doc_save` and delete the memory with
+`handoff_memory_delete` rather than expecting an automatic conversion.