handoff-mcp-server 0.19.1 → 0.22.0

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.

package/src/context/injection.rs

@@ -0,0 +1,239 @@
+//! Shared BM25 + scope-path ranking used by `memory_query` and (from t96.3)
+//! `doc_query`.
+//!
+//! Extracted from the original `memory_query` implementation
+//! (`src/mcp/handlers/memory.rs`) so both features rank candidates the same
+//! way: BM25 relevance over a `lexsim::Corpus`, a fixed bonus when a
+//! candidate's `scope_paths` prefix-matches one of the query's `file_paths`,
+//! a `min_score` floor, then a stable sort + `limit` truncation.
+
+/// One ranked candidate: the index into the caller's original slice, plus its
+/// final score (BM25 + scope bonus).
+#[derive(Debug, Clone, Copy, PartialEq)]
+pub struct RankItem {
+    pub index: usize,
+    pub score: f64,
+}
+
+/// Tuning knobs for [`rank_by_bm25_and_scope`].
+#[derive(Debug, Clone, Copy)]
+pub struct RankConfig {
+    /// Candidates scoring below this are dropped before sorting.
+    pub min_score: f64,
+    /// Added to a candidate's BM25 score when [`scope_matches`] is true.
+    pub scope_path_bonus: f64,
+    /// Max number of items returned (applied after sort, before session diff).
+    pub limit: usize,
+}
+
+/// True if any `scope` prefix matches any `file` path (substring match on the
+/// path, not a strict prefix — mirrors the original `memory_query` behavior).
+pub fn scope_matches(scopes: &[String], files: &[String]) -> bool {
+    if scopes.is_empty() || files.is_empty() {
+        return false;
+    }
+    scopes
+        .iter()
+        .any(|scope| files.iter().any(|f| f.contains(scope.as_str())))
+}
+
+/// Rank every document in `corpus` against `query_tokens` via BM25, add
+/// `config.scope_path_bonus` when `scope_paths[i]` matches `file_paths`, drop
+/// anything below `config.min_score`, sort descending by score, and truncate
+/// to `config.limit`.
+///
+/// `scope_paths` and the corpus must be index-aligned (one entry per
+/// document); `corpus.len()` and `scope_paths.len()` are expected to match —
+/// a mismatch simply means the extra `scope_paths` entries are never
+/// consulted (indices beyond `corpus.len()` are not produced).
+pub fn rank_by_bm25_and_scope(
+    corpus: &lexsim::Corpus,
+    query_tokens: &[String],
+    scope_paths: &[Vec<String>],
+    file_paths: &[String],
+    config: &RankConfig,
+) -> Vec<RankItem> {
+    let scores = corpus.bm25_scores_tokens(query_tokens);
+
+    let mut ranked: Vec<RankItem> = scores
+        .into_iter()
+        .enumerate()
+        .map(|(index, mut score)| {
+            if let Some(scopes) = scope_paths.get(index) {
+                if scope_matches(scopes, file_paths) {
+                    score += config.scope_path_bonus;
+                }
+            }
+            RankItem { index, score }
+        })
+        .filter(|item| item.score >= config.min_score)
+        .collect();
+
+    ranked.sort_by(|a, b| {
+        b.score
+            .partial_cmp(&a.score)
+            .unwrap_or(std::cmp::Ordering::Equal)
+    });
+    ranked.truncate(config.limit);
+    ranked
+}
+
+/// Drop already-injected candidates (per the caller's session sidecar) from
+/// `ranked`, then truncate the survivors to `limit`.
+///
+/// `already_injected(index)` receives the original document index (as stored
+/// on [`RankItem::index`]) and returns true when that document was already
+/// injected into the current session at its current content hash.
+pub fn filter_already_injected<F>(
+    ranked: Vec<RankItem>,
+    already_injected: F,
+    limit: usize,
+) -> Vec<RankItem>
+where
+    F: Fn(usize) -> bool,
+{
+    ranked
+        .into_iter()
+        .filter(|item| !already_injected(item.index))
+        .take(limit)
+        .collect()
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn docs() -> Vec<String> {
+        vec![
+            "rust error handling with Result and anyhow".to_string(),
+            "javascript promises and async await".to_string(),
+            "rust ownership borrow checker ownership".to_string(),
+        ]
+    }
+
+    fn default_config() -> RankConfig {
+        RankConfig {
+            min_score: 0.0,
+            scope_path_bonus: 2.0,
+            limit: 10,
+        }
+    }
+
+    #[test]
+    fn scope_matches_prefix() {
+        let scopes = vec!["src/storage/".to_string()];
+        let files = vec!["/repo/src/storage/mod.rs".to_string()];
+        assert!(scope_matches(&scopes, &files));
+        let files2 = vec!["/repo/src/mcp/mod.rs".to_string()];
+        assert!(!scope_matches(&scopes, &files2));
+    }
+
+    #[test]
+    fn scope_matches_empty_inputs_false() {
+        assert!(!scope_matches(&[], &["a".to_string()]));
+        assert!(!scope_matches(&["a".to_string()], &[]));
+    }
+
+    #[test]
+    fn rank_by_bm25_orders_relevant_docs_first() {
+        let corpus = lexsim::Corpus::build(&docs());
+        let query_tokens = lexsim::tokenize("rust ownership");
+        let scope_paths: Vec<Vec<String>> = vec![vec![], vec![], vec![]];
+        let ranked =
+            rank_by_bm25_and_scope(&corpus, &query_tokens, &scope_paths, &[], &default_config());
+
+        assert!(!ranked.is_empty());
+        // Doc 2 mentions "rust" and "ownership" twice — should rank first.
+        assert_eq!(ranked[0].index, 2);
+    }
+
+    #[test]
+    fn rank_by_bm25_applies_scope_path_bonus() {
+        let corpus = lexsim::Corpus::build(&docs());
+        // Query barely mentions doc 1's content, but its scope matches the
+        // queried file path, so the bonus should promote it into the results.
+        let query_tokens = lexsim::tokenize("javascript");
+        let scope_paths: Vec<Vec<String>> = vec![vec![], vec!["src/web/".to_string()], vec![]];
+        let file_paths = vec!["/repo/src/web/app.js".to_string()];
+        let config = RankConfig {
+            min_score: 0.0,
+            scope_path_bonus: 2.0,
+            limit: 10,
+        };
+        let ranked =
+            rank_by_bm25_and_scope(&corpus, &query_tokens, &scope_paths, &file_paths, &config);
+        assert_eq!(ranked[0].index, 1);
+        assert!(ranked[0].score >= 2.0);
+    }
+
+    #[test]
+    fn rank_by_bm25_filters_below_min_score() {
+        let corpus = lexsim::Corpus::build(&docs());
+        let query_tokens = lexsim::tokenize("completely unrelated gibberish zzz");
+        let scope_paths: Vec<Vec<String>> = vec![vec![], vec![], vec![]];
+        let config = RankConfig {
+            min_score: 0.01,
+            scope_path_bonus: 2.0,
+            limit: 10,
+        };
+        let ranked = rank_by_bm25_and_scope(&corpus, &query_tokens, &scope_paths, &[], &config);
+        assert!(ranked.is_empty());
+    }
+
+    #[test]
+    fn rank_by_bm25_respects_limit() {
+        let corpus = lexsim::Corpus::build(&docs());
+        let query_tokens = lexsim::tokenize("rust javascript");
+        let scope_paths: Vec<Vec<String>> = vec![vec![], vec![], vec![]];
+        let config = RankConfig {
+            min_score: 0.0,
+            scope_path_bonus: 2.0,
+            limit: 1,
+        };
+        let ranked = rank_by_bm25_and_scope(&corpus, &query_tokens, &scope_paths, &[], &config);
+        assert_eq!(ranked.len(), 1);
+    }
+
+    #[test]
+    fn filter_already_injected_drops_marked_and_respects_limit() {
+        let ranked = vec![
+            RankItem {
+                index: 0,
+                score: 5.0,
+            },
+            RankItem {
+                index: 1,
+                score: 4.0,
+            },
+            RankItem {
+                index: 2,
+                score: 3.0,
+            },
+        ];
+        let already = |i: usize| i == 1;
+        let out = filter_already_injected(ranked, already, 10);
+        assert_eq!(out.iter().map(|i| i.index).collect::<Vec<_>>(), vec![0, 2]);
+    }
+
+    #[test]
+    fn filter_already_injected_applies_limit_after_filtering() {
+        let ranked = vec![
+            RankItem {
+                index: 0,
+                score: 5.0,
+            },
+            RankItem {
+                index: 1,
+                score: 4.0,
+            },
+            RankItem {
+                index: 2,
+                score: 3.0,
+            },
+        ];
+        let out = filter_already_injected(ranked, |_| false, 2);
+        assert_eq!(out.len(), 2);
+        assert_eq!(out[0].index, 0);
+        assert_eq!(out[1].index, 1);
+    }
+}

package/src/context/mod.rs

@@ -0,0 +1,129 @@
+//! Shared ranking + corpus-cache infrastructure for full-text search across
+//! features (`memory_query` today, `doc_query` from t96.3).
+//!
+//! See `wiki/130-document-management.md` §3.1 for the design rationale: a
+//! single BM25 corpus cache, invalidated by a generation counter bumped on
+//! every mutating call (`doc_save`/`doc_delete`/`doc_import`), avoids
+//! rebuilding the corpus on every query once fragment counts reach the
+//! thousands. `memory_query` stays on the un-cached path (memory counts are
+//! small enough that a per-call rebuild is cheap) and only adopts the shared
+//! ranking function from [`injection`].
+
+pub mod injection;
+
+use std::sync::{Mutex, OnceLock};
+
+/// Process-wide cache of the document-fragment BM25 corpus, invalidated by a
+/// monotonically increasing generation counter.
+///
+/// `doc_save`/`doc_delete`/`doc_import` call [`CorpusCache::increment_generation`]
+/// on every mutation; the next [`CorpusCache::get_or_build_corpus`] call
+/// notices its cached generation is stale and rebuilds. The MCP server is
+/// single-threaded stdio today, so the `Mutex` is uncontended in practice —
+/// it exists for forward compatibility with a future multi-session server.
+pub struct CorpusCache {
+    generation: u64,
+    built_generation: Option<u64>,
+    corpus: Option<lexsim::Corpus>,
+    doc_texts: Vec<String>,
+}
+
+impl CorpusCache {
+    fn new() -> Self {
+        CorpusCache {
+            generation: 0,
+            built_generation: None,
+            corpus: None,
+            doc_texts: Vec::new(),
+        }
+    }
+
+    /// Invalidate the cached corpus. Called after any mutation to the
+    /// underlying fragment store (`doc_save`, `doc_delete`, `doc_import`).
+    pub fn increment_generation(&mut self) {
+        self.generation += 1;
+    }
+
+    /// Return the cached corpus if it is still current for `doc_texts`,
+    /// otherwise rebuild it from `doc_texts` and cache the result.
+    ///
+    /// `doc_texts` is the caller's current full set of fragment index texts,
+    /// supplied fresh on every call (the cache does not own fragment
+    /// storage) — only the expensive `lexsim::Corpus::build` step is skipped
+    /// when the generation hasn't moved since the last build.
+    pub fn get_or_build_corpus(&mut self, doc_texts: &[String]) -> &lexsim::Corpus {
+        let stale = self.built_generation != Some(self.generation) || self.doc_texts != doc_texts;
+        if stale {
+            self.corpus = Some(lexsim::Corpus::build(doc_texts));
+            self.doc_texts = doc_texts.to_vec();
+            self.built_generation = Some(self.generation);
+        }
+        self.corpus
+            .as_ref()
+            .expect("corpus is always populated by the stale branch above")
+    }
+
+    /// Current generation counter (test/inspection hook).
+    pub fn generation(&self) -> u64 {
+        self.generation
+    }
+}
+
+impl Default for CorpusCache {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
+static DOC_CORPUS_CACHE: OnceLock<Mutex<CorpusCache>> = OnceLock::new();
+
+/// The process-wide document corpus cache, created lazily on first access.
+pub fn doc_corpus_cache() -> &'static Mutex<CorpusCache> {
+    DOC_CORPUS_CACHE.get_or_init(|| Mutex::new(CorpusCache::new()))
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn get_or_build_corpus_reuses_cache_when_generation_unchanged() {
+        let mut cache = CorpusCache::new();
+        let texts = vec!["alpha beta".to_string(), "gamma delta".to_string()];
+        {
+            let corpus = cache.get_or_build_corpus(&texts);
+            assert_eq!(corpus.len(), 2);
+        }
+        assert_eq!(cache.built_generation, Some(0));
+        // Second call with identical inputs and generation should not rebuild
+        // (rebuild is observable only via built_generation staying put).
+        let _ = cache.get_or_build_corpus(&texts);
+        assert_eq!(cache.built_generation, Some(0));
+    }
+
+    #[test]
+    fn increment_generation_forces_rebuild() {
+        let mut cache = CorpusCache::new();
+        let texts = vec!["alpha".to_string()];
+        let _ = cache.get_or_build_corpus(&texts);
+        assert_eq!(cache.built_generation, Some(0));
+
+        cache.increment_generation();
+        assert_eq!(cache.generation(), 1);
+
+        let texts2 = vec!["alpha".to_string(), "beta".to_string()];
+        let corpus = cache.get_or_build_corpus(&texts2);
+        assert_eq!(corpus.len(), 2);
+        assert_eq!(cache.built_generation, Some(1));
+    }
+
+    #[test]
+    fn doc_corpus_cache_is_a_shared_singleton() {
+        {
+            let mut guard = doc_corpus_cache().lock().expect("cache mutex poisoned");
+            guard.increment_generation();
+        }
+        let guard = doc_corpus_cache().lock().expect("cache mutex poisoned");
+        assert!(guard.generation() >= 1);
+    }
+}

package/src/lib.rs

@@ -1,4 +1,5 @@
 pub mod cli;
+pub mod context;
 pub mod mcp;
 pub mod setup;
 pub mod storage;