@a13xu/lucid 1.0.0 → 1.1.0

package/build/guardian/checklist.d.ts

@@ -0,0 +1 @@
+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";

package/build/guardian/checklist.js

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

package/build/guardian/validator.d.ts

@@ -0,0 +1,21 @@
+export type Severity = "critical" | "high" | "medium" | "low" | "info";
+export interface Issue {
+    file: string;
+    line: number;
+    severity: Severity;
+    driftId: string;
+    message: string;
+    suggestion?: string;
+    snippet?: string;
+}
+export declare function formatIssue(issue: Issue): string;
+export declare function detectLanguage(filepath: string): string;
+export interface ValidationResult {
+    issues: Issue[];
+    filesChecked: number;
+    linesChecked: number;
+    passed: boolean;
+}
+export declare function validateSource(filepath: string, source: string, lang?: string): Issue[];
+export declare function validateFile(filepath: string): Issue[];
+export declare function formatReport(filepath: string, issues: Issue[]): string;

package/build/guardian/validator.js

@@ -0,0 +1,332 @@
+import { readFileSync } from "fs";
+import { extname } from "path";
+const SEVERITY_ORDER = {
+    critical: 0, high: 1, medium: 2, low: 3, info: 4,
+};
+const SEVERITY_ICON = {
+    critical: "🔴", high: "🟠", medium: "🟡", low: "🔵", info: "ℹ️",
+};
+export function formatIssue(issue) {
+    const icon = SEVERITY_ICON[issue.severity];
+    let s = `${icon} [${issue.driftId}] ${issue.file}:${issue.line} — ${issue.message}`;
+    if (issue.suggestion)
+        s += `\n   💡 ${issue.suggestion}`;
+    if (issue.snippet)
+        s += `\n   📄 ${issue.snippet.trim().slice(0, 80)}`;
+    return s;
+}
+// ---------------------------------------------------------------------------
+// Language detection
+// ---------------------------------------------------------------------------
+const LANG_MAP = {
+    ".py": "python",
+    ".js": "javascript",
+    ".jsx": "javascript",
+    ".ts": "typescript",
+    ".tsx": "typescript",
+    ".rs": "rust",
+    ".go": "go",
+};
+export function detectLanguage(filepath) {
+    return LANG_MAP[extname(filepath).toLowerCase()] ?? "generic";
+}
+// ---------------------------------------------------------------------------
+// Python analyzer (regex-based port of AST checks)
+// ---------------------------------------------------------------------------
+function analyzePython(filepath, lines) {
+    const issues = [];
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        const num = i + 1;
+        const trimmed = line.trim();
+        // Mutable default argument: def f(x=[], def f(x={})
+        if (/def\s+\w+\s*\(/.test(trimmed) && /=\s*[\[\{]/.test(trimmed)) {
+            issues.push({
+                file: filepath, line: num, severity: "high",
+                driftId: "PY-MUT-DEFAULT",
+                message: "Mutable default argument in function definition",
+                suggestion: "Use None as default and create inside function body.",
+                snippet: trimmed,
+            });
+        }
+        // Bare except:
+        if (/^\s*except\s*:/.test(line)) {
+            issues.push({
+                file: filepath, line: num, severity: "high",
+                driftId: "PY-BARE-EXCEPT",
+                message: "Bare `except:` catches everything including KeyboardInterrupt",
+                suggestion: "Use `except Exception:` or catch specific exceptions.",
+            });
+        }
+        // Silent except (except followed by pass on next line)
+        if (/^\s*except[\s:]/.test(line) && i + 1 < lines.length) {
+            const next = lines[i + 1].trim();
+            if (next === "pass") {
+                issues.push({
+                    file: filepath, line: num, severity: "critical",
+                    driftId: "DRIFT-002",
+                    message: "Exception silently swallowed with `pass`",
+                    suggestion: "Log the error, re-raise, or handle explicitly.",
+                });
+            }
+        }
+        // == None instead of is None
+        if (/==\s*None/.test(trimmed) && !trimmed.startsWith("#")) {
+            issues.push({
+                file: filepath, line: num, severity: "medium",
+                driftId: "PY-IS-NONE",
+                message: "Using `== None` instead of `is None`",
+                suggestion: "Use `is None` for None checks (PEP 8).",
+                snippet: trimmed,
+            });
+        }
+        // != None instead of is not None
+        if (/!=\s*None/.test(trimmed) && !trimmed.startsWith("#")) {
+            issues.push({
+                file: filepath, line: num, severity: "medium",
+                driftId: "PY-IS-NONE",
+                message: "Using `!= None` instead of `is not None`",
+                suggestion: "Use `is not None` for None checks (PEP 8).",
+                snippet: trimmed,
+            });
+        }
+        // f-string without interpolation
+        if (/f['"][^{'"]*['"]/.test(trimmed) && !trimmed.includes("{")) {
+            issues.push({
+                file: filepath, line: num, severity: "low",
+                driftId: "PY-FSTRING-EMPTY",
+                message: "f-string without any interpolation",
+                suggestion: "Remove the `f` prefix or add variables.",
+                snippet: trimmed,
+            });
+        }
+        // async def without await in body (heuristic: next non-empty line doesn't await)
+        if (/^\s*async\s+def\s+/.test(line)) {
+            // Collect the function body (next ~20 lines) and check for await
+            const body = lines.slice(i + 1, i + 20).join("\n");
+            if (!body.includes("await ") && !body.includes("async for") && !body.includes("async with")) {
+                issues.push({
+                    file: filepath, line: num, severity: "medium",
+                    driftId: "DRIFT-003",
+                    message: "async function may not use await — could be incorrectly async",
+                    suggestion: "Verify this function actually needs to be async.",
+                    snippet: trimmed,
+                });
+            }
+        }
+    }
+    return issues;
+}
+// ---------------------------------------------------------------------------
+// JavaScript / TypeScript analyzer
+// ---------------------------------------------------------------------------
+function analyzeJavaScript(filepath, lines) {
+    const issues = [];
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        const num = i + 1;
+        const trimmed = line.trim();
+        // Skip comments
+        if (trimmed.startsWith("//") || trimmed.startsWith("*"))
+            continue;
+        // == instead of === (but not !== or ===)
+        if (/[^!=><]={2}[^=]/.test(trimmed) && !/={3}/.test(trimmed)) {
+            issues.push({
+                file: filepath, line: num, severity: "medium",
+                driftId: "JS-STRICT-EQ",
+                message: "Using `==` instead of `===`",
+                suggestion: "Use strict equality `===` unless coercion is intentional.",
+                snippet: trimmed,
+            });
+        }
+        // console.log left in
+        if (/console\.log\s*\(/.test(trimmed)) {
+            issues.push({
+                file: filepath, line: num, severity: "low",
+                driftId: "JS-CONSOLE",
+                message: "console.log() left in code",
+                suggestion: "Remove or replace with proper logging.",
+                snippet: trimmed,
+            });
+        }
+        // .then() without .catch() on same line
+        if (/\.then\s*\(/.test(trimmed) && !/\.catch\s*\(/.test(trimmed)) {
+            issues.push({
+                file: filepath, line: num, severity: "medium",
+                driftId: "JS-UNCAUGHT-PROMISE",
+                message: "`.then()` without `.catch()` — unhandled promise rejection",
+                suggestion: "Add `.catch()` or use try/catch with async/await.",
+                snippet: trimmed,
+            });
+        }
+        // .sort() without comparator
+        if (/\.sort\s*\(\s*\)/.test(trimmed)) {
+            issues.push({
+                file: filepath, line: num, severity: "high",
+                driftId: "JS-SORT-DEFAULT",
+                message: "`.sort()` without comparator sorts as strings",
+                suggestion: "Use `.sort((a, b) => a - b)` for numeric sort.",
+                snippet: trimmed,
+            });
+        }
+        // any type in TypeScript
+        if (/:\s*any\b/.test(trimmed) || /as\s+any\b/.test(trimmed)) {
+            issues.push({
+                file: filepath, line: num, severity: "low",
+                driftId: "TS-ANY",
+                message: "`any` type leaking through — disables type safety",
+                suggestion: "Use a specific type or `unknown` with type narrowing.",
+                snippet: trimmed,
+            });
+        }
+        // non-null assertion masking bugs
+        if (/\w!\.\w/.test(trimmed) || /\w!\[/.test(trimmed)) {
+            issues.push({
+                file: filepath, line: num, severity: "medium",
+                driftId: "TS-NON-NULL",
+                message: "Non-null assertion `!` — could crash if value is actually null",
+                suggestion: "Add explicit null check instead.",
+                snippet: trimmed,
+            });
+        }
+        // Early return with potential wrong value (heuristic)
+        if (/return\s+true\b/.test(trimmed) || /return\s+false\b/.test(trimmed)) {
+            issues.push({
+                file: filepath, line: num, severity: "info",
+                driftId: "DRIFT-005",
+                message: "Boolean return — verify this is the correct value for this branch",
+                suggestion: "Logic inversions are the #1 LLM drift pattern. Double-check.",
+                snippet: trimmed,
+            });
+        }
+    }
+    return issues;
+}
+// ---------------------------------------------------------------------------
+// Generic analyzer (language-agnostic)
+// ---------------------------------------------------------------------------
+function analyzeGeneric(filepath, lines) {
+    const issues = [];
+    // TODO / FIXME / HACK markers
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        const num = i + 1;
+        for (const marker of ["TODO", "FIXME", "HACK", "XXX", "BUG"]) {
+            if (line.toUpperCase().includes(marker) && /[/#*\-]/.test(line)) {
+                issues.push({
+                    file: filepath, line: num, severity: "info",
+                    driftId: "MARKER",
+                    message: `${marker} marker found`,
+                    snippet: line.trim(),
+                });
+            }
+        }
+    }
+    // Near-duplicate blocks (copy-paste drift detection)
+    const BLOCK_SIZE = 5;
+    const seen = new Map();
+    for (let i = 0; i <= lines.length - BLOCK_SIZE; i++) {
+        const block = lines.slice(i, i + BLOCK_SIZE).map((l) => l.trim()).filter(Boolean);
+        if (block.length < 3)
+            continue;
+        // Normalize: replace identifiers with placeholder
+        const sig = block.map((l) => l.replace(/\b[a-z_]\w*\b/g, "_")).join("|");
+        const prev = seen.get(sig);
+        if (prev !== undefined && i - prev > BLOCK_SIZE) {
+            issues.push({
+                file: filepath, line: i + 1, severity: "medium",
+                driftId: "DRIFT-007",
+                message: `Near-duplicate block (similar to line ${prev + 1})`,
+                suggestion: "Verify all variable names were updated correctly in the copy.",
+            });
+        }
+        else {
+            seen.set(sig, i);
+        }
+    }
+    // Magic numbers (2+ digit numbers not in common whitelist)
+    const MAGIC_WHITELIST = new Set([10, 16, 32, 64, 100, 128, 256, 512, 1000, 1024, 2048, 4096, 8080, 3000, 8000]);
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        const trimmed = line.trim();
+        if (/^[/#*\-]/.test(trimmed))
+            continue;
+        for (const match of trimmed.matchAll(/(?<![.\w])(\d{2,})(?![.\w])/g)) {
+            const num = parseInt(match[1], 10);
+            if (!MAGIC_WHITELIST.has(num) && !/port|size|limit|max|min/i.test(trimmed)) {
+                issues.push({
+                    file: filepath, line: i + 1, severity: "low",
+                    driftId: "MAGIC-NUM",
+                    message: `Magic number \`${num}\` — consider a named constant`,
+                    snippet: trimmed,
+                });
+                break; // one per line is enough
+            }
+        }
+    }
+    return issues;
+}
+export function validateSource(filepath, source, lang) {
+    const language = lang ?? detectLanguage(filepath);
+    const lines = source.split("\n");
+    const issues = [];
+    if (language === "python") {
+        issues.push(...analyzePython(filepath, lines));
+    }
+    else if (language === "javascript" || language === "typescript") {
+        issues.push(...analyzeJavaScript(filepath, lines));
+    }
+    issues.push(...analyzeGeneric(filepath, lines));
+    issues.sort((a, b) => SEVERITY_ORDER[a.severity] - SEVERITY_ORDER[b.severity]);
+    return issues;
+}
+export function validateFile(filepath) {
+    let source;
+    try {
+        source = readFileSync(filepath, { encoding: "utf-8" });
+    }
+    catch (err) {
+        return [{
+                file: filepath, line: 0, severity: "critical",
+                driftId: "IO-ERROR",
+                message: `Cannot read file: ${err instanceof Error ? err.message : String(err)}`,
+            }];
+    }
+    return validateSource(filepath, source);
+}
+export function formatReport(filepath, issues) {
+    const lines = [
+        "=".repeat(60),
+        "🛡️  LOGIC GUARDIAN — Validation Report",
+        "=".repeat(60),
+        `File: ${filepath}`,
+        `Issues: ${issues.length}`,
+        "",
+    ];
+    if (issues.length === 0) {
+        lines.push("✅ No issues detected. Proceed with confidence.");
+        lines.push("");
+        lines.push("⚠️  Automated checks catch ~40% of drift patterns.");
+        lines.push("   The manual checklist (Passes 1-5) catches the rest.");
+    }
+    else {
+        const bySeverity = (s) => issues.filter((i) => i.severity === s);
+        for (const sev of ["critical", "high", "medium", "low", "info"]) {
+            const group = bySeverity(sev);
+            if (group.length > 0) {
+                lines.push(`--- ${sev.toUpperCase()} (${group.length}) ---`);
+                for (const issue of group)
+                    lines.push(formatIssue(issue));
+                lines.push("");
+            }
+        }
+        const criticalCount = bySeverity("critical").length;
+        const highCount = bySeverity("high").length;
+        const passed = criticalCount === 0 && highCount === 0;
+        lines.push(passed
+            ? "✅ PASS — No critical or high severity issues."
+            : "❌ FAIL — Fix critical/high issues before proceeding.");
+    }
+    lines.push("=".repeat(60));
+    return lines.join("\n");
+}

package/build/index.js

@@ -10,6 +10,7 @@ import { recall, RecallSchema } from "./tools/recall.js";
 import { recallAll } from "./tools/recall-all.js";
 import { forget, ForgetSchema } from "./tools/forget.js";
 import { memoryStats } from "./tools/stats.js";
+import { handleValidateFile, ValidateFileSchema, handleCheckDrift, CheckDriftSchema, handleGetChecklist, } from "./tools/guardian.js";
 // ---------------------------------------------------------------------------
 // Init DB
 // ---------------------------------------------------------------------------
@@ -18,12 +19,13 @@ const stmts = prepareStatements(db);
 // ---------------------------------------------------------------------------
 // MCP Server
 // ---------------------------------------------------------------------------
-const server = new Server({ name: "lucid", version: "1.0.0" }, { capabilities: { tools: {} } });
+const server = new Server({ name: "lucid", version: "1.1.0" }, { capabilities: { tools: {} } });
 // ---------------------------------------------------------------------------
 // Tool definitions
 // ---------------------------------------------------------------------------
 server.setRequestHandler(ListToolsRequestSchema, async () => ({
     tools: [
+        // ── Memory ──────────────────────────────────────────────────────────────
         {
             name: "remember",
             description: "Store a fact, decision, or observation about an entity in the knowledge graph.",
@@ -88,6 +90,43 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
             description: "Get memory usage statistics.",
             inputSchema: { type: "object", properties: {} },
         },
+        // ── Logic Guardian ───────────────────────────────────────────────────────
+        {
+            name: "validate_file",
+            description: "Run Logic Guardian validation on a source file. Detects LLM drift patterns: " +
+                "logic inversions, null propagation, type confusion, copy-paste drift, silent exceptions, and more. " +
+                "Supports Python, JavaScript, TypeScript. Use after writing or modifying any code.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    path: { type: "string", description: "Absolute or relative path to the file to validate." },
+                },
+                required: ["path"],
+            },
+        },
+        {
+            name: "check_drift",
+            description: "Analyze a code snippet for LLM drift patterns without saving to disk. " +
+                "Use this to validate code before writing it to a file.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    code: { type: "string", description: "The code snippet to analyze." },
+                    language: {
+                        type: "string",
+                        enum: ["python", "javascript", "typescript", "generic"],
+                        description: "Programming language. Defaults to 'generic'.",
+                    },
+                },
+                required: ["code"],
+            },
+        },
+        {
+            name: "get_checklist",
+            description: "Get the full Logic Guardian validation checklist (5 passes). " +
+                "Call this before marking any implementation task as done.",
+            inputSchema: { type: "object", properties: {} },
+        },
     ],
 }));
 // ---------------------------------------------------------------------------
@@ -98,52 +137,45 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     try {
         let text;
         switch (name) {
-            case "remember": {
-                const input = RememberSchema.parse(args);
-                text = remember(stmts, input);
+            // Memory
+            case "remember":
+                text = remember(stmts, RememberSchema.parse(args));
                 break;
-            }
-            case "relate": {
-                const input = RelateSchema.parse(args);
-                text = relate(stmts, input);
+            case "relate":
+                text = relate(stmts, RelateSchema.parse(args));
                 break;
-            }
-            case "recall": {
-                const input = RecallSchema.parse(args);
-                text = recall(stmts, input);
+            case "recall":
+                text = recall(stmts, RecallSchema.parse(args));
                 break;
-            }
-            case "recall_all": {
+            case "recall_all":
                 text = recallAll(db, stmts);
                 break;
-            }
-            case "forget": {
-                const input = ForgetSchema.parse(args);
-                text = forget(stmts, input);
+            case "forget":
+                text = forget(stmts, ForgetSchema.parse(args));
                 break;
-            }
-            case "memory_stats": {
+            case "memory_stats":
                 text = memoryStats(db, stmts);
                 break;
-            }
+            // Logic Guardian
+            case "validate_file":
+                text = handleValidateFile(ValidateFileSchema.parse(args));
+                break;
+            case "check_drift":
+                text = handleCheckDrift(CheckDriftSchema.parse(args));
+                break;
+            case "get_checklist":
+                text = handleGetChecklist();
+                break;
             default:
-                return {
-                    content: [{ type: "text", text: `Unknown tool: ${name}` }],
-                    isError: true,
-                };
+                return { content: [{ type: "text", text: `Unknown tool: ${name}` }], isError: true };
         }
         return { content: [{ type: "text", text }] };
     }
     catch (err) {
         const message = err instanceof z.ZodError
             ? `Validation error: ${err.errors.map((e) => e.message).join(", ")}`
-            : err instanceof Error
-                ? err.message
-                : String(err);
-        return {
-            content: [{ type: "text", text: `Error: ${message}` }],
-            isError: true,
-        };
+            : err instanceof Error ? err.message : String(err);
+        return { content: [{ type: "text", text: `Error: ${message}` }], isError: true };
     }
 });
 // ---------------------------------------------------------------------------

package/build/tools/guardian.d.ts

@@ -0,0 +1,21 @@
+import { z } from "zod";
+export declare const ValidateFileSchema: z.ZodObject<{
+    path: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    path: string;
+}, {
+    path: string;
+}>;
+export declare const CheckDriftSchema: z.ZodObject<{
+    code: z.ZodString;
+    language: z.ZodOptional<z.ZodEnum<["python", "javascript", "typescript", "generic"]>>;
+}, "strip", z.ZodTypeAny, {
+    code: string;
+    language?: "python" | "javascript" | "typescript" | "generic" | undefined;
+}, {
+    code: string;
+    language?: "python" | "javascript" | "typescript" | "generic" | undefined;
+}>;
+export declare function handleValidateFile(args: z.infer<typeof ValidateFileSchema>): string;
+export declare function handleCheckDrift(args: z.infer<typeof CheckDriftSchema>): string;
+export declare function handleGetChecklist(): string;

package/build/tools/guardian.js

@@ -0,0 +1,58 @@
+import { z } from "zod";
+import { writeFileSync, unlinkSync } from "fs";
+import { tmpdir } from "os";
+import { join } from "path";
+import { validateFile, validateSource, formatReport, } from "../guardian/validator.js";
+import { CHECKLIST } from "../guardian/checklist.js";
+// ---------------------------------------------------------------------------
+// Schemas
+// ---------------------------------------------------------------------------
+export const ValidateFileSchema = z.object({
+    path: z.string().min(1),
+});
+export const CheckDriftSchema = z.object({
+    code: z.string().min(1),
+    language: z.enum(["python", "javascript", "typescript", "generic"]).optional(),
+});
+// ---------------------------------------------------------------------------
+// Handlers
+// ---------------------------------------------------------------------------
+export function handleValidateFile(args) {
+    const issues = validateFile(args.path);
+    return formatReport(args.path, issues);
+}
+export function handleCheckDrift(args) {
+    const lang = args.language ?? "generic";
+    const extMap = {
+        python: ".py",
+        javascript: ".js",
+        typescript: ".ts",
+        generic: ".txt",
+    };
+    const ext = extMap[lang] ?? ".txt";
+    const tmpPath = join(tmpdir(), `lucid-drift-${Date.now()}${ext}`);
+    try {
+        writeFileSync(tmpPath, args.code, "utf-8");
+        const issues = validateSource(tmpPath, args.code, lang === "generic" ? undefined : lang);
+        if (issues.length === 0) {
+            return "✅ No drift patterns detected in this code snippet.";
+        }
+        const lines = [`Found ${issues.length} potential issue(s):\n`];
+        for (const issue of issues) {
+            const icon = { critical: "🔴", high: "🟠", medium: "🟡", low: "🔵", info: "ℹ️" }[issue.severity];
+            lines.push(`${icon} [${issue.driftId}] line ${issue.line} — ${issue.message}`);
+            if (issue.suggestion)
+                lines.push(`   💡 ${issue.suggestion}`);
+        }
+        return lines.join("\n");
+    }
+    finally {
+        try {
+            unlinkSync(tmpPath);
+        }
+        catch { /* ignore */ }
+    }
+}
+export function handleGetChecklist() {
+    return CHECKLIST;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@a13xu/lucid",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Persistent memory for Claude Code agents — SQLite + FTS5 knowledge graph via MCP",
   "type": "module",
   "bin": {