handoff-mcp-server 0.24.6 → 0.25.0

package/Cargo.lock

@@ -145,7 +145,7 @@ dependencies = [
 
 [[package]]
 name = "handoff-mcp"
-version = "0.24.6"
+version = "0.25.0"
 dependencies = [
  "anyhow",
  "chrono",
@@ -153,6 +153,7 @@ dependencies = [
  "pulldown-cmark",
  "serde",
  "serde_json",
+ "serde_yaml",
  "tempfile",
  "thiserror",
  "toml",
@@ -218,9 +219,9 @@ dependencies = [
 
 [[package]]
 name = "lexsim"
-version = "0.6.0"
+version = "0.7.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "b64f48de8c9d203c0ed3ac8c68e9ba1072206d5072551c08889a4bbae9d84677"
+checksum = "c7bf6d7f096edac1f6d1f955d41d2acbe238b5775da9c7f4039fdd975138a5d1"
 dependencies = [
  "unicode-normalization",
  "unicode-segmentation",
@@ -333,6 +334,12 @@ version = "1.0.23"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "cf54715a573b99ac80df0bc206da022bcd442c974952c7b9720069370852e21f"
 
+[[package]]
+name = "ryu"
+version = "1.0.23"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9774ba4a74de5f7b1c1451ed6cd5285a32eddb5cccb8cc655a4e50009e06477f"
+
 [[package]]
 name = "serde"
 version = "1.0.228"
@@ -386,6 +393,19 @@ dependencies = [
  "serde",
 ]
 
+[[package]]
+name = "serde_yaml"
+version = "0.9.34+deprecated"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6a8b1a1a2ebf674015cc02edccce75287f1a0130d394307b36743c2f5d504b47"
+dependencies = [
+ "indexmap",
+ "itoa",
+ "ryu",
+ "serde",
+ "unsafe-libyaml",
+]
+
 [[package]]
 name = "shlex"
 version = "2.0.1"
@@ -531,6 +551,12 @@ version = "0.2.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "b4ac048d71ede7ee76d585517add45da530660ef4390e49b098733c6e897f254"
 
+[[package]]
+name = "unsafe-libyaml"
+version = "0.2.11"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "673aac59facbab8a9007c7f6108d11f63b603f7cabff99fabf650fea5c32b861"
+
 [[package]]
 name = "wasm-bindgen"
 version = "0.2.126"

package/Cargo.toml

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

package/README.md

@@ -452,21 +452,29 @@ See [Project Memory](#project-memory-1) below for what it is and how to wire aut
 
 | 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_save` | Create or update a document (auto-splits into sections) |
+| `handoff_doc_get` | Read a document — full, meta, or single section |
 | `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_delete` | Delete a document; unlinks from tasks |
+| `handoff_doc_reassemble` | Reconstruct original Markdown from sections, with drift detection |
+| `handoff_doc_update_section` | Replace a single section by seq (optimistic locking) |
 | `handoff_doc_tree` | Walk family tree (ancestors/descendants/related) |
+| `handoff_doc_graph` | Visualize inter-document relationships with optional verification status |
+| `handoff_doc_trace` | Trace a document's lineage or dependency chain |
 | `handoff_doc_query` | Context injection — staged full/outline, hook-driven |
+| `handoff_doc_verify` | Verification matrix: generate, check, check_all, skip, sync, set_refs |
+| `handoff_doc_verify_status` | Verification progress summary with optional per-section details |
 | `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.
+Documents live in `.handoff/docs/` as single `_doc.<slug>.md` files (YAML
+frontmatter + body). Large Markdown is split into sections 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. `handoff_doc_verify` provides a verification matrix for tracking
+per-section review status, implementation/test references, and staleness
+detection after spec changes.
 
 ### Task Data Model
 
@@ -823,10 +831,15 @@ This project uses handoff-mcp for session continuity.
   When the VSCode extension is running, the timer delegates to it automatically.
   When the extension is absent, MCP runs a fallback timer and logs hours on stop.
   Use `handoff_timer_get_time` to check elapsed time without stopping.
+- **Spec registration**: if the task has a spec or design document,
+  register it via `handoff_doc_save(task_ids=[...])` so it survives across
+  sessions and links bidirectionally to the task. Generate a verification
+  matrix with `handoff_doc_verify(action="generate")` for review tracking.
 - **Project memory**: Use `handoff_memory_save` to record durable lessons, rules,
   conventions, and gotchas that every future session should know. Use
   `handoff_memory_query` to retrieve relevant memories. Near-duplicate memories are
   surfaced as conflicts for you to merge or force-save — never merged silently.
+  Save **as you learn them** during work, not at session end.
 ```
 
 ## Skills
@@ -837,6 +850,7 @@ This repository includes skill files that make handoff behavior automatic in Cla
 |-------|---------|
 | `handoff` | Core session lifecycle, task management, metrics, scheduling |
 | `handoff-load` | Quick session-start procedure |
+| `handoff-docs` | Document management — save, search, verify, import, family tree |
 | `handoff-memory` | Memory CRUD, conflict handling, cleanup |
 | `handoff-refer` | Cross-project referrals |
 | `handoff-import` | Bulk import from documents |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "handoff-mcp-server",
-  "version": "0.24.6",
+  "version": "0.25.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-docs/SKILL.md

@@ -60,17 +60,21 @@ Check readiness:
    - MCP automatically computes a section index at each h2 heading boundary
    - Use `doc_get(format="section", seq=N)` to retrieve individual sections on demand
 
-## The 9 Doc Tools
+## The 13 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_save` | Create or update a document. Splits `body` into sections automatically. |
+| `handoff_doc_get` | Read a document — `full` (reassembled body), `meta` (manifest only), or `section` (one section by seq). |
+| `handoff_doc_list` | List/search documents (BM25 over title + section bodies), filter by `doc_type`, `tags`, `task_id`. |
+| `handoff_doc_delete` | Delete a document; unlinks it from any linked tasks. |
+| `handoff_doc_reassemble` | Reconstruct the original Markdown from sections, with drift detection. |
+| `handoff_doc_update_section` | Replace a single section's content by seq (optimistic locking via `expected_hash`). |
 | `handoff_doc_tree` | Walk the family tree (ancestors/descendants/related) for a document. |
+| `handoff_doc_graph` | Visualize inter-document relationships; optionally includes verification status per node. |
+| `handoff_doc_trace` | Trace a document's lineage or dependency chain. |
 | `handoff_doc_query` | Context injection — hook-driven, staged `full`/`outline` results ranked by relevance. |
+| `handoff_doc_verify` | Verification matrix operations: `generate`, `check`, `check_all`, `skip`, `sync`, `set_refs`, `add_item` (v2 — freeform items / sub_items), `suggest_refs` (scan scope_paths for impl/test ref candidates). |
 | `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. |
 
@@ -133,6 +137,19 @@ 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_update_section`
+
+| Param | Required | Description |
+|---|---|---|
+| `doc_id` | yes | Document to update |
+| `seq` | yes | Section sequence number to replace |
+| `new_content` | yes | New Markdown content for the section (empty string deletes it) |
+| `expected_hash` | no | Optimistic lock — if set, the update fails when the section's current `content_hash` differs (returns the current hash so you can retry) |
+
+Replaces a single section's content without rewriting the entire document.
+The section's `content_hash` is recomputed after the update, and any
+verification matrix item for this seq is marked stale.
+
 ### `handoff_doc_tree`
 
 | Param | Required | Description |
@@ -141,6 +158,20 @@ edited directly after the split, its `content_hash` no longer matches and
 | `depth` | no | How many parent/child levels to return |
 | `include_related` | no | Whether to also include semantically `related` documents |
 
+### `handoff_doc_graph`
+
+| Param | Required | Description |
+|---|---|---|
+| `doc_id` | no | Focus on a specific document and its neighbors |
+| `include_verification` | no | Include `{total, verified}` verification progress per node |
+
+### `handoff_doc_trace`
+
+| Param | Required | Description |
+|---|---|---|
+| `doc_id` | yes | Document to trace from |
+| `direction` | no | `"up"` (ancestors) or `"down"` (descendants), default both |
+
 ### `handoff_doc_query`
 
 | Param | Required | Description |
@@ -177,9 +208,150 @@ each carrying a concrete `suggestion` the AI can approve, edit, or reject.
 | `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.
+Writes all documents atomically in one transaction, including any task links
+— matches the "validate whole tree, then write" pattern used by
+`handoff_import_context` for tasks.
+
+### `handoff_doc_verify`
+
+| Param | Required | Description |
+|---|---|---|
+| `doc_id` | yes | Document whose verification matrix to operate on |
+| `action` | yes | One of: `generate`, `check`, `check_all`, `skip`, `sync`, `set_refs`, `add_item`, `suggest_refs` |
+| `fragment_seq` | for `check`/`skip`/`set_refs`/`add_item` | Section seq to operate on (integer or array of integers for batch). For `add_item`, omit to add a freeform top-level item instead of a section sub_item. |
+| `sub_item_index` | no | For `check`/`skip`: the 0-based `SubItem.index` within `fragment_seq`'s `sub_items` to operate on, instead of the parent item itself (v2) |
+| `description` | for `add_item` when `fragment_seq` given | The new sub_item's description (v2) |
+| `label` | for `add_item` when `fragment_seq` omitted | The new freeform top-level item's label (v2) |
+| `category` | no | For `add_item`: item/sub_item category — `"requirement"` (default for sub_items), `"visual"`, `"regression"`, `"manual"`, ... free-extensible (v2) |
+| `skip_seqs` | for `generate` | Seqs to mark `skipped` on generation (e.g. `[0]` to skip the preamble) |
+| `reviewer` | no | `"ai"` or `"user"` — who performed the review |
+| `notes` | no | Free-text notes attached to the check |
+| `impl_refs` | for `set_refs` | Array of `{ path, lines?, label? }` — implementation locations |
+| `test_refs` | for `set_refs` | Array of `{ path, lines?, label? }` — test locations |
+
+**Actions:**
+
+| Action | What it does |
+|---|---|
+| `generate` | Create a new verification matrix from the document's sections. Errors if a matrix already exists (use `sync` to update). |
+| `check` | Mark one or more sections (or, with `sub_item_index`, a single sub_item) as `verified`. Records `verified_at` and `content_hash_at_verify`. |
+| `check_all` | Mark every section — and every sub_item (v2) — in the matrix as `verified` in one call. |
+| `skip` | Mark a section (or, with `sub_item_index`, a single sub_item) as `skipped` (not applicable for review). |
+| `sync` | Re-synchronize the matrix after sections changed (added/removed). Preserves existing item statuses; freeform items (v2) are never dropped. |
+| `set_refs` | Attach `impl_refs` / `test_refs` to a section item. |
+| `add_item` (v2) | With `fragment_seq`: append a `SubItem` (individual requirement) to that section's `sub_items` — `description` required. Without `fragment_seq`: append a freeform top-level item not tied to any section (e.g. a GUI check or regression test) — `label` required. |
+| `suggest_refs` | Read-only. Scans the document's `scope_paths` for source/test files (`.rs`/`.ts`/`.tsx`/`.py`/`.go`/`.js`/`.jsx`) and fuzzy-matches `fn`/`struct`/`impl`/`mod` definitions and test functions (`#[test]`, `fn test_*`, files under `tests/`) against each item's heading, returning up to 20 `impl_refs`/`test_refs` candidates per item for review. Requires an existing matrix (`generate` first). Does not mutate the document — accept candidates by passing them to `set_refs`. |
+
+### `handoff_doc_verify_status`
+
+| Param | Required | Description |
+|---|---|---|
+| `doc_id` | yes | Document to query |
+| `include_items` | no | `true` to include per-section item details (default `false` — summary only) |
+| `format` | no | `"json"` (default) or `"checklist"` (v2 — Markdown checklist rendering, see below) |
+
+Returns verification progress: `{ verification_status, progress: { checked, skipped, pending, total, stale, percentage } }`.
+When `include_items: true`, also returns an `items` array with each section's
+status, staleness flag, refs, reviewer, and notes (v2: including `category`,
+`sub_items`, and `label` for freeform items). v2 progress counts are
+leaf-based: an item with `sub_items` contributes its sub_items to
+`checked`/`skipped`/`pending`/`total` instead of itself, and freeform items
+(`fragment_seq: null`) are counted directly.
+
+#### `format="checklist"` (v2)
+
+`handoff_doc_verify_status(doc_id=..., include_items=true, format="checklist")`
+returns a Markdown checklist instead of JSON — useful for pasting into a PR
+description or presenting readiness to a human reviewer:
+
+```markdown
+# Verification: Document Title
+Status: in_review (5/16, 31%)
+
+## §2 1. Requirements ✓ verified ⚠ stale
+- impl: src/storage/docs/mod.rs:42-180 (DocStore)
+- test: tests/doc_save.rs (roundtrip test)
+- [ ] Shape must be an octahedron
+- [x] Color matches status (@ai, 2026-07-11)
+
+## — Drag-and-drop visual check ○ pending [visual]
+## — No layout regressions in the existing task list ○ pending [regression]
+```
+
+## Verification Workflow
+
+### When to use each action
+
+| Situation | What to do |
+|---|---|
+| Spec just saved | `generate` (optionally with `skip_seqs: [0]` to skip the preamble) |
+| Implementation complete for a section | `check(fragment_seq=N, reviewer="ai")` + `set_refs` |
+| Section is background/context only | `skip(fragment_seq=N)` |
+| Spec was updated after matrix existed | `sync` to add/remove items, then re-check stale items |
+| GUI/visual check needed | `check(fragment_seq=N, reviewer="user")` — user confirms manually |
+| A section has multiple distinct requirements to track individually | `add_item(fragment_seq=N, description=...)` per requirement, then `check(fragment_seq=N, sub_item_index=I)` on each |
+| A check doesn't map to any single section (GUI/regression/manual sweep) | `add_item(label=..., category="visual"\|"regression"\|"manual")` (freeform, no `fragment_seq`), then `check(fragment_seq=<its seq>)` |
+| Human-readable readiness summary (PR description, review handoff) | `doc_verify_status(include_items=true, format="checklist")` — Markdown checklist |
+| Quick release readiness | `doc_verify_status` — check `verification_status == "verified"` |
+| Don't want to hunt for impl/test locations by hand | `suggest_refs` to get candidates per item, review them, then `set_refs(fragment_seq=N, impl_refs=..., test_refs=...)` with the ones you accept |
+
+### `reviewer` guidelines
+
+| Reviewer | When |
+|---|---|
+| `"ai"` | AI verified by reading the code, running tests, or comparing spec vs implementation |
+| `"user"` | User verified visually (GUI, layout, drag behavior) or confirmed a judgment call |
+
+### Stale detection and response
+
+When a section's content changes after being verified, `doc_verify_status`
+flags it as `stale: true`. Response flow:
+
+1. Check `doc_verify_status(include_items: true)` — look for `stale` items
+2. Review the changed section: `doc_get(format="section", seq=N)`
+3. If still valid: `check(fragment_seq=N)` to re-verify (updates `content_hash_at_verify`)
+4. If invalid: update implementation, then re-verify
+
+### Multi-document release verification
+
+For release readiness across multiple specs:
+
+```
+1. handoff_doc_list(doc_type="spec", tags=["release-target"])
+2. For each doc: handoff_doc_verify_status(doc_id=...)
+3. All docs must have verification_status == "verified" and stale == 0
+```
+
+### E2E workflow example
+
+```
+# 1. Write and save the spec
+handoff_doc_save(slug="auth-spec", title="Authentication Spec",
+                 body="# Auth Spec\n\n## Requirements\n...",
+                 doc_type="spec", task_ids=["t42"])
+
+# 2. Generate verification matrix (skip preamble)
+handoff_doc_verify(doc_id="doc-...", action="generate", skip_seqs=[0])
+
+# 3. Implement, then mark sections verified
+handoff_doc_verify(doc_id="doc-...", action="check", fragment_seq=1,
+                   reviewer="ai", notes="Implemented and tested")
+handoff_doc_verify(doc_id="doc-...", action="set_refs", fragment_seq=1,
+                   impl_refs=[{path: "src/auth.rs", lines: "10-50"}],
+                   test_refs=[{path: "tests/auth.rs", label: "login flow"}])
+
+# 3b. Or let suggest_refs propose candidates instead of hand-picking them —
+#     requires scope_paths to be set on the document (doc_save(scope_paths=[...]))
+handoff_doc_verify(doc_id="doc-...", action="suggest_refs")
+# → { suggestions: [{ fragment_seq: 1, heading: "Requirements",
+#      suggested_impl_refs: [{path: "src/auth.rs", lines: "12", label: "handle_login"}],
+#      suggested_test_refs: [{path: "tests/auth.rs", lines: "5", label: "test_login_flow"}] }] }
+# Review the candidates, then accept the ones you want via set_refs (same as 3).
+
+# 4. Check release readiness
+handoff_doc_verify_status(doc_id="doc-...", include_items=true)
+# → verification_status: "verified", stale: 0 → ready to ship
+```
 
 ## Staged Injection (outline vs full)
 

package/src/context/injection.rs

@@ -20,6 +20,9 @@ pub struct RankItem {
 pub struct RankConfig {
     /// Candidates scoring below this are dropped before sorting.
     pub min_score: f64,
+    /// Relative threshold (0.0–1.0): after ranking, a candidate is dropped
+    /// unless `score >= top_score * relative_threshold`. 0.0 disables.
+    pub relative_threshold: 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).
@@ -37,10 +40,10 @@ pub fn scope_matches(scopes: &[String], files: &[String]) -> bool {
         .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`.
+/// Rank every document in `corpus` against `query_tokens` via weighted 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 —
@@ -48,12 +51,12 @@ pub fn scope_matches(scopes: &[String], files: &[String]) -> bool {
 /// consulted (indices beyond `corpus.len()` are not produced).
 pub fn rank_by_bm25_and_scope(
     corpus: &lexsim::Corpus,
-    query_tokens: &[String],
+    query_tokens: &[lexsim::WeightedToken],
     scope_paths: &[Vec<String>],
     file_paths: &[String],
     config: &RankConfig,
 ) -> Vec<RankItem> {
-    let scores = corpus.bm25_scores_tokens(query_tokens);
+    let scores = corpus.bm25_scores_weighted_tokens(query_tokens);
 
     let mut ranked: Vec<RankItem> = scores
         .into_iter()
@@ -66,7 +69,7 @@ pub fn rank_by_bm25_and_scope(
             }
             RankItem { index, score }
         })
-        .filter(|item| item.score >= config.min_score)
+        .filter(|item| item.score > 0.0 && item.score >= config.min_score)
         .collect();
 
     ranked.sort_by(|a, b| {
@@ -74,6 +77,16 @@ pub fn rank_by_bm25_and_scope(
             .partial_cmp(&a.score)
             .unwrap_or(std::cmp::Ordering::Equal)
     });
+
+    // Relative threshold: drop candidates whose score is below a fraction of
+    // the top hit. Applied after sorting so `ranked[0]` is the best match.
+    if config.relative_threshold > 0.0 {
+        if let Some(top) = ranked.first() {
+            let floor = top.score * config.relative_threshold;
+            ranked.retain(|item| item.score >= floor);
+        }
+    }
+
     ranked.truncate(config.limit);
     ranked
 }
@@ -114,6 +127,7 @@ mod tests {
     fn default_config() -> RankConfig {
         RankConfig {
             min_score: 0.0,
+            relative_threshold: 0.0,
             scope_path_bonus: 2.0,
             limit: 10,
         }
@@ -136,27 +150,25 @@ mod tests {
 
     #[test]
     fn rank_by_bm25_orders_relevant_docs_first() {
-        let corpus = lexsim::Corpus::build(&docs());
-        let query_tokens = lexsim::tokenize("rust ownership");
+        let corpus = lexsim::Corpus::build_weighted(&docs());
+        let query_tokens = lexsim::tokenize_weighted("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 corpus = lexsim::Corpus::build_weighted(&docs());
+        let query_tokens = lexsim::tokenize_weighted("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,
+            relative_threshold: 0.0,
             scope_path_bonus: 2.0,
             limit: 10,
         };
@@ -168,11 +180,12 @@ mod tests {
 
     #[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 corpus = lexsim::Corpus::build_weighted(&docs());
+        let query_tokens = lexsim::tokenize_weighted("completely unrelated gibberish zzz");
         let scope_paths: Vec<Vec<String>> = vec![vec![], vec![], vec![]];
         let config = RankConfig {
             min_score: 0.01,
+            relative_threshold: 0.0,
             scope_path_bonus: 2.0,
             limit: 10,
         };
@@ -182,11 +195,12 @@ mod tests {
 
     #[test]
     fn rank_by_bm25_respects_limit() {
-        let corpus = lexsim::Corpus::build(&docs());
-        let query_tokens = lexsim::tokenize("rust javascript");
+        let corpus = lexsim::Corpus::build_weighted(&docs());
+        let query_tokens = lexsim::tokenize_weighted("rust javascript");
         let scope_paths: Vec<Vec<String>> = vec![vec![], vec![], vec![]];
         let config = RankConfig {
             min_score: 0.0,
+            relative_threshold: 0.0,
             scope_path_bonus: 2.0,
             limit: 1,
         };
@@ -194,6 +208,29 @@ mod tests {
         assert_eq!(ranked.len(), 1);
     }
 
+    #[test]
+    fn rank_by_bm25_applies_relative_threshold() {
+        let corpus = lexsim::Corpus::build_weighted(&docs());
+        let query_tokens = lexsim::tokenize_weighted("rust ownership");
+        let scope_paths: Vec<Vec<String>> = vec![vec![], vec![], vec![]];
+        let all =
+            rank_by_bm25_and_scope(&corpus, &query_tokens, &scope_paths, &[], &default_config());
+        assert!(all.len() >= 2, "need at least 2 results to test relative");
+        let config_rel = RankConfig {
+            min_score: 0.0,
+            relative_threshold: 0.95,
+            scope_path_bonus: 0.0,
+            limit: 10,
+        };
+        let filtered =
+            rank_by_bm25_and_scope(&corpus, &query_tokens, &scope_paths, &[], &config_rel);
+        assert!(
+            filtered.len() < all.len(),
+            "relative threshold should drop low-scoring tail"
+        );
+        assert_eq!(filtered[0].index, all[0].index, "top hit must survive");
+    }
+
     #[test]
     fn filter_already_injected_drops_marked_and_respects_limit() {
         let ranked = vec![

package/src/context/mod.rs

@@ -54,7 +54,7 @@ impl CorpusCache {
     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.corpus = Some(lexsim::Corpus::build_weighted(doc_texts));
             self.doc_texts = doc_texts.to_vec();
             self.built_generation = Some(self.generation);
         }

package/src/mcp/handlers/auto_schedule.rs

@@ -6,6 +6,7 @@ use serde_json::{json, Value};
 use toml_edit::DocumentMut;
 
 use super::resolve_project_dir;
+use crate::storage::config::weekday_to_num;
 use crate::storage::ensure_handoff_exists;
 use crate::storage::tasks::*;
 
@@ -486,16 +487,3 @@ fn parse_assignee_calendars(config_path: &std::path::Path) -> Result<HashMap<Str
 
     Ok(result)
 }
-
-fn weekday_to_num(s: &str) -> Option<u32> {
-    match s.to_lowercase().as_str() {
-        "sun" | "sunday" => Some(0),
-        "mon" | "monday" => Some(1),
-        "tue" | "tuesday" => Some(2),
-        "wed" | "wednesday" => Some(3),
-        "thu" | "thursday" => Some(4),
-        "fri" | "friday" => Some(5),
-        "sat" | "saturday" => Some(6),
-        _ => None,
-    }
-}

package/src/mcp/handlers/capacity.rs

@@ -4,7 +4,7 @@ use serde_json::{json, Value};
 use toml_edit::DocumentMut;
 
 use super::resolve_project_dir;
-use crate::storage::config::read_config;
+use crate::storage::config::{read_config, weekday_to_num};
 use crate::storage::ensure_handoff_exists;
 use crate::storage::tasks::{build_task_index, is_terminal_status, TaskIndex};
 
@@ -245,19 +245,6 @@ fn parse_calendar(config_path: &std::path::Path, assignee: Option<&str>) -> Resu
     Ok(cal)
 }
 
-fn weekday_to_num(s: &str) -> Option<u32> {
-    match s.to_lowercase().as_str() {
-        "sun" | "sunday" => Some(0),
-        "mon" | "monday" => Some(1),
-        "tue" | "tuesday" => Some(2),
-        "wed" | "wednesday" => Some(3),
-        "thu" | "thursday" => Some(4),
-        "fri" | "friday" => Some(5),
-        "sat" | "saturday" => Some(6),
-        _ => None,
-    }
-}
-
 fn allocate_task_hours(
     tree: &[TaskIndex],
     assignee_filter: Option<&str>,

package/src/mcp/handlers/config.rs

@@ -50,6 +50,7 @@ pub fn handle_update(arguments: &Value) -> Result<String> {
         "settings.memory_enabled",
         "settings.memory_dup_threshold",
         "settings.memory_query_min_score",
+        "settings.memory_query_relative_threshold",
         "settings.memory_query_limit",
         "settings.memory_stale_days",
         "settings.memory_injected_gc_days",
@@ -153,6 +154,18 @@ pub fn handle_update(arguments: &Value) -> Result<String> {
                     config.settings.memory_query_min_score = n;
                     applied.push(format!("settings.memory_query_min_score = {n}"));
                 }
+                "settings.memory_query_relative_threshold" => {
+                    let Some(n) = value.as_f64() else {
+                        anyhow::bail!("settings.memory_query_relative_threshold must be a number");
+                    };
+                    if !(0.0..=1.0).contains(&n) {
+                        anyhow::bail!(
+                            "settings.memory_query_relative_threshold must be between 0 and 1"
+                        );
+                    }
+                    config.settings.memory_query_relative_threshold = n;
+                    applied.push(format!("settings.memory_query_relative_threshold = {n}"));
+                }
                 "settings.memory_query_limit" => {
                     let Some(n) = value.as_u64() else {
                         anyhow::bail!("settings.memory_query_limit must be a non-negative integer");