@a13xu/lucid 1.16.1 → 1.19.0

package/README.md

@@ -96,7 +96,7 @@ Default DB path: `~/.claude/memory.db`
 | `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 (`todo` → `in_progress` → `done`) and optionally add notes. |
+| `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 |

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/database.d.ts

@@ -45,6 +45,36 @@ export interface PlanRow {
     created_at: number;
     updated_at: number;
 }
+export interface FileBackupRow {
+    id: number;
+    filepath: string;
+    content: Buffer;
+    content_hash: string;
+    original_size: number;
+    compressed_size: number;
+    reason: string;
+    created_at: number;
+}
+export interface CliSessionRow {
+    session_id: string;
+    started_at: number;
+    last_activity_at: number;
+    prompt_count: number;
+    last_compact_hint_at: number | null;
+    last_clear_hint_at: number | null;
+    last_compact_event_at: number | null;
+    compact_count: number;
+    cwd: string | null;
+}
+export interface TruncateEventRow {
+    id: number;
+    filepath: string;
+    prev_size: number;
+    new_size: number;
+    shrink_ratio: number;
+    blocked: number;
+    created_at: number;
+}
 export interface PlanTaskRow {
     id: number;
     plan_id: number;
@@ -115,6 +145,27 @@ export interface Statements {
     countRemainingTasks: Stmt<[number], {
         count: number;
     }>;
+    insertBackup: WriteStmt<[string, Buffer, string, number, number, string]>;
+    getBackupsByPath: Stmt<[string], FileBackupRow>;
+    getLatestBackup: Stmt<[string], FileBackupRow>;
+    getBackupById: Stmt<[number], FileBackupRow>;
+    deleteOldBackups: WriteStmt<[string, string, number]>;
+    countBackups: Stmt<[string], {
+        count: number;
+    }>;
+    insertTruncateEvent: WriteStmt<[string, number, number, number, number]>;
+    recentTruncateEvents: Stmt<[number], TruncateEventRow>;
+    countRecentTruncates: Stmt<[number], {
+        count: number;
+    }>;
+    getCliSession: Stmt<[string], CliSessionRow>;
+    insertCliSession: WriteStmt<[string, number, number, string | null]>;
+    tickCliSession: WriteStmt<[number, string]>;
+    markCompactHint: WriteStmt<[number, string]>;
+    markClearHint: WriteStmt<[number, string]>;
+    markCompactEvent: WriteStmt<[number, string]>;
+    recentCliSessions: Stmt<[number], CliSessionRow>;
+    resetCliSessionCount: WriteStmt<[string]>;
 }
 export declare function prepareStatements(db: Database.Database): Statements;
 export {};

package/build/database.js

@@ -170,6 +170,46 @@ function createSchema(db) {
 
     CREATE INDEX IF NOT EXISTS idx_plan_tasks_plan ON plan_tasks(plan_id, seq);
     CREATE INDEX IF NOT EXISTS idx_plans_status    ON plans(status);
+
+    -- Versioned backups of file content (last N kept per file)
+    CREATE TABLE IF NOT EXISTS file_backups (
+      id              INTEGER PRIMARY KEY,
+      filepath        TEXT NOT NULL,
+      content         BLOB NOT NULL,
+      content_hash    TEXT NOT NULL,
+      original_size   INTEGER NOT NULL,
+      compressed_size INTEGER NOT NULL,
+      reason          TEXT NOT NULL DEFAULT 'manual',
+      created_at      INTEGER NOT NULL DEFAULT (unixepoch())
+    );
+    CREATE INDEX IF NOT EXISTS idx_fb_path     ON file_backups(filepath, created_at DESC);
+    CREATE INDEX IF NOT EXISTS idx_fb_created  ON file_backups(created_at);
+
+    -- Claude Code session tracking — drives /compact and /clear hints
+    CREATE TABLE IF NOT EXISTS cli_sessions (
+      session_id              TEXT PRIMARY KEY,
+      started_at              INTEGER NOT NULL,
+      last_activity_at        INTEGER NOT NULL,
+      prompt_count            INTEGER NOT NULL DEFAULT 0,
+      last_compact_hint_at    INTEGER,
+      last_clear_hint_at      INTEGER,
+      last_compact_event_at   INTEGER,
+      compact_count           INTEGER NOT NULL DEFAULT 0,
+      cwd                     TEXT
+    );
+    CREATE INDEX IF NOT EXISTS idx_cli_sessions_activity ON cli_sessions(last_activity_at DESC);
+
+    -- Truncate-event log (drives cascade detection)
+    CREATE TABLE IF NOT EXISTS truncate_events (
+      id           INTEGER PRIMARY KEY,
+      filepath     TEXT NOT NULL,
+      prev_size    INTEGER NOT NULL,
+      new_size     INTEGER NOT NULL,
+      shrink_ratio REAL NOT NULL,
+      blocked      INTEGER NOT NULL DEFAULT 1,
+      created_at   INTEGER NOT NULL DEFAULT (unixepoch())
+    );
+    CREATE INDEX IF NOT EXISTS idx_te_created ON truncate_events(created_at DESC);
   `);
 }
 export function prepareStatements(db) {
@@ -261,5 +301,51 @@ export function prepareStatements(db) {
         getTaskById: db.prepare("SELECT * FROM plan_tasks WHERE id = ?"),
         updateTaskStatus: db.prepare("UPDATE plan_tasks SET status = ?, notes = ?, updated_at = unixepoch() WHERE id = ?"),
         countRemainingTasks: db.prepare("SELECT COUNT(*) as count FROM plan_tasks WHERE plan_id = ? AND status != 'done'"),
+        // file_backups
+        insertBackup: db.prepare(`INSERT INTO file_backups (filepath, content, content_hash, original_size, compressed_size, reason)
+       VALUES (?, ?, ?, ?, ?, ?)`),
+        getBackupsByPath: db.prepare("SELECT * FROM file_backups WHERE filepath = ? ORDER BY created_at DESC, id DESC"),
+        getLatestBackup: db.prepare("SELECT * FROM file_backups WHERE filepath = ? ORDER BY created_at DESC, id DESC LIMIT 1"),
+        getBackupById: db.prepare("SELECT * FROM file_backups WHERE id = ?"),
+        deleteOldBackups: db.prepare(`DELETE FROM file_backups
+       WHERE filepath = ?
+         AND id NOT IN (
+           SELECT id FROM file_backups
+           WHERE filepath = ?
+           ORDER BY created_at DESC, id DESC
+           LIMIT ?
+         )`),
+        countBackups: db.prepare("SELECT COUNT(*) as count FROM file_backups WHERE filepath = ?"),
+        // truncate_events
+        insertTruncateEvent: db.prepare(`INSERT INTO truncate_events (filepath, prev_size, new_size, shrink_ratio, blocked)
+       VALUES (?, ?, ?, ?, ?)`),
+        recentTruncateEvents: db.prepare("SELECT * FROM truncate_events WHERE created_at >= ? ORDER BY created_at DESC"),
+        countRecentTruncates: db.prepare("SELECT COUNT(*) as count FROM truncate_events WHERE created_at >= ? AND blocked = 1"),
+        // cli_sessions
+        getCliSession: db.prepare("SELECT * FROM cli_sessions WHERE session_id = ?"),
+        insertCliSession: db.prepare(`INSERT INTO cli_sessions (session_id, started_at, last_activity_at, prompt_count, cwd)
+       VALUES (?, ?, ?, 1, ?)
+       ON CONFLICT(session_id) DO UPDATE SET
+         last_activity_at = excluded.last_activity_at,
+         prompt_count     = cli_sessions.prompt_count + 1`),
+        tickCliSession: db.prepare(`UPDATE cli_sessions SET
+         last_activity_at = ?,
+         prompt_count     = prompt_count + 1
+       WHERE session_id = ?`),
+        markCompactHint: db.prepare("UPDATE cli_sessions SET last_compact_hint_at = ? WHERE session_id = ?"),
+        markClearHint: db.prepare("UPDATE cli_sessions SET last_clear_hint_at = ? WHERE session_id = ?"),
+        markCompactEvent: db.prepare(`UPDATE cli_sessions SET
+         last_compact_event_at = ?,
+         compact_count         = compact_count + 1,
+         prompt_count          = 0,
+         last_compact_hint_at  = NULL,
+         last_clear_hint_at    = NULL
+       WHERE session_id = ?`),
+        recentCliSessions: db.prepare("SELECT * FROM cli_sessions ORDER BY last_activity_at DESC LIMIT ?"),
+        resetCliSessionCount: db.prepare(`UPDATE cli_sessions SET
+         prompt_count = 0,
+         last_compact_hint_at = NULL,
+         last_clear_hint_at   = NULL
+       WHERE session_id = ?`),
     };
 }

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;

package/build/guardian/session-tracker.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Session Tracker — emits hints to invoke /compact or /clear when a Claude Code
+ * session grows expensive. Driven by UserPromptSubmit and PreCompact hooks.
+ *
+ * Cost model: Anthropic prompt cache has a 5-minute TTL. Beyond that the next
+ * turn re-reads the entire transcript. Long sessions also pay per-turn linearly
+ * with transcript length even when warm. Two pressures, two hints:
+ *
+ *   1) prompt_count >= COMPACT_HINT_AT  → suggest /compact (re-emitted every N).
+ *   2) prompt_count >= CLEAR_HINT_AT    → suggest /clear  (one-shot).
+ *   3) idle > CACHE_STALE_SECONDS       → cache cold; warn next turn re-bills.
+ *
+ * Emitted hints are written to STDOUT so the UserPromptSubmit hook injects them
+ * into Claude's context (Claude Code convention). Empty stdout = no hint.
+ */
+import type { Statements } from "../database.js";
+export interface SessionTickResult {
+    session_id: string;
+    prompt_count: number;
+    hints: string[];
+    cache_likely_cold: boolean;
+    idle_seconds: number;
+}
+/** Fired once per UserPromptSubmit. Returns hints to surface to Claude. */
+export declare function tickSession(stmts: Statements, sessionId: string, cwd: string | null): SessionTickResult;
+/** Fired by PreCompact hook — resets per-session counters. */
+export declare function markCompactEvent(stmts: Statements, sessionId: string): void;
+export declare const SESSION_TUNABLES: {
+    readonly COMPACT_HINT_AT: number;
+    readonly COMPACT_HINT_EVERY: number;
+    readonly CLEAR_HINT_AT: number;
+    readonly CACHE_STALE_SECONDS: number;
+    readonly IDLE_HINT_MIN_PROMPTS: 5;
+};

package/build/guardian/session-tracker.js

@@ -0,0 +1,105 @@
+/**
+ * Session Tracker — emits hints to invoke /compact or /clear when a Claude Code
+ * session grows expensive. Driven by UserPromptSubmit and PreCompact hooks.
+ *
+ * Cost model: Anthropic prompt cache has a 5-minute TTL. Beyond that the next
+ * turn re-reads the entire transcript. Long sessions also pay per-turn linearly
+ * with transcript length even when warm. Two pressures, two hints:
+ *
+ *   1) prompt_count >= COMPACT_HINT_AT  → suggest /compact (re-emitted every N).
+ *   2) prompt_count >= CLEAR_HINT_AT    → suggest /clear  (one-shot).
+ *   3) idle > CACHE_STALE_SECONDS       → cache cold; warn next turn re-bills.
+ *
+ * Emitted hints are written to STDOUT so the UserPromptSubmit hook injects them
+ * into Claude's context (Claude Code convention). Empty stdout = no hint.
+ */
+const num = (envKey, fallback) => {
+    const v = process.env[envKey];
+    if (!v)
+        return fallback;
+    const n = Number(v);
+    return Number.isFinite(n) && n > 0 ? n : fallback;
+};
+const COMPACT_HINT_AT = num("LUCID_COMPACT_HINT_AT", 15);
+const COMPACT_HINT_EVERY = num("LUCID_COMPACT_HINT_EVERY", 10);
+const CLEAR_HINT_AT = num("LUCID_CLEAR_HINT_AT", 30);
+const CACHE_STALE_SECONDS = num("LUCID_CACHE_STALE_SECONDS", 300);
+/** Below this many prompts, idle gaps don't matter — short session, cheap. */
+const IDLE_HINT_MIN_PROMPTS = 5;
+/** Fired once per UserPromptSubmit. Returns hints to surface to Claude. */
+export function tickSession(stmts, sessionId, cwd) {
+    if (process.env["LUCID_SESSION_HINTS_DISABLED"] === "1") {
+        return { session_id: sessionId, prompt_count: 0, hints: [], cache_likely_cold: false, idle_seconds: 0 };
+    }
+    const now = Math.floor(Date.now() / 1000);
+    const existing = stmts.getCliSession.get(sessionId);
+    if (!existing) {
+        stmts.insertCliSession.run(sessionId, now, now, cwd);
+        return { session_id: sessionId, prompt_count: 1, hints: [], cache_likely_cold: false, idle_seconds: 0 };
+    }
+    const idleSeconds = now - existing.last_activity_at;
+    const cacheCold = idleSeconds > CACHE_STALE_SECONDS;
+    stmts.tickCliSession.run(now, sessionId);
+    const newCount = existing.prompt_count + 1;
+    const hints = [];
+    // ── /compact hint: at threshold, then every N prompts after ────────────────
+    const compactDue = newCount === COMPACT_HINT_AT ||
+        (newCount > COMPACT_HINT_AT &&
+            (newCount - COMPACT_HINT_AT) % COMPACT_HINT_EVERY === 0);
+    if (compactDue) {
+        hints.push(formatCompactHint(newCount, existing.compact_count));
+        stmts.markCompactHint.run(now, sessionId);
+    }
+    // ── /clear hint: one-shot at CLEAR_HINT_AT ─────────────────────────────────
+    if (newCount >= CLEAR_HINT_AT && existing.last_clear_hint_at === null) {
+        hints.push(formatClearHint(newCount));
+        stmts.markClearHint.run(now, sessionId);
+    }
+    // ── Cache-cold hint: only meaningful past warmup ───────────────────────────
+    if (cacheCold && newCount >= IDLE_HINT_MIN_PROMPTS) {
+        hints.push(formatColdCacheHint(idleSeconds));
+    }
+    return { session_id: sessionId, prompt_count: newCount, hints, cache_likely_cold: cacheCold, idle_seconds: idleSeconds };
+}
+/** Fired by PreCompact hook — resets per-session counters. */
+export function markCompactEvent(stmts, sessionId) {
+    const now = Math.floor(Date.now() / 1000);
+    // Insert a placeholder row if hook fires before any UserPromptSubmit
+    if (!stmts.getCliSession.get(sessionId)) {
+        stmts.insertCliSession.run(sessionId, now, now, null);
+    }
+    stmts.markCompactEvent.run(now, sessionId);
+}
+// ---------------------------------------------------------------------------
+// Hint formatters — kept terse: every word costs tokens once injected.
+// ---------------------------------------------------------------------------
+function formatCompactHint(promptCount, prevCompacts) {
+    const tail = prevCompacts > 0 ? ` (${prevCompacts} prior /compact in this session)` : "";
+    return [
+        `[Lucid · session-cost]`,
+        `Session is at ${promptCount} prompts${tail}. Per-turn cost grows with transcript length even when cached.`,
+        `→ Run /compact mid-task to summarize earlier turns and reduce input tokens for the next ~${COMPACT_HINT_EVERY} prompts.`,
+    ].join(" ");
+}
+function formatClearHint(promptCount) {
+    return [
+        `[Lucid · session-cost]`,
+        `Session has reached ${promptCount} prompts.`,
+        `→ If you are switching to a new task with little overlap, prefer /clear over /compact — fresh context is cheaper than a summary.`,
+    ].join(" ");
+}
+function formatColdCacheHint(idleSeconds) {
+    const mins = Math.round(idleSeconds / 60);
+    return [
+        `[Lucid · session-cost]`,
+        `${mins}m idle: prompt cache (5-min TTL) is cold. This turn rebuilds it from scratch (~3-4× the cached cost).`,
+        `→ For long pauses, run /compact before resuming so the rebuilt cache covers a smaller transcript.`,
+    ].join(" ");
+}
+export const SESSION_TUNABLES = {
+    COMPACT_HINT_AT,
+    COMPACT_HINT_EVERY,
+    CLEAR_HINT_AT,
+    CACHE_STALE_SECONDS,
+    IDLE_HINT_MIN_PROMPTS,
+};

package/build/guardian/truncate-guard.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Truncate Guard — prevents data-loss writes (file emptied, drastically shrunk)
+ * and detects truncate cascades (≥N truncate attempts within a short window),
+ * which signal a runaway loop in automode.
+ *
+ * Two layers:
+ *   1) Per-write check: empty content over non-empty file, or new size < 30% prev.
+ *   2) Cascade lock: ≥2 blocked truncates within 60s blocks ALL further Write/Edit
+ *      until the user clears the lock (clear_truncate_lock tool or env override).
+ */
+import type { Statements } from "../database.js";
+export type TruncateRule = "EMPTY_OVERWRITE" | "WHITESPACE_ONLY" | "MAJOR_SHRINK" | "CASCADE_LOCK";
+export interface TruncateAssessment {
+    blocked: boolean;
+    rule?: TruncateRule;
+    prevSize: number;
+    newSize: number;
+    shrinkRatio: number;
+    reason?: string;
+    /** True when CASCADE_LOCK is the active reason. */
+    cascade: boolean;
+    /** Number of blocked truncates inside the cascade window. */
+    cascadeCount: number;
+}
+export declare function isCascadeBlocked(stmts: Statements): {
+    blocked: boolean;
+    count: number;
+};
+/**
+ * Assess whether writing `newContent` to `path` is a destructive truncate.
+ * Pure function — does NOT mutate state. Caller decides whether to record.
+ */
+export declare function assessTruncate(path: string, newContent: string | null, stmts: Statements): TruncateAssessment;
+/** Persist a truncate event so cascade detection can see it on the next call. */
+export declare function recordTruncateEvent(stmts: Statements, path: string, prevSize: number, newSize: number, blocked: boolean): void;
+export interface BackupResult {
+    saved: boolean;
+    reason: string;
+    size?: number;
+    hash?: string;
+}
+/**
+ * Snapshot the current on-disk file content into file_backups, then GC older
+ * versions beyond BACKUP_RETENTION. No-op if the file does not exist or is
+ * identical to the most recent backup.
+ */
+export declare function backupFile(stmts: Statements, path: string, snapshotReason?: string): BackupResult;
+export declare const TUNABLES: {
+    readonly MIN_KEEP_RATIO: 0.3;
+    readonly SMALL_FILE_BYTES: 80;
+    readonly CASCADE_WINDOW_SECONDS: 60;
+    readonly CASCADE_THRESHOLD: 2;
+    readonly BACKUP_RETENTION: 10;
+};

package/build/guardian/truncate-guard.js

@@ -0,0 +1,136 @@
+/**
+ * Truncate Guard — prevents data-loss writes (file emptied, drastically shrunk)
+ * and detects truncate cascades (≥N truncate attempts within a short window),
+ * which signal a runaway loop in automode.
+ *
+ * Two layers:
+ *   1) Per-write check: empty content over non-empty file, or new size < 30% prev.
+ *   2) Cascade lock: ≥2 blocked truncates within 60s blocks ALL further Write/Edit
+ *      until the user clears the lock (clear_truncate_lock tool or env override).
+ */
+import { existsSync, readFileSync, statSync } from "fs";
+import { resolve } from "path";
+import { compress, sha256 } from "../store/content.js";
+// ---------------------------------------------------------------------------
+// Tunables (kept local — no config knob until requested)
+// ---------------------------------------------------------------------------
+/** New content must keep ≥ this fraction of previous size, else flagged. */
+const MIN_KEEP_RATIO = 0.30;
+/** Files smaller than this are exempt — too small for ratio to be meaningful. */
+const SMALL_FILE_BYTES = 80;
+/** Cascade window: how far back we look for blocked truncate events. */
+const CASCADE_WINDOW_SECONDS = 60;
+/** Number of blocked truncates within the window that triggers a hard lock. */
+const CASCADE_THRESHOLD = 2;
+/** Backups kept per file (last N). */
+const BACKUP_RETENTION = 10;
+// ---------------------------------------------------------------------------
+// Cascade detection
+// ---------------------------------------------------------------------------
+export function isCascadeBlocked(stmts) {
+    if (process.env["LUCID_TRUNCATE_OVERRIDE"] === "1") {
+        return { blocked: false, count: 0 };
+    }
+    const since = Math.floor(Date.now() / 1000) - CASCADE_WINDOW_SECONDS;
+    const row = stmts.countRecentTruncates.get(since);
+    const count = row?.count ?? 0;
+    return { blocked: count >= CASCADE_THRESHOLD, count };
+}
+// ---------------------------------------------------------------------------
+// Per-write assessment
+// ---------------------------------------------------------------------------
+/**
+ * Assess whether writing `newContent` to `path` is a destructive truncate.
+ * Pure function — does NOT mutate state. Caller decides whether to record.
+ */
+export function assessTruncate(path, newContent, stmts) {
+    const cascade = isCascadeBlocked(stmts);
+    const absPath = resolve(path);
+    // Resolve previous size: filesystem first (source of truth), DB as fallback.
+    let prevSize = 0;
+    if (existsSync(absPath)) {
+        try {
+            prevSize = statSync(absPath).size;
+        }
+        catch { /* ignore */ }
+    }
+    if (prevSize === 0) {
+        const dbRow = stmts.getFileByPath.get(absPath);
+        if (dbRow)
+            prevSize = dbRow.original_size;
+    }
+    const newSize = newContent === null
+        ? -1 // unknown — only cascade lock can apply
+        : Buffer.byteLength(newContent, "utf-8");
+    const ratio = prevSize > 0 && newSize >= 0 ? newSize / prevSize : 1;
+    // Cascade lock takes precedence — even non-truncating writes are blocked.
+    if (cascade.blocked) {
+        return {
+            blocked: true,
+            rule: "CASCADE_LOCK",
+            prevSize, newSize, shrinkRatio: ratio,
+            cascade: true,
+            cascadeCount: cascade.count,
+            reason: `Cascade lock active: ${cascade.count} truncate attempts within ${CASCADE_WINDOW_SECONDS}s. ` +
+                `Run "lucid guard clear" or set LUCID_TRUNCATE_OVERRIDE=1 to release.`,
+        };
+    }
+    // Nothing to compare against — first-time write, allow.
+    if (prevSize === 0 || prevSize <= SMALL_FILE_BYTES || newSize < 0) {
+        return { blocked: false, prevSize, newSize, shrinkRatio: ratio, cascade: false, cascadeCount: cascade.count };
+    }
+    if (newSize === 0) {
+        return rule("EMPTY_OVERWRITE", prevSize, newSize, ratio, cascade.count, `Refusing to overwrite ${prevSize}B file with empty content.`);
+    }
+    if (newContent !== null && newContent.trim().length === 0) {
+        return rule("WHITESPACE_ONLY", prevSize, newSize, ratio, cascade.count, `Refusing to overwrite ${prevSize}B file with whitespace-only content (${newSize}B).`);
+    }
+    if (ratio < MIN_KEEP_RATIO) {
+        return rule("MAJOR_SHRINK", prevSize, newSize, ratio, cascade.count, `New content keeps only ${Math.round(ratio * 100)}% of previous size ` +
+            `(${newSize}B vs ${prevSize}B). Threshold: ${Math.round(MIN_KEEP_RATIO * 100)}%.`);
+    }
+    return { blocked: false, prevSize, newSize, shrinkRatio: ratio, cascade: false, cascadeCount: cascade.count };
+}
+function rule(r, prev, next, ratio, cascadeCount, reason) {
+    return { blocked: true, rule: r, prevSize: prev, newSize: next,
+        shrinkRatio: ratio, cascade: false, cascadeCount, reason };
+}
+/** Persist a truncate event so cascade detection can see it on the next call. */
+export function recordTruncateEvent(stmts, path, prevSize, newSize, blocked) {
+    const ratio = prevSize > 0 ? Math.max(0, newSize) / prevSize : 1;
+    stmts.insertTruncateEvent.run(resolve(path), prevSize, Math.max(0, newSize), ratio, blocked ? 1 : 0);
+}
+/**
+ * Snapshot the current on-disk file content into file_backups, then GC older
+ * versions beyond BACKUP_RETENTION. No-op if the file does not exist or is
+ * identical to the most recent backup.
+ */
+export function backupFile(stmts, path, snapshotReason = "manual") {
+    const absPath = resolve(path);
+    if (!existsSync(absPath))
+        return { saved: false, reason: `File not found: ${absPath}` };
+    let source;
+    try {
+        source = readFileSync(absPath, "utf-8");
+    }
+    catch (e) {
+        return { saved: false, reason: `Could not read file: ${e.message}` };
+    }
+    const hash = sha256(source);
+    const latest = stmts.getLatestBackup.get(absPath);
+    if (latest && latest.content_hash === hash) {
+        return { saved: false, reason: "Identical to latest backup — skipped", hash, size: latest.original_size };
+    }
+    const compressed = compress(source);
+    stmts.insertBackup.run(absPath, compressed, hash, Buffer.byteLength(source, "utf-8"), compressed.length, snapshotReason);
+    // Garbage-collect older versions beyond retention.
+    stmts.deleteOldBackups.run(absPath, absPath, BACKUP_RETENTION);
+    return { saved: true, reason: `Snapshot stored (${snapshotReason})`, hash, size: Buffer.byteLength(source, "utf-8") };
+}
+export const TUNABLES = {
+    MIN_KEEP_RATIO,
+    SMALL_FILE_BYTES,
+    CASCADE_WINDOW_SECONDS,
+    CASCADE_THRESHOLD,
+    BACKUP_RETENTION,
+};