@a13xu/lucid 1.13.0 → 1.16.1

package/package.json

@@ -1,59 +1,64 @@
-{
-  "name": "@a13xu/lucid",
-  "version": "1.13.0",
-  "description": "Token-efficient memory, code indexing, and validation for Claude Code agents — SQLite + FTS5, TF-IDF + Qdrant retrieval, AST skeleton pruning, diff-aware context, Logic Guardian drift detection",
-  "type": "module",
-  "bin": {
-    "lucid": "./build/index.js"
-  },
-  "files": [
-    "build/**/*.js",
-    "build/**/*.d.ts",
-    "skills/**/*.md",
-    "README.md"
-  ],
-  "scripts": {
-    "build": "tsc",
-    "prepublishOnly": "npm run build"
-  },
-  "keywords": [
-    "mcp",
-    "claude",
-    "claude-code",
-    "memory",
-    "sqlite",
-    "knowledge-graph",
-    "code-indexing",
-    "logic-guardian",
-    "drift-detection",
-    "tfidf",
-    "qdrant",
-    "token-optimization",
-    "context-pruning",
-    "ai",
-    "anthropic"
-  ],
-  "author": "a13xu",
-  "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/a13xu/lucid.git"
-  },
-  "homepage": "https://github.com/a13xu/lucid#readme",
-  "publishConfig": {
-    "access": "public"
-  },
-  "engines": {
-    "node": ">=18"
-  },
-  "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.0.0",
-    "better-sqlite3": "^12.0.0",
-    "zod": "^3.23.8"
-  },
-  "devDependencies": {
-    "@types/better-sqlite3": "^7.6.11",
-    "@types/node": "^22.0.0",
-    "typescript": "^5.4.0"
-  }
-}
+{
+  "name": "@a13xu/lucid",
+  "version": "1.16.1",
+  "description": "Token-efficient memory, code indexing, and validation for Claude Code agents — SQLite + FTS5, TF-IDF + Qdrant retrieval, AST skeleton pruning, diff-aware context, Logic Guardian drift detection",
+  "type": "module",
+  "bin": {
+    "lucid": "./build/index.js",
+    "lucid-sync": "./build/lucid-sync.js"
+  },
+  "files": [
+    "build/**/*.js",
+    "build/**/*.d.ts",
+    "skills/**/*.md",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "mcp",
+    "claude",
+    "claude-code",
+    "memory",
+    "sqlite",
+    "knowledge-graph",
+    "code-indexing",
+    "logic-guardian",
+    "drift-detection",
+    "tfidf",
+    "qdrant",
+    "token-optimization",
+    "context-pruning",
+    "ai",
+    "anthropic"
+  ],
+  "author": "a13xu",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/a13xu/lucid.git"
+  },
+  "homepage": "https://github.com/a13xu/lucid#readme",
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@huggingface/transformers": "^4.0.0",
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "better-sqlite3": "^12.0.0",
+    "chokidar": "^4.0.3",
+    "express": "^5.2.1",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@types/better-sqlite3": "^7.6.11",
+    "@types/express": "^5.0.6",
+    "@types/node": "^22.0.0",
+    "typescript": "^5.4.0"
+  }
+}

package/skills/lucid-audit/SKILL.md

@@ -1,53 +1,73 @@
 ---
 name: lucid-audit
-description: Run after writing or modifying code — validates logic correctness (Logic Guardian 5 passes) and code quality (25 Golden Rules) before marking work as done.
-argument-hint: "[file path or 'all']"
+description: MANDATORY before marking any task done — runs Logic Guardian + Code Quality checks. HARD-GATE blocks completion without validation.
+argument-hint: "[file path or 'all changed files']"
 ---
 
-# Lucid Code Audit
+<HARD-GATE>
+You are about to say "done", "fixed", "complete", or "implemented".
+STOP. You have NOT verified the code yet.
 
-Run this skill BEFORE marking any implementation as complete. It runs two complementary validators:
+Do NOT mark any task as done, do NOT commit, do NOT say the work is complete
+until you have run BOTH validators below and fixed all 🔴 CRITICAL issues.
 
-- **Logic Guardian** (`validate_file`) — detects LLM drift: logic inversions, null propagation, off-by-one, copy-paste mistakes
-- **Code Quality Guard** (`check_code_quality`) — detects structural issues: file/function size, vague naming, deep nesting, prop explosion, inline styles
+"It looks correct" is not verification. Run the tools.
+</HARD-GATE>
+
+## When to invoke
+
+**INVOKE when:** about to say done/fixed/complete/implemented, before committing, before creating a PR
+**DO NOT INVOKE for:** read-only tasks, pure research, config changes with no logic
 
 ## Steps
 
+```dot
+digraph lucid_audit {
+    "About to say done?" -> "validate_file(path)";
+    "validate_file(path)" -> "Critical issues?";
+    "Critical issues?" -> "Fix issues" [label="yes 🔴"];
+    "Fix issues" -> "validate_file(path)";
+    "Critical issues?" -> "check_code_quality(path)" [label="no ✓"];
+    "check_code_quality(path)" -> "HIGH issues?";
+    "HIGH issues?" -> "Fix if safe" [label="yes 🟠"];
+    "Fix if safe" -> "Mark done ✓";
+    "HIGH issues?" -> "Mark done ✓" [label="no ✓"];
+}
+```
+
+### 0. Get model recommendation
+```
+suggest_model(task_description="<paste the file path or description of what was written>")
+```
+Say: **"Using [model] — [reasoning]"** then proceed.
+
 ### 1. Validate logic correctness
 ```
 validate_file(path="<file you wrote or modified>")
 ```
-Fix any 🔴 CRITICAL issues before continuing.
+Fix every 🔴 CRITICAL issue. Re-run until clean.
 
 ### 2. Validate code quality
 ```
 check_code_quality(path="<same file>")
 ```
-Fix any 🔴 HIGH severity issues. Address 🟠 MEDIUM where practical.
+Fix 🔴 HIGH severity issues. Address 🟠 MEDIUM where practical.
 
-### 3. If unsure about a snippet before writing it to disk
+### 3. For complex logic — get the full checklist
 ```
-check_drift(code="<your code>", language="typescript")
+get_checklist()
 ```
+Run all 5 mental passes before marking done.
 
-### 4. Get the full 5-pass mental checklist
+### 4. Pre-write validation (before writing to disk)
 ```
-get_checklist()
+check_drift(code="<your code snippet>", language="typescript")
 ```
-Use this when changes are complex or involve critical business logic.
 
 ## Severity guide
 
 | Icon | Level | Action |
 |---|---|---|
-| 🔴 | Critical/High | Fix immediately — do not ship |
-| 🟠 | Medium/Warning | Fix if not risky refactor |
+| 🔴 | Critical/High | Fix immediately — do not proceed |
+| 🟠 | Medium | Fix if the refactor is safe |
 | 🔵 | Low/Info | Note for future cleanup |
-
-## What each tool catches
-
-| Tool | Catches |
-|---|---|
-| `validate_file` | Logic inversions, silent exceptions, null propagation, type confusion, stale closures |
-| `check_code_quality` | Files >500 lines, functions >100 lines, vague names, nesting >4 levels, dead code, React/Vue component anti-patterns |
-| `check_drift` | Same as validate_file but on inline snippets — use before writing |

package/skills/lucid-context/SKILL.md

@@ -1,35 +1,69 @@
 ---
 name: lucid-context
-description: Use before starting any coding task — retrieves minimal relevant context via Lucid's TF-IDF retrieval, then rewards or penalizes based on usefulness.
+description: Use BEFORE starting any coding task — retrieves relevant context via smart_context (code + knowledge graph). HARD-GATE: do not read files manually before calling smart_context.
 argument-hint: "[what you are working on]"
 ---
 
-# Lucid Context Retrieval
+<HARD-GATE>
+Do NOT open any source file, read any code, or start implementation
+until you have called smart_context and reviewed the result.
+Reading files manually when Lucid is available wastes tokens and misses context.
+</HARD-GATE>
 
-Use this skill at the START of every coding task to get only the relevant files instead of reading the whole codebase.
+## When to invoke this skill
 
-## Steps
+**INVOKE when:** about to work on a feature, fix a bug, understand a module, or any coding task
+**DO NOT INVOKE for:** pure conversation, reading docs, non-code questions
 
-1. **Call `get_context`** with a concise description of what you're working on:
-   ```
-   get_context(query="<what you are working on>", maxTokens=4000)
-   ```
+## Steps
 
-2. **Review the returned skeletons/files.** If they are relevant → call `reward()`. If they missed important files → call `penalize()` and note what was missing.
+```dot
+digraph lucid_context {
+    "Describe task" -> "suggest_model";
+    "suggest_model" -> "call smart_context";
+    "call smart_context" -> "Result relevant?";
+    "Result relevant?" -> "call reward()" [label="yes"];
+    "Result relevant?" -> "call penalize()" [label="no — note what was missing"];
+    "reward()" -> "Start coding";
+    "penalize()" -> "Start coding";
+}
+```
 
-3. **Start coding** using the context you received.
+### 0. Get model recommendation
+```
+suggest_model(task_description="<concise description of what you are working on>")
+```
+Say: **"Using [model] — [reasoning]"**
 
-## Tips
+### 1. Call smart_context
+```
+smart_context(query="<concise description of what you are working on>", task_type="moderate")
+```
 
-- Use `dirs` to narrow scope: `get_context(query="...", dirs=["src/api"])`
-- Use `get_recent(hours=2)` after a git pull or when resuming a session to see what changed
-- Use `grep_code(pattern="...")` to locate specific function usages without reading full files
-- After finishing, call `sync_file(path="<modified file>")` to keep the knowledge graph current
+Use `dirs` to narrow scope and `task_type` to adjust budget:
+```
+smart_context(query="...", dirs=["src/api"], task_type="simple")
+```
 
-## When to reward vs penalize
+### 2. Review results and give feedback
 
-| Situation | Action |
+| Result quality | Action |
 |---|---|
-| Context included the files that helped solve the task | `reward()` |
-| Context missed key files you had to find manually | `penalize(note="missed: src/utils/auth.ts")` |
-| Context was partially useful | No action needed |
+| Included the files you needed | `reward()` |
+| Missed important files you had to find manually | `penalize(note="missed: src/path/file.ts")` |
+| Partially useful | no action |
+
+### 3. Supplement if needed
+
+```
+grep_code(pattern="functionName")          # locate specific usages
+get_recent(hours=2)                        # after git pull — see what changed
+recall(query="<topic>")                    # search accumulated knowledge
+```
+
+### 4. After finishing — sync
+
+After every Write/Edit:
+```
+sync_file(path="<modified file>")
+```

package/skills/lucid-plan/SKILL.md

@@ -1,60 +1,52 @@
 ---
 name: lucid-plan
-description: Create and track an implementation plan before writing any code — use Lucid's planning tools to define user story, ordered tasks, and test criteria.
+description: MANDATORY before writing code for any non-trivial feature — creates a persisted plan with tasks. HARD-GATE: no coding without a plan.
 argument-hint: "[feature or task description]"
 ---
 
-# Lucid Planning Workflow
+<HARD-GATE>
+You are about to write code for a feature or fix.
+STOP. Create a plan first. Plans survive session restarts.
+Do NOT write implementation code until a plan exists and tasks are defined.
+</HARD-GATE>
 
-Use this skill BEFORE writing code for any non-trivial feature. Plans are persisted in the Lucid DB and survive session restarts.
+## When to invoke
+
+**INVOKE when:** implementing a feature, fixing a non-trivial bug, any task with 3+ steps
+**DO NOT INVOKE for:** single-line fixes, config changes, documentation-only tasks
 
 ## Steps
 
+### 0. Get model recommendation
+```
+suggest_model(task_description="<paste the user's task description>")
+```
+Say: **"Using [model] — [reasoning]"** then proceed.
+
 ### 1. Create the plan
 ```
 plan_create(
-  title="<short title>",
-  description="<what this plan accomplishes>",
+  title="<short descriptive title>",
+  description="<what this accomplishes>",
   user_story="As a <user>, I want <goal>, so that <benefit>.",
   tasks=[
-    { title: "Task 1", description: "...", test_criteria: "How to verify done" },
+    { title: "Task 1", description: "...", test_criteria: "How to verify it's done" },
     { title: "Task 2", description: "...", test_criteria: "..." },
   ]
 )
 ```
 Returns a `plan_id` and task IDs (format: `planId * 100 + sequence`).
 
-### 2. Work through tasks
-For each task, mark it in progress when you start:
+### 2. Mark tasks in progress / done as you work
 ```
 plan_update_task(task_id=101, status="in_progress")
+plan_update_task(task_id=101, status="done", note="Decision made: used X instead of Y")
 ```
 
-When done, mark it complete (optionally add a note):
+### 3. Resume a session
 ```
-plan_update_task(task_id=101, status="done", note="Used useFetch instead of axios")
+plan_list()           # all active plans
+plan_get(plan_id=1)   # full details + task status
 ```
 
-Plan auto-completes when all tasks reach `done`.
-
-### 3. Resume a session — check plan status
-```
-plan_list()                  # see all active plans
-plan_get(plan_id=1)          # see full details + task status
-```
-
-## Task statuses
-
-| Status | When to use |
-|---|---|
-| `pending` | Not started yet |
-| `in_progress` | Currently working on it |
-| `done` | Completed and verified |
-| `blocked` | Waiting on external dependency |
-
-## Tips
-
-- Define `test_criteria` clearly — it becomes your acceptance test
-- Use `plan_get` when resuming to quickly re-orient yourself
-- Keep tasks small (1–4 hours each); use more tasks rather than fewer
-- Notes are append-only — use them to document decisions made during implementation
+## Task statuses: `pending` → `in_progress` → `done` | `blocked`

package/skills/lucid-security/SKILL.md

@@ -1,59 +1,41 @@
 ---
 name: lucid-security
-description: Run a full security review on a file or snippet — combines web vulnerability scanning (XSS, injection, secrets) with LLM drift detection before shipping code.
-argument-hint: "[file path or paste code]"
+description: Run before merging any code that handles user input, auth, or external data — security scan + drift check for injection, XSS, and credential exposure.
+argument-hint: "[file path or directory]"
 ---
 
-# Lucid Security Review
+<HARD-GATE>
+Before merging code that:
+- Handles user input (forms, query params, file uploads)
+- Implements auth, tokens, sessions, or permissions
+- Calls external APIs or parses external data
+- Manages files or runs shell commands
 
-Run this skill before shipping any code that handles user input, authentication, file access, or external data.
+Run this skill. No exceptions.
+</HARD-GATE>
 
 ## Steps
 
-### 1. Scan for web security vulnerabilities
+### 0. Get model recommendation
 ```
-security_scan(
-  code="<file contents or snippet>",
-  language="typescript",    # javascript | typescript | html | vue
-  context="backend"         # frontend | backend | api
-)
+suggest_model(task_description="<paste the user's task description>")
 ```
-Detects: XSS vectors, eval/new Function, SQL injection via string concat, hardcoded secrets/keys, open redirects, prototype pollution, path traversal, insecure CORS.
+Say: **"Using [model] — [reasoning]"** then proceed.
 
-### 2. Scan for logic errors (LLM drift)
+### 1. Security scan
 ```
-validate_file(path="<file path>")
+security_scan(code="<file contents or snippet>", language="typescript", context="backend")
 ```
-Catches security-adjacent logic bugs: wrong condition direction, silent exception swallowing, null propagation into auth checks.
 
-### 3. For frontend components — audit accessibility too
+### 2. Drift check for security-sensitive snippets
 ```
-accessibility_audit(code="<template or JSX>", wcag_level="AA", framework="vue")
+check_drift(code="<auth/input-handling code>", language="typescript")
 ```
 
-## Severity guide
+### 3. Fix all CRITICAL issues before merging
 
-| Icon | Severity | Action |
-|---|---|---|
-| 🔴 Critical | XSS, eval, hardcoded secret, SQL injection | Fix before any commit |
-| 🟠 High | Open redirect, path traversal, prototype pollution | Fix before merge |
-| 🟡 Medium | Wildcard CORS, missing CSRF protection | Fix before production |
-| 🔵 Low | console.log, minor info leakage | Fix when convenient |
-
-## Common patterns to watch
-
-| Pattern | Risk |
+| Severity | Action |
 |---|---|
-| `element.innerHTML = userInput` | XSS — use `textContent` or DOMPurify |
-| `eval(...)` / `new Function(...)` | Code injection |
-| `const key = "sk-abc123..."` | Hardcoded secret — move to env var |
-| `res.redirect(req.query.url)` | Open redirect — validate against allowlist |
-| `readFile(req.params.filename)` | Path traversal — use `path.resolve` + bounds check |
-| `Access-Control-Allow-Origin: *` | Overly permissive CORS |
-
-## Note
-
-Static scanning finds patterns, not all vulnerabilities. Complement with:
-- Manual code review for business logic flaws
-- DAST (dynamic testing) for runtime issues
-- Dependency audit: `npm audit` / `pip-audit`
+| 🔴 CRITICAL | Block merge — fix immediately |
+| 🟠 HIGH | Fix before merge |
+| 🔵 MEDIUM/LOW | Track, fix in follow-up |

package/skills/lucid-start/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: lucid-start
+description: MANDATORY at every session start and before any coding task — loads project context via Lucid before Claude reads any file or writes any code
+argument-hint: "[optional: what you are about to work on]"
+---
+
+<HARD-GATE>
+You MUST complete ALL steps below BEFORE:
+- Reading any source file
+- Writing or editing any code
+- Answering any coding question
+- Creating any plan or task
+
+This is not optional. There are no exceptions. "I'll do it after" is not acceptable.
+</HARD-GATE>
+
+## Steps (all mandatory, in order)
+
+### 0. Get model recommendation
+```
+suggest_model(task_description="<paste the user's task description>")
+```
+Say: **"Using [model] — [reasoning]"** then proceed.
+
+### 1. Check what changed recently
+```
+get_recent(hours=48)
+```
+This shows files modified since your last session. Review the list.
+
+### 2. If working on a specific task — load relevant context
+```
+smart_context(query="<describe what you are about to work on>", task_type="moderate")
+```
+If the user's request involves code, call smart_context. For purely conversational exchanges with zero code involvement, this step may be omitted.
+
+### 3. Announce readiness
+Say: "✓ Lucid active — context loaded"
+
+---
+
+## After EVERY file write or edit
+
+Call `sync_file` IMMEDIATELY after the tool call completes:
+```
+sync_file(path="<exact path of file you just wrote or edited>")
+```
+
+**Do this before anything else.** Before the next file. Before the next thought. Now.
+
+If you modified multiple files (refactor, git pull): call `sync_project()` instead.
+
+---
+
+## Before marking any task as done
+
+Run /lucid-audit before saying "done", "fixed", "complete", or "implemented".
+
+---
+
+## Trigger conditions
+
+**USE this skill:**
+- At the start of every new conversation
+- When resuming work after a break
+- When the user says "let's work on X" or similar
+
+**DO NOT USE for:**
+- Pure conversation with no code involved
+- Answering theoretical questions