feat: self-healing engine — rule failure detection + auto-patching

sdk/mkdocs.yml

@@ -0,0 +1,78 @@
+site_name: Gradata
+site_description: AI behavioral adaptation engine. Corrections graduate into rules.
+repo_url: https://github.com/gradata-systems/gradata
+repo_name: gradata-systems/gradata
+
+theme:
+  name: material
+  palette:
+    - scheme: slate
+      primary: deep purple
+      accent: amber
+      toggle:
+        icon: material/brightness-4
+        name: Light mode
+    - scheme: default
+      primary: deep purple
+      accent: amber
+      toggle:
+        icon: material/brightness-7
+        name: Dark mode
+  features:
+    - navigation.instant
+    - navigation.tracking
+    - navigation.sections
+    - navigation.expand
+    - content.code.copy
+    - content.code.annotate
+    - search.highlight
+
+nav:
+  - Home: index.md
+  - Getting Started:
+    - Installation: getting-started/install.md
+    - Quick Start: getting-started/quickstart.md
+    - Core Concepts: getting-started/concepts.md
+  - Gradata Cloud:
+    - Overview: cloud/overview.md
+    - Getting Started: cloud/quickstart.md
+    - API Reference: cloud/api.md
+    - Marketplace: cloud/marketplace.md
+  - Guides:
+    - Training a Brain: guides/training.md
+    - Custom Domains: guides/custom-domains.md
+    - MCP Integration: guides/mcp.md
+  - API Reference:
+    - Brain Class: api/brain.md
+    - CLI: api/cli.md
+  - Contributing:
+    - Architecture: architecture/overview.md
+    - Patterns: architecture/patterns.md
+    - Enhancements: architecture/enhancements.md
+    - Brain Data: architecture/brain.md
+    - Agent Adaptation: architecture/agent-graduation.md
+    - Patterns API: api/patterns.md
+    - Enhancements API: api/enhancements.md
+    - Agent Adaptation Guide: guides/agent-graduation.md
+
+plugins:
+  - search
+  - mkdocstrings:
+      handlers:
+        python:
+          paths: [src]
+          options:
+            show_source: false
+            show_root_heading: true
+            heading_level: 2
+
+markdown_extensions:
+  - admonition
+  - pymdownx.details
+  - pymdownx.superfences
+  - pymdownx.highlight:
+      anchor_linenums: true
+  - pymdownx.tabbed:
+      alternate_style: true
+  - toc:
+      permalink: true

src/gradata/_core.py

@@ -377,6 +377,29 @@ def brain_correct(
     except Exception as e:
         _log.debug("Domain fire attribution failed: %s", e)
 
+    # Self-healing: detect rule failures
+    try:
+        from gradata.enhancements.self_healing import detect_rule_failure
+
+        all_lessons = brain._load_lessons()
+        failure = detect_rule_failure(
+            lessons=all_lessons,
+            correction_category=category or "UNKNOWN",
+            correction_description=desc or summary or "",
+        )
+        if failure:
+            failure["correction_event_id"] = event.get("id")
+            failure["correction_severity"] = diff.severity
+            brain.emit(
+                "RULE_FAILURE", "brain.correct:self_healing",
+                failure,
+                [f"category:{failure['failed_rule_category']}", "self_healing"],
+                session,
+            )
+            event["rule_failure_detected"] = True
+    except Exception as e:
+        _log.debug("Self-healing detection failed: %s", e)
+
     # Persist rule graph
     if hasattr(brain, '_rule_graph') and brain._rule_graph:
         with contextlib.suppress(Exception):

src/gradata/brain.py

@@ -336,6 +336,48 @@ def correct(self, draft: str, final: str, category: str | None = None,
                              approval_required=approval_required, dry_run=dry_run,
                              min_severity=min_severity, scope=scope)
 
+    def patch_rule(self, category: str, old_description: str, new_description: str,
+                   reason: str = "") -> dict:
+        """Rewrite a rule's description. Preserves confidence/metadata. Emits RULE_PATCHED event."""
+        from gradata._db import write_lessons_safe
+        from gradata.enhancements.self_healing import apply_patch
+        from gradata.enhancements.self_improvement import format_lessons, parse_lessons
+
+        # Only patch the brain-local lessons file — never external fallbacks
+        lessons_path = self.dir / "lessons.md"
+        if not lessons_path.is_file():
+            return {"patched": False, "error": "not_found: no brain-local lessons file"}
+
+        lessons = parse_lessons(lessons_path.read_text(encoding="utf-8"))
+        patched = apply_patch(lessons, category, old_description, new_description)
+
+        if not patched:
+            return {"patched": False, "error": f"not_found: no rule matching category={category!r}"}
+
+        write_lessons_safe(lessons_path, format_lessons(lessons))
+
+        # Re-sign the patched rule so HMAC verification stays valid
+        try:
+            from gradata.enhancements.rule_integrity import sign_and_store
+            sign_and_store(self.db_path, new_description, category, patched.confidence)
+        except ImportError:
+            pass  # unsigned mode — no-op
+
+        self.emit("RULE_PATCHED", "brain.patch_rule", {
+            "category": category,
+            "old_description": old_description[:200],
+            "new_description": new_description[:200],
+            "reason": reason,
+            "confidence_preserved": patched.confidence,
+        }, [f"category:{category}", "self_healing"])
+
+        return {
+            "patched": True,
+            "old_description": old_description,
+            "new_description": new_description,
+            "confidence_preserved": patched.confidence,
+        }
+
     def end_session(self, session_corrections: list[dict] | None = None,
                     session_type: str = "full", machine_mode: bool | None = None,
                     skip_meta_rules: bool = False) -> dict:
@@ -665,6 +707,7 @@ def review_pending(self) -> list[dict]:
             import sqlite3
 
             from gradata._db import get_connection
+
             conn = get_connection(self.db_path)
             conn.row_factory = sqlite3.Row
             rows = conn.execute(

src/gradata/enhancements/rule_canary.py

@@ -78,6 +78,7 @@ def _get_db_path(ctx=None) -> Path:
             return p
 
     # 3. Relative traversal (SDK installed alongside brain)
+    # Expects: src/gradata/enhancements/rule_canary.py -> 5 parents -> repo/brain/
     try:
         scripts_dir = Path(__file__).resolve().parent.parent.parent.parent.parent / "brain"
         p = scripts_dir / "system.db"
@@ -148,8 +149,9 @@ def check_canary_health(rule_category: str, session: int, db_path: Path | None =
             try:
                 corr_row = conn.execute(
                     "SELECT COUNT(*) as cnt FROM events WHERE type = 'CORRECTION' "
-                    "AND data_json LIKE ? AND CAST(session AS INTEGER) >= ?",
-                    (f'%"{rule_category}"%', start_session),
+                    "AND json_extract(data_json, '$.rule_category') = ? "
+                    "AND CAST(session AS INTEGER) >= ?",
+                    (rule_category, start_session),
                 ).fetchone()
                 if corr_row:
                     correction_count = corr_row["cnt"]

src/gradata/enhancements/rule_integrity.py

@@ -139,6 +139,10 @@ def sign_lesson_file(lessons_path: Path) -> dict[str, str]:
     Parses lesson lines matching [STATE:CONF] CATEGORY: description
     and returns a {category: signature} map.
 
+    Note: Only the *last* rule per category is retained. This is intentional —
+    graduation produces one canonical rule per category, so duplicates indicate
+    stale entries. The returned dict is keyed by category for O(1) lookup.
+
     Args:
         lessons_path: Path to lessons.md file.
 
@@ -208,8 +212,7 @@ def verify_lesson_file(lessons_path: Path, signatures: dict[str, str]) -> list[s
 
 def _ensure_table(db_path: Path) -> None:
     """Create rule_signatures table if it doesn't exist."""
-    conn = sqlite3.connect(str(db_path))
-    try:
+    with sqlite3.connect(str(db_path)) as conn:
         conn.execute("""
             CREATE TABLE IF NOT EXISTS rule_signatures (
                 category TEXT PRIMARY KEY,
@@ -218,8 +221,6 @@ def _ensure_table(db_path: Path) -> None:
             )
         """)
         conn.commit()
-    finally:
-        conn.close()
 
 
 def store_signature(db_path: Path, category: str, signature: str) -> None: