kernhell 0.1.0__py3-none-any.whl

kernhell/scanner/runner.py

@@ -0,0 +1,242 @@
+"""Scanner runner — executes Playwright tests and captures failures + live DOM.
+
+Weekend 1 strategy: **Subprocess-based** execution.
+  1. Run the test file via ``pytest`` in a subprocess.
+  2. If it fails, parse the error output for broken selectors.
+  3. Re-launch a browser, navigate to the page URL extracted from the test,
+     and capture ``page.content()`` for the live DOM snapshot.
+
+This approach is simpler but less precise than the step-by-step interceptor
+(planned for Weekend 3).  It works reliably for the common case where the
+test navigates to a URL before interacting with elements.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import subprocess
+import re
+import sys
+from pathlib import Path
+
+import structlog
+
+from kernhell.core.config import KernHellConfig
+from kernhell.core.exceptions import (
+    NoFailuresDetectedError,
+    PlaywrightNotInstalledError,
+    ScannerError,
+    TestFileNotFoundError,
+)
+from kernhell.core.models import FailureContext
+from kernhell.scanner.parser import parse_playwright_errors
+
+logger = structlog.get_logger()
+
+
+def _extract_url_from_test(test_file: Path) -> str | None:
+    """Extract the first ``page.goto(...)`` URL from a test file.
+
+    This is a best-effort heuristic used to re-open the page for DOM capture.
+    """
+    try:
+        content = test_file.read_text(encoding="utf-8")
+    except Exception:
+        return None
+
+    # Match: page.goto("https://example.com") or page.goto('...')
+    m = re.search(r"""page\.goto\(\s*["'](.+?)["']""", content)
+    return m.group(1) if m else None
+
+
+class ScannerRunner:
+    """Executes a Playwright test file and captures failure context.
+
+    Parameters
+    ----------
+    config:
+        The KernHell configuration (scanner timeout, browser, headless, etc.).
+    """
+
+    def __init__(self, config: KernHellConfig) -> None:
+        self._config = config
+        self._scanner_cfg = config.scanner
+
+    def run(self, test_file: Path) -> list[FailureContext]:
+        """Run the test file and return structured failures.
+
+        Parameters
+        ----------
+        test_file:
+            Path to the Playwright test file (e.g., ``tests/test_checkout.py``).
+
+        Returns
+        -------
+        list[FailureContext]
+            One entry per broken selector detected.  The ``live_dom`` field
+            will be populated if we can successfully re-open the page.
+
+        Raises
+        ------
+        TestFileNotFoundError
+            If *test_file* does not exist.
+        ScannerError
+            If the test runner itself fails to execute.
+        NoFailuresDetectedError
+            If the test passes with zero selector failures.
+        """
+        test_file = test_file.resolve()
+        if not test_file.is_file():
+            raise TestFileNotFoundError(f"Test file not found: {test_file}")
+
+        logger.info("scanner.run.start", test_file=str(test_file))
+
+        # Step 1: Run the test via pytest subprocess
+        error_output = self._run_pytest(test_file)
+
+        if error_output is None:
+            raise NoFailuresDetectedError(
+                f"All tests passed in {test_file.name} — nothing to heal!"
+            )
+
+        # Step 2: Parse the error output
+        failures = parse_playwright_errors(error_output, test_file)
+
+        if not failures:
+            raise NoFailuresDetectedError(
+                f"Test failed but no Playwright selector errors detected in {test_file.name}. "
+                "The failure may not be selector-related."
+            )
+
+        # Step 3: Capture live DOM for each failure
+        page_url = _extract_url_from_test(test_file)
+        if page_url:
+            live_dom = self._capture_live_dom(page_url)
+            if live_dom:
+                for f in failures:
+                    f.live_dom = live_dom
+                    f.page_url = page_url
+
+        logger.info(
+            "scanner.run.done",
+            test_file=str(test_file),
+            failures=len(failures),
+            has_dom=bool(failures[0].live_dom) if failures else False,
+        )
+        return failures
+
+    def _run_pytest(self, test_file: Path) -> str | None:
+        """Execute pytest on the test file and return error output.
+
+        Returns *None* if the test passes (exit code 0).
+        """
+        cmd = [
+            sys.executable,
+            "-m",
+            "pytest",
+            str(test_file),
+            "-v",
+            "--tb=long",
+            "--no-header",
+            f"--timeout={self._scanner_cfg.timeout_ms // 1000}",
+        ]
+
+        logger.debug("scanner.pytest.exec", cmd=" ".join(cmd))
+
+        try:
+            result = subprocess.run(
+                cmd,
+                capture_output=True,
+                text=True,
+                timeout=self._scanner_cfg.timeout_ms * 3 / 1000,  # 3x the action timeout
+                cwd=str(test_file.parent),
+            )
+        except FileNotFoundError:
+            raise PlaywrightNotInstalledError(
+                "pytest is not installed or not on PATH. "
+                "Run: pip install pytest pytest-playwright"
+            )
+        except subprocess.TimeoutExpired:
+            raise ScannerError(
+                f"Test execution timed out after {self._scanner_cfg.timeout_ms * 3}ms"
+            )
+
+        if result.returncode == 0:
+            logger.info("scanner.pytest.passed", test_file=str(test_file))
+            return None
+
+        # Combine stdout and stderr for full error context
+        combined = result.stdout + "\n" + result.stderr
+        logger.debug(
+            "scanner.pytest.failed",
+            exit_code=result.returncode,
+            output_len=len(combined),
+        )
+        return combined
+
+    def _capture_live_dom(self, url: str) -> str:
+        """Re-open the page URL and capture the live DOM HTML.
+
+        Uses Playwright's sync API to launch a browser, navigate to the URL,
+        and grab ``page.content()``.  This gives us the actual DOM state
+        the developer sees, even if selectors changed.
+        """
+        try:
+            return asyncio.get_event_loop().run_until_complete(
+                self._async_capture_dom(url)
+            )
+        except RuntimeError:
+            # No event loop running — create one
+            return asyncio.run(self._async_capture_dom(url))
+
+    async def _async_capture_dom(self, url: str) -> str:
+        """Async implementation of DOM capture."""
+        try:
+            from playwright.async_api import async_playwright
+        except ImportError:
+            raise PlaywrightNotInstalledError(
+                "Playwright is not installed. Run: pip install playwright && playwright install"
+            )
+
+        logger.debug("scanner.dom_capture.start", url=url)
+
+        try:
+            async with async_playwright() as p:
+                browser_type = getattr(p, self._scanner_cfg.browser, p.chromium)
+                browser = await browser_type.launch(headless=self._scanner_cfg.headless)
+                page = await browser.new_page()
+
+                try:
+                    await page.goto(
+                        url,
+                        wait_until="domcontentloaded",
+                        timeout=self._scanner_cfg.timeout_ms,
+                    )
+                    # Wait a bit for dynamic content
+                    await page.wait_for_timeout(1000)
+                    dom = await page.content()
+
+                    # Optional screenshot
+                    if self._scanner_cfg.capture_screenshot:
+                        screenshot = await page.screenshot(full_page=True)
+                        logger.debug(
+                            "scanner.screenshot.captured",
+                            size=len(screenshot),
+                        )
+
+                    logger.info(
+                        "scanner.dom_capture.done",
+                        url=url,
+                        dom_size=len(dom),
+                    )
+                    return dom
+                finally:
+                    await browser.close()
+
+        except Exception as exc:
+            logger.warning(
+                "scanner.dom_capture.failed",
+                url=url,
+                error=str(exc),
+            )
+            return ""

kernhell/utils/__init__.py

@@ -0,0 +1 @@
+"""Utility package — logging, file I/O, and git helpers."""

kernhell/utils/file_utils.py

@@ -0,0 +1,117 @@
+"""Safe file I/O utilities for KernHell.
+
+Every file write goes through these helpers so we can:
+  - Create automatic backups before patching.
+  - Handle encoding consistently (UTF-8 everywhere).
+  - Provide atomic writes to prevent half-written files on crash.
+"""
+
+from __future__ import annotations
+
+import os
+import shutil
+import tempfile
+from pathlib import Path
+
+import structlog
+
+logger = structlog.get_logger()
+
+
+def read_file(path: Path) -> str:
+    """Read a file as UTF-8 text.
+
+    Raises
+    ------
+    FileNotFoundError
+        If the file does not exist.
+    """
+    resolved = path.resolve()
+    logger.debug("file.read", path=str(resolved))
+    return resolved.read_text(encoding="utf-8")
+
+
+def write_file(path: Path, content: str) -> None:
+    """Write content to a file atomically.
+
+    Writes to a temporary file in the same directory first, then
+    atomically replaces the target.  This prevents data loss if the
+    process crashes mid-write.
+    """
+    resolved = path.resolve()
+    resolved.parent.mkdir(parents=True, exist_ok=True)
+
+    # Write to a temp file in the same directory so os.replace is atomic.
+    fd, tmp_path_str = tempfile.mkstemp(
+        dir=str(resolved.parent),
+        prefix=".kernhell_",
+        suffix=".tmp",
+    )
+    # Important on Windows: close file descriptor immediately so file isn't locked
+    os.close(fd)
+    tmp_path = Path(tmp_path_str)
+    try:
+        tmp_path.write_text(content, encoding="utf-8")
+        os.replace(str(tmp_path), str(resolved))
+        logger.debug("file.write", path=str(resolved), size=len(content))
+    except Exception:
+        # Clean up the temp file on failure.
+        tmp_path.unlink(missing_ok=True)
+        raise
+
+
+def backup_file(path: Path, suffix: str = ".kernhell.bak") -> Path:
+    """Create a backup copy of a file before patching.
+
+    Returns the path to the backup file.
+    """
+    resolved = path.resolve()
+    backup_path = resolved.with_suffix(resolved.suffix + suffix)
+    shutil.copy2(str(resolved), str(backup_path))
+    logger.info("file.backup", original=str(resolved), backup=str(backup_path))
+    return backup_path
+
+
+def restore_from_backup(original: Path, suffix: str = ".kernhell.bak") -> bool:
+    """Restore a file from its backup.  Returns True if successful."""
+    resolved = original.resolve()
+    backup_path = resolved.with_suffix(resolved.suffix + suffix)
+    if backup_path.is_file():
+        shutil.copy2(str(backup_path), str(resolved))
+        logger.info("file.restore", path=str(resolved))
+        return True
+    logger.warning("file.restore.missing", backup=str(backup_path))
+    return False
+
+
+def extract_surrounding_lines(
+    content: str,
+    line_number: int,
+    context: int = 10,
+) -> str:
+    """Extract ±context lines around a specific line number.
+
+    Parameters
+    ----------
+    content:
+        Full file content.
+    line_number:
+        1-indexed line number to centre on.
+    context:
+        Number of lines to include above and below.
+
+    Returns
+    -------
+    str
+        The extracted lines with line numbers prefixed.
+    """
+    lines = content.splitlines()
+    start = max(0, line_number - 1 - context)
+    end = min(len(lines), line_number + context)
+
+    numbered: list[str] = []
+    for i, line in enumerate(lines[start:end], start=start + 1):
+        marker = " >>> " if i == line_number else "     "
+        numbered.append(f"{i:4d}{marker}{line}")
+
+    return "\n".join(numbered)

kernhell/utils/logger.py

@@ -0,0 +1,78 @@
+"""Structured logging configuration for KernHell.
+
+Uses ``structlog`` with two output modes:
+  - **Console** (default): Rich-coloured, human-friendly output via
+    ``structlog.dev.ConsoleRenderer``.
+  - **JSON** (``--json-log`` or CI): Machine-parseable JSON lines, ideal
+    for log aggregation.
+
+Call :func:`setup_logging` once at startup (done automatically by the CLI).
+After that, obtain loggers anywhere with ``structlog.get_logger()``.
+"""
+
+from __future__ import annotations
+
+import logging
+import sys
+
+import structlog
+
+
+def setup_logging(*, level: str = "INFO", json_output: bool = False) -> None:
+    """Configure structlog and stdlib logging for the application.
+
+    Parameters
+    ----------
+    level:
+        Minimum log level (``DEBUG``, ``INFO``, ``WARNING``, ``ERROR``).
+    json_output:
+        When *True*, emit JSON lines instead of coloured console output.
+        Recommended for CI/CD environments.
+    """
+    log_level = getattr(logging, level.upper(), logging.INFO)
+
+    # Shared processors run before the final renderer.
+    shared_processors: list[structlog.types.Processor] = [
+        structlog.contextvars.merge_contextvars,
+        structlog.stdlib.add_log_level,
+        structlog.stdlib.add_logger_name,
+        structlog.processors.TimeStamper(fmt="iso"),
+        structlog.processors.StackInfoRenderer(),
+        structlog.processors.UnicodeDecoder(),
+    ]
+
+    if json_output:
+        renderer: structlog.types.Processor = structlog.processors.JSONRenderer()
+    else:
+        renderer = structlog.dev.ConsoleRenderer(
+            colors=sys.stderr.isatty(),
+        )
+
+    structlog.configure(
+        processors=[
+            *shared_processors,
+            structlog.stdlib.ProcessorFormatter.wrap_for_formatter,
+        ],
+        logger_factory=structlog.stdlib.LoggerFactory(),
+        wrapper_class=structlog.stdlib.BoundLogger,
+        cache_logger_on_first_use=True,
+    )
+
+    formatter = structlog.stdlib.ProcessorFormatter(
+        processors=[
+            structlog.stdlib.ProcessorFormatter.remove_processors_meta,
+            renderer,
+        ],
+    )
+
+    handler = logging.StreamHandler(sys.stderr)
+    handler.setFormatter(formatter)
+
+    root = logging.getLogger()
+    root.handlers.clear()
+    root.addHandler(handler)
+    root.setLevel(log_level)
+
+    # Silence noisy third-party loggers.
+    for noisy in ("playwright", "urllib3", "httpx", "chromadb"):
+        logging.getLogger(noisy).setLevel(logging.WARNING)

kernhell-0.1.0.dist-info/METADATA

@@ -0,0 +1,245 @@
+Metadata-Version: 2.5
+Name: kernhell
+Version: 0.1.0
+Summary: AI-Powered Autonomous Self-Healing Testing Engine — The Heart of Your System Where Innovation Meets Precision
+Project-URL: Homepage, https://github.com/riteshkumar072/KernHell
+Project-URL: Documentation, https://github.com/riteshkumar072/KernHell#readme
+Project-URL: Repository, https://github.com/riteshkumar072/KernHell
+Project-URL: Issues, https://github.com/riteshkumar072/KernHell/issues
+Author-email: Ritesh <ritesh@kernhell.dev>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai,cli,playwright,self-healing,testing
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.11
+Requires-Dist: libcst>=1.1.0
+Requires-Dist: litellm<2.0,>=1.30
+Requires-Dist: playwright<2.0,>=1.40
+Requires-Dist: pydantic-settings<3.0,>=2.1
+Requires-Dist: pydantic<3.0,>=2.5
+Requires-Dist: rich<16.0,>=13.0
+Requires-Dist: selectolax<1.0,>=0.3
+Requires-Dist: structlog>=24.0
+Requires-Dist: tomli>=2.0; python_version < '3.11'
+Requires-Dist: typer<1.0,>=0.12
+Provides-Extra: all
+Requires-Dist: aiosqlite<1.0,>=0.19; extra == 'all'
+Requires-Dist: build>=1.0.0; extra == 'all'
+Requires-Dist: chromadb<1.0,>=0.4; extra == 'all'
+Requires-Dist: fastapi<1.0,>=0.110; extra == 'all'
+Requires-Dist: mypy<2.0,>=1.8; extra == 'all'
+Requires-Dist: pytest-asyncio<1.0,>=0.23; extra == 'all'
+Requires-Dist: pytest-cov<6.0,>=5.0; extra == 'all'
+Requires-Dist: pytest<9.0,>=8.0; extra == 'all'
+Requires-Dist: ruff<1.0,>=0.3; extra == 'all'
+Requires-Dist: sentence-transformers<3.0,>=2.2; extra == 'all'
+Requires-Dist: twine>=5.0.0; extra == 'all'
+Requires-Dist: uvicorn[standard]<1.0,>=0.27; extra == 'all'
+Provides-Extra: cache
+Requires-Dist: chromadb<1.0,>=0.4; extra == 'cache'
+Requires-Dist: sentence-transformers<3.0,>=2.2; extra == 'cache'
+Provides-Extra: dashboard
+Requires-Dist: aiosqlite<1.0,>=0.19; extra == 'dashboard'
+Requires-Dist: fastapi<1.0,>=0.110; extra == 'dashboard'
+Requires-Dist: uvicorn[standard]<1.0,>=0.27; extra == 'dashboard'
+Provides-Extra: dev
+Requires-Dist: build>=1.0.0; extra == 'dev'
+Requires-Dist: mypy<2.0,>=1.8; extra == 'dev'
+Requires-Dist: pytest-asyncio<1.0,>=0.23; extra == 'dev'
+Requires-Dist: pytest-cov<6.0,>=5.0; extra == 'dev'
+Requires-Dist: pytest<9.0,>=8.0; extra == 'dev'
+Requires-Dist: ruff<1.0,>=0.3; extra == 'dev'
+Requires-Dist: twine>=5.0.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# 🔥 KernHell
+
+> *"The Heart of Your System Where Innovation Meets Precision"*
+
+**AI-Powered Autonomous Self-Healing Testing Engine & CLI tool for Playwright.**
+
+[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/)
+[![Next.js 14](https://img.shields.io/badge/dashboard-Next.js%2014-black.svg)](https://nextjs.org/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![CI/CD Status](https://img.shields.io/badge/tests-59%20passed%20(100%25)-brightgreen.svg)](https://github.com/riteshkumar072/KernHell)
+
+---
+
+## ⚡ The Problem
+
+Modern frontend engineering moves fast. When developers refactor classes, IDs, or DOM wrappers (e.g., `#buy-now` becomes `#purchase-btn`), automated Playwright and Selenium test suites fail even though the business functionality works seamlessly. QA teams waste 30–40% of their time manually maintaining broken selectors.
+
+**KernHell autonomously resolves broken selectors in real-time, preserving 100% of your code formatting, comments, and QA sanity.**
+
+---
+
+## 🏛️ Autonomous 6-Stage Healing Architecture
+
+```mermaid
+flowchart TD
+    A[Playwright Locator Timeout] -->|1. Intercept| B(Scanner & Live DOM Capture)
+    B -->|2. Prune| C(Selectolax Lexbor HTML5 Pruner)
+    C -->|85% Token Reduction| D{3. Dense Vector Cache}
+    D -->|Cache Hit <5ms| G[Strict DOM Verification]
+    D -->|Cache Miss| E[4. AI Brain: LiteLLM Gateway]
+    E -->|Intent Diagnosis| F{RENAME vs MISSING?}
+    F -->|MISSING: Real Bug| H[Anti-Hallucination Guardrail: Abort Healing]
+    F -->|RENAME: Safe Refactor| G
+    G -->|5. Verify Unambiguous Element| I[Selector Fix: role / data-testid / text]
+    I -->|Store Embedding| D
+    I -->|6. Surgical Patch| J[LibCST AST Patcher]
+    J -->|Preserve Comments & Formatting| K[Automatic Verification Runner]
+    K -->|Pass| L[Commit Fix & Log Run]
+    K -->|Fail| M[Immediate Rollback from .kernhell.bak]
+```
+
+---
+
+## 🚀 Key Features
+
+- **Failure Interception & Live DOM Capture (`Scanner`)**: Intercepts Playwright selector timeouts and crashes, capturing the error stack trace, line number, broken selector, and live DOM snapshot (`page.content()`).
+- **High-Speed Semantic DOM Pruning (`DOMPruner`)**: Strips scripts, styles, SVGs, base64 data, and non-semantic wrappers using `selectolax` to slash token usage by 80–90% while keeping semantic landmarks and accessibility roles.
+- **Semantic Vector Memory (`Vector Cache`)**: 384-dimensional dense cosine index matching broken selectors against historical fixes. Resolves recurring failures in **<5ms** with zero LLM API cost.
+- **Strict Anti-Hallucination Guardrails**: Distinguishes between renamed selectors (`RENAME`) and genuine missing features (`MISSING`) to prevent false-positive heals on actual product regressions.
+- **Surgical LibCST AST Patching (`Patcher`)**: Surgically transforms only the target locator expression in the AST without reformatting unrelated code or stripping inline comments.
+- **Automated Verification & Zero-Risk Rollback (`Verifier`)**: Re-runs the patched test in a sandbox; if it fails, immediately restores the code from `.kernhell.bak`.
+- **Mission Control Dashboard (`Next.js App Router`)**: High-tech, dark-mode glassmorphic web dashboard providing live stats, real-time healing stream, semantic memory inspector, and interactive simulation playground.
+
+---
+
+## 📦 Installation
+
+```bash
+# Clone the repository
+git clone https://github.com/riteshkumar072/KernHell.git
+cd KernHell
+
+# Install Python package in editable mode with all dependencies
+pip install -e ".[all]"
+
+# Install Mission Control dashboard dependencies
+cd dashboard
+npm install
+cd ..
+```
+
+---
+
+## 🛠️ CLI Usage
+
+```text
+Usage: kernhell [OPTIONS] COMMAND [ARGS]...
+
+┌─ Commands ──────────────────────────────────────────────────────────────────┐
+│ scan       Scan a test file to detect broken selectors and capture DOM      │
+│            snapshots.                                                       │
+│ heal       Autonomously heal broken Playwright selectors in a test file.    │
+│ dashboard  Launch the KernHell Mission Control Dashboard and REST API.      │
+│ ui         Alias for 'dashboard' command.                                   │
+│ cache      Inspect, query, and manage KernHell's Semantic Vector Cache.     │
+│ config     View and configure KernHell engine parameters.                   │
+└─────────────────────────────────────────────────────────────────────────────┘
+```
+
+### 1. Scan a Test File for Broken Selectors
+
+```bash
+kernhell scan tests/test_checkout.py
+```
+
+### 2. Autonomously Heal a Test File or Suite
+
+```bash
+# Preview changes without modifying code (dry run)
+kernhell heal tests/test_checkout.py --dry-run
+
+# Surgically patch and verify fix with automatic backup
+kernhell heal tests/test_checkout.py
+
+# Batch heal all test files in a folder
+kernhell heal tests/
+
+# Export machine-readable report for CI/CD pipelines
+kernhell heal tests/ --output json
+```
+
+### 3. Launch the Mission Control Dashboard
+
+```bash
+# Start FastAPI REST API and open dashboard in browser
+kernhell dashboard
+
+# Or run Next.js frontend directly:
+cd dashboard
+npm run dev
+```
+
+Visit **`http://localhost:3000`** to view the live dashboard and interactive playground.
+
+### 4. Semantic Vector Memory & Cache
+
+```bash
+# List all verified cached selector mappings
+kernhell cache list
+
+# View cache hit/miss ratio and efficiency metrics
+kernhell cache stats
+
+# Purge semantic memory
+kernhell cache clear
+```
+
+### 5. Engine Configuration
+
+```bash
+# Display active settings
+kernhell config show
+
+# Run the interactive configuration wizard
+kernhell config init
+```
+
+---
+
+## 🖥️ Mission Control Dashboard
+
+The dashboard provides a production-grade operations center:
+
+- **Overview (`/`)**: Real-time healing metrics (autonomous fixes, cache efficiency, real bugs guarded, dollar savings), live 6-stage pipeline status, and recent activity stream.
+- **Interactive Playground (`/playground`)**: Test healer sandbox with pre-configured refactor scenarios and out-of-stock guardrail alerts.
+- **Semantic Memory Explorer (`/cache`)**: Searchable browser for 384-dimensional dense vector embeddings with hit counts and verification badges.
+- **Run History & Diffs (`/history`)**: Audit trail with side-by-side syntax-highlighted unified diffs of AST code patches.
+
+---
+
+## 🧪 Running the Test Suite
+
+```bash
+# Run all 59 unit and integration tests
+python -m pytest -v
+
+# Run with test coverage
+python -m pytest tests/unit -v --cov=src/kernhell
+```
+
+---
+
+## 🗺️ Execution Roadmap
+
+- [x] **Weekend 1: Foundation (Scanner, Pruner, Core Models & CLI)**
+- [x] **Weekend 2: AI Brain (Analyzer, Healer, CST Surgical Patcher & Verifier)**
+- [x] **Weekend 3: Semantic Memory (Vector Cache, Embedder, Batch Healing & CI Export)**
+- [x] **Weekend 4: Mission Control Dashboard (Next.js & Production Release)**
+
+---
+
+## 📄 License
+
+MIT &copy; 2026 Ritesh Kumar • KernHell Systems