Verdict

Sovereign Shards - J A fully local AI developer agent that runs from a USB stick. No cloud. No API keys. No internet. Plug in and build. Landing Page - The Five Masters - User Manual - Roadmap What Is J? J is a self-contained, autonomous developer agent - not a chatbot. It decomposes tasks into dependency graphs, calls tools, verifies results, and self-corrects. The language model is the language engine. The framework is the reasoning layer. User Input │ ▼ ┌──────────┐ match? ┌──────────┐ │ Router │─────────▶│ Tool │──▶ Result │ (zero │ yes │ Execute │ │ inference│ └──────────┘ │ cost) │ └────┬─────┘ │ no match ▼ ┌────────────────────────────┐ │ Context Reconstruction │ │ System + BM25 Memory + │ │ Conversation (trimmed) │ └────────────┬───────────────┘ ▼ ┌────────────────────────────┐ │ LLM (local GGUF model) │ │ → ACTION:{tool, args} │ │ → Verify → Loop or Done │ └────────────────────────────┘ Think of it as Codex or Claude Code, but it runs off a Kingston USB stick in your pocket. ✨ Key Features Feature Description 🧠 Plan → Execute → Verify DAG-based task planner with dependency resolution, parallel execution, and automatic verification ⚡ Fast Command Router Regex/keyword dispatcher handles shell, file, and code operations at zero inference cost - model only called when language understanding is needed 🔧 18+ Built-In Dev Tools File editing, bash, git, search, tree, test, SQL, integrity hashing - all auto-discovered from tools/run/ 🔨 Inference Tool Forge "Build a tool for X" → J researches the domain, generates code, validates in sandbox, and hot-registers the new tool mid-session 💾 3-Tier Memory System Active context reconstruction + rolling working memory + persistent long-term memory with BM25 retrieval 🏛️ The Five Masters AST-powered code governance - 5 engineering dimensions, 8 deterministic transforms, zero inference cost detection 🔬 Code Optimizer /optimize command: analyse code against the Five Masters, apply deterministic fixes, then optional LLM-assisted semantic rewrites - the first product feature 🛡️ Pre-Push Sandbox 5-check validation gauntlet (conflicts, syntax, AST, tests, Five Masters) - nothing broken leaves the drive 🔄 Self-Healing Circuit Breaker Detects stuck loops, repeat errors, and runaway turns - auto-recovers or gracefully exits 📡 Streaming Output Real-time line-by-line tool output - see builds, tests, and processes as they happen 🧪 147+ Test Suite Full unittest coverage: memory, retriever, planner, executor, sandbox, forge, circuit breaker, optimizer - runs anywhere with zero test deps 🔒 Fully Offline Zero network calls. Zero telemetry. Your code never leaves your machine 🚀 Quick Start USB Drive (Recommended) 1. Plug in your USB drive (e.g., E:\) 2. Open Command Prompt (not PowerShell, not Git Bash) 3. E: 4. cd "dev shard" 5. run-shard.bat J starts the local model server, loads the brain, and drops you into an interactive session. ⚠️ Always use run-shard.bat from Command Prompt. Windows associates .py files with VS Code - running run.py directly opens the editor instead of executing. Development Machine git clone https://github.com/s4ndm4n33-spec/sovereign-shards.git cd sovereign-shards pip install python-dotenv psutil cp .env.example .env # Edit for your hardware python run.py --doctor # Preflight check python run.py # Launch 📘 See docs/USER_MANUAL.md for the full guide with example builds, configuration tuning, and architecture deep dives. 🏛️ The Five Masters The engineering philosophy that governs all code quality decisions. Not a linter - a transformer. Master Domain What They Enforce Korotkevich Efficiency No range(len()). No list(filter()). No repeated dict lookups in loops. Prefer generators. Torvalds Error Handling No bare except:. No swallowed exceptions. Every error handled with intent. Carmack Performance No nested loops beyond O(n²). No string concat in loops. Flag excessive nesting. Hamilton Fault Tolerance Every non-trivial function has a failure return path. Defensive coding. No silent failures. Ritchie Clarity snake_case functions, PascalCase classes. All call sites updated on rename. Dunders and privates exempt. Detection is pure AST - zero inference cost. Transforms are deterministic - 8 AST rewrites that produce valid Python every time. The optimizer chains it all: analyse → plan → transform → verify. /optimize app/chat.py # Analyse and fix one file /optimize app/ --dry-run # Preview all changes in a directory /optimize app/ --no-model --diff # Deterministic fixes only, show diffs 🏛️ Read the Code Commandments → 🧠 The Memory System J doesn't use a growing conversation that eventually overflows. It reconstructs a fresh, minimal context every turn: Tier What Storage Lifecycle Active Context What the model sees right now Ephemeral Rebuilt every turn from tiers below Working Memory Rolling compressed summaries JSONL (auto-prunes at 32 KB) Weight-triggered reflection compresses automatically Long-Term Memory Persistent facts and preferences JSON (64 KB cap) Survives across sessions indefinitely BM25 retrieval scores all memory entries against the current task and pulls only what's relevant - no embeddings, no vectors, no external service. Pure term-frequency math in ~97 lines of Python. Pre-flight budget gate enforces a hard context ceiling with 3-stage escalation trimming. The system prompt is always protected. Identity never gets trimmed away. 🏗️ Architecture sovereign-shards/ ├── run.py # Entry point - args, modes, diagnostics ├── run-shard.bat # Windows USB one-click launcher ├── app/ │ ├── chat.py # Main chat loop (891 lines) │ ├── client.py # RuntimeConfig - provider-agnostic backend │ ├── local_server.py # llama.cpp server lifecycle management │ ├── router.py # Fast command router (zero inference cost) │ ├── doctor.py # Preflight hardware diagnostics │ └── agent/ │ ├── context.py # 3-stage context budget gate + step seaming │ ├── working_memory.py # Tier 2: append-only JSONL summaries │ ├── memory.py # Tier 3: persistent key-value store │ ├── retriever.py # BM25 retrieval (~97 lines) │ ├── reflection.py # Weight-triggered memory compression │ ├── planner.py # Task decomposition → DAG │ ├── executor.py # Tool dispatch + result capture │ ├── graph.py # Kahn's algorithm DAG execution │ ├── parallel.py # ThreadPool for independent steps │ ├── optimizer.py # Five Masters code optimizer pipeline │ ├── transforms.py # 8 deterministic AST transforms │ ├── sandbox.py # Pre-push validation gauntlet │ ├── tool_registry.py # Auto-discovery + schema extraction │ ├── tool_forge.py # Runtime tool generation │ ├── circuit_breaker.py # Stuck-loop detection + recovery │ └── refactor.py # Multi-file AST analysis engine ├── core/ │ └── fivemasters.py # Five Masters AST governance (5 visitors) ├── prompts/ │ ├── J-system.txt # System prompt (~279 tokens - lean) │ └── J-chat-template.jinja # ChatML template for llama.cpp ├── tools/run/ # 18+ auto-discovered tool scripts ├── tests/ # 147+ tests (unittest, zero deps) ├── models/ # GGUF model files (gitignored) ├── memory/ # Runtime memory (gitignored) └── docs/ ├── USER_MANUAL.md # Full user guide ├── ROADMAP.md # 5-phase roadmap with phase gates ├── MIGRATION_LOG.md # Architecture + handoff document ├── CODE_OPTIMIZER_SPEC.md # Optimizer technical specification ├── BUSINESS_MODEL.md # Three-tier business model └── TEST_PLAN.md