yvgude/lean-ctx v3.7.0 on GitHub

Shadow Mode + Meaningful Instructions. Rules injected into agents are now
actionable (concrete tool names, examples, workflow), and a new shadow_mode
transparently intercepts native Read/Grep/Shell calls for users who want full
automatic routing.

Added

Shadow Mode (lean-ctx config set shadow_mode true): transparently intercepts native Read/Grep/Shell via hooks, strengthens MCP instructions to MUST-level, activates immediate bypass hints on first native tool use, logs all intercepts to ~/.lean-ctx/shadow.log for audit transparency. Visible in lean-ctx doctor and lean-ctx status.
6-step workflow in all injected rules: Orient → Locate → Read → Edit → Verify → Record — agents can follow blindly without memorizing tool names.
Tool Mapping table in rules: every injected rule file now includes a MANDATORY table with exact tool names, parameters, and runnable examples (ctx_read("src/main.rs", "full")).
Proactive section in RULES_DEDICATED: ctx_overview at session start, ctx_compress at phase boundaries, ctx_knowledge(action="wakeup") for prior findings.
Compression Bypass ladder: lines:N-M → full → raw=true — documented escape hatch when compression hides detail.
Risk Gate guidance: before editing exported symbols, auth, DB schemas, or 3+ files — run ctx_impact + ctx_callgraph.
Registry-driven hook refresh + doctor staleness check: lean-ctx doctor detects stale hooks, IDE path misconfiguration, and auto-refreshes outdated rules on first tool call.
Reference appendices generated from code: docs-gen renders MCP tool reference, CLI reference, and journey golden outputs directly from source — with CI drift-gate to catch divergence.
Complete user-journey reference (14 journeys): install-to-first-save through performance tuning, with IDE quickstarts and golden output examples.
Semantic-index observability (#249): lean-ctx index status and lean-ctx doctor surface BM25 state (idle/building/ready/failed), build duration, persisted size, and failure notes.

Changed

Rules version v10 → v11: all templates (RULES_SHARED, RULES_DEDICATED, lean-ctx.mdc, lean-ctx-hybrid.mdc) rewritten with actionable structure. Existing installations auto-upgrade on next lean-ctx setup or lean-ctx update.
MCP instructions include workflow hint: "Orient(ctx_overview) → Locate(ctx_search) → Read(ctx_read) → Edit → Verify → Record".
bypass_hint.rs respects shadow_mode: when active, hints trigger on first native use (not after 5 calls) with stronger "intercepted" wording.
Hook redirect messaging: in shadow_mode, redirected Read/Grep outputs include a header explaining the interception and suggesting direct ctx_* usage.

Fixed

Config.toml overwritten on update (#330): all config writes now use toml_edit-based format-preserving merge with atomic backup. User comments, formatting, and unknown keys survive any write. Minimal-diff mode: only non-default values are written (no config bloat).
WSL cache hit rate near 0% (#329): mtime=None on DrvFS no longer causes spurious invalidation; path normalization uses canonicalize (with verbatim-prefix stripping) for consistent cache keys; lean-ctx cache stats now shows both CLI and MCP session cache metrics.
Semantic index stuck "warming up" forever (#249): on a repo whose BM25 index exceeded the disk cap, the index rebuilt from scratch every call. Three fixes: (1) disk persist ceiling decoupled from RAM profile (default 512 MB); (2) save reports typed SaveOutcome with actionable notes; (3) ctx_compose deferred message is state-aware and honest.
Test-runner output compressed/truncated, losing pass/fail summaries: test-runner commands across all ecosystems are now kept verbatim; test-outcome markers survive truncation on every code path.
Knowledge store split on Windows (#325): forward-slash/casing-normalized project hash converges CLI and MCP on a single store. Pre-fix backslash-keyed stores auto-migrate.
Parallel remember calls clobbered each other (#326): read-modify-write serialized with in-process + cross-process file locks; atomic temp-file-then-rename saves prevent JSON corruption.
Windows \\?\ prefix from canonicalize: normalize_tool_path now uses safe_canonicalize (strips extended-length prefix) and skips root-only paths (/, C:/).
IDE hook integrations check: doctor now correctly parses hook binary path from minified JSON.
Docs-drift gate line-ending agnostic: Windows CI no longer fails due to CRLF vs LF in generated docs.
Benchmark system info detection on Windows: RAM + CPU detection now works on all platforms.

Security

Shell-command injection in the Node SDK (CodeQL js/shell-command-constructed-from-input): switched to execFileSync — no shell interpretation.
XSS in VS Code sidebar webview (CodeQL js/xss, 3× high): all dynamic values escaped.
Missing origin check on webview message handler (CodeQL js/missing-origin-check): rejects untrusted origins.

Upgrade

lean-ctx update                 # recommended (auto-downloads + refreshes shell hooks)
cargo install lean-ctx          # or
npm update -g lean-ctx-bin      # or
brew upgrade lean-ctx

Note: After upgrading via cargo/npm/brew, run lean-ctx setup to refresh shell aliases. lean-ctx update does this automatically.

Full Changelog: v3.7.0...v3.7.0