kardo_core/llm/

engine.rs

//! Three-tier document classification: rules -> embeddings -> LLM.
//!
//! Hierarchical taxonomy: 7 categories + subcategories.
//! Uses Longest-Prefix-Match (LPM) for path rules with word-boundary matching.
//! For now, implements rules tier + LLM tier (embeddings is future work).

use super::ollama::OllamaClient;
use super::{GenerateRequest, LlmBackend, LlmError};
use serde::{Deserialize, Serialize};

/// Safely truncate a string to at most `max_bytes` bytes without splitting a
/// multi-byte UTF-8 character.
fn safe_truncate(s: &str, max_bytes: usize) -> &str {
    if s.len() <= max_bytes {
        return s;
    }
    let mut end = max_bytes;
    while end > 0 && !s.is_char_boundary(end) {
        end -= 1;
    }
    &s[..end]
}

/// Valid top-level categories.
const VALID_CATEGORIES: &[&str] = &[
    "product", "research", "technical", "design", "decisions", "guides", "unknown",
];

/// Validate that a category is known.
fn is_valid_category(cat: &str) -> bool {
    VALID_CATEGORIES.contains(&cat)
}

/// Validate that a subcategory belongs to the given category.
fn is_valid_subcategory(category: &str, subcategory: &str) -> bool {
    let valid = match category {
        "product" => &["prd", "roadmap", "brief"][..],
        "research" => &["customer-interviews", "competitive-analysis", "user-research", "market-research"][..],
        "technical" => &["api-docs", "architecture", "spec", "code", "config"][..],
        "design" => &["design-system", "ui-specs", "mockups"][..],
        "decisions" => &["adr", "rfc", "meetings"][..],
        "guides" => &["readme", "onboarding", "how-to", "code-instructions"][..],
        _ => return false,
    };
    valid.contains(&subcategory)
}

/// Document classification result.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct Classification {
    pub doc_type: String,
    pub subcategory: Option<String>,
    pub confidence: f64,
    pub source: ClassificationSource,
}

/// How the classification was determined.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
pub enum ClassificationSource {
    /// Matched a filename/path rule
    Rule,
    /// Classified by LLM
    Llm,
    /// Default fallback
    Fallback,
}

impl std::fmt::Display for ClassificationSource {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        match self {
            ClassificationSource::Rule => write!(f, "rule"),
            ClassificationSource::Llm => write!(f, "llm"),
            ClassificationSource::Fallback => write!(f, "fallback"),
        }
    }
}

// ── LPM Path Rules ──

/// A path-prefix rule for Longest-Prefix-Match classification.
struct PathRule {
    prefix: &'static str,
    doc_type: &'static str,
    subcategory: &'static str,
    confidence: f64,
}

/// Path rules sorted by prefix length (longest first) for LPM behavior.
/// First matching rule wins — more specific paths always take priority.
///
/// INVARIANT: Rules MUST be sorted by descending prefix length.
/// The `test_path_rules_sorted` test verifies this at compile-check time.
const PATH_RULES: &[PathRule] = &[
    // .claude/ subtree — most specific first
    PathRule { prefix: ".claude/research/calibration/dataset/", doc_type: "technical", subcategory: "config", confidence: 0.70 },
    PathRule { prefix: ".claude/research/competitors/", doc_type: "research", subcategory: "competitive-analysis", confidence: 0.80 },
    PathRule { prefix: ".claude/research/kardo-pmf/", doc_type: "research", subcategory: "market-research", confidence: 0.80 },
    PathRule { prefix: ".claude/research/experiments/", doc_type: "research", subcategory: "user-research", confidence: 0.75 },
    PathRule { prefix: ".claude/research/", doc_type: "research", subcategory: "market-research", confidence: 0.75 },
    PathRule { prefix: ".claude/plans/", doc_type: "product", subcategory: "roadmap", confidence: 0.75 },
    PathRule { prefix: ".claude/analysis/", doc_type: "research", subcategory: "market-research", confidence: 0.75 },
    PathRule { prefix: ".claude/agents/", doc_type: "guides", subcategory: "code-instructions", confidence: 0.80 },
    PathRule { prefix: ".claude/skills/", doc_type: "guides", subcategory: "code-instructions", confidence: 0.80 },
    PathRule { prefix: ".claude/commands/", doc_type: "guides", subcategory: "code-instructions", confidence: 0.80 },
    PathRule { prefix: ".claude/hooks/", doc_type: "technical", subcategory: "config", confidence: 0.80 },
    PathRule { prefix: ".claude/memory/", doc_type: "guides", subcategory: "how-to", confidence: 0.70 },
    PathRule { prefix: ".claude/discovery/", doc_type: "research", subcategory: "market-research", confidence: 0.75 },
    PathRule { prefix: ".claude/summaries/", doc_type: "guides", subcategory: "how-to", confidence: 0.70 },
    PathRule { prefix: ".claude/knowledge/", doc_type: "guides", subcategory: "how-to", confidence: 0.70 },
    PathRule { prefix: ".claude/components-registry/", doc_type: "design", subcategory: "design-system", confidence: 0.75 },
    PathRule { prefix: ".claude/training-data/", doc_type: "technical", subcategory: "config", confidence: 0.75 },
    // .claude/ catch-all — LOW confidence triggers LLM
    PathRule { prefix: ".claude/", doc_type: "guides", subcategory: "code-instructions", confidence: 0.50 },

    // docs/ subtree
    PathRule { prefix: "docs/plans/", doc_type: "product", subcategory: "roadmap", confidence: 0.75 },
    PathRule { prefix: "docs/reviews/", doc_type: "decisions", subcategory: "meetings", confidence: 0.70 },
    PathRule { prefix: "docs/drafts/", doc_type: "guides", subcategory: "how-to", confidence: 0.50 },
    PathRule { prefix: "docs/layers/", doc_type: "product", subcategory: "brief", confidence: 0.60 },
    // docs/ catch-all — LOW confidence triggers LLM
    PathRule { prefix: "docs/", doc_type: "guides", subcategory: "how-to", confidence: 0.50 },
    PathRule { prefix: "doc/", doc_type: "guides", subcategory: "how-to", confidence: 0.50 },

    // AI_First_Idea/ subtree
    PathRule { prefix: "ai_first_idea/research/", doc_type: "research", subcategory: "market-research", confidence: 0.75 },
    PathRule { prefix: "ai_first_idea/articles/", doc_type: "guides", subcategory: "how-to", confidence: 0.70 },
    PathRule { prefix: "ai_first_idea/", doc_type: "research", subcategory: "market-research", confidence: 0.55 },

    // Habr_plan/ subtree
    PathRule { prefix: "habr_plan/pipeline/research/", doc_type: "research", subcategory: "market-research", confidence: 0.75 },
    PathRule { prefix: "habr_plan/pipeline/prompts/", doc_type: "guides", subcategory: "code-instructions", confidence: 0.75 },
    PathRule { prefix: "habr_plan/pipeline/articles/", doc_type: "guides", subcategory: "how-to", confidence: 0.70 },
    PathRule { prefix: "habr_plan/articles/", doc_type: "guides", subcategory: "how-to", confidence: 0.70 },
    PathRule { prefix: "habr_plan/pipeline/", doc_type: "guides", subcategory: "how-to", confidence: 0.60 },
    PathRule { prefix: "habr_plan/", doc_type: "guides", subcategory: "how-to", confidence: 0.55 },

    // .github/ subtree
    PathRule { prefix: ".github/workflows/", doc_type: "technical", subcategory: "config", confidence: 0.85 },
    PathRule { prefix: ".github/", doc_type: "technical", subcategory: "config", confidence: 0.75 },

    // Generic path patterns (work for any project)
    PathRule { prefix: "research/", doc_type: "research", subcategory: "market-research", confidence: 0.70 },
    PathRule { prefix: "articles/", doc_type: "guides", subcategory: "how-to", confidence: 0.65 },
    PathRule { prefix: "plans/", doc_type: "product", subcategory: "roadmap", confidence: 0.70 },

    // kardo/ monorepo catch-all — catch internal files (build notes, specs)
    PathRule { prefix: "kardo/", doc_type: "technical", subcategory: "code", confidence: 0.50 },
];

/// Check if a path contains a word (not just a substring).
/// Matches "spec" but NOT "aspect", "inspect", "specification".
/// Word boundaries are: start/end of string, non-alphanumeric characters.
fn path_contains_word(path: &str, word: &str) -> bool {
    for (i, _) in path.match_indices(word) {
        let before_ok = i == 0 || !path.as_bytes()[i - 1].is_ascii_alphanumeric();
        let after_idx = i + word.len();
        let after_ok = after_idx >= path.len() || !path.as_bytes()[after_idx].is_ascii_alphanumeric();
        if before_ok && after_ok {
            return true;
        }
    }
    false
}

/// Synchronous rule-based classification. No LLM, no async.
/// Use this from CLI or anywhere you don't have a tokio runtime.
///
/// Pipeline: extension → filename → filename-prefix (path-aware) → LPM path → contains → fallback
pub fn classify_by_rules(relative_path: &str) -> Classification {
    let path_lower = relative_path.to_lowercase();
    let filename = relative_path
        .rsplit('/')
        .next()
        .unwrap_or(relative_path)
        .to_lowercase();

    // Tier 1: File extension (code/config) — highest confidence
    if let Some(ext_result) = classify_by_extension(&filename) {
        return ext_result;
    }

    // Tier 2: Exact filename match
    if let Some(c) = classify_filename(&filename) {
        return c;
    }

    // Tier 3: Filename prefix (path-aware — skips inside .claude/agents/ etc.)
    if let Some(c) = classify_filename_prefix(&filename, &path_lower) {
        return c;
    }

    // Tier 4: Longest-Prefix-Match path rules
    if let Some(c) = classify_path_lpm(&path_lower) {
        return c;
    }

    // Tier 5: Word-boundary contains patterns (low confidence)
    if let Some(c) = classify_path_contains(&path_lower) {
        return c;
    }

    // Fallback
    Classification {
        doc_type: "unknown".to_string(),
        subcategory: None,
        confidence: 0.10,
        source: ClassificationSource::Fallback,
    }
}

/// Classify by file extension (code and config files).
fn classify_by_extension(filename: &str) -> Option<Classification> {
    let ext = filename.rsplit('.').next()?;
    let (doc_type, subcategory) = match ext {
        "rs" | "py" | "ts" | "tsx" | "js" | "jsx" | "go" | "java" | "c" | "cpp" | "h" | "rb"
        | "swift" | "kt" | "cs" | "php" | "sh" | "bash" | "zsh" => ("technical", "code"),
        "json" | "yaml" | "yml" | "toml" | "ini" | "cfg" | "conf" => ("technical", "config"),
        _ => return None,
    };

    Some(Classification {
        doc_type: doc_type.to_string(),
        subcategory: Some(subcategory.to_string()),
        confidence: 0.95,
        source: ClassificationSource::Rule,
    })
}

/// Classify by exact filename match.
fn classify_filename(filename: &str) -> Option<Classification> {
    let (doc_type, subcategory, confidence) = match filename {
        "readme.md" | "readme.txt" | "readme" | "readme.rst" => ("guides", "readme", 0.95),
        "claude.md" | ".cursorrules" | ".clinerules" | ".windsurfrules" => ("guides", "code-instructions", 0.95),
        "agents.md" => ("guides", "code-instructions", 0.95),
        "changelog.md" | "changes.md" | "history.md" => ("decisions", "meetings", 0.90),
        "license" | "license.md" | "license.txt" | "copying" => ("guides", "readme", 0.95),
        "contributing.md" | "contribute.md" => ("guides", "onboarding", 0.90),
        "code_of_conduct.md" => ("guides", "onboarding", 0.90),
        "security.md" | "security.txt" => ("technical", "spec", 0.90),
        "ui_decisions.md" | "ui-decisions.md" => ("design", "ui-specs", 0.90),
        "product_strategy.md" | "product-strategy.md" => ("product", "brief", 0.85),
        "todo.md" | "todo.txt" => ("product", "roadmap", 0.85),
        "makefile" | "justfile" | "taskfile.yml" => ("technical", "config", 0.90),
        "dockerfile" | "docker-compose.yml" | "docker-compose.yaml" => ("technical", "config", 0.90),
        ".gitignore" | ".gitattributes" => ("technical", "config", 0.90),
        ".env.example" | ".env.sample" => ("technical", "config", 0.85),
        _ => return None,
    };

    Some(Classification {
        doc_type: doc_type.to_string(),
        subcategory: Some(subcategory.to_string()),
        confidence,
        source: ClassificationSource::Rule,
    })
}

/// Classify by filename prefix patterns.
/// Path-aware: skips prefix matching inside .claude/agents/, .claude/skills/, .claude/commands/
/// because path rules are more authoritative for those directories.
fn classify_filename_prefix(filename: &str, path_lower: &str) -> Option<Classification> {
    // Skip prefix matching inside known agent/skill/command directories
    if path_lower.starts_with(".claude/agents/")
        || path_lower.starts_with(".claude/skills/")
        || path_lower.starts_with(".claude/commands/")
    {
        return None;
    }

    // AI_First_Idea/ timestamp files: "YYYY-MM-DD HH.MM.SS.md" are voice transcripts
    if path_lower.starts_with("ai_first_idea/") {
        // filename starts with 4 digits (year) → voice transcript
        let starts_with_year = filename
            .chars()
            .take(4)
            .all(|c| c.is_ascii_digit());
        if starts_with_year {
            return Some(Classification {
                doc_type: "research".to_string(),
                subcategory: Some("customer-interviews".to_string()),
                confidence: 0.80,
                source: ClassificationSource::Rule,
            });
        }
    }

    let (doc_type, subcategory, confidence) = if filename.starts_with("prd") {
        ("product", "prd", 0.95)
    } else if filename.starts_with("adr-") || filename.starts_with("adr_") {
        ("decisions", "adr", 0.95)
    } else if filename.starts_with("rfc-") || filename.starts_with("rfc_") {
        ("decisions", "rfc", 0.95)
    } else if filename.starts_with("roadmap") {
        ("product", "roadmap", 0.90)
    } else if filename.starts_with("interview") || filename.starts_with("transcript") {
        ("research", "customer-interviews", 0.90)
    } else if filename.starts_with("competitive") {
        ("research", "competitive-analysis", 0.90)
    } else if filename.starts_with("architecture") {
        ("technical", "architecture", 0.90)
    } else if filename.starts_with("api-") || filename.starts_with("api_") {
        ("technical", "api-docs", 0.90)
    } else if filename.starts_with("meeting-notes") || filename.starts_with("meeting_notes") {
        ("decisions", "meetings", 0.85)
    } else if filename.starts_with("design-system") || filename.starts_with("design_system") {
        ("design", "design-system", 0.90)
    } else {
        return None;
    };

    Some(Classification {
        doc_type: doc_type.to_string(),
        subcategory: Some(subcategory.to_string()),
        confidence,
        source: ClassificationSource::Rule,
    })
}

/// Classify by Longest-Prefix-Match path rules.
/// Rules are sorted by prefix length (longest first) — first match wins.
/// After matching .claude/research/ or .claude/research/kardo-pmf/, refines subcategory
/// by checking filename word patterns.
fn classify_path_lpm(path_lower: &str) -> Option<Classification> {
    for rule in PATH_RULES {
        if path_lower.starts_with(rule.prefix) {
            let mut result = Classification {
                doc_type: rule.doc_type.to_string(),
                subcategory: Some(rule.subcategory.to_string()),
                confidence: rule.confidence,
                source: ClassificationSource::Rule,
            };

            // Refine subcategory for .claude/research/ files (but not in /competitors/ — already correct)
            if rule.prefix == ".claude/research/"
                || rule.prefix == ".claude/research/kardo-pmf/"
            {
                if let Some(refined) = refine_research_subcategory(path_lower) {
                    result.doc_type = refined.0.to_string();
                    result.subcategory = Some(refined.1.to_string());
                    result.confidence = refined.2;
                }
            }

            // Refine docs/ catch-all: check filename for product document keywords
            if rule.prefix == "docs/" || rule.prefix == "doc/" {
                if let Some(refined) = refine_docs_subcategory(path_lower) {
                    result.doc_type = refined.0.to_string();
                    result.subcategory = Some(refined.1.to_string());
                    result.confidence = refined.2;
                }
            }

            return Some(result);
        }
    }
    None
}

/// Refine subcategory for research files by checking filename words.
/// Returns (doc_type, subcategory, confidence) override if filename contains known keywords.
fn refine_research_subcategory(path_lower: &str) -> Option<(&'static str, &'static str, f64)> {
    // Check for "prd" word in filename → product/prd
    if path_contains_word(path_lower, "prd") {
        return Some(("product", "prd", 0.80));
    }
    // Check for interview/custdev → customer-interviews
    if path_contains_word(path_lower, "interview") || path_contains_word(path_lower, "custdev") {
        return Some(("research", "customer-interviews", 0.80));
    }
    // Check for competitive/competitor(s) → competitive-analysis
    if path_contains_word(path_lower, "competitive")
        || path_contains_word(path_lower, "competitor")
        || path_contains_word(path_lower, "competitors")
    {
        return Some(("research", "competitive-analysis", 0.80));
    }
    // Check for customer/persona/jtbd → user-research
    if path_contains_word(path_lower, "customer")
        || path_contains_word(path_lower, "persona")
        || path_contains_word(path_lower, "jtbd")
    {
        return Some(("research", "user-research", 0.75));
    }
    // Check for ux → user-research
    if path_contains_word(path_lower, "ux") {
        return Some(("research", "user-research", 0.70));
    }
    // Check for architecture/blueprint → technical/architecture
    if path_contains_word(path_lower, "architecture")
        || path_contains_word(path_lower, "blueprint")
    {
        return Some(("technical", "architecture", 0.75));
    }
    // Check for "implementation" + "plan" together → product/roadmap
    if path_contains_word(path_lower, "implementation")
        && path_contains_word(path_lower, "plan")
    {
        return Some(("product", "roadmap", 0.75));
    }
    None
}

/// Refine subcategory for docs/ catch-all files by checking filename keywords.
/// Returns (doc_type, subcategory, confidence) override if filename contains known patterns.
fn refine_docs_subcategory(path_lower: &str) -> Option<(&'static str, &'static str, f64)> {
    // "prd" or "requirements" word in filename → product/prd
    if path_contains_word(path_lower, "prd") || path_contains_word(path_lower, "requirements") {
        return Some(("product", "prd", 0.65));
    }
    None
}

/// Classify by word-boundary-aware substring patterns.
/// Lower confidence — these are hints, not definitive matches.
fn classify_path_contains(path_lower: &str) -> Option<Classification> {
    let (doc_type, subcategory, confidence) = if path_contains_word(path_lower, "spec") || path_contains_word(path_lower, "requirement") {
        ("product", "prd", 0.55)
    } else if path_contains_word(path_lower, "api") && path_lower.ends_with(".md") {
        ("technical", "api-docs", 0.55)
    } else if path_contains_word(path_lower, "design") {
        ("design", "design-system", 0.55)
    } else if path_contains_word(path_lower, "architecture") {
        ("technical", "architecture", 0.55)
    } else if path_contains_word(path_lower, "test") {
        ("technical", "spec", 0.50)
    } else {
        return None;
    };

    Some(Classification {
        doc_type: doc_type.to_string(),
        subcategory: Some(subcategory.to_string()),
        confidence,
        source: ClassificationSource::Rule,
    })
}

/// The classification engine.
pub struct ClassificationEngine {
    #[allow(dead_code)]
    backend: LlmBackend,
    ollama: Option<OllamaClient>,
}

impl ClassificationEngine {
    pub fn new(backend: LlmBackend) -> Self {
        let ollama = match &backend {
            LlmBackend::Ollama => Some(OllamaClient::new()),
            LlmBackend::Disabled => None,
        };

        Self { backend, ollama }
    }

    /// Classify a document based on its path and content.
    /// Uses three-tier approach: rules first, then LLM if confidence <= 0.70.
    /// LLM "unknown" never overrides a non-unknown rule result.
    pub async fn classify(&self, relative_path: &str, content: &str) -> Classification {
        // Tier 1: Rule-based classification
        let rule_result = classify_by_rules(relative_path);

        // If confidence > 0.70, rules are sufficient
        if rule_result.confidence > 0.70 {
            return rule_result;
        }

        // Tier 2: LLM-based classification (if available and file is markdown)
        if let Some(ollama) = &self.ollama {
            if relative_path.to_lowercase().ends_with(".md")
                || relative_path.to_lowercase().ends_with(".txt")
                || relative_path.to_lowercase().ends_with(".rst")
            {
                if let Ok(llm_result) =
                    self.classify_by_llm(ollama, relative_path, content).await
                {
                    // LLM "unknown" should NOT override a non-unknown rule result.
                    // Rules found something (even low confidence) — keep it unless
                    // LLM provides a better (non-unknown) answer.
                    if llm_result.doc_type == "unknown" && rule_result.doc_type != "unknown" {
                        return rule_result;
                    }
                    return llm_result;
                }
            }
        }

        // Return rule result as-is (even low confidence) or fallback
        rule_result
    }

    /// LLM-based classification using structured JSON output.
    async fn classify_by_llm(
        &self,
        ollama: &OllamaClient,
        relative_path: &str,
        content: &str,
    ) -> Result<Classification, LlmError> {
        // Truncate content to ~500 chars for classification
        let truncated = safe_truncate(content, 500);

        let prompt = format!(
            r#"Classify this document. Reply with ONLY a JSON object, no other text.

Categories (pick one):
- product (subcategories: prd, roadmap, brief)
- research (subcategories: customer-interviews, competitive-analysis, user-research, market-research)
- technical (subcategories: api-docs, architecture, spec, code, config)
- design (subcategories: design-system, ui-specs, mockups)
- decisions (subcategories: adr, rfc, meetings)
- guides (subcategories: readme, onboarding, how-to, code-instructions)
- unknown (no subcategory)

File: {path}
Content: "{content}"

JSON:"#,
            path = relative_path,
            content = truncated.replace('"', "'"),
        );

        let response = ollama
            .generate(&GenerateRequest {
                prompt,
                max_tokens: 80,
                temperature: 0.1,
            })
            .await?;

        // Parse structured JSON from response
        parse_llm_response(&response.text)
    }
}

/// Parse LLM response into a Classification. Expects JSON with category, subcategory, confidence.
fn parse_llm_response(text: &str) -> Result<Classification, LlmError> {
    // Try to extract JSON object from response
    let json_str = extract_json(text)
        .ok_or_else(|| LlmError::Parse("No JSON found in response".to_string()))?;

    // Parse the JSON
    let parsed: serde_json::Value = serde_json::from_str(&json_str)
        .map_err(|e| LlmError::Parse(format!("JSON parse error: {}", e)))?;

    let category = parsed
        .get("category")
        .and_then(|v| v.as_str())
        .unwrap_or("unknown")
        .to_lowercase();

    let subcategory = parsed
        .get("subcategory")
        .and_then(|v| v.as_str())
        .map(|s| s.to_lowercase());

    let raw_confidence = parsed
        .get("confidence")
        .and_then(|v| v.as_f64())
        .unwrap_or(0.70);

    // Validate category
    let category = if is_valid_category(&category) {
        category
    } else {
        "unknown".to_string()
    };

    // Validate subcategory
    let subcategory = match &subcategory {
        Some(sub) if category != "unknown" && is_valid_subcategory(&category, sub) => {
            Some(sub.clone())
        }
        _ if category == "unknown" => None,
        _ => None,
    };

    // Clamp confidence: 0.60-0.90 for LLM results
    let confidence = if category == "unknown" {
        0.30
    } else {
        raw_confidence.clamp(0.60, 0.90)
    };

    Ok(Classification {
        doc_type: category,
        subcategory,
        confidence,
        source: ClassificationSource::Llm,
    })
}

/// Extract a JSON object `{...}` from a string that may contain surrounding text.
fn extract_json(text: &str) -> Option<String> {
    let start = text.find('{')?;
    let mut depth = 0;
    let mut end = start;

    for (i, ch) in text[start..].char_indices() {
        match ch {
            '{' => depth += 1,
            '}' => {
                depth -= 1;
                if depth == 0 {
                    end = start + i + 1;
                    break;
                }
            }
            _ => {}
        }
    }

    if depth == 0 && end > start {
        Some(text[start..end].to_string())
    } else {
        None
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    // ── PATH_RULES invariant: must be sorted by prefix length (longest first) ──

    #[test]
    fn test_path_rules_sorted_by_prefix_length() {
        for window in PATH_RULES.windows(2) {
            let a = &window[0];
            let b = &window[1];
            // Within a shared prefix group, longer prefixes must come first.
            // Cross-group ordering is fine (e.g., .claude/ group before docs/ group).
            if b.prefix.starts_with(a.prefix) || a.prefix.starts_with(b.prefix) {
                assert!(
                    a.prefix.len() >= b.prefix.len(),
                    "LPM invariant violated: '{}' (len {}) should come after '{}' (len {})",
                    a.prefix, a.prefix.len(), b.prefix, b.prefix.len()
                );
            }
        }
    }

    // ── Word boundary tests ──

    #[test]
    fn test_path_contains_word_basic() {
        assert!(path_contains_word("some/spec/file.md", "spec"));
        assert!(path_contains_word("spec/file.md", "spec"));
        assert!(path_contains_word("dir/spec.md", "spec"));
        assert!(path_contains_word("spec", "spec"));
    }

    #[test]
    fn test_path_contains_word_rejects_substring() {
        assert!(!path_contains_word("aspect-1/file.md", "spec"));
        assert!(!path_contains_word("inspect/file.md", "spec"));
        assert!(!path_contains_word("specification.md", "spec"));
        assert!(!path_contains_word("retrospective.md", "spec"));
    }

    #[test]
    fn test_path_contains_word_boundaries() {
        assert!(path_contains_word("path/spec-v2.md", "spec"));
        assert!(path_contains_word("path/spec_v2.md", "spec"));
        assert!(path_contains_word("path/spec.md", "spec"));
        assert!(path_contains_word("api/v2/docs.md", "api"));
        assert!(!path_contains_word("rapid/file.md", "api"));
    }

    // ── Rule-based tests ──

    #[test]
    fn test_rule_readme() {
        let result = classify_by_rules("README.md");
        assert_eq!(result.doc_type, "guides");
        assert_eq!(result.subcategory.as_deref(), Some("readme"));
        assert_eq!(result.source, ClassificationSource::Rule);
        assert!(result.confidence >= 0.95);
    }

    #[test]
    fn test_rule_claude_md() {
        let result = classify_by_rules("CLAUDE.md");
        assert_eq!(result.doc_type, "guides");
        assert_eq!(result.subcategory.as_deref(), Some("code-instructions"));
    }

    #[test]
    fn test_rule_docs_directory() {
        let result = classify_by_rules("docs/setup.md");
        assert_eq!(result.doc_type, "guides");
        assert_eq!(result.subcategory.as_deref(), Some("how-to"));
        // Now 0.50 (catch-all) — will trigger LLM
        assert!((result.confidence - 0.50).abs() < 0.01);
    }

    #[test]
    fn test_rule_github_workflow() {
        let result = classify_by_rules(".github/workflows/ci.yml");
        assert_eq!(result.doc_type, "technical");
        assert_eq!(result.subcategory.as_deref(), Some("config"));
        assert!(result.confidence >= 0.85);
    }

    #[test]
    fn test_rule_license() {
        let result = classify_by_rules("LICENSE");
        assert_eq!(result.doc_type, "guides");
        assert_eq!(result.subcategory.as_deref(), Some("readme"));
    }

    #[test]
    fn test_fallback_unknown_file() {
        let result = classify_by_rules("random-notes.md");
        assert_eq!(result.doc_type, "unknown");
        assert_eq!(result.subcategory, None);
        assert_eq!(result.source, ClassificationSource::Fallback);
        assert!(result.confidence <= 0.10);
    }

    #[test]
    fn test_rule_changelog() {
        let result = classify_by_rules("CHANGELOG.md");
        assert_eq!(result.doc_type, "decisions");
        assert_eq!(result.subcategory.as_deref(), Some("meetings"));
    }

    #[test]
    fn test_rule_dockerfile() {
        let result = classify_by_rules("Dockerfile");
        assert_eq!(result.doc_type, "technical");
        assert_eq!(result.subcategory.as_deref(), Some("config"));
    }

    #[test]
    fn test_rule_architecture_in_docs() {
        // filename prefix "architecture" matches (docs path doesn't block prefix)
        let result = classify_by_rules("docs/architecture-overview.md");
        assert_eq!(result.doc_type, "technical");
        assert_eq!(result.subcategory.as_deref(), Some("architecture"));
        assert_eq!(result.source, ClassificationSource::Rule);
    }

    #[test]
    fn test_rule_cursorrules() {
        let result = classify_by_rules(".cursorrules");
        assert_eq!(result.doc_type, "guides");
        assert_eq!(result.subcategory.as_deref(), Some("code-instructions"));
    }

    // ── New taxonomy tests ──

    #[test]
    fn test_rule_prd() {
        let result = classify_by_rules("prd-v2.md");
        assert_eq!(result.doc_type, "product");
        assert_eq!(result.subcategory.as_deref(), Some("prd"));
        assert!(result.confidence >= 0.95);
    }

    #[test]
    fn test_rule_adr() {
        let result = classify_by_rules("adr-001-use-sqlite.md");
        assert_eq!(result.doc_type, "decisions");
        assert_eq!(result.subcategory.as_deref(), Some("adr"));
    }

    #[test]
    fn test_rule_rfc() {
        let result = classify_by_rules("rfc-classification-v2.md");
        assert_eq!(result.doc_type, "decisions");
        assert_eq!(result.subcategory.as_deref(), Some("rfc"));
    }

    #[test]
    fn test_rule_interview() {
        let result = classify_by_rules("interview-user-01.md");
        assert_eq!(result.doc_type, "research");
        assert_eq!(result.subcategory.as_deref(), Some("customer-interviews"));
    }

    #[test]
    fn test_rule_rust_code() {
        let result = classify_by_rules("src/main.rs");
        assert_eq!(result.doc_type, "technical");
        assert_eq!(result.subcategory.as_deref(), Some("code"));
        assert!(result.confidence >= 0.95);
    }

    #[test]
    fn test_rule_config_file() {
        let result = classify_by_rules("config/settings.json");
        assert_eq!(result.doc_type, "technical");
        assert_eq!(result.subcategory.as_deref(), Some("config"));
    }

    #[test]
    fn test_rule_claude_directory() {
        // .claude/instructions — no file extension, so falls through to LPM
        let result = classify_by_rules(".claude/instructions");
        assert_eq!(result.doc_type, "guides");
        assert_eq!(result.subcategory.as_deref(), Some("code-instructions"));
    }

    #[test]
    fn test_rule_roadmap() {
        let result = classify_by_rules("roadmap-2026.md");
        assert_eq!(result.doc_type, "product");
        assert_eq!(result.subcategory.as_deref(), Some("roadmap"));
    }

    #[test]
    fn test_rule_competitive_analysis() {
        let result = classify_by_rules("competitive-analysis.md");
        assert_eq!(result.doc_type, "research");
        assert_eq!(result.subcategory.as_deref(), Some("competitive-analysis"));
    }

    #[test]
    fn test_rule_api_docs() {
        let result = classify_by_rules("api-reference.md");
        assert_eq!(result.doc_type, "technical");
        assert_eq!(result.subcategory.as_deref(), Some("api-docs"));
    }

    // ── LPM-specific tests ──

    #[test]
    fn test_lpm_claude_research() {
        let result = classify_by_rules(".claude/research/2026-01-19-kardo-market-research.md");
        assert_eq!(result.doc_type, "research");
        assert_eq!(result.subcategory.as_deref(), Some("market-research"));
        assert!((result.confidence - 0.75).abs() < 0.01);
    }

    #[test]
    fn test_lpm_claude_research_competitors() {
        let result = classify_by_rules(".claude/research/competitors/kardo-competitors.md");
        assert_eq!(result.doc_type, "research");
        assert_eq!(result.subcategory.as_deref(), Some("competitive-analysis"));
        assert!((result.confidence - 0.80).abs() < 0.01);
    }

    #[test]
    fn test_lpm_claude_plans() {
        let result = classify_by_rules(".claude/plans/phase-6-fine-tuning-qwen3-4b.md");
        assert_eq!(result.doc_type, "product");
        assert_eq!(result.subcategory.as_deref(), Some("roadmap"));
        assert!((result.confidence - 0.75).abs() < 0.01);
    }

    #[test]
    fn test_lpm_claude_analysis() {
        let result = classify_by_rules(".claude/analysis/recommendations-final.md");
        assert_eq!(result.doc_type, "research");
        assert_eq!(result.subcategory.as_deref(), Some("market-research"));
    }

    #[test]
    fn test_lpm_claude_agents_no_prefix_collision() {
        // api-validator.md inside .claude/agents/ should NOT match "api-" prefix
        let result = classify_by_rules(".claude/agents/api-validator.md");
        assert_eq!(result.doc_type, "guides");
        assert_eq!(result.subcategory.as_deref(), Some("code-instructions"));
        assert!((result.confidence - 0.80).abs() < 0.01);
    }

    #[test]
    fn test_lpm_claude_agents_competitive_no_prefix_collision() {
        // competitive-research.md inside .claude/agents/ should NOT match "competitive" prefix
        let result = classify_by_rules(".claude/agents/competitive-research.md");
        assert_eq!(result.doc_type, "guides");
        assert_eq!(result.subcategory.as_deref(), Some("code-instructions"));
    }

    #[test]
    fn test_lpm_claude_catch_all_low_confidence() {
        // Generic .claude/ file — should get LOW confidence (0.50)
        let result = classify_by_rules(".claude/OPEN_QUESTIONS.md");
        assert_eq!(result.doc_type, "guides");
        assert_eq!(result.subcategory.as_deref(), Some("code-instructions"));
        assert!((result.confidence - 0.50).abs() < 0.01);
    }

    #[test]
    fn test_lpm_docs_plans() {
        let result = classify_by_rules("docs/plans/IDEAS.md");
        assert_eq!(result.doc_type, "product");
        assert_eq!(result.subcategory.as_deref(), Some("roadmap"));
        assert!((result.confidence - 0.75).abs() < 0.01);
    }

    #[test]
    fn test_lpm_docs_catch_all_low_confidence() {
        // docs/MVP_PRD.md now correctly classified as product/prd via "prd" word check
        let result = classify_by_rules("docs/MVP_PRD.md");
        assert_eq!(result.doc_type, "product");
        assert_eq!(result.subcategory.as_deref(), Some("prd"));
    }

    #[test]
    fn test_lpm_ai_first_idea_research() {
        let result = classify_by_rules("AI_First_Idea/research/FINAL-RESEARCH-REPORT.md");
        assert_eq!(result.doc_type, "research");
        assert_eq!(result.subcategory.as_deref(), Some("market-research"));
        assert!((result.confidence - 0.75).abs() < 0.01);
    }

    #[test]
    fn test_lpm_ai_first_idea_articles() {
        let result = classify_by_rules("AI_First_Idea/articles/ai-first-manifesto/article-en.md");
        assert_eq!(result.doc_type, "guides");
        assert_eq!(result.subcategory.as_deref(), Some("how-to"));
        assert!((result.confidence - 0.70).abs() < 0.01);
    }

    #[test]
    fn test_lpm_ai_first_idea_root() {
        let result = classify_by_rules("AI_First_Idea/VISION_DOCUMENT.md");
        assert_eq!(result.doc_type, "research");
        assert_eq!(result.subcategory.as_deref(), Some("market-research"));
        assert!((result.confidence - 0.55).abs() < 0.01);
    }

    #[test]
    fn test_lpm_habr_plan_pipeline_research() {
        let result = classify_by_rules("Habr_plan/pipeline/research/habr-content-strategy.md");
        assert_eq!(result.doc_type, "research");
        assert_eq!(result.subcategory.as_deref(), Some("market-research"));
    }

    #[test]
    fn test_lpm_habr_plan_articles() {
        let result = classify_by_rules("Habr_plan/articles/ai-killing-b2b-saas/habr-article.md");
        assert_eq!(result.doc_type, "guides");
        assert_eq!(result.subcategory.as_deref(), Some("how-to"));
    }

    #[test]
    fn test_lpm_habr_plan_root() {
        let result = classify_by_rules("Habr_plan/habr-editor.skill");
        // No extension match, no filename match, no prefix match
        // LPM: "habr_plan/" matches with 0.55
        assert_eq!(result.doc_type, "guides");
        assert_eq!(result.subcategory.as_deref(), Some("how-to"));
    }

    #[test]
    fn test_spec_word_boundary_no_false_positive() {
        // "aspect" should NOT match "spec" word-boundary check
        let result = classify_by_rules("AI_First_Idea/research/aspect-1-saas-decline/raw-findings.md");
        // Should match ai_first_idea/research/ path rule, NOT product/prd via "spec"
        assert_eq!(result.doc_type, "research");
        assert_eq!(result.subcategory.as_deref(), Some("market-research"));
    }

    #[test]
    fn test_spec_word_boundary_true_positive() {
        let result = classify_by_rules("project/spec/requirements.md");
        assert_eq!(result.doc_type, "product");
        assert_eq!(result.subcategory.as_deref(), Some("prd"));
    }

    #[test]
    fn test_lpm_claude_discovery() {
        let result = classify_by_rules(".claude/discovery/2026-02-03-kardo-core-problem.md");
        assert_eq!(result.doc_type, "research");
        assert_eq!(result.subcategory.as_deref(), Some("market-research"));
    }

    #[test]
    fn test_lpm_claude_components_registry() {
        let result = classify_by_rules(".claude/components-registry/docs/shared/animated-tabs.md");
        assert_eq!(result.doc_type, "design");
        assert_eq!(result.subcategory.as_deref(), Some("design-system"));
    }

    #[test]
    fn test_lpm_claude_memory() {
        let result = classify_by_rules(".claude/memory/context.md");
        assert_eq!(result.doc_type, "guides");
        assert_eq!(result.subcategory.as_deref(), Some("how-to"));
    }

    #[test]
    fn test_lpm_github_without_workflow() {
        let result = classify_by_rules(".github/CODEOWNERS");
        assert_eq!(result.doc_type, "technical");
        assert_eq!(result.subcategory.as_deref(), Some("config"));
    }

    // ── New AI format classification tests ──

    #[test]
    fn test_rule_windsurfrules() {
        let result = classify_by_rules(".windsurfrules");
        assert_eq!(result.doc_type, "guides");
        assert_eq!(result.subcategory.as_deref(), Some("code-instructions"));
        assert!(result.confidence >= 0.95);
    }

    #[test]
    fn test_rule_agents_md() {
        let result = classify_by_rules("AGENTS.md");
        assert_eq!(result.doc_type, "guides");
        assert_eq!(result.subcategory.as_deref(), Some("code-instructions"));
        assert!(result.confidence >= 0.95);
    }

    // ── LLM response parsing tests ──

    #[test]
    fn test_parse_llm_valid_json() {
        let response = r#"{"category": "product", "subcategory": "prd", "confidence": 0.85}"#;
        let result = parse_llm_response(response).unwrap();
        assert_eq!(result.doc_type, "product");
        assert_eq!(result.subcategory.as_deref(), Some("prd"));
        assert!((result.confidence - 0.85).abs() < 0.01);
        assert_eq!(result.source, ClassificationSource::Llm);
    }

    #[test]
    fn test_parse_llm_json_with_surrounding_text() {
        let response = r#"Here is the classification:
{"category": "research", "subcategory": "customer-interviews", "confidence": 0.90}
That's my answer."#;
        let result = parse_llm_response(response).unwrap();
        assert_eq!(result.doc_type, "research");
        assert_eq!(
            result.subcategory.as_deref(),
            Some("customer-interviews")
        );
    }

    #[test]
    fn test_parse_llm_unknown_with_low_confidence() {
        let response = r#"{"category": "unknown", "confidence": 0.50}"#;
        let result = parse_llm_response(response).unwrap();
        assert_eq!(result.doc_type, "unknown");
        assert_eq!(result.subcategory, None);
        assert!((result.confidence - 0.30).abs() < 0.01);
    }

    #[test]
    fn test_parse_llm_confidence_clamping() {
        let response = r#"{"category": "product", "subcategory": "prd", "confidence": 0.99}"#;
        let result = parse_llm_response(response).unwrap();
        assert!((result.confidence - 0.90).abs() < 0.01); // clamped to 0.90

        let response2 = r#"{"category": "product", "subcategory": "prd", "confidence": 0.20}"#;
        let result2 = parse_llm_response(response2).unwrap();
        assert!((result2.confidence - 0.60).abs() < 0.01); // clamped to 0.60
    }

    #[test]
    fn test_parse_llm_invalid_category() {
        let response = r#"{"category": "banana", "confidence": 0.80}"#;
        let result = parse_llm_response(response).unwrap();
        assert_eq!(result.doc_type, "unknown");
        assert!((result.confidence - 0.30).abs() < 0.01);
    }

    #[test]
    fn test_parse_llm_invalid_subcategory() {
        let response = r#"{"category": "product", "subcategory": "nonexistent", "confidence": 0.80}"#;
        let result = parse_llm_response(response).unwrap();
        assert_eq!(result.doc_type, "product");
        assert_eq!(result.subcategory, None); // invalid subcategory stripped
    }

    #[test]
    fn test_parse_llm_no_json() {
        let response = "This is just plain text with no JSON";
        let result = parse_llm_response(response);
        assert!(result.is_err());
    }

    #[test]
    fn test_extract_json() {
        assert_eq!(
            extract_json(r#"blah {"a": 1} blah"#),
            Some(r#"{"a": 1}"#.to_string())
        );
        assert_eq!(extract_json("no json here"), None);
        assert_eq!(
            extract_json(r#"{"nested": {"b": 2}}"#),
            Some(r#"{"nested": {"b": 2}}"#.to_string())
        );
    }

    // ── Engine async tests ──

    #[test]
    fn test_engine_high_confidence_skips_llm() {
        let engine = ClassificationEngine::new(LlmBackend::Disabled);
        let rt = tokio::runtime::Runtime::new().unwrap();
        let result = rt.block_on(engine.classify("README.md", "# My Project"));
        assert_eq!(result.doc_type, "guides");
        assert_eq!(result.subcategory.as_deref(), Some("readme"));
        assert_eq!(result.source, ClassificationSource::Rule);
    }

    #[test]
    fn test_engine_low_confidence_returns_rule_when_no_llm() {
        let engine = ClassificationEngine::new(LlmBackend::Disabled);
        let rt = tokio::runtime::Runtime::new().unwrap();
        let result = rt.block_on(engine.classify("random-notes.md", "Some random content"));
        assert_eq!(result.doc_type, "unknown");
        assert_eq!(result.source, ClassificationSource::Fallback);
    }

    // ── Group 1: docs/ catch-all fixes ──

    #[test]
    fn test_docs_mvp_prd_classified_as_product_prd() {
        // docs/MVP_PRD.md — "prd" word in filename → product/prd
        let result = classify_by_rules("docs/MVP_PRD.md");
        assert_eq!(result.doc_type, "product");
        assert_eq!(result.subcategory.as_deref(), Some("prd"));
    }

    #[test]
    fn test_docs_requirements_system_classified_as_product_prd() {
        // docs/REQUIREMENTS_SYSTEM.md — "requirements" word in filename → product/prd
        let result = classify_by_rules("docs/REQUIREMENTS_SYSTEM.md");
        assert_eq!(result.doc_type, "product");
        assert_eq!(result.subcategory.as_deref(), Some("prd"));
    }

    #[test]
    fn test_docs_ui_decisions_classified_as_design_ui_specs() {
        // docs/UI_DECISIONS.md — exact filename match → design/ui-specs
        let result = classify_by_rules("docs/UI_DECISIONS.md");
        assert_eq!(result.doc_type, "design");
        assert_eq!(result.subcategory.as_deref(), Some("ui-specs"));
    }

    #[test]
    fn test_docs_product_strategy_classified_as_product_brief() {
        // docs/PRODUCT_STRATEGY.md — exact filename match → product/brief
        let result = classify_by_rules("docs/PRODUCT_STRATEGY.md");
        assert_eq!(result.doc_type, "product");
        assert_eq!(result.subcategory.as_deref(), Some("brief"));
    }

    // ── Group 2: .claude/research/ date-prefixed files refinement ──

    #[test]
    fn test_research_custdev_interview_classified_correctly() {
        // Date-prefixed custdev interview → research/customer-interviews
        let result = classify_by_rules(".claude/research/2026-01-19-custdev-interview-1.md");
        assert_eq!(result.doc_type, "research");
        assert_eq!(result.subcategory.as_deref(), Some("customer-interviews"));
    }

    #[test]
    fn test_research_competitive_analysis_date_prefix() {
        // Date-prefixed competitive analysis → research/competitive-analysis
        let result = classify_by_rules(
            ".claude/research/2026-01-28-competitive-analysis-docs-visualization.md",
        );
        assert_eq!(result.doc_type, "research");
        assert_eq!(result.subcategory.as_deref(), Some("competitive-analysis"));
    }

    #[test]
    fn test_research_competitive_positioning_date_prefix() {
        let result = classify_by_rules(
            ".claude/research/2026-01-28-competitive-positioning-claude-code-companion.md",
        );
        assert_eq!(result.doc_type, "research");
        assert_eq!(result.subcategory.as_deref(), Some("competitive-analysis"));
    }

    #[test]
    fn test_research_cycle_competitive_moat() {
        let result = classify_by_rules(".claude/research/cycle8-competitive-moat.md");
        assert_eq!(result.doc_type, "research");
        assert_eq!(result.subcategory.as_deref(), Some("competitive-analysis"));
    }

    #[test]
    fn test_research_kardo_pmf_prd_file() {
        // kardo-pmf/ PRD file → product/prd via prd word refinement
        let result = classify_by_rules(
            ".claude/research/kardo-pmf/Feature_Requirements_PRD.md",
        );
        assert_eq!(result.doc_type, "product");
        assert_eq!(result.subcategory.as_deref(), Some("prd"));
    }

    #[test]
    fn test_research_competitors_dir_still_correct() {
        // .claude/research/competitors/ still classified correctly (not refined)
        let result = classify_by_rules(
            ".claude/research/competitors/kardo-competitors.md",
        );
        assert_eq!(result.doc_type, "research");
        assert_eq!(result.subcategory.as_deref(), Some("competitive-analysis"));
        assert!((result.confidence - 0.80).abs() < 0.01);
    }

    // ── Group 3: AI_First_Idea/ timestamp transcripts ──

    #[test]
    fn test_ai_first_idea_timestamp_file_is_customer_interview() {
        // Voice transcript with timestamp filename → research/customer-interviews
        let result = classify_by_rules("AI_First_Idea/2026-02-14 22.19.41.md");
        assert_eq!(result.doc_type, "research");
        assert_eq!(result.subcategory.as_deref(), Some("customer-interviews"));
        assert!((result.confidence - 0.80).abs() < 0.01);
    }

    #[test]
    fn test_ai_first_idea_non_timestamp_not_affected() {
        // Non-timestamp files in AI_First_Idea/ should NOT be affected
        let result = classify_by_rules("AI_First_Idea/VISION_DOCUMENT.md");
        assert_eq!(result.doc_type, "research");
        assert_eq!(result.subcategory.as_deref(), Some("market-research"));
    }

    // ── Group 4: calibration/dataset/ path rule ──

    #[test]
    fn test_calibration_dataset_classified_as_technical_config() {
        let result = classify_by_rules(
            ".claude/research/calibration/dataset/Alive24--CKBoost/claude-md.md",
        );
        assert_eq!(result.doc_type, "technical");
        assert_eq!(result.subcategory.as_deref(), Some("config"));
        assert!((result.confidence - 0.70).abs() < 0.01);
    }

    // ── Group 6: kardo/ catch-all ──

    #[test]
    fn test_kardo_build_notes_classified_as_technical() {
        // kardo/ catch-all — technical/code (0.50) triggers LLM for spec classification
        let result = classify_by_rules(
            "kardo/crates/kardo-desktop/build-notes.md",
        );
        assert_eq!(result.doc_type, "technical");
        assert_eq!(result.subcategory.as_deref(), Some("code"));
        assert!((result.confidence - 0.50).abs() < 0.01);
    }

    // ── Iteration 2: subcategory refinement fixes ──

    #[test]
    fn test_research_competitors_word_refined_to_competitive_analysis() {
        // "competitors" (not "competitive") should also trigger competitive-analysis
        let result = classify_by_rules(".claude/research/2026-01-22-kardo-competitors.md");
        assert_eq!(result.doc_type, "research");
        assert_eq!(result.subcategory.as_deref(), Some("competitive-analysis"));
    }

    #[test]
    fn test_research_customer_voice_refined_to_user_research() {
        // "customer" in filename → user-research
        let result = classify_by_rules(".claude/research/cycle1-customer-voice.md");
        assert_eq!(result.doc_type, "research");
        assert_eq!(result.subcategory.as_deref(), Some("user-research"));
    }

    #[test]
    fn test_research_ux_patterns_refined_to_user_research() {
        // "ux" in filename → user-research
        let result = classify_by_rules(
            ".claude/research/2026-02-03-R5-health-dashboard-ux-patterns.md",
        );
        assert_eq!(result.doc_type, "research");
        assert_eq!(result.subcategory.as_deref(), Some("user-research"));
    }

    #[test]
    fn test_research_persona_refined_to_user_research() {
        // "persona" in filename → user-research
        let result = classify_by_rules(".claude/research/persona-analysis.md");
        assert_eq!(result.doc_type, "research");
        assert_eq!(result.subcategory.as_deref(), Some("user-research"));
    }

    #[test]
    fn test_research_market_still_default() {
        // Files without special keywords remain market-research
        let result = classify_by_rules(
            ".claude/research/2026-01-19-kardo-market-research.md",
        );
        assert_eq!(result.doc_type, "research");
        assert_eq!(result.subcategory.as_deref(), Some("market-research"));
    }

    // ── Iteration 3: architecture and implementation plan refinement ──

    #[test]
    fn test_research_architecture_blueprint_refined_to_technical() {
        let result = classify_by_rules(
            ".claude/research/2026-02-11-architecture-blueprint.md",
        );
        assert_eq!(result.doc_type, "technical");
        assert_eq!(result.subcategory.as_deref(), Some("architecture"));
    }

    #[test]
    fn test_research_classification_architecture_refined_to_technical() {
        let result = classify_by_rules(
            ".claude/research/2026-01-28-context-aware-classification-architecture.md",
        );
        assert_eq!(result.doc_type, "technical");
        assert_eq!(result.subcategory.as_deref(), Some("architecture"));
    }

    #[test]
    fn test_research_implementation_plan_refined_to_product_roadmap() {
        let result = classify_by_rules(
            ".claude/research/2026-02-11-phase1-implementation-plan.md",
        );
        assert_eq!(result.doc_type, "product");
        assert_eq!(result.subcategory.as_deref(), Some("roadmap"));
    }

    #[test]
    fn test_research_implementation_without_plan_stays_research() {
        // "implementation" alone (without "plan") should NOT become roadmap
        let result = classify_by_rules(
            ".claude/research/2026-01-22-virtual-structure-implementation.md",
        );
        assert_eq!(result.doc_type, "research");
        assert_eq!(result.subcategory.as_deref(), Some("market-research"));
    }
}