Module rules_canonical

Expand description

Canonical rules source — single source of truth for all lean-ctx guidance.

All content is declared as pub const at the top. Three profiles (LONGFORM, FULL, COMPACT) define which sections compose each output format. Four wrappers (Longform, Dedicated, Shared, Bare) select the profile and wrapping style. One render() function assembles everything, including the compression-level output-style prompt (Lite / Standard / Max).

Profile economics (#578): every injected file bills its tokens on every single session, so FULL (dedicated rule files) and COMPACT (shared files + MCP instructions) stay tight. LONGFORM is carried only by the project LEAN-CTX.md, which agents open on demand — it keeps the verbose teaching sections (loop taxonomy, navigation paradox, recovery vocabulary, CEP).

Every template, injected rule file, AGENTS.md block, and MCP instructions field MUST derive its content from this module.

Re-exports§

pub use super::rules_validation::RulesFile;

Enums§

Wrapper: Selects the profile (LONGFORM / FULL / COMPACT) and the wrapping style (markers, headers, footers) for render().

Constants§

AGENTS_BLOCK_END: End marker for AGENTS.md/CODEBUDDY.md/CLAUDE.md pointer blocks.
AGENTS_BLOCK_START: Start marker for lightweight AGENTS.md/CODEBUDDY.md/CLAUDE.md pointer blocks. These are deliberately separate from START_MARK /  because the pointer-only vs full-rules distinction drives duplicate detection in doctor overhead — a pointer-only file (is_pointer_only) must not be counted as a second source for its client.
AGENT_LOOP: Agent-loop tool taxonomy (#609). Names each phase of the gather → act → verify loop an agent actually runs in and the one lean-ctx tool that serves it. Since v5 (#578) LONGFORM-only — the injected profiles carry the phases folded into INTENT.
ANTI: Anti-patterns that waste tokens and round-trips.
AUTO: One-line automation reminder.
BULLETS: Compact bullet-list mapping (for both dedicated and shared contexts).
CEP: Context Engineering Protocol version reference.
COMPRESSION_BLOCK_END: Closing marker of the compression / output-style block (see COMPRESSION_BLOCK_START).
COMPRESSION_BLOCK_START: Markers of the heavy compression / output-style block — the per-turn payload that drives cross-channel duplication (#684/#548).
CRITICAL: Banner placed at the top of dedicated rule files (non-shadow only).
END_MARK: Closing marker that ends a lean-ctx rule section.
HOOK_COVERED_HEADER: Hook-covered header (GL #1153): the honest replacement for the CRITICAL/BULLETS/NEVER mapping on hosts whose installed hooks already compress the native tools (Cursor: preToolUse rewrite covers Shell, redirect covers Read/Grep). There a “NEVER use native tools” rule fights the host’s own tool guidance and is unenforceable — the model calls native tools anyway and the hooks compress them transparently. Saying so removes the instruction dissonance instead of losing the battle silently.
HOOK_COVERED_TOOLS: The tools worth an explicit MCP call on a hook-covered host: capabilities with no native equivalent the hooks could intercept. Kept in sync with SHADOW_MINIMAL’s exclusive-tools line (same rationale, different cause).
INTELLIGENCE: Output style rule.
INTENT: Intent-to-tool playbook — maps common agent questions to the right tool. Since v5 it also absorbs the agent-loop phases (#609) and the navigation paradox one-liner, replacing the separate verbose sections in the injected profile (they stay verbatim in LONGFORM).
LITE_PROMPT: Lite compression — concise, bullet-point output.
LITM_END: LITM end-of-instructions preference line.
MAX_PROMPT: Max compression — expert-terse, telegraph format, symbolic vocabulary.
MUST_INVOKE: Weak-model adherence nudge (#1067 / GH #593). Smaller models (e.g. GLM 5.2 in Windsurf) often read the tool-mapping rules yet still answer from memory or reach for a built-in tool instead of emitting an actual MCP call — so lean-ctx watch stays empty and the layer looks “off”. This one imperative line makes the act of invoking a ctx_* tool the explicit first step. It lives in the dedicated rule files of every agent (FULL_NON_SHADOW), which is what #1067 asks for; the Windsurf project template (windsurfrules.txt) carries its own copy. It is omitted where it would be dead weight: shadow mode enforces routing at the call layer, and the Bare/instructions channel is capped separately.
NAV_PARADOX: Navigation-paradox guidance (#609): reading more is not understanding more. Steers semantic questions to BM25 + meaning search and reserves the call/dep graph for genuinely hidden architectural edges. Since v5 LONGFORM-only — INTENT carries the one-line thesis in the injected profiles.
NEVER: One-line admonition reinforcing the tool preference. Always right after BULLETS in both profiles.
PARALLEL: Encourages parallel tool calls to reduce round-trips.
PROJECT_LEAN_CTX_OWNED_MARKER: Owner banner placed as the first line of the project-level LEAN-CTX.md artifact (<repo>/LEAN-CTX.md, rust/LEAN-CTX.md). Marks the whole file as lean-ctx-owned so uninstall can remove it wholesale; the writer (hooks::ensure_project_agents_integration), the regenerator (gen_rules example) and the drift gate all share this one literal.
RAW_PROMPT: Raw compression — densest possible output. Bullet points only, zero prose, diff-style facts, no intro/outro. Tighter than Max (#795).
RECOVER: Recovery vocabulary (verbose, LONGFORM profile). lean-ctx compression is fully reversible (CCR), but agents otherwise only discover the escape hatch reactively from output hints — so they re-read compressed files line-by-line instead of expanding (the “too compressed” complaint). The MCP-free path (“read the shown file path with any tool”) covers orgs that forbid MCP. Since v5 every injected profile (FULL + COMPACT/Bare) carries the terser RECOVER_COMPACT instead; the reactive footers in ctx_read/archive/ctx_shell still teach the ctx_expand path in context.
RECOVER_COMPACT: Terse injected variant of RECOVER (FULL + COMPACT/Bare). The cold first-contact handshake renders the COMPACT profile, so this one-liner keeps the static char/token budget (tests/intensive_benchmarks.rs, instructions.rs); since v5 the FULL dedicated files carry it too (#578). Keeps the two primary MCP-optional paths and the “never line-by-line” rule. Must keep the (no MCP) clause (asserted in tests).
RULES_MARKER_PREFIX: Prefix shared by every lean-ctx rules marker including legacy versioned formats (). Use for substring detection when the exact constant would miss older installs.
RULES_VERSION: Current rules version (monotonically increasing integer). Embedded as  right after START_MARK so the injection layer can parse it and decide whether a file is up-to-date.
SHADOW_MINIMAL: Minimal rules body for shadow mode (#963). Under shadow-mode interception native Read/Grep/Shell/Glob calls are transparently routed to ctx_, so the tool-mapping and “use ctx_ instead of native” guidance is dead weight — the enforcement happens at the call layer, not in the prompt. Only the lean-ctx tools that have no native trigger to intercept still need advertising.
STANDARD_PROMPT: Standard compression — dense, atomic fact lines, abbreviations.
START_MARK: Stable HTML-comment anchor that marks the start of any lean-ctx rule section. Never changes — used for find/replace in shared files and for ownership detection in dedicated files. The version number follows on the next line (see render).

Functions§

compression_text: Return the compression prompt text for a given level (empty string for Off).
render: Render lean-ctx rules for a given wrapper, shadow mode, compression level, and tool profile (#756).
render_hook_covered_bare: Unmarked render of the hook-covered profile for ephemeral channels (the mcp.json instructions snapshot on hook-covered hosts, GL #1153). The Bare counterpart of Wrapper::HookCovered: same body, no markers — per-session channels are governed by carrier coverage, so markers would be noise (see COMPRESSION_BLOCK_START). Shadow collapses to the regular bare shadow profile (interception supersedes hook coverage).