handoff-mcp-server 0.24.5 → 0.25.0

package/src/storage/docs/model.rs

@@ -4,7 +4,10 @@
 //! in-memory (byte offsets into the body) rather than split into physical
 //! fragment files.
 
+use std::collections::HashMap;
+
 use serde::{Deserialize, Serialize};
+use serde_json::Value;
 
 /// Current document schema version. Bump when `DocMetadata` changes shape in
 /// a way that needs migration handling on read.
@@ -89,6 +92,15 @@ pub struct DocMetadata {
     #[serde(default = "default_line_ending")]
     pub line_ending: String,
 
+    /// ATX heading level (1-6) at which this document is split into
+    /// sections (frontmatter migration, t123.1/t123.2). Persisted per-doc so
+    /// a manually-edited `.md` file recomputes the same section boundaries
+    /// on every read. Defaults to
+    /// [`super::split::DEFAULT_SPLIT_LEVEL`] for documents saved before this
+    /// field existed.
+    #[serde(default = "default_split_level")]
+    pub split_level: u8,
+
     /// Section manifest, in `seq` order (v5: replaces the old `fragments`
     /// physical-file manifest — `sections` are in-memory byte-offset
     /// indexes into `_doc.<slug>.md`, not separate files). Old on-disk
@@ -112,6 +124,15 @@ pub struct DocMetadata {
     /// `#[serde(default)]`.
     #[serde(default, skip_serializing_if = "Option::is_none")]
     pub verification: Option<Verification>,
+
+    /// Unknown/unrecognized frontmatter keys, preserved for round-trip
+    /// fidelity (frontmatter migration spec: "extra fields"). Never written
+    /// by handoff-mcp itself; only ever populated by parsing a document
+    /// whose frontmatter has keys outside the known schema (e.g. hand-edited
+    /// or authored by another tool). Not present in the JSON-era on-disk
+    /// format, so `#[serde(default)]` keeps old fixtures deserializing.
+    #[serde(default, skip_serializing_if = "HashMap::is_empty")]
+    pub extra: HashMap<String, Value>,
 }
 
 fn default_auto_inject() -> String {
@@ -122,6 +143,10 @@ fn default_line_ending() -> String {
     "lf".to_string()
 }
 
+fn default_split_level() -> u8 {
+    super::split::DEFAULT_SPLIT_LEVEL
+}
+
 /// Maximum allowed length of a `slug` (spec §3.1 v5 proposal).
 pub const MAX_SLUG_LEN: usize = 60;
 
@@ -147,11 +172,13 @@ impl DocMetadata {
             source: DocSource::default(),
             has_bom: false,
             line_ending: default_line_ending(),
+            split_level: default_split_level(),
             sections: Vec::new(),
             created_at: now.clone(),
             updated_at: now,
             content_hash: String::new(),
             verification: None,
+            extra: HashMap::new(),
         }
     }
 }
@@ -176,21 +203,27 @@ pub struct DocSource {
     /// Original file path when imported from `wiki/` or `tmp/`.
     #[serde(default, skip_serializing_if = "Option::is_none")]
     pub original_path: Option<String>,
-    /// Canonical-form hash used to detect drift on reassembly.
+    /// Canonical-form hash used to detect drift on reassembly. In the
+    /// frontmatter format (t123.1+), this is the value persisted at the
+    /// *last save* (`source.canonical_hash` in frontmatter, untouched by
+    /// `read_doc`'s on-read `content_hash` recompute — t123.2), so comparing
+    /// it against the freshly-recomputed top-level `content_hash` is the
+    /// drift signal `doc_reassemble` uses.
     #[serde(default, skip_serializing_if = "Option::is_none")]
     pub canonical_hash: Option<String>,
-    /// Raw YAML frontmatter block (spec §5.1 scope rule 6), extracted by
-    /// [`super::split::split`] and excluded from section seq-0. `None` when
-    /// the document has no frontmatter.
+    /// Legacy field (pre-frontmatter-migration, t96): raw YAML frontmatter
+    /// block stashed by the old 2-file format when a caller's authored
+    /// `body` started with its own `---`-fenced block, so it could be
+    /// restored losslessly on `doc_get`/`doc_reassemble`. **Dead in the
+    /// frontmatter format** — kept only so a legacy `_doc.<slug>.json`
+    /// sidecar still deserializes during migration
+    /// (`storage::docs::migrate_legacy_doc`); a document's own frontmatter
+    /// is now handoff-owned metadata, so a caller's leading frontmatter
+    /// block in `body` is absorbed rather than round-tripped (see
+    /// `handle_doc_get`'s `read_full_body`).
     #[serde(default, skip_serializing_if = "Option::is_none")]
     pub frontmatter: Option<String>,
-    /// `true` if a line ending immediately followed the closing `---` fence
-    /// in the originally authored body (see
-    /// [`super::split::SplitDocument::frontmatter_trailing_eol`]).
-    /// Meaningless when `frontmatter` is `None`. Defaults to `true` so
-    /// documents persisted before this field existed keep the pre-fix
-    /// reassembly behavior (always re-adding the eol) rather than silently
-    /// dropping a byte they never reported not having.
+    /// Legacy field, paired with [`Self::frontmatter`] — see its doc comment.
     #[serde(default = "default_frontmatter_trailing_eol")]
     pub frontmatter_trailing_eol: bool,
 }
@@ -251,10 +284,14 @@ pub struct Verification {
 }
 
 /// One row in the verification matrix — tracks review state of a single
-/// spec fragment.
+/// spec fragment (v1) or, since v2 (wiki/140-verification-matrix.md §7), a
+/// freeform top-level item not tied to any section (`fragment_seq: None`).
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct VerificationItem {
-    pub fragment_seq: usize,
+    /// The section this item tracks. `None` (v2) = a freeform item, not
+    /// tied to any document section — see `label`.
+    #[serde(default)]
+    pub fragment_seq: Option<usize>,
     pub heading: String,
     /// "pending" | "skipped" | "verified".
     pub status: String,
@@ -273,6 +310,47 @@ pub struct VerificationItem {
     /// flagged (`doc_verify_status`).
     #[serde(default, skip_serializing_if = "Option::is_none")]
     pub content_hash_at_verify: Option<String>,
+
+    /// v2: item category — `"section"` (default, existing heading-level
+    /// items), `"requirement"`, `"visual"`, `"regression"`, `"manual"`
+    /// (free-extensible, not an enforced enum).
+    #[serde(default = "default_category")]
+    pub category: String,
+    /// v2: individual requirements tracked within a `category="section"`
+    /// item.
+    #[serde(default, skip_serializing_if = "Vec::is_empty")]
+    pub sub_items: Vec<SubItem>,
+    /// v2: label for a freeform item (`fragment_seq: None`).
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub label: Option<String>,
+}
+
+fn default_category() -> String {
+    "section".to_string()
+}
+
+/// v2 (wiki/140-verification-matrix.md §7.1): one individual requirement
+/// tracked within a section-level `VerificationItem::sub_items`.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct SubItem {
+    /// 0-based position within the parent item's `sub_items`.
+    pub index: usize,
+    pub description: String,
+    /// "pending" | "skipped" | "verified".
+    pub status: String,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub reviewer: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub verified_at: Option<String>,
+    #[serde(default)]
+    pub notes: String,
+    /// "requirement" (default) | "visual" | "manual" | ... (free-extensible).
+    #[serde(default = "default_sub_category")]
+    pub category: String,
+}
+
+fn default_sub_category() -> String {
+    "requirement".to_string()
 }
 
 /// A reference to a source code location.
@@ -494,7 +572,7 @@ mod tests {
             created_at: "2026-07-11T10:00:00Z".to_string(),
             updated_at: "2026-07-11T14:30:00Z".to_string(),
             items: vec![VerificationItem {
-                fragment_seq: 2,
+                fragment_seq: Some(2),
                 heading: "1. 課題".to_string(),
                 status: "verified".to_string(),
                 impl_refs: vec![CodeRef {
@@ -511,6 +589,9 @@ mod tests {
                 verified_at: Some("2026-07-11T14:30:00Z".to_string()),
                 notes: String::new(),
                 content_hash_at_verify: Some("abc123".to_string()),
+                category: "section".to_string(),
+                sub_items: Vec::new(),
+                label: None,
             }],
         });
 
@@ -519,7 +600,7 @@ mod tests {
         let v = back.verification.expect("verification must round-trip");
         assert_eq!(v.status, "in_review");
         assert_eq!(v.items.len(), 1);
-        assert_eq!(v.items[0].fragment_seq, 2);
+        assert_eq!(v.items[0].fragment_seq, Some(2));
         assert_eq!(v.items[0].impl_refs[0].path, "src/storage/docs/mod.rs");
         assert_eq!(
             v.items[0].test_refs[0].label.as_deref(),
@@ -527,6 +608,96 @@ mod tests {
         );
     }
 
+    /// wiki/140-verification-matrix.md §7.1 (v2 extension): a v1
+    /// `VerificationItem` (plain-number `fragment_seq`, no `category` /
+    /// `sub_items` / `label`) must still deserialize, defaulting
+    /// `category` to `"section"`, `sub_items` to empty, and `label` to
+    /// `None` — v1 behavior is fully preserved.
+    #[test]
+    fn verification_item_v1_json_deserializes_with_v2_defaults() {
+        let v1_item = serde_json::json!({
+            "fragment_seq": 2,
+            "heading": "1. 課題",
+            "status": "verified",
+            "reviewer": "ai",
+            "verified_at": "2026-07-11T14:30:00Z",
+        });
+        let item: VerificationItem = serde_json::from_value(v1_item).unwrap();
+        assert_eq!(item.fragment_seq, Some(2));
+        assert_eq!(item.category, "section");
+        assert!(item.sub_items.is_empty());
+        assert!(item.label.is_none());
+    }
+
+    #[test]
+    fn sub_item_defaults_category_to_requirement() {
+        let json = serde_json::json!({
+            "index": 0,
+            "description": "形状=八面体であること",
+            "status": "pending",
+        });
+        let sub: SubItem = serde_json::from_value(json).unwrap();
+        assert_eq!(sub.category, "requirement");
+        assert!(sub.notes.is_empty());
+        assert!(sub.reviewer.is_none());
+    }
+
+    #[test]
+    fn verification_item_supports_freeform_fragment_seq_none() {
+        let item = VerificationItem {
+            fragment_seq: None,
+            heading: "ドラッグ操作の目視確認".to_string(),
+            status: "pending".to_string(),
+            impl_refs: Vec::new(),
+            test_refs: Vec::new(),
+            reviewer: None,
+            verified_at: None,
+            notes: String::new(),
+            content_hash_at_verify: None,
+            category: "visual".to_string(),
+            sub_items: Vec::new(),
+            label: Some("ドラッグ操作の目視確認".to_string()),
+        };
+        let json = serde_json::to_string(&item).unwrap();
+        let back: VerificationItem = serde_json::from_str(&json).unwrap();
+        assert!(back.fragment_seq.is_none());
+        assert_eq!(back.label.as_deref(), Some("ドラッグ操作の目視確認"));
+        assert_eq!(back.category, "visual");
+    }
+
+    #[test]
+    fn verification_item_sub_items_round_trip() {
+        let mut item = VerificationItem {
+            fragment_seq: Some(2),
+            heading: "1. 課題".to_string(),
+            status: "in_review".to_string(),
+            impl_refs: Vec::new(),
+            test_refs: Vec::new(),
+            reviewer: None,
+            verified_at: None,
+            notes: String::new(),
+            content_hash_at_verify: None,
+            category: "section".to_string(),
+            sub_items: Vec::new(),
+            label: None,
+        };
+        item.sub_items.push(SubItem {
+            index: 0,
+            description: "形状=八面体であること".to_string(),
+            status: "verified".to_string(),
+            reviewer: Some("ai".to_string()),
+            verified_at: Some("2026-07-11T14:30:00Z".to_string()),
+            notes: String::new(),
+            category: "requirement".to_string(),
+        });
+
+        let json = serde_json::to_string(&item).unwrap();
+        let back: VerificationItem = serde_json::from_str(&json).unwrap();
+        assert_eq!(back.sub_items.len(), 1);
+        assert_eq!(back.sub_items[0].description, "形状=八面体であること");
+        assert_eq!(back.sub_items[0].status, "verified");
+    }
+
     #[test]
     fn valid_constants_contain_spec_values() {
         assert!(VALID_DOC_TYPES.contains(&"spec"));

package/src/storage/memory/mod.rs

@@ -152,6 +152,7 @@ mod tests {
             "lesson".to_string(),
             vec![],
             vec![],
+            vec![],
             now_rfc3339(),
         )
     }

package/src/storage/memory/model.rs

@@ -2,7 +2,9 @@ use serde::{Deserialize, Serialize};
 
 /// Current memory schema version. Bump when `MemoryEntry` changes shape in a way
 /// that needs migration handling on read.
-pub const MEMORY_SCHEMA_VERSION: u32 = 1;
+///
+/// v1 → v2: added `keywords` field (defaults to empty on read).
+pub const MEMORY_SCHEMA_VERSION: u32 = 2;
 
 /// Valid `kind` values for a memory. Free-form text is rejected so the field
 /// stays a small, queryable enumeration.
@@ -32,6 +34,13 @@ pub struct MemoryEntry {
     /// Free-form tags; also fed into the similarity index.
     #[serde(default)]
     pub tags: Vec<String>,
+    /// Subject keywords — nouns, technical terms, proper nouns that identify what
+    /// this memory is *about*. Used for BM25 matching with boosted weight.
+    /// Distinct from `tags` (classification labels) and `scope_paths` (file
+    /// prefixes). Populated by the AI at save time; defaults to empty for v1
+    /// memories.
+    #[serde(default)]
+    pub keywords: Vec<String>,
     /// Path prefixes this memory applies to (e.g. `src/storage/`). A query whose
     /// file paths start with one of these gets a relevance boost.
     #[serde(default)]
@@ -64,6 +73,7 @@ impl MemoryEntry {
         text: String,
         kind: String,
         tags: Vec<String>,
+        keywords: Vec<String>,
         scope_paths: Vec<String>,
         now: String,
     ) -> Self {
@@ -74,6 +84,7 @@ impl MemoryEntry {
             text,
             kind,
             tags,
+            keywords,
             scope_paths,
             content_hash,
             created_at: now.clone(),
@@ -84,13 +95,33 @@ impl MemoryEntry {
         }
     }
 
-    /// The text used for similarity: body plus tags (tags carry intent that may
-    /// not appear verbatim in the body).
+    /// Plain-text index for Jaccard similarity: body + tags + keywords.
     pub fn index_text(&self) -> String {
-        if self.tags.is_empty() {
-            self.text.clone()
-        } else {
-            format!("{} {}", self.text, self.tags.join(" "))
+        let mut parts = vec![self.text.clone()];
+        if !self.tags.is_empty() {
+            parts.push(self.tags.join(" "));
+        }
+        if !self.keywords.is_empty() {
+            parts.push(self.keywords.join(" "));
+        }
+        parts.join(" ")
+    }
+
+    /// Weighted tokens for `Corpus::build_weighted_tokens`. Body + tags are
+    /// tokenized at default weight; keywords are added with weight 2.0
+    /// (doc-side TF boost), replacing the old 2x-concatenation hack.
+    pub fn index_weighted_tokens(&self) -> Vec<lexsim::WeightedToken> {
+        let mut base = vec![self.text.clone()];
+        if !self.tags.is_empty() {
+            base.push(self.tags.join(" "));
+        }
+        let mut tokens = lexsim::tokenize_weighted(&base.join(" "));
+        for kw in &self.keywords {
+            for mut wt in lexsim::tokenize_weighted(kw) {
+                wt.weight *= 2.0;
+                tokens.push(wt);
+            }
         }
+        tokens
     }
 }

package/src/storage/sessions.rs

@@ -384,18 +384,37 @@ pub fn read_latest_closed_session(sessions_dir: &Path) -> Result<Option<SessionD
     Ok(sessions.into_iter().last())
 }
 
-fn apply_session_updates(data: &mut SessionData, updates: &SessionData) {
+fn apply_session_updates(
+    data: &mut SessionData,
+    updates: &SessionData,
+    provided_keys: Option<&Value>,
+) {
     data.summary = updates.summary.clone();
     data.ended_at = updates.ended_at.clone();
     data.branch = updates.branch.clone();
     data.commit = updates.commit.clone();
     data.dirty_files = updates.dirty_files.clone();
-    data.decisions = updates.decisions.clone();
-    data.blockers = updates.blockers.clone();
-    data.checklist = updates.checklist.clone();
-    data.handoff_notes = updates.handoff_notes.clone();
-    data.references = updates.references.clone();
-    data.context_pointers = updates.context_pointers.clone();
+
+    let was_provided = |key: &str| provided_keys.and_then(|v| v.get(key)).is_some();
+
+    if was_provided("decisions") {
+        data.decisions = updates.decisions.clone();
+    }
+    if was_provided("blockers") {
+        data.blockers = updates.blockers.clone();
+    }
+    if was_provided("checklist") {
+        data.checklist = updates.checklist.clone();
+    }
+    if was_provided("handoff_notes") {
+        data.handoff_notes = updates.handoff_notes.clone();
+    }
+    if was_provided("references") {
+        data.references = updates.references.clone();
+    }
+    if was_provided("context_pointers") {
+        data.context_pointers = updates.context_pointers.clone();
+    }
     if updates.environment.is_some() {
         data.environment = updates.environment.clone();
     }
@@ -405,7 +424,7 @@ fn apply_session_updates(data: &mut SessionData, updates: &SessionData) {
     if updates.label.is_some() {
         data.label = updates.label.clone();
     }
-    if !updates.related_task_ids.is_empty() {
+    if was_provided("related_task_ids") && !updates.related_task_ids.is_empty() {
         data.related_task_ids = updates.related_task_ids.clone();
     }
 }
@@ -415,6 +434,7 @@ fn find_and_update_active_session(
     session_id: &str,
     updates: &SessionData,
     transition_to: Option<&str>,
+    provided_keys: Option<&Value>,
 ) -> Result<Option<PathBuf>> {
     let suffix = ".active.json";
 
@@ -464,7 +484,7 @@ fn find_and_update_active_session(
         let mut data: SessionData = serde_json::from_str(&content)
             .with_context(|| format!("Failed to parse session: {}", path.display()))?;
 
-        apply_session_updates(&mut data, updates);
+        apply_session_updates(&mut data, updates, provided_keys);
 
         let updated_content =
             serde_json::to_string_pretty(&data).context("Failed to serialize session")?;
@@ -495,16 +515,24 @@ pub fn update_and_close_active_session(
     sessions_dir: &Path,
     session_id: &str,
     updates: &SessionData,
+    provided_keys: Option<&Value>,
 ) -> Result<Option<PathBuf>> {
-    find_and_update_active_session(sessions_dir, session_id, updates, Some("closed"))
+    find_and_update_active_session(
+        sessions_dir,
+        session_id,
+        updates,
+        Some("closed"),
+        provided_keys,
+    )
 }
 
 pub fn update_active_session(
     sessions_dir: &Path,
     session_id: &str,
     updates: &SessionData,
+    provided_keys: Option<&Value>,
 ) -> Result<Option<PathBuf>> {
-    find_and_update_active_session(sessions_dir, session_id, updates, None)
+    find_and_update_active_session(sessions_dir, session_id, updates, None, provided_keys)
 }
 
 pub fn read_session_by_id(sessions_dir: &Path, session_id: &str) -> Result<Option<SessionData>> {