@ruso-0/nreki 8.6.1 → 9.0.0

package/README.md

@@ -47,11 +47,27 @@ npx @ruso-0/nreki init
 
 ---
 
+## ⚡ The "Zero-Config" Promise (80% of the value instantly)
+
+NREKI is designed to be plug-and-play. You don't need a PhD in graph theory to use it.
+
+Out of the box, NREKI automatically provides:
+
+1. **Tree-sitter AST Shield (Layer 1):** Instantly catches missing commas, unclosed brackets, and hallucinated syntax in TS, JS, Python, and Go *before* they hit your disk. Zero native dependencies.
+2. **TypeScript VFS (Layer 2):** Full cross-file type checking and CodeFix Auto-Healing in RAM using your existing `tsconfig.json`.
+3. **TFC-Ultra Compression:** Bounding parafoveal overhead to O(1), saving 85-98% of tokens on file reads while keeping the LLM laser-focused on the exact method it needs to edit.
+
+**What about Go and Python LSPs? (Graceful Degradation)**
+
+If you happen to have `gopls` or `pyright` in your PATH, NREKI will silently detect them and upgrade Go/Python to Layer 2 (Cross-file semantics & LSP Auto-Healing). **If you don't have them, NREKI gracefully degrades to Layer 1.** Your agent never breaks. You get the core value with zero installation friction.
+
+---
+
 ## What It Actually Does
 
 | Without NREKI | With NREKI | Result |
 |---------------|-----------|--------|
-| `cat file.ts` dumps entire file | `nreki_code action:"read"` compresses to signatures | 60-80% fewer tokens |
+| `cat huge_file.ts` (burns 20k tokens) | `compress focus:"<method>"` (TFC-Ultra) | **82% to 98.2% Token Savings** |
 | Agent writes broken code to disk | Edit validated in RAM before write | Zero broken files on disk |
 | Error -> read output -> guess fix -> retry -> repeat | Auto-Healing fixes structural errors in RAM | Zero doom loop tokens |
 | Agent manages 16+ tool calls | 3 tools, 20 actions | 85% less tool overhead |
@@ -62,6 +78,13 @@ npx @ruso-0/nreki init
 
 ---
 
+## 🔬 Pro Features: Architecture Intelligence
+*(For Staff Engineers, Tech Leads, and complex refactors)*
+
+Under the hood, NREKI doesn't just read text; it builds a mathematical graph of your repository. It computes the combinatorial Laplacian of the file-level dependency graph to unlock advanced architectural insights that act as a passive radar for your team. **You don't need to understand any of this to get the Zero-Config benefits above** — these features kick in when you opt-in to them for complex refactors.
+
+---
+
 ## What's New in v8 (Antigravity)
 
 ### Spectral Clustering
@@ -149,61 +172,50 @@ True topological circuit rank via Union-Find on the type constraint graph. `beta
 
 ## What's New in v8.6 (TFC-Ultra)
 
-**Topological Foveal Compression** — Hyper-causal context sculpting for frontier LLMs. Point TFC-Ultra at a specific method or function inside a file, and it extracts the target symbol at 100% resolution plus its causal dependencies (upstream callers, downstream deps, resolved imports, blast radius), while annihilating orthogonal "dark matter" code.
+**Topological Foveal Compression (TFC-Ultra)** — Hyper-causal context sculpting for frontier LLMs (Opus 4.6 / Gemini 3.1 Pro). Point TFC-Ultra at a specific method or function inside a monolith, and it extracts the target symbol at 100% resolution plus its causal dependencies (upstream callers, downstream deps, resolved external imports, blast radius), while annihilating orthogonal "dark matter" code.
 
 ```bash
 nreki_code action:"compress" path:"src/huge-file.ts" focus:"criticalMethod"
 ```
 
-### Empirical results (benchmarked against NREKI src/ — 5 files, 15 focus probes + 15 boundary probes)
+### The Physics of TFC-Ultra (Empirically Benchmarked)
 
-**Operational case** (methods of medium-to-large size):
+We benchmarked TFC against NREKI's own `src/` directory (15 focus probes on operational methods, plus 15 boundary probes on minimal getters). No marketing fluff. Just math.
 
-| Metric | Value |
-|--------|-------|
-| **Avg compression** | **82.2%** (~5.6x) |
-| **p50 compression** | **84.8%** |
-| **p95 compression** | **89.9%** (~10x) |
-| **Advantage vs legacy tier-3** | **+9.8pp** (consistent) |
-| **Fovea fidelity** | **100%** — target symbol preserved verbatim for zero-loss reasoning |
-| **True LRU AST cache** | **34x avg speedup**, **137x in extreme cases** (1,819ms → 13.3ms on 82 KB file) |
-| **Fallback rate (Density Shield)** | **13.3%** — when TFC can't beat 15% compression, falls through to legacy aggressive |
+**The Asymptotic Boundary (Theoretical Ceiling):**
 
-**Best case boundary** (theoretical ceiling — small focus inside large file):
+- **Max Compression Observed: 98.2% (55x)**
+- **Context:** Focus on a 3-line getter (`isBooted`) inside an 82 KB, 1,640-line monolith (`nreki-kernel.ts`). 1,605 orthogonal lines annihilated.
+- **The Amdahl Law of Context:** The compression ratio scales inversely with the focus-to-file size ratio. The larger the monolith and the smaller the target, the more devastating the compression.
 
-| Metric | Value |
-|--------|-------|
-| **Max compression observed** | **98.2%** (**55x**) |
-| **Context** | focus `isBooted` (3-line getter) inside `nreki-kernel.ts` (82 KB, 1,640 lines) |
-| **Boundary probes** | 15 (top-3 smallest symbols per file), **0 fallbacks**, compression range: **30x–55x** |
+**The Operational Case (Medium-to-large methods):**
 
-### The Amdahl law of focused compression
+- **Avg Compression: 82.2%** (~5.6x smaller)
+- **p95 Compression: 89.9%** (~10x smaller)
+- **Fovea Fidelity: 100%** — Target symbol preserved verbatim for zero-loss reasoning.
+- **LRU Cache Speedup: 33x faster on average** (1,819ms → 11.7ms) via True LRU AST Cache. **142x in extreme cases.**
 
-TFC compression ratio follows an asymptotic limit:
+### Zero-Regression Density Shield
 
-```
-Ratio ≈ 1 − (Preamble + Fovea + Markov_Mantle_O(1)) / TotalFileSize
-```
+What happens if the LLM gets lazy and aims TFC at a 1,500-line "God Class"? The parafoveal overhead (callers, deps, metadata) would make the output larger than reading the file raw.
 
-- When the Fovea is a small getter (3 lines) inside a 1,640-line file, the numerator is minuscule vs. the denominator. **Ratio approaches 100%. Empirical ceiling: 98.2% (55x).**
-- When the Fovea is a large operational method (500 lines), the numerator grows. **Ratio drops to 70-80%.** Still preserves 100% of the causal information the agent needs.
-- When the Fovea is a God Class (entire file), the numerator **exceeds** the denominator due to parafovea overhead. **The Density Shield detects this and falls through to legacy aggressive**, guaranteeing the output is never worse than baseline.
+TFC-Ultra prevents this. If it cannot mathematically guarantee at least **15% real compression** (ratio < 0.85), it aborts silently in RAM and gracefully degrades to the Legacy Aggressive compressor. **The user never receives an output worse than the baseline.**
 
-**This is not marketing. This is physics.** See [BENCH-TFC.md](BENCH-TFC.md) for the raw dogfooding benchmark with per-file breakdowns.
+### Prompt Cache Inversion
+
+TFC-Ultra forces a topological inversion of the output:
+
+```
+[Static Preamble] -> [Dark Matter Tombstones] -> [External Contracts] -> [Upstream/Downstream] -> [VOLATILE FOVEA]
+```
 
-### How it works
+By placing the volatile target code at the absolute bottom of the payload, the top 90% of the prompt remains static across subsequent iterative edits. This guarantees **Anthropic Prefix Cache hits**, saving users up to **90% in API costs**.
 
-- **Fovea**: the target symbol is preserved byte-for-byte at 100% resolution
-- **Upstream vectorial collapse** (O(1)): N local callers condensed to a single line of names
-- **Downstream event horizon** (O(1)): top-10 local dependencies + `cleanSignature` to strip JSDoc waste
-- **External parafovea**: BM25-resolved signatures of imported symbols used inside the fovea
-- **Blast radius**: dependents from the project-wide import graph
-- **Dark matter**: everything else in the file is omitted as a single annotation line
-- **Density Shield 0.85**: if TFC can't achieve ≥15% real compression (e.g. when the agent aims at a God Class and pulls the entire file into the fovea), the compressor returns `null` and the system falls through to the legacy aggressive compressor — **mathematically guarantees you never perform worse than baseline**
+### TFC-Pro Enforcer (Cognitive Bouncer)
 
-### TFC-Pro Enforcer (auto-guard on `read`)
+When a file exceeds 3,000 tokens and the agent tries to read it raw, NREKI's `PreToolUseHook` intercepts the call, blocking context-window suicide. It forces the agent to use outline + focus-driven compression instead.
 
-When a file exceeds 3,000 tokens and the agent tries to read it raw, NREKI's hook intercepts the call and instructs the agent to use outline + focus-driven compression instead. This eliminates context-window suicide before it happens.
+**This is not marketing. This is physics.** See [BENCH-TFC.md](BENCH-TFC.md) for the raw dogfooding benchmark with per-file breakdowns.
 
 ---
 
@@ -440,6 +452,8 @@ Re-injects 4-layer session state every ~15 tool calls to survive context compact
 |--------|-------|
 | Tests | 713 (44 suites) |
 | Architecture Health Index | 9.7/10 (self-scored) |
+| **Max TFC-Ultra Compression** | **98.2% (55x)** |
+| **TFC LRU Cache Speedup** | **34x avg (11.7ms latency)** |
 | Languages | 4 (TypeScript, JavaScript, Go, Python) |
 | Failure modes sealed | 32 (P1-P32) |
 | Audit findings resolved | 30/30 + 22 additional |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ruso-0/nreki",
-  "version": "8.6.1",
+  "version": "9.0.0",
   "description": "MCP plugin that validates AI agent edits in RAM before they touch disk. Spectral clustering, architecture diffs, bridge detection, dead code oracle, and cross-file semantic checks for TypeScript, Go (gopls), and Python (pyright). Zero cloud dependencies.",
   "main": "dist/index.js",
   "type": "module",

package/templates/CLAUDE.md

@@ -1,21 +1,55 @@
-# NREKI Active
-
-This workspace has the NREKI MCP plugin installed. It extends your capabilities with AST-aware tools that protect your context window and prevent syntax errors before they reach disk.
-
-## Optimal Workflow
-
-1. **Run tests & commands freely.** Use Bash for npm test, builds, git - NREKI doesn't interfere with your terminal.
-2. **Navigate with AST precision.** Prefer `nreki_navigate` over grep/glob. It returns exact structural matches (functions, classes, references) without flooding your context with noise.
-3. **Read files efficiently.** ALWAYS prefer `nreki_code action:"read"` over native Read. Native Read dumps the entire file into your context - a 2,000-line file burns ~5,000 tokens in one call. `nreki_code read` auto-compresses to ~1,200 tokens while keeping all structural context. This is the single biggest token saver available to you.
-4. **Debugging? Read uncompressed.** If you need to understand a function's internal logic (not just its signature), use `nreki_code action:"read" compress:false`. Compression hides function bodies to save tokens - great for navigation, but not for debugging.
-5. **Edit surgically.** Prefer `nreki_code action:"edit"` for modifying existing functions/classes. It validates the AST before writing to disk - if your code has a syntax error, the file stays untouched and you get the exact line/column to fix.
-6. **Multi-file refactors? Use batch_edit.** `nreki_code action:"batch_edit" edits:[...]` edits multiple files atomically. If ANY file has a syntax error, NOTHING is written to disk. All-or-nothing safety.
-7. **Renaming a symbol? Use prepare_refactor first.** `nreki_navigate action:"prepare_refactor" symbol:"OldName"` analyzes every occurrence and classifies it as "high confidence" (safe to rename) or "review" (might be a string, comment, or object key). Then use batch_edit to apply the renames.
-8. **Watch for blast radius warnings.** When you change a function's signature, NREKI automatically warns you which files import it. Fix those files before running tests.
-9. **The repo map shows architecture tiers.** `nreki_navigate action:"map"` now classifies files as CORE (high import count - modify with caution), BUSINESS LOGIC (medium), or LEAF (safe to experiment).
-10. **Create new files normally.** Use native Write for brand new files that don't exist yet.
-11. **Pin rules that matter.** Use `nreki_guard action:"pin"` to persist instructions across messages (e.g., "always use fetch, not axios").
-12. **Anchor your plan.** If you're working on a complex task with strict schemas or architectural constraints, use `nreki_guard action:"set_plan" text:"PLAN.md"` at the start. NREKI will silently re-inject your plan every ~15 tool calls to survive context compaction. Use `nreki_guard action:"memorize" text:"your progress notes"` to leave notes for yourself.
-13. **If the circuit breaker triggers, follow its instructions.** It detected a doom loop and is protecting your session from burning tokens on repeated failures.
-
-NREKI handles the context heavy-lifting so you can focus on writing correct code on the first try.
+# 🛡️ NREKI SYSTEM ACTIVE: AI DIRECTIVES
+
+This workspace is protected by NREKI, an AST-aware context firewall.
+
+## 0. 🚨 EMERGENCY FALLBACK (MCP FAILURE)
+If the `nreki_*` tools fail to load, timeout, or return connection errors:
+1. **DO NOT PANIC or freeze.**
+2. **TEMPORARILY SUSPEND** the "NEVER use Native Read/Write" rules below.
+3. Fall back to your native `Read File`, `Write`, and `Replace` tools to complete the task.
+4. Inform the user: *"NREKI connection lost. Proceeding with native tools (AST safety disabled)."*
+
+*(Assuming NREKI is online, strictly obey the following laws):*
+
+## 1. 📖 READING & DISCOVERY (The TFC-Ultra Protocol)
+* **NEVER use Native `Read File` for existing files** (unless in Emergency Fallback). It dumps raw text, triggers "Attention Sinks", and burns context.
+* **MANDATORY TFC-ULTRA FOR EDITS:** To understand or edit a specific logic block in a large file (>3000 tokens):
+  1. Run `nreki_navigate action:"outline" path:"<file>"` to map the structure.
+  2. Identify the exact **METHOD or FUNCTION** you need (DO NOT target entire classes).
+  3. Run `nreki_code action:"compress" path:"<file>" focus:"<method_name>"`.
+  *NREKI will isolate your target at 100% resolution, resolve causal dependencies, and annihilate up to 98% of orthogonal noise.*
+* **GENERAL EXPLORATION:** If skimming a smaller file, use `nreki_code action:"read"`.
+* **NAVIGATION:** Do not use grep/glob. Use `nreki_navigate` (`search`, `definition`, `references`, `outline`, `map`) for zero-noise discovery.
+
+## 2. ✍️ SURGICAL EDITING & REFACTORING
+* **NEVER use Native `Write` or `Replace` to modify existing files.** It bypasses the RAM safety shield.
+* **SINGLE EDITS:** ALWAYS use `nreki_code action:"edit" symbol:"<Name>"`.
+* **MULTI-FILE EDITS:** ALWAYS use `nreki_code action:"batch_edit"`. It is a strict ACID transaction.
+* **PATCH MODE (Minimum Output Tokens):** For ANY edit that changes less than 30% of a symbol's body,
+  you **MUST** use `mode:"patch"` with `search_text` and `replace_text`.
+  **NEVER** rewrite an entire function to change a single line. Output tokens are 5x more expensive than input.
+* **CRITICAL FOR PATCH:** Your `search_text` must be an EXACT substring of the existing AST node,
+  including exact whitespace and indentation. If patch fails, NREKI returns a preview of the actual AST content.
+* **SCAFFOLDING EXCEPTION:** When creating BRAND NEW files from scratch, use Native `Write`.
+  New files have nothing pre-existing to break. NREKI `edit`/`batch_edit` is for modifying existing code only.
+* **NEW FILES:** Use Native `Write` ONLY for creating brand-new files.
+* **RENAMING:** Run `nreki_navigate action:"prepare_refactor"` before renaming.
+
+## 3. 🏗️ BLAST RADIUS & ARCHITECTURE
+* **RESPECT THE BLAST RADIUS:** When changing a signature, NREKI warns you of downstream dependent files. You **MUST** fix them in the SAME `batch_edit` transaction.
+* **AUTO-HEALER:** If NREKI injects an import or fixes syntax, it will notify you: `[Auto-Heal applied]`. **DO NOT PANIC.** Do not manually revert it.
+
+## 4. 🧠 CONTEXT SURVIVAL
+* **ANCHOR PLANS:** Start complex tasks with `nreki_guard action:"set_plan" text:"PLAN.md"`. NREKI silently re-injects this plan every ~15,000 tokens so you never forget it.
+* **BREADCRUMBS:** Use `nreki_guard action:"memorize" text:"<notes>"` to save your progress state.
+
+## 5. 🚨 TERMINAL & SYSTEM ALERTS
+* Run `npm test`, builds, and `git` normally via Bash. If logs are massive, use `nreki_code action:"filter_output"`.
+* **CIRCUIT BREAKER:** If NREKI triggers the Circuit Breaker, you are in a token-burning doom loop. **STOP IMMEDIATELY.** Read the instructions.
+
+## 6. 🔍 ARCHITECTURAL HEALTH (Passive Radar)
+* **THE RULE:** NREKI monitors the codebase for "God Files" (Bus Factor) and "Spaghetti Code" (Coupling). If your refactor triggers a CRITICAL alert in an audit, treat it as a strong architectural hint to decouple, but **prioritize fixing syntax/logic first**.
+
+## 7. 🐍🐹 MULTI-LANGUAGE & LSP SIDECARS
+* **NATIVE SHIELD:** NREKI natively shields TS/JS. For Go/Python, it attempts to spawn `gopls`/`pyright` for Layer 2 Semantic validation.
+* **MISSING BINARY?** If an LSP is not installed, NREKI gracefully degrades to Layer 1 (Syntax-Only AST Validation). **DO NOT PANIC.** Do NOT ask the user to install them. Acknowledge the downgrade silently and proceed with syntax-level confidence.