@a13xu/lucid 1.4.0 → 1.9.1

package/build/guardian/coding-analyzer.js

@@ -0,0 +1,393 @@
+import { extname } from "path";
+const SEVERITY_ORDER = {
+    high: 0, medium: 1, low: 2,
+};
+const SEVERITY_ICON = {
+    high: "🔴", medium: "🟠", low: "🔵",
+};
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+function isFrontend(filepath, lang) {
+    if (lang === "vue")
+        return true;
+    const ext = extname(filepath).toLowerCase();
+    return ext === ".tsx" || ext === ".jsx" || ext === ".vue";
+}
+/** Returns true if the line looks like a function definition with an opening brace. */
+function isFuncDefLine(line) {
+    const trimmed = line.trim();
+    if (trimmed.startsWith("//") || trimmed.startsWith("*") || trimmed.startsWith("#"))
+        return false;
+    // Exclude control-flow keywords
+    if (/^\s*(?:if|for|while|switch|try|catch|else)\b/.test(line))
+        return false;
+    return (/\bfunction\b/.test(line) ||
+        /=>\s*\{/.test(line) ||
+        /\)\s*(?::\s*[\w<>[\]|\s,&]+)?\s*\{/.test(line)) && line.includes("{");
+}
+/** Extract function name from a definition line, or null. */
+function extractFuncName(line) {
+    // function foo(
+    let m = line.match(/\bfunction\s+(\w+)\s*\(/);
+    if (m)
+        return m[1] ?? null;
+    // const/let/var foo =
+    m = line.match(/(?:const|let|var)\s+(\w+)\s*=/);
+    if (m)
+        return m[1] ?? null;
+    // method foo(: TypeScript class method
+    m = line.match(/^\s*(?:async\s+)?(\w+)\s*\(/);
+    if (m && !["if", "for", "while", "switch", "try", "catch", "else", "return"].includes(m[1])) {
+        return m[1] ?? null;
+    }
+    return null;
+}
+// ---------------------------------------------------------------------------
+// General quality rules (all languages)
+// ---------------------------------------------------------------------------
+function analyzeGeneral(filepath, lines) {
+    const issues = [];
+    const totalLines = lines.length;
+    // GR001-FILE-SIZE
+    if (totalLines > 500) {
+        issues.push({
+            file: filepath, line: 1, severity: "high", ruleId: "GR001-FILE-SIZE",
+            message: `File is ${totalLines} lines (max: 500)`,
+            suggestion: "Split into smaller modules or extract helpers.",
+        });
+    }
+    // GR002-FUNC-LENGTH: brace-counting, max 400-line scan
+    {
+        let i = 0;
+        while (i < lines.length) {
+            const line = lines[i];
+            if (isFuncDefLine(line)) {
+                let depth = 0;
+                let end = i;
+                let found = false;
+                for (let j = i; j < Math.min(i + 400, lines.length); j++) {
+                    for (const ch of lines[j]) {
+                        if (ch === "{")
+                            depth++;
+                        else if (ch === "}")
+                            depth--;
+                    }
+                    if (depth === 0 && j > i) {
+                        const funcLen = j - i;
+                        if (funcLen > 60) {
+                            const name = extractFuncName(line);
+                            const label = name ? `"${name}"` : "Anonymous function";
+                            issues.push({
+                                file: filepath, line: i + 1,
+                                severity: funcLen > 100 ? "high" : "medium",
+                                ruleId: "GR002-FUNC-LENGTH",
+                                message: `${label} is ${funcLen} lines (max: 60)`,
+                                suggestion: "Break into smaller functions. Each function should do ONE thing.",
+                            });
+                        }
+                        end = j;
+                        found = true;
+                        break;
+                    }
+                }
+                i = found ? end + 1 : i + 1;
+            }
+            else {
+                i++;
+            }
+        }
+    }
+    // GR003 — naming issues (single pass over all lines)
+    const BAD_VAR_NAMES = /\b(?:const|let|var)\s+(x|y|z|tmp|temp|data2|result2|val|obj|foo|bar)\s*=/;
+    const VAGUE_FUNC_NAMES = /\b(handleStuff|doSomething|processData|doWork|manage)\b/;
+    const AND_OR_IN_NAME = /\b\w*(?:And|Or)\w+\b/;
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        const trimmed = line.trim();
+        const num = i + 1;
+        if (trimmed.startsWith("//") || trimmed.startsWith("*") || trimmed.startsWith("#"))
+            continue;
+        // GR003-BAD-VAR
+        const badVarMatch = line.match(BAD_VAR_NAMES);
+        if (badVarMatch) {
+            issues.push({
+                file: filepath, line: num, severity: "medium", ruleId: "GR003-BAD-VAR",
+                message: `Vague variable name "${badVarMatch[1]}"`,
+                suggestion: "Use descriptive names that explain purpose, not shape.",
+            });
+        }
+        // GR003-VAGUE-FUNC (on definition lines only)
+        if (isFuncDefLine(line)) {
+            const vagueMatch = line.match(VAGUE_FUNC_NAMES);
+            if (vagueMatch) {
+                issues.push({
+                    file: filepath, line: num, severity: "medium", ruleId: "GR003-VAGUE-FUNC",
+                    message: `Vague function name "${vagueMatch[1]}"`,
+                    suggestion: "Name functions after their specific action and object (e.g. parseUserResponse).",
+                });
+            }
+            // GR003-AND-NAME
+            const funcName = extractFuncName(line);
+            if (funcName && AND_OR_IN_NAME.test(funcName)) {
+                issues.push({
+                    file: filepath, line: num, severity: "low", ruleId: "GR003-AND-NAME",
+                    message: `Function "${funcName}" suggests multiple responsibilities`,
+                    suggestion: "Split into two functions, one per responsibility.",
+                });
+            }
+        }
+        // GR004-DEEP-NEST: ≥16 leading spaces or ≥4 tabs
+        if (trimmed.length > 0) {
+            const leadingSpaces = line.match(/^( +)/)?.[1]?.length ?? 0;
+            const leadingTabs = line.match(/^(\t+)/)?.[1]?.length ?? 0;
+            if (leadingSpaces >= 16 || leadingTabs >= 4) {
+                issues.push({
+                    file: filepath, line: num, severity: "medium", ruleId: "GR004-DEEP-NEST",
+                    message: "Code nested 4+ levels deep",
+                    suggestion: "Extract nested logic into helper functions or use early returns.",
+                });
+            }
+        }
+    }
+    // GR005-DEAD-CODE: 3+ consecutive commented lines containing code-like tokens
+    {
+        let blockStart = 0;
+        let blockLen = 0;
+        for (let i = 0; i < lines.length; i++) {
+            const trimmed = lines[i].trim();
+            const isCommentedCode = (trimmed.startsWith("//") || trimmed.startsWith("#")) &&
+                /[=({;]/.test(trimmed);
+            if (isCommentedCode) {
+                if (blockLen === 0)
+                    blockStart = i + 1;
+                blockLen++;
+                if (blockLen === 3) {
+                    issues.push({
+                        file: filepath, line: blockStart, severity: "low", ruleId: "GR005-DEAD-CODE",
+                        message: "3+ consecutive commented-out code lines",
+                        suggestion: "Remove dead code. Use version control (git) to track history.",
+                    });
+                }
+            }
+            else {
+                blockLen = 0;
+            }
+        }
+    }
+    return issues;
+}
+// ---------------------------------------------------------------------------
+// Frontend rules (.tsx, .jsx, .vue)
+// ---------------------------------------------------------------------------
+function analyzeFrontend(filepath, lines) {
+    const issues = [];
+    const totalLines = lines.length;
+    // FE001-COMP-SIZE
+    if (totalLines > 300) {
+        issues.push({
+            file: filepath, line: 1, severity: "high", ruleId: "FE001-COMP-SIZE",
+            message: `Component is ${totalLines} lines (max: 300)`,
+            suggestion: "Extract sub-components or custom hooks.",
+        });
+    }
+    // FE002-PROP-COUNT: component destructures > 8 props
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        if (!/(?:function\s+[A-Z]|const\s+[A-Z])\w*.*\(\s*\{/.test(line))
+            continue;
+        // Collect lines until the destructuring block closes
+        let collected = line;
+        let j = i;
+        let opens = (collected.match(/\{/g) ?? []).length;
+        let closes = (collected.match(/\}/g) ?? []).length;
+        while (opens > closes && j < lines.length - 1) {
+            j++;
+            const next = lines[j];
+            collected += " " + next;
+            opens += (next.match(/\{/g) ?? []).length;
+            closes += (next.match(/\}/g) ?? []).length;
+        }
+        // Extract content between ({ and first })
+        const propBlock = collected.match(/\(\s*\{([^}]*)\}/);
+        if (propBlock) {
+            const props = propBlock[1]
+                .split(",")
+                .map((s) => s.trim())
+                .filter((s) => s.length > 0 && !s.startsWith("//"));
+            if (props.length > 8) {
+                issues.push({
+                    file: filepath, line: i + 1, severity: "medium", ruleId: "FE002-PROP-COUNT",
+                    message: `Component destructures ${props.length} props`,
+                    suggestion: "Group related props into objects. Apply Rule #14: Prefer composition.",
+                });
+            }
+        }
+    }
+    // FE003-BOOL-PROPS: 3+ is/has/can/should-prefixed boolean props in a Props interface/type
+    {
+        let inProps = false;
+        let depth = 0;
+        let boolCount = 0;
+        let propsStartLine = 0;
+        for (let i = 0; i < lines.length; i++) {
+            const line = lines[i];
+            if (!inProps && /(?:type|interface)\s+\w*Props\s*(?:=\s*\{|\{)/.test(line)) {
+                inProps = true;
+                depth = 0;
+                boolCount = 0;
+                propsStartLine = i + 1;
+            }
+            if (inProps) {
+                for (const ch of line) {
+                    if (ch === "{")
+                        depth++;
+                    else if (ch === "}")
+                        depth--;
+                }
+                if (/^\s*(is|has|can|should)[A-Z]\w*[?:].*boolean/.test(line)) {
+                    boolCount++;
+                }
+                if (depth <= 0 && i > propsStartLine - 1) {
+                    if (boolCount >= 3) {
+                        issues.push({
+                            file: filepath, line: propsStartLine, severity: "medium", ruleId: "FE003-BOOL-PROPS",
+                            message: `${boolCount} boolean props found (is/has/can/should prefix)`,
+                            suggestion: "Replace with a single `status` prop or `variant` enum.",
+                        });
+                    }
+                    inProps = false;
+                }
+            }
+        }
+    }
+    // FE004-INLINE-STYLE: style={{ in JSX or Vue template
+    for (let i = 0; i < lines.length; i++) {
+        if (/style=\{\{/.test(lines[i])) {
+            issues.push({
+                file: filepath, line: i + 1, severity: "medium", ruleId: "FE004-INLINE-STYLE",
+                message: "Inline style object in JSX/Vue template",
+                suggestion: "Move to a CSS/SCSS module, styled-components, or Tailwind class.",
+            });
+        }
+    }
+    // FE005-FETCH-IN-COMP: fetch/axios at component body depth 1 (not inside hook/effect)
+    {
+        let inComponent = false;
+        let compBraceDepth = 0;
+        for (let i = 0; i < lines.length; i++) {
+            const line = lines[i];
+            if (!inComponent && /(?:function\s+[A-Z]\w*|const\s+[A-Z]\w*\s*=)/.test(line)) {
+                inComponent = true;
+                compBraceDepth = 0;
+            }
+            if (inComponent) {
+                for (const ch of line) {
+                    if (ch === "{")
+                        compBraceDepth++;
+                    else if (ch === "}")
+                        compBraceDepth--;
+                }
+                // depth 1 = top-level body of the component function (not inside a hook/callback)
+                if (compBraceDepth === 1 && /(?:fetch\s*\(|axios\.)/.test(line)) {
+                    issues.push({
+                        file: filepath, line: i + 1, severity: "high", ruleId: "FE005-FETCH-IN-COMP",
+                        message: "fetch() or axios called directly in component body",
+                        suggestion: "Move to a custom hook (e.g. useUserData) or a service layer.",
+                    });
+                }
+                if (compBraceDepth <= 0) {
+                    inComponent = false;
+                    compBraceDepth = 0;
+                }
+            }
+        }
+    }
+    // FE006-DIRECT-DOM: document.querySelector / getElementById in component file
+    for (let i = 0; i < lines.length; i++) {
+        if (/document\.querySelector|document\.getElementById/.test(lines[i])) {
+            issues.push({
+                file: filepath, line: i + 1, severity: "high", ruleId: "FE006-DIRECT-DOM",
+                message: "Direct DOM access in component file",
+                suggestion: "Use refs (useRef in React, ref= in Vue) instead of direct DOM queries.",
+            });
+        }
+    }
+    // FE007-MIXED-STYLE: Tailwind + styled-components + CSS module all in same file
+    {
+        const hasTailwind = lines.some((l) => /className=["'][^"']*(?:flex|grid|text-|bg-|p-\d|m-\d)/.test(l));
+        const hasStyled = lines.some((l) => /import.*from\s+['"]styled-components['"]/.test(l));
+        const hasCssModule = lines.some((l) => /import.*from\s+['"].*\.module\.css['"]/.test(l));
+        if (hasTailwind && hasStyled && hasCssModule) {
+            issues.push({
+                file: filepath, line: 1, severity: "low", ruleId: "FE007-MIXED-STYLE",
+                message: "Three styling systems in one file (Tailwind + styled-components + CSS module)",
+                suggestion: "Choose one styling approach per project and be consistent.",
+            });
+        }
+    }
+    // FE008-JSX-TERNARY: nested ternary on a JSX-bearing line
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        // JSX line: contains < followed by uppercase letter or /
+        if (!/<[A-Z/]/.test(line) && !/<\//.test(line))
+            continue;
+        // Nested ternary: two ? ... : patterns on the same line
+        if (/\?[^?:]+:[^?:]*\?/.test(line)) {
+            issues.push({
+                file: filepath, line: i + 1, severity: "medium", ruleId: "FE008-JSX-TERNARY",
+                message: "Nested ternary expression in JSX",
+                suggestion: "Extract condition to a variable or sub-component for readability.",
+            });
+        }
+    }
+    return issues;
+}
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+export function analyzeCodeQuality(filepath, source, lang) {
+    const lines = source.split("\n");
+    const issues = [
+        ...analyzeGeneral(filepath, lines),
+        ...(isFrontend(filepath, lang) ? analyzeFrontend(filepath, lines) : []),
+    ];
+    issues.sort((a, b) => {
+        const sevDiff = SEVERITY_ORDER[a.severity] - SEVERITY_ORDER[b.severity];
+        return sevDiff !== 0 ? sevDiff : a.line - b.line;
+    });
+    return issues;
+}
+export function formatQualityReport(filepath, issues) {
+    const out = [
+        "=".repeat(60),
+        "🏛️  CODE QUALITY GUARD — Report",
+        "=".repeat(60),
+        `File: ${filepath}`,
+        `Issues: ${issues.length}`,
+        "",
+    ];
+    if (issues.length === 0) {
+        out.push("✅ All quality checks passed.");
+        out.push("   Review the full checklist with the coding_rules tool before marking done.");
+    }
+    else {
+        for (const sev of ["high", "medium", "low"]) {
+            const group = issues.filter((i) => i.severity === sev);
+            if (group.length === 0)
+                continue;
+            out.push(`--- ${sev.toUpperCase()} (${group.length}) ---`);
+            for (const issue of group) {
+                out.push(`${SEVERITY_ICON[sev]} [${issue.ruleId}] line ${issue.line} — ${issue.message}`);
+                out.push(`   💡 ${issue.suggestion}`);
+            }
+            out.push("");
+        }
+        const hasHigh = issues.some((i) => i.severity === "high");
+        out.push(hasHigh
+            ? "❌ FAIL — Fix high-severity issues before proceeding."
+            : "⚠️  WARN — Medium/low issues found. Review before marking done.");
+    }
+    out.push("=".repeat(60));
+    return out.join("\n");
+}

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

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

package/build/guardian/coding-rules.js

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