@a13xu/lucid 1.16.0 → 1.16.2

package/README.md

@@ -4,11 +4,11 @@
 [![npm downloads](https://img.shields.io/npm/dm/@a13xu/lucid)](https://www.npmjs.com/package/@a13xu/lucid)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-> **MCP server for Claude Code** — persistent memory, smart code indexing, and code quality validation. Works out of the box with zero configuration.
+> **MCP server for Claude Code** — persistent memory, smart code indexing, model selection, and code quality validation. Works out of the box with zero configuration.
 
 Token-efficient memory, code indexing, and validation for Claude Code agents — backed by **SQLite + FTS5**.
 
-Stores a persistent knowledge graph (entities, relations, observations), indexes source files as compressed binary with change detection, retrieves minimal relevant context via TF-IDF or Qdrant, and validates code for LLM drift patterns. Supports TypeScript, JavaScript, Python, **Vue, Nuxt**.
+Stores a persistent knowledge graph (entities, relations, observations), indexes source files as compressed binary with change detection, retrieves minimal relevant context via TF-IDF or Qdrant, and validates code for LLM drift patterns. Supports TypeScript, JavaScript, Python, **Vue, Nuxt**. Optional **LLMLingua-2 semantic compression** reduces context tokens by 30–70% while preserving meaning.
 
 ## Install
 
@@ -45,15 +45,16 @@ Default DB path: `~/.claude/memory.db`
 ## Quick start
 
 ```
-1. "Index this project" → init_project()        → scans CLAUDE.md, package.json, src/**
-2. Write code          → sync_file(path)         → compressed + hashed + diff stored
-3. "What's relevant?"  → get_context("auth flow") → TF-IDF ranked skeletons, ~500 tokens
-4. "What changed?"     → get_recent(hours=2)      → line diffs of recent edits
-5. "Where is X used?"  → grep_code("X")           → matching lines only, ~30 tokens
-6. "What do we know?"  → recall("query")          → knowledge graph search
+1. "Index this project" → init_project()               → scans CLAUDE.md, package.json, src/**
+2. Write code           → sync_file(path)               → compressed + hashed + diff stored
+3. "What's relevant?"  → smart_context("auth flow")    → recall + code in one call, adaptive budget
+4. "What model?"       → suggest_model("refactor auth") → haiku (lookup) or sonnet (reasoning)
+5. "What changed?"     → get_recent(hours=2)            → line diffs of recent edits
+6. "Where is X used?"  → grep_code("X")                → matching lines only, ~30 tokens
+7. "What do we know?"  → recall("query")               → knowledge graph search
 ```
 
-## Tools (30)
+## Tools (37)
 
 ### Memory
 | Tool | Description |
@@ -76,8 +77,11 @@ Default DB path: `~/.claude/memory.db`
 ### Token optimization
 | Tool | Description |
 |---|---|
-| `get_context` | **Smart context retrieval.** Ranks all indexed files by TF-IDF relevance (or Qdrant vector search if `QDRANT_URL` is set), applies recency boost, returns skeletons (imports + signatures only) for large files. Respects `maxContextTokens` budget. |
+| `smart_context` | **Recommended entry point.** Combines `recall()` (knowledge graph) + `get_context()` (code files) in one call. Adaptive token budget: `simple`=2000, `moderate`=6000, `complex`=12000. Logs an experience for `reward()`/`penalize()` feedback. |
+| `suggest_model` | Classify task complexity → recommend Claude model. Returns `{ model, model_id, reasoning, context_budget }`. Simple lookups → Haiku; reasoning/code → Sonnet. Call at the start of any workflow. |
+| `get_context` | **Classic code context.** Ranks indexed files by TF-IDF (or Qdrant), applies recency boost, returns skeletons for large files. Respects `maxContextTokens` budget. |
 | `get_recent` | Return files modified in the last N hours with line-level diffs. |
+| `compress_text` | Compress any text using LLMLingua-2 semantic compression. Returns compressed text + stats (ratio, tokens saved). Model downloads ~700MB on first use. |
 
 ### Logic Guardian
 | Tool | Description |
@@ -86,11 +90,19 @@ Default DB path: `~/.claude/memory.db`
 | `check_drift` | Analyze a code snippet inline without saving to disk. |
 | `get_checklist` | Return the full 5-pass validation protocol (Logic Trace, Contract Verification, Stupid Mistakes, Integration Sanity, Explain It). |
 
+### Plans
+| Tool | Description |
+|---|---|
+| `plan_create` | Create a development plan with title, description, and tasks. Returns plan ID. |
+| `plan_list` | List all plans with status summary (total/done/in-progress tasks). |
+| `plan_get` | Get full plan details including all tasks and their status. |
+| `plan_update_task` | Update a task's status (`pending` → `in_progress` → `done` \| `blocked`) and optionally add notes. Accepts `task_id` as number or string. |
+
 ### Reward system
 | Tool | Description |
 |---|---|
-| `reward` | Signal that the last `get_context()` result was helpful (+1). Rewarded files rank higher in future similar queries. |
-| `penalize` | Signal that the last `get_context()` result was unhelpful (-1). Penalized files rank lower in future queries. |
+| `reward` | Signal that the last `smart_context()`/`get_context()` result was helpful (+1). Rewarded files rank higher in future similar queries. |
+| `penalize` | Signal that the last result was unhelpful (-1). Penalized files rank lower. Accepts optional `note` to log what was missing. |
 | `show_rewards` | Show top rewarded experiences and most rewarded files. Rewards decay exponentially (half-life ~14 days). |
 
 ### Code Quality Guard
@@ -115,7 +127,31 @@ Default DB path: `~/.claude/memory.db`
 
 ## Token optimization in depth
 
-### How `get_context` works
+### How `smart_context` works (recommended)
+
+```
+query: "auth middleware"
+         ↓
+  1. recall(query)  — knowledge graph search (entities, relations)
+         ↓
+  2. TF-IDF score all indexed files against query
+     (or Qdrant top-k if QDRANT_URL is set)
+         ↓
+  3. Boost recently-modified files (+0.3 score)
+     Boost rewarded files (+0.25 score, decayed)
+         ↓
+  4. For each file within token budget:
+       file < maxTokensPerFile  → return full source
+       file > maxTokensPerFile  → return skeleton only
+                                   (imports + signatures + TODOs)
+                                   + relevant fragments around query terms
+         ↓
+  5. Optional: LLMLingua-2 compression (if enabled in config)
+         ↓
+  output: merged knowledge + code — budget: 2k/6k/12k by task_type
+```
+
+### How `get_context` works (classic)
 
 ```
 query: "auth middleware"
@@ -183,6 +219,32 @@ Or in `.mcp.json`:
 
 Falls back to TF-IDF automatically if Qdrant is unreachable.
 
+### Semantic compression (optional)
+
+LLMLingua-2 (`microsoft/llmlingua-2-bert-base-multilingual-cased-meetingbank`) identifies and drops semantically unimportant tokens before returning context to Claude — and before generating Qdrant embeddings.
+
+Enable in `lucid.config.json`:
+
+```json
+{
+  "semanticCompression": {
+    "enabled": true,
+    "ratio": 0.5,
+    "minLength": 300,
+    "applyToEmbeddings": true
+  }
+}
+```
+
+| Key | Default | Description |
+|---|---|---|
+| `enabled` | `false` | Opt-in — model downloads ~700MB on first use |
+| `ratio` | `0.5` | Fraction of tokens to keep (0.3 = keep 30%) |
+| `minLength` | `300` | Skip compression for texts shorter than this |
+| `applyToEmbeddings` | `true` | Also compress chunk text before Qdrant embedding |
+
+Model is cached in `~/.lucid/models/` after first download. Falls back to uncompressed text on any error — safe to enable unconditionally.
+
 ### Configuration (`lucid.config.json`)
 
 Create in your project root to customize behavior:
@@ -191,9 +253,13 @@ Create in your project root to customize behavior:
 {
   "whitelistDirs": ["src", "backend", "api"],
   "blacklistDirs": ["migrations", "fixtures"],
-  "maxTokensPerFile": 400,
-  "maxContextTokens": 6000,
-  "recentWindowHours": 12
+  "maxTokensPerFile": 600,
+  "maxContextTokens": 8000,
+  "recentWindowHours": 48,
+  "semanticCompression": {
+    "enabled": false,
+    "ratio": 0.5
+  }
 }
 ```
 
@@ -201,9 +267,9 @@ Create in your project root to customize behavior:
 |---|---|---|
 | `whitelistDirs` | — | Only index/return files from these dirs |
 | `blacklistDirs` | — | Extra dirs to skip (merged with built-in skips) |
-| `maxTokensPerFile` | `400` | Files above this get skeleton treatment |
-| `maxContextTokens` | `4000` | Total token budget for `get_context` |
-| `recentWindowHours` | `24` | "Recently touched" threshold |
+| `maxTokensPerFile` | `600` | Files above this get skeleton treatment |
+| `maxContextTokens` | `8000` | Total token budget for `get_context` |
+| `recentWindowHours` | `48` | "Recently touched" threshold |
 
 ## Why no vectors by default?
 
@@ -237,6 +303,63 @@ TF-IDF is fast, deterministic, and requires zero external services. Qdrant is av
 ## Relation types
 `uses` · `depends_on` · `created_by` · `part_of` · `replaced_by` · `conflicts_with` · `tested_by`
 
+## HTTP daemon & auto-sync
+
+Lucid can run as a background HTTP daemon (port 7821) for auto-syncing files without Claude's cooperation.
+
+```bash
+# Start daemon (watches for sync requests, serves REST API)
+lucid watch
+
+# With HTTP server
+lucid watch --http
+
+# Check status
+lucid status
+
+# Stop
+lucid stop
+```
+
+### REST API (when `--http` is active)
+
+| Endpoint | Description |
+|---|---|
+| `POST /sync` `{ path }` | Sync a single file |
+| `POST /sync-project` `{ directory? }` | Sync entire project |
+| `GET /context?q=<query>` | Get context via HTTP |
+| `POST /validate` `{ path }` | Validate file for drift |
+| `GET /health` | Daemon health check |
+
+### Auto-sync hook (`lucid-sync`)
+
+`init_project` installs a Claude Code `PostToolUse` hook that calls `lucid-sync` after every file write/edit. The sync binary:
+
+1. Tries HTTP sync (500ms timeout, if daemon running)
+2. Falls back to direct SQLite sync (no daemon needed)
+
+This keeps the knowledge graph current automatically — without relying on Claude remembering to call `sync_file`.
+
+## Skills enforcement
+
+Lucid ships **enforcement skills** that install globally into `~/.claude/skills/` and activate in every project:
+
+| Skill | Purpose |
+|---|---|
+| `lucid-start` | Session start — `get_recent` + `smart_context` before any coding |
+| `lucid-context` | Pre-task context loading — `suggest_model` + `smart_context` |
+| `lucid-audit` | Pre-done gate — validate + check drift before marking complete |
+| `lucid-plan` | Planning workflow |
+| `lucid-sync` | Post-edit sync reminder |
+| `lucid-webdev` | Web dev workflow with context |
+
+All skills use `<HARD-GATE>` blocks that prevent proceeding until required tools are called.
+
+Install globally:
+```bash
+init_project()   # installs skills to ~/.claude/skills/ automatically
+```
+
 ## Debugging
 
 ```bash
@@ -244,7 +367,7 @@ echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"capabilities":{},
   | npx @a13xu/lucid
 ```
 
-In Claude Code: run `/mcp` — you should see `lucid` with 20 tools.
+In Claude Code: run `/mcp` — you should see `lucid` with 37 tools.
 
 ## Contributing
 
@@ -260,8 +383,11 @@ Bug reports and pull requests are welcome on [GitHub](https://github.com/a13xu/l
 - **Runtime:** Node.js 18+, TypeScript, ES modules
 - **MCP SDK:** `@modelcontextprotocol/sdk`
 - **Database:** `better-sqlite3` (synchronous, WAL mode)
-- **Compression:** Node.js built-in `zlib` (deflate level 9)
+- **Compression:** Node.js built-in `zlib` (deflate level 9) + LLMLingua-2 semantic compression (optional)
 - **Hashing:** SHA-256 via `crypto` (change detection)
 - **Ranking:** TF-IDF (built-in) or Qdrant (optional, via REST)
+- **Semantic compression:** `@huggingface/transformers` (ONNX Runtime, q8 quantization)
+- **HTTP daemon:** Express 5 on port 7821 (optional)
+- **File watcher:** `chokidar`
 - **Validation:** `zod`
 - **Transport:** stdio

package/build/compression/semantic.js

@@ -13,7 +13,11 @@
 import { join } from "path";
 import { homedir } from "os";
 import { mkdirSync } from "fs";
-const MODEL_ID = "microsoft/llmlingua-2-bert-base-multilingual-cased-meetingbank";
+// Microsoft's original repo ships only PyTorch weights, so transformers.js
+// (ONNX Runtime) cannot load it. ldenoue/* mirrors the same checkpoint with
+// pre-built `onnx/model.onnx` (710 MB) and `onnx/model_quantized.onnx` (179 MB),
+// matching the dtype lookups used below.
+const MODEL_ID = "ldenoue/llmlingua-2-bert-base-multilingual-cased-meetingbank";
 const MODELS_DIR = join(homedir(), ".lucid", "models");
 let _pipeline = null;
 let _loadError = null;

package/build/guardian/checklist.d.ts

@@ -1 +1,2 @@
-export declare const CHECKLIST = "# Logic Guardian \u2014 Validation Checklist (5 passes)\n\n## Pass 1: Logic Trace\nTrace through the code with CONCRETE values:\n- Happy path   \u2192 real values, write each variable state\n- Empty/zero   \u2192 null, 0, \"\", []\n- Boundary     \u2192 first element, last element, max int, single char\n- Error case   \u2192 network down, file missing, permission denied\n\nSTOP if any trace produces unexpected output. Fix before continuing.\n\n## Pass 2: Contract Verification\n- [ ] Preconditions: what must be true BEFORE this runs? Is it checked?\n- [ ] Postconditions: what must be true AFTER? Can you prove it?\n- [ ] Invariants: what must ALWAYS be true? Does the code maintain it?\n- [ ] Return type: does EVERY code path return the expected type?\n- [ ] Side effects: are all side effects intentional?\n\n## Pass 3: Stupid Mistakes Checklist\n\n### Off-by-one\n- [ ] < vs <= \u2014 verify with boundary values\n- [ ] Array indices \u2014 last is length - 1\n- [ ] Loop iterations \u2014 exactly N times?\n\n### Null/Undefined Propagation\n- [ ] Every .property access \u2014 can the object be null?\n- [ ] Every array index \u2014 can the array be empty?\n- [ ] Every map lookup \u2014 can the key be missing?\n\n### Type Confusion\n- [ ] String vs Number comparisons\n- [ ] Integer vs Float division\n- [ ] Boolean coercion edge cases\n\n### Logic Inversions (THE #1 LLM drift pattern)\n- [ ] if/else \u2014 is the condition testing what you THINK?\n- [ ] Early returns \u2014 does the guard return the RIGHT value?\n- [ ] filter/find/some \u2014 keeping the RIGHT elements?\n- [ ] Error handling \u2014 catching and re-throwing correctly?\n\n### State & Mutation\n- [ ] Mutating shared object when you should copy?\n- [ ] Async state read after it might have changed?\n\n### Copy-Paste Drift\n- [ ] ALL variable names updated in copied blocks?\n- [ ] Conditions changed, not just variable names?\n\n## Pass 4: Integration Sanity\n- [ ] Breaks existing callers?\n- [ ] Imports/exports correct?\n- [ ] If async, all callers awaiting it?\n- [ ] If type changed, all usages updated?\n\n## Pass 5: Explain It Test\nIn ONE sentence: what does this code do?\nIf you can't explain it, or the sentence doesn't match the code \u2192 something is wrong.\n\n## Anti-Drift Triggers\nSTOP if you find yourself thinking:\n- \"This is similar to...\" \u2192 You're pattern-matching. TRACE THE LOGIC.\n- \"This should work because the other one does\" \u2192 VERIFY INDEPENDENTLY.\n- \"I'll just copy and change the names\" \u2192 CHECK EVERY DIFFERENCE.\n- \"The error handling is probably fine\" \u2192 TRACE THE ERROR PATH.\n- \"This is standard boilerplate\" \u2192 Verify it fits this context.\n";
+export declare const ORIGINAL_CHECKLIST = "# Logic Guardian \u2014 Validation Checklist (5 passes)\n\n## Pass 1: Logic Trace\nTrace through the code with CONCRETE values:\n- Happy path   \u2192 real values, write each variable state\n- Empty/zero   \u2192 null, 0, \"\", []\n- Boundary     \u2192 first element, last element, max int, single char\n- Error case   \u2192 network down, file missing, permission denied\n\nSTOP if any trace produces unexpected output. Fix before continuing.\n\n## Pass 2: Contract Verification\n- [ ] Preconditions: what must be true BEFORE this runs? Is it checked?\n- [ ] Postconditions: what must be true AFTER? Can you prove it?\n- [ ] Invariants: what must ALWAYS be true? Does the code maintain it?\n- [ ] Return type: does EVERY code path return the expected type?\n- [ ] Side effects: are all side effects intentional?\n\n## Pass 3: Stupid Mistakes Checklist\n\n### Off-by-one\n- [ ] < vs <= \u2014 verify with boundary values\n- [ ] Array indices \u2014 last is length - 1\n- [ ] Loop iterations \u2014 exactly N times?\n\n### Null/Undefined Propagation\n- [ ] Every .property access \u2014 can the object be null?\n- [ ] Every array index \u2014 can the array be empty?\n- [ ] Every map lookup \u2014 can the key be missing?\n\n### Type Confusion\n- [ ] String vs Number comparisons\n- [ ] Integer vs Float division\n- [ ] Boolean coercion edge cases\n\n### Logic Inversions (THE #1 LLM drift pattern)\n- [ ] if/else \u2014 is the condition testing what you THINK?\n- [ ] Early returns \u2014 does the guard return the RIGHT value?\n- [ ] filter/find/some \u2014 keeping the RIGHT elements?\n- [ ] Error handling \u2014 catching and re-throwing correctly?\n\n### State & Mutation\n- [ ] Mutating shared object when you should copy?\n- [ ] Async state read after it might have changed?\n\n### Copy-Paste Drift\n- [ ] ALL variable names updated in copied blocks?\n- [ ] Conditions changed, not just variable names?\n\n## Pass 4: Integration Sanity\n- [ ] Breaks existing callers?\n- [ ] Imports/exports correct?\n- [ ] If async, all callers awaiting it?\n- [ ] If type changed, all usages updated?\n\n## Pass 5: Explain It Test\nIn ONE sentence: what does this code do?\nIf you can't explain it, or the sentence doesn't match the code \u2192 something is wrong.\n\n## Anti-Drift Triggers\nSTOP if you find yourself thinking:\n- \"This is similar to...\" \u2192 You're pattern-matching. TRACE THE LOGIC.\n- \"This should work because the other one does\" \u2192 VERIFY INDEPENDENTLY.\n- \"I'll just copy and change the names\" \u2192 CHECK EVERY DIFFERENCE.\n- \"The error handling is probably fine\" \u2192 TRACE THE ERROR PATH.\n- \"This is standard boilerplate\" \u2192 Verify it fits this context.\n";
+export declare const CHECKLIST: string;

package/build/guardian/checklist.js

@@ -1,4 +1,7 @@
-export const CHECKLIST = `# Logic Guardian — Validation Checklist (5 passes)
+import { join } from "path";
+import { homedir } from "os";
+import { existsSync, readFileSync } from "fs";
+export const ORIGINAL_CHECKLIST = `# Logic Guardian — Validation Checklist (5 passes)
 
 ## Pass 1: Logic Trace
 Trace through the code with CONCRETE values:
@@ -65,3 +68,19 @@ STOP if you find yourself thinking:
 - "The error handling is probably fine" → TRACE THE ERROR PATH.
 - "This is standard boilerplate" → Verify it fits this context.
 `;
+// Opt-in: if a pre-compressed copy exists at ~/.lucid/compressed-prompts/checklist.txt
+// (produced by `npm run compress-prompts`), serve that instead. Falls back to the
+// original on any error so this is always safe.
+function loadCompressed() {
+    try {
+        const p = join(homedir(), ".lucid", "compressed-prompts", "checklist.txt");
+        if (!existsSync(p))
+            return null;
+        const text = readFileSync(p, "utf-8").trim();
+        return text.length > 0 ? text : null;
+    }
+    catch {
+        return null;
+    }
+}
+export const CHECKLIST = loadCompressed() ?? ORIGINAL_CHECKLIST;

package/build/guardian/coding-rules.d.ts

@@ -1 +1,2 @@
-export declare const CODING_RULES = "# 25 Golden Rules \u2014 Code Quality Checklist\n\n## Section 1: General Quality (Rules 1\u201310)\n\n- [ ] **Rule 1 \u2014 File Size**: File is under 500 lines (components under 300).\n      PASS: file has fewer lines. FAIL: file exceeds limit \u2014 split into modules.\n\n- [ ] **Rule 2 \u2014 Function Length**: Every function/method is under 60 lines.\n      PASS: function is focused and short. FAIL: function exceeds 60 lines \u2014 break it up.\n\n- [ ] **Rule 3 \u2014 Meaningful Names**: No vague variable names (x, tmp, data, val, obj, foo, bar).\n      No vague function names (doSomething, handleStuff, processData, manage, doWork).\n      PASS: names explain purpose. FAIL: name is a placeholder \u2014 rename to intent.\n\n- [ ] **Rule 4 \u2014 Single Responsibility**: Functions/methods do exactly ONE thing.\n      If the name contains \"And\" or \"Or\", it is doing two things.\n      PASS: one verb, one concept. FAIL: split into two functions.\n\n- [ ] **Rule 5 \u2014 No Dead Code**: No commented-out code blocks (3+ consecutive lines with =, (, {, ;).\n      PASS: code is live. FAIL: remove dead code \u2014 use version control for history.\n\n- [ ] **Rule 6 \u2014 Explicit Error Handling**: Errors are caught, logged, or re-thrown.\n      No silent swallowing (catch {} or except: pass).\n      PASS: every error path is handled. FAIL: add logging or re-throw.\n\n- [ ] **Rule 7 \u2014 No Magic Numbers**: Numeric literals are replaced with named constants.\n      PASS: constants have descriptive names. FAIL: extract to a named constant.\n\n- [ ] **Rule 8 \u2014 Max 3 Nesting Levels**: Code is not nested more than 3 levels deep.\n      PASS: deepest indent is 3 levels. FAIL: extract logic or use early returns.\n\n- [ ] **Rule 9 \u2014 DRY (Don't Repeat Yourself)**: No near-duplicate blocks of code.\n      PASS: logic is extracted into a shared function. FAIL: refactor duplicates.\n\n- [ ] **Rule 10 \u2014 Explicit Return Types**: Typed languages declare return types on public functions.\n      PASS: all public functions have explicit return types. FAIL: add return type annotation.\n\n## Section 2: Frontend Components (Rules 11\u201318)\n\n- [ ] **Rule 11 \u2014 Component Size**: UI components are under 300 lines.\n      PASS: component is focused. FAIL: extract sub-components or custom hooks.\n\n- [ ] **Rule 12 \u2014 No Inline Styles**: No style={{ }} in JSX/Vue templates.\n      PASS: styles are in CSS/SCSS/CSS-in-JS. FAIL: move to stylesheet or styled component.\n\n- [ ] **Rule 13 \u2014 Prop Limit**: Components accept at most 8 props.\n      PASS: props are few and cohesive. FAIL: group related props into an object.\n\n- [ ] **Rule 14 \u2014 Prefer Composition**: Large components are split into sub-components.\n      No \"god components\" handling layout + data + formatting + interaction.\n      PASS: each component has one visual/logical role. FAIL: extract a sub-component.\n\n- [ ] **Rule 15 \u2014 No Direct DOM Access**: No document.querySelector / getElementById in components.\n      PASS: refs are used (useRef, ref=). FAIL: replace with ref mechanism.\n\n- [ ] **Rule 16 \u2014 Data Fetching in Services/Hooks**: No fetch() or axios calls in component body.\n      PASS: data fetching is in a custom hook or service. FAIL: extract to useXxx hook.\n\n- [ ] **Rule 17 \u2014 One Styling System**: File uses only one styling approach\n      (Tailwind OR styled-components OR CSS modules \u2014 not all three).\n      PASS: consistent styling. FAIL: standardize on one approach.\n\n- [ ] **Rule 18 \u2014 No Nested Ternaries in JSX**: JSX conditionals use if/else or variables, not nested ternaries.\n      PASS: conditions are readable. FAIL: extract condition to a variable or early return.\n\n## Section 3: Architecture (Rules 19\u201325)\n\n- [ ] **Rule 19 \u2014 Single Source of Truth**: State is not duplicated across multiple stores or components.\n      PASS: one authoritative source for each piece of state. FAIL: remove duplication.\n\n- [ ] **Rule 20 \u2014 UI/Logic Separation**: Business logic is not inside UI components.\n      PASS: components call services/hooks; logic lives elsewhere. FAIL: extract to service.\n\n- [ ] **Rule 21 \u2014 Dependency Abstraction**: External APIs/SDKs are wrapped in adapter/service layers.\n      PASS: swapping a library touches one file. FAIL: add an abstraction layer.\n\n- [ ] **Rule 22 \u2014 No Circular Imports**: Module dependency graph is a DAG (no cycles).\n      PASS: import graph has no cycles. FAIL: restructure modules to remove the cycle.\n\n- [ ] **Rule 23 \u2014 Config in Dedicated Files**: Magic strings and environment-specific values are in config files.\n      PASS: config is centralized. FAIL: extract to config.ts or .env.\n\n- [ ] **Rule 24 \u2014 Public API Coverage**: Every exported function has a corresponding test.\n      PASS: public API is covered by tests. FAIL: write a test for the new export.\n\n- [ ] **Rule 25 \u2014 No God Objects**: Classes/modules are focused \u2014 no object that knows everything.\n      PASS: objects have clear, narrow responsibilities. FAIL: split the god object.\n\n---\n\n## Quick Check Before Marking Done\n\n1. Run `check_code_quality` on modified files \u2014 fix HIGH severity issues.\n2. Run `validate_file` (Logic Guardian) \u2014 fix correctness bugs first.\n3. Verify rules 3, 4, 8 manually (naming and nesting are hard to auto-detect fully).\n4. For frontend work, verify rules 12, 15, 16 \u2014 these are the most common oversights.\n";
+export declare const ORIGINAL_CODING_RULES = "# 25 Golden Rules \u2014 Code Quality Checklist\n\n## Section 1: General Quality (Rules 1\u201310)\n\n- [ ] **Rule 1 \u2014 File Size**: File is under 500 lines (components under 300).\n      PASS: file has fewer lines. FAIL: file exceeds limit \u2014 split into modules.\n\n- [ ] **Rule 2 \u2014 Function Length**: Every function/method is under 60 lines.\n      PASS: function is focused and short. FAIL: function exceeds 60 lines \u2014 break it up.\n\n- [ ] **Rule 3 \u2014 Meaningful Names**: No vague variable names (x, tmp, data, val, obj, foo, bar).\n      No vague function names (doSomething, handleStuff, processData, manage, doWork).\n      PASS: names explain purpose. FAIL: name is a placeholder \u2014 rename to intent.\n\n- [ ] **Rule 4 \u2014 Single Responsibility**: Functions/methods do exactly ONE thing.\n      If the name contains \"And\" or \"Or\", it is doing two things.\n      PASS: one verb, one concept. FAIL: split into two functions.\n\n- [ ] **Rule 5 \u2014 No Dead Code**: No commented-out code blocks (3+ consecutive lines with =, (, {, ;).\n      PASS: code is live. FAIL: remove dead code \u2014 use version control for history.\n\n- [ ] **Rule 6 \u2014 Explicit Error Handling**: Errors are caught, logged, or re-thrown.\n      No silent swallowing (catch {} or except: pass).\n      PASS: every error path is handled. FAIL: add logging or re-throw.\n\n- [ ] **Rule 7 \u2014 No Magic Numbers**: Numeric literals are replaced with named constants.\n      PASS: constants have descriptive names. FAIL: extract to a named constant.\n\n- [ ] **Rule 8 \u2014 Max 3 Nesting Levels**: Code is not nested more than 3 levels deep.\n      PASS: deepest indent is 3 levels. FAIL: extract logic or use early returns.\n\n- [ ] **Rule 9 \u2014 DRY (Don't Repeat Yourself)**: No near-duplicate blocks of code.\n      PASS: logic is extracted into a shared function. FAIL: refactor duplicates.\n\n- [ ] **Rule 10 \u2014 Explicit Return Types**: Typed languages declare return types on public functions.\n      PASS: all public functions have explicit return types. FAIL: add return type annotation.\n\n## Section 2: Frontend Components (Rules 11\u201318)\n\n- [ ] **Rule 11 \u2014 Component Size**: UI components are under 300 lines.\n      PASS: component is focused. FAIL: extract sub-components or custom hooks.\n\n- [ ] **Rule 12 \u2014 No Inline Styles**: No style={{ }} in JSX/Vue templates.\n      PASS: styles are in CSS/SCSS/CSS-in-JS. FAIL: move to stylesheet or styled component.\n\n- [ ] **Rule 13 \u2014 Prop Limit**: Components accept at most 8 props.\n      PASS: props are few and cohesive. FAIL: group related props into an object.\n\n- [ ] **Rule 14 \u2014 Prefer Composition**: Large components are split into sub-components.\n      No \"god components\" handling layout + data + formatting + interaction.\n      PASS: each component has one visual/logical role. FAIL: extract a sub-component.\n\n- [ ] **Rule 15 \u2014 No Direct DOM Access**: No document.querySelector / getElementById in components.\n      PASS: refs are used (useRef, ref=). FAIL: replace with ref mechanism.\n\n- [ ] **Rule 16 \u2014 Data Fetching in Services/Hooks**: No fetch() or axios calls in component body.\n      PASS: data fetching is in a custom hook or service. FAIL: extract to useXxx hook.\n\n- [ ] **Rule 17 \u2014 One Styling System**: File uses only one styling approach\n      (Tailwind OR styled-components OR CSS modules \u2014 not all three).\n      PASS: consistent styling. FAIL: standardize on one approach.\n\n- [ ] **Rule 18 \u2014 No Nested Ternaries in JSX**: JSX conditionals use if/else or variables, not nested ternaries.\n      PASS: conditions are readable. FAIL: extract condition to a variable or early return.\n\n## Section 3: Architecture (Rules 19\u201325)\n\n- [ ] **Rule 19 \u2014 Single Source of Truth**: State is not duplicated across multiple stores or components.\n      PASS: one authoritative source for each piece of state. FAIL: remove duplication.\n\n- [ ] **Rule 20 \u2014 UI/Logic Separation**: Business logic is not inside UI components.\n      PASS: components call services/hooks; logic lives elsewhere. FAIL: extract to service.\n\n- [ ] **Rule 21 \u2014 Dependency Abstraction**: External APIs/SDKs are wrapped in adapter/service layers.\n      PASS: swapping a library touches one file. FAIL: add an abstraction layer.\n\n- [ ] **Rule 22 \u2014 No Circular Imports**: Module dependency graph is a DAG (no cycles).\n      PASS: import graph has no cycles. FAIL: restructure modules to remove the cycle.\n\n- [ ] **Rule 23 \u2014 Config in Dedicated Files**: Magic strings and environment-specific values are in config files.\n      PASS: config is centralized. FAIL: extract to config.ts or .env.\n\n- [ ] **Rule 24 \u2014 Public API Coverage**: Every exported function has a corresponding test.\n      PASS: public API is covered by tests. FAIL: write a test for the new export.\n\n- [ ] **Rule 25 \u2014 No God Objects**: Classes/modules are focused \u2014 no object that knows everything.\n      PASS: objects have clear, narrow responsibilities. FAIL: split the god object.\n\n---\n\n## Quick Check Before Marking Done\n\n1. Run `check_code_quality` on modified files \u2014 fix HIGH severity issues.\n2. Run `validate_file` (Logic Guardian) \u2014 fix correctness bugs first.\n3. Verify rules 3, 4, 8 manually (naming and nesting are hard to auto-detect fully).\n4. For frontend work, verify rules 12, 15, 16 \u2014 these are the most common oversights.\n";
+export declare const CODING_RULES: string;

package/build/guardian/coding-rules.js

@@ -1,4 +1,7 @@
-export const CODING_RULES = `# 25 Golden Rules — Code Quality Checklist
+import { join } from "path";
+import { homedir } from "os";
+import { existsSync, readFileSync } from "fs";
+export const ORIGINAL_CODING_RULES = `# 25 Golden Rules — Code Quality Checklist
 
 ## Section 1: General Quality (Rules 1–10)
 
@@ -95,3 +98,19 @@ export const CODING_RULES = `# 25 Golden Rules — Code Quality Checklist
 3. Verify rules 3, 4, 8 manually (naming and nesting are hard to auto-detect fully).
 4. For frontend work, verify rules 12, 15, 16 — these are the most common oversights.
 `;
+// Opt-in: if a pre-compressed copy exists at ~/.lucid/compressed-prompts/coding-rules.txt
+// (produced by `npm run compress-prompts`), serve that instead. Falls back to the
+// original on any error so this is always safe.
+function loadCompressed() {
+    try {
+        const p = join(homedir(), ".lucid", "compressed-prompts", "coding-rules.txt");
+        if (!existsSync(p))
+            return null;
+        const text = readFileSync(p, "utf-8").trim();
+        return text.length > 0 ? text : null;
+    }
+    catch {
+        return null;
+    }
+}
+export const CODING_RULES = loadCompressed() ?? ORIGINAL_CODING_RULES;