lean_ctx/core/
rules_canonical.rs

1//! Canonical Hybrid Policy — the single source of truth for all lean-ctx rules.
2//!
3//! Every template, injected rule file, SKILL.md, and MCP instructions field
4//! MUST derive its tool-mapping table from this module. No inline tool tables
5//! elsewhere in the codebase.
6
7/// Generates the canonical tool-mapping table for the given mode.
8pub fn tool_table(mode: Mode) -> &'static str {
9    match mode {
10        Mode::Hybrid => HYBRID_TABLE,
11        Mode::Mcp => MCP_TABLE,
12    }
13}
14
15/// Returns the full rules block (LITM-optimized) for dedicated rule files.
16pub fn dedicated_rules(mode: Mode) -> String {
17    let table = tool_table(mode);
18    let shell_note = match mode {
19        Mode::Hybrid => "Shell commands: use `lean-ctx -c \"<cmd>\"` via your Shell tool. NEVER use `ctx_shell` in Hybrid mode.",
20        Mode::Mcp => "Shell commands: use `ctx_shell(command)`. NEVER use raw Shell/bash.",
21    };
22
23    format!(
24        r"# lean-ctx — Context Engineering Layer
25<!-- lean-ctx-rules-v9 -->
26
27CRITICAL: ALWAYS use lean-ctx tools instead of native equivalents. This is NOT optional.
28
29{table}
30
31{shell_note}
32
33File editing: use native Edit/StrReplace. Write, Delete, Glob → use normally.
34NEVER loop on Edit failures — switch to ctx_edit immediately.
35
36Fallback only if a lean-ctx tool is unavailable: use native equivalents.
37REMINDER: You MUST use lean-ctx tools. NEVER use native Read, Grep, or Shell directly.
38<!-- /lean-ctx -->"
39    )
40}
41
42/// Returns a short instructions string for MCP JSON `instructions` field.
43pub fn mcp_instructions(mode: Mode) -> &'static str {
44    match mode {
45        Mode::Hybrid => MCP_INSTRUCTIONS_HYBRID,
46        Mode::Mcp => MCP_INSTRUCTIONS_MCP,
47    }
48}
49
50#[derive(Debug, Clone, Copy, PartialEq, Eq)]
51pub enum Mode {
52    Hybrid,
53    Mcp,
54}
55
56impl Mode {
57    pub fn from_hook_mode(hook: &crate::hooks::HookMode) -> Self {
58        match hook {
59            crate::hooks::HookMode::Hybrid => Mode::Hybrid,
60            crate::hooks::HookMode::Mcp => Mode::Mcp,
61        }
62    }
63}
64
65const HYBRID_TABLE: &str = "\
66| MUST USE | NEVER USE | Why |
67|----------|-----------|-----|
68| `ctx_read(path, mode)` | `Read` / `cat` / `head` / `tail` | Cached, 10 read modes, re-reads ~13 tokens |
69| `ctx_search(pattern, path)` | `Grep` / `rg` | Compact, token-efficient results |
70| `lean-ctx -c \"<cmd>\"` (via Shell) | `ctx_shell` / raw `Shell` | CLI compression, no MCP overhead |
71| `lean-ctx ls [path]` (via Shell) | `ctx_tree` / `ls` / `find` | Compact directory maps |";
72
73const MCP_TABLE: &str = "\
74| MUST USE | NEVER USE | Why |
75|----------|-----------|-----|
76| `ctx_read(path, mode)` | `Read` / `cat` / `head` / `tail` | Cached, 10 read modes, re-reads ~13 tokens |
77| `ctx_search(pattern, path)` | `Grep` / `rg` | Compact, token-efficient results |
78| `ctx_shell(command)` | `Shell` / `bash` / terminal | Pattern compression for git/npm/cargo output |
79| `ctx_tree(path, depth)` | `ls` / `find` | Compact directory maps |";
80
81const MCP_INSTRUCTIONS_HYBRID: &str = "\
82lean-ctx tools replace Read/Grep/Shell/ls. See tool descriptions for details. Edit/Write/Glob: native.";
83
84const MCP_INSTRUCTIONS_MCP: &str = "\
85lean-ctx tools replace Read/Grep/Shell/ls. See tool descriptions for details. Edit/Write/Glob: native.";
86
87#[cfg(test)]
88mod tests {
89    use super::*;
90
91    #[test]
92    fn hybrid_table_contains_must() {
93        assert!(HYBRID_TABLE.contains("MUST USE"));
94        assert!(!HYBRID_TABLE.contains("PREFER"));
95    }
96
97    #[test]
98    fn mcp_table_contains_must() {
99        assert!(MCP_TABLE.contains("MUST USE"));
100        assert!(!MCP_TABLE.contains("PREFER"));
101    }
102
103    #[test]
104    fn hybrid_table_uses_cli() {
105        assert!(HYBRID_TABLE.contains("lean-ctx -c"));
106        for line in HYBRID_TABLE.lines() {
107            assert!(
108                !line.starts_with("| `ctx_shell"),
109                "Hybrid table must not list ctx_shell in MUST USE column"
110            );
111        }
112    }
113
114    #[test]
115    fn mcp_table_uses_ctx_shell() {
116        assert!(MCP_TABLE.contains("ctx_shell"));
117        assert!(!MCP_TABLE.contains("lean-ctx -c"));
118    }
119
120    #[test]
121    fn dedicated_rules_have_markers() {
122        let rules = dedicated_rules(Mode::Hybrid);
123        assert!(rules.contains("lean-ctx-rules-v9"));
124        assert!(rules.contains("<!-- /lean-ctx -->"));
125    }
126
127    #[test]
128    fn dedicated_rules_litm_structure() {
129        for mode in [Mode::Hybrid, Mode::Mcp] {
130            let rules = dedicated_rules(mode);
131            let lines: Vec<&str> = rules.lines().collect();
132            let first_5 = lines[..5.min(lines.len())].join("\n");
133            assert!(
134                first_5.contains("CRITICAL") || first_5.contains("MUST"),
135                "LITM: MUST instruction near start for {mode:?}"
136            );
137            let last_3 = lines[lines.len().saturating_sub(3)..].join("\n");
138            assert!(
139                last_3.contains("MUST") || last_3.contains("NEVER"),
140                "LITM: reinforcement near end for {mode:?}"
141            );
142        }
143    }
144
145    #[test]
146    fn no_prefer_in_any_output() {
147        for mode in [Mode::Hybrid, Mode::Mcp] {
148            let rules = dedicated_rules(mode);
149            assert!(
150                !rules.contains("PREFER"),
151                "canonical rules must use MUST, not PREFER for {mode:?}"
152            );
153            let instructions = mcp_instructions(mode);
154            assert!(
155                !instructions.contains("PREFER"),
156                "MCP instructions must use MUST, not PREFER for {mode:?}"
157            );
158        }
159    }
160}
lean_ctx/core/rules_canonical.rs

lean_ctx/core/
rules_canonical.rs
