synapse-hub 0.0.0-stage → 2.0.0

package/tools/analyze_project.py

@@ -0,0 +1,242 @@
+#!/usr/bin/env python3
+"""
+Enterprise QA Project Analyzer & Intelligence Aggregator
+---------------------------------------------------------
+Consolidates all project diagnostic and AST analysis tools into a single workflow.
+Dispatched when user requests: 'analyze project', 're-analyze', 'audit project'.
+
+Executes in sequence:
+  1. Environment & Structure Diagnostic (tools/check_env.py)
+  2. Page Class & AST Repository Mapping (tools/repo_map.py)
+  3. Static Defect & Fake-Pass Sentinel (tools/infer_linter.py)
+  4. Data Flow Lifecycle & Teardown Audit (tools/trace_data_flow.py)
+  5. Definition of Done 7 Quality Gates (tools/verify_all.py)
+
+Generates & Updates In-Place inside the Target Project:
+  - PROJECT_HEALTH_REPORT.md (Root & reports/ of target project)
+  - repo_map.txt (AST method map inside target project root)
+"""
+
+import os
+import sys
+import json
+import argparse
+from datetime import datetime
+from pathlib import Path
+
+# Enforce UTF-8 stdout encoding for Windows console compatibility
+if hasattr(sys.stdout, 'reconfigure'):
+    try:
+        sys.stdout.reconfigure(encoding='utf-8')
+        sys.stderr.reconfigure(encoding='utf-8')
+    except Exception:
+        pass
+
+SCRIPT_DIR = os.path.dirname(os.path.abspath(__file__))
+HUB_ROOT = os.path.abspath(os.path.join(SCRIPT_DIR, ".."))
+sys.path.insert(0, SCRIPT_DIR)
+
+import check_env
+import repo_map
+import infer_linter
+import trace_data_flow
+import verify_all
+
+# ANSI formatting
+GREEN = "\033[92m"
+RED = "\033[91m"
+YELLOW = "\033[93m"
+CYAN = "\033[96m"
+BOLD = "\033[1m"
+RESET = "\033[0m"
+
+
+def resolve_target_repo(cli_target=None, cli_repo=None):
+    chosen = cli_repo or cli_target
+    if chosen:
+        resolved = os.path.abspath(chosen)
+        if not os.path.exists(resolved):
+            raise FileNotFoundError(f"Target repository path not found: {resolved}")
+        return resolved
+
+    env_dir = os.environ.get("TARGET_PROJECT_DIR")
+    if env_dir and os.path.exists(env_dir):
+        return os.path.abspath(env_dir)
+
+    cwd = os.path.abspath(os.getcwd())
+    if cwd.lower() != HUB_ROOT.lower():
+        return cwd
+
+    return HUB_ROOT
+
+
+def run_full_analysis(target_repo):
+    """Executes the complete diagnostic and AST intelligence suite."""
+    start_time = datetime.now()
+    mode = verify_all.detect_repo_mode(target_repo)
+
+    print(f"\n{BOLD}{CYAN}======================================================================{RESET}")
+    print(f"{BOLD}{CYAN}      ENTERPRISE QA - COMPREHENSIVE PROJECT ANALYSIS SUITE            {RESET}")
+    print(f"{BOLD}{CYAN}======================================================================{RESET}")
+    print(f"📁 Target Repository : {target_repo}")
+    print(f"🏷️  Operational Mode  : {mode}")
+    print(f"⏱️  Timestamp         : {start_time.strftime('%Y-%m-%d %H:%M:%S')}\n")
+
+    summary = {
+        "timestamp": start_time.isoformat(),
+        "target_repo": target_repo,
+        "mode": mode,
+        "env_status": "UNKNOWN",
+        "repo_map": {},
+        "infer_linter": {},
+        "data_flow": {},
+        "gates_status": "UNKNOWN"
+    }
+
+    # Step 1: Environment & Project Structure
+    print(f"{BOLD}[1/5] Checking Environment & Project Structure (check_env)...{RESET}")
+    env_runner = check_env.DiagnosticRunner(target_dir=target_repo)
+    env_code = env_runner.run_all()
+    summary["env_status"] = "READY" if env_code == 0 else "WARNINGS_OR_MISSING"
+
+    # Step 2: Page Classes & Method AST Mapping
+    print(f"\n{BOLD}[2/5] Mapping Page Classes & API Signatures (repo_map)...{RESET}")
+    try:
+        map_stats = repo_map.build_repo_map(target_repo=target_repo)
+        summary["repo_map"] = {
+            "classes_count": map_stats["classes_count"],
+            "methods_count": map_stats["methods_count"],
+            "source_lines": map_stats["source_lines"],
+            "output_file": map_stats["output_file"]
+        }
+        print(f"   -> Indexed {map_stats['classes_count']} Page Classes ({map_stats['methods_count']} API signatures).")
+        print(f"   -> Condensed context map: {map_stats['output_file']}")
+    except Exception as e:
+        print(f"   ⚠️ repo_map error: {e}")
+
+    # Step 3: Static Defect & Fake-Pass Sentinel
+    print(f"\n{BOLD}[3/5] Scanning Static Defects & Fake-Passes (infer_linter)...{RESET}")
+    scripts_dir = os.path.join(target_repo, "Scripts")
+    try:
+        linter_code = infer_linter.run_infer_linter(target_dir=scripts_dir)
+        summary["infer_linter"]["exit_code"] = linter_code
+    except Exception as e:
+        print(f"   ⚠️ infer_linter error: {e}")
+
+    # Step 4: Data Flow Lifecycle & Teardown Hygiene
+    print(f"\n{BOLD}[4/5] Auditing Synthetic Data Lifecycle & Teardown (trace_data_flow)...{RESET}")
+    try:
+        data_flow_code = trace_data_flow.run_data_flow_tracer(target_dir=scripts_dir, repo_root=target_repo)
+        summary["data_flow"]["exit_code"] = data_flow_code
+    except Exception as e:
+        print(f"   ⚠️ trace_data_flow error: {e}")
+
+    # Step 5: 7 Quality Gates DoD Verification
+    print(f"\n{BOLD}[5/5] Verifying 7 Quality Gates DoD (verify_all)...{RESET}")
+    gates_passed = True
+    gates = [
+        ("Gate 1: UTF-8 No BOM", verify_all.gate_1_bom_check),
+        ("Gate 2: Path Portability", verify_all.gate_2_path_portability),
+        ("Gate 3: Clean POM & Flat Architecture", verify_all.gate_3_clean_pom),
+        ("Gate 4: AI Documentation Linter", verify_all.gate_4_ai_docs_lint),
+        ("Gate 5: Temporary Files Blacklist", verify_all.gate_5_cleanup_blacklist),
+        ("Gate 6: Credential Security", verify_all.gate_6_credential_security),
+        ("Gate 7: Static Defect Sentinel", verify_all.gate_7_infer_linter),
+    ]
+    for name, gate_fn in gates:
+        if not gate_fn(target_repo, mode=mode):
+            gates_passed = False
+
+    summary["gates_status"] = "100%_PASS" if gates_passed else "FAILURES_DETECTED"
+
+    # Generate Markdown Executive Report
+    elapsed = (datetime.now() - start_time).total_seconds()
+    reports_dir = os.path.join(target_repo, "reports") if mode == "TARGET" else os.path.join(HUB_ROOT, "reports")
+    os.makedirs(reports_dir, exist_ok=True)
+    report_in_reports = os.path.join(reports_dir, "PROJECT_HEALTH_REPORT.md")
+    report_in_root = os.path.join(target_repo, "PROJECT_HEALTH_REPORT.md")
+
+    md_content = f"""# Project Health & AST Analysis Report
+
+- **Target Repository:** `{target_repo}`
+- **Operational Mode:** `{mode}`
+- **Execution Timestamp:** `{start_time.strftime('%Y-%m-%d %H:%M:%S')}` (Completed in `{elapsed:.2f}s`)
+
+---
+
+## 1. Executive Health Metrics
+
+| Metric / Standard | Result | Status |
+| :--- | :---: | :---: |
+| **Environment & Structure** | `{summary['env_status']}` | {'✅ PASS' if summary['env_status'] == 'READY' else '⚠️ WARN'} |
+| **Page Classes & Helpers** | `{summary['repo_map'].get('classes_count', 0)}` classes (`{summary['repo_map'].get('methods_count', 0)}` methods) | ✅ INDEXED |
+| **Static Defect Sentinel** | `infer_linter` exit `{summary['infer_linter'].get('exit_code', 0)}` | {'✅ CLEAN' if summary['infer_linter'].get('exit_code', 0) == 0 else '❌ CRITICAL'} |
+| **Lifecycle & Teardown** | `trace_data_flow` exit `{summary['data_flow'].get('exit_code', 0)}` | ✅ AUDITED |
+| **7 Quality Gates DoD** | `{summary['gates_status']}` | {'✅ 100% PASS' if gates_passed else '❌ BLOCKED'} |
+
+---
+
+## 2. In-Project Synchronized Artifacts
+
+1. **Executive Health Summary (This file):** `PROJECT_HEALTH_REPORT.md`
+2. **Condensed API Signatures Map (< 600 tokens):** `repo_map.txt`
+3. **AST Static Defect Log:** `reports/infer_linter_report.json`
+4. **Data Lifecycle Taint Audit:** `reports/data_flow_trace_report.json`
+
+---
+
+## 3. AI Context Anchoring & Post-Audit Protocol (0-Token Overhead)
+
+> 📌 **AI Agent Guidelines:**
+> - In subsequent sessions on this project, **DO NOT rescan** the entire codebase from scratch.
+> - Anchor context directly by reading only two local in-project artifacts:
+>   1. `PROJECT_HEALTH_REPORT.md` (immediate architecture status, warnings, and DoD readiness).
+>   2. `repo_map.txt` (instant lookup for Page Classes, methods, and parameters in < 600 tokens).
+> - **Post-Audit Git Push (Mandatory):** Once analysis completes, stage, commit, and push updated in-project artifacts to git (`git add PROJECT_HEALTH_REPORT.md repo_map.txt && git commit -m "docs(audit): update project health report and AST repo map" && git push origin <branch>`).
+> - Whenever the user requests **"analyze project"** or **"project audit"**, re-run `agent-qa analyze` to update this file in-place.
+"""
+    with open(report_in_reports, "w", encoding="utf-8") as f:
+        f.write(md_content)
+
+    # Save directly at the root of target_repo as well so it's instantly discoverable
+    if os.path.abspath(target_repo).lower() != os.path.abspath(HUB_ROOT).lower():
+        try:
+            with open(report_in_root, "w", encoding="utf-8") as f:
+                f.write(md_content)
+        except Exception:
+            pass
+
+    print(f"\n{BOLD}{CYAN}======================================================================{RESET}")
+    print(f"{BOLD}{CYAN}                     EXECUTIVE ANALYSIS COMPLETE                      {RESET}")
+    print(f"{BOLD}{CYAN}======================================================================{RESET}")
+    print(f"  Elapsed Time            : {elapsed:.2f}s")
+    print(f"  Page Classes Indexed    : {summary['repo_map'].get('classes_count', 0)} classes")
+    print(f"  7 Quality Gates DoD     : {GREEN + '100% PASS' if gates_passed else RED + 'FAILED'}{RESET}")
+    print(f"  In-Project Report Path  : {report_in_root if os.path.abspath(target_repo).lower() != os.path.abspath(HUB_ROOT).lower() else report_in_reports}")
+    if os.path.abspath(target_repo).lower() != os.path.abspath(HUB_ROOT).lower():
+        print(f"  {YELLOW}💡 Post-Analysis Action: Push updated files to Git:{RESET}")
+        print(f"     git add PROJECT_HEALTH_REPORT.md repo_map.txt")
+        print(f"     git commit -m \"docs(audit): update project health report and AST repo map\"")
+        print(f"     git push origin <branch>")
+    print(f"{BOLD}{CYAN}======================================================================{RESET}\n")
+
+    return 0 if gates_passed else 1
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Comprehensive Enterprise QA Project Analyzer")
+    parser.add_argument("target", nargs="?", default=None, help="Target repository path to analyze")
+    parser.add_argument("--repo", "--path", dest="repo_path", default=None, help="Target repository path")
+    args = parser.parse_args()
+
+    try:
+        target_repo = resolve_target_repo(cli_target=args.target, cli_repo=args.repo_path)
+    except FileNotFoundError as e:
+        print(f"❌ Error: {e}")
+        return 1
+
+    return run_full_analysis(target_repo)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/tools/api_drift_sentinel.py

@@ -0,0 +1,208 @@
+#!/usr/bin/env python3
+"""
+Enterprise API Contract Drift & Breaking Change Sentinel
+---------------------------------------------------------
+Compares OpenAPI / Swagger specifications (v2 / v3) across versions to detect
+breaking changes (deleted endpoints, removed fields, newly required parameters, type shifts)
+before UI test suites run and fail due to backend contract drift.
+"""
+
+import os
+import sys
+import json
+import argparse
+from typing import Dict, List, Any, Tuple
+
+# Enforce UTF-8 stdout encoding for Windows console compatibility
+if hasattr(sys.stdout, 'reconfigure'):
+    try:
+        sys.stdout.reconfigure(encoding='utf-8')
+        sys.stderr.reconfigure(encoding='utf-8')
+    except Exception:
+        pass
+
+
+def load_spec(file_path: str) -> Dict[str, Any]:
+    """Loads an OpenAPI/Swagger spec from a JSON file."""
+    if not os.path.exists(file_path):
+        raise FileNotFoundError(f"Spec file not found: {file_path}")
+    with open(file_path, "r", encoding="utf-8") as f:
+        return json.load(f)
+
+
+def compare_specs(old_spec: Dict[str, Any], new_spec: Dict[str, Any]) -> Dict[str, Any]:
+    """
+    Computes breaking changes and non-breaking contract modifications between two specs.
+    """
+    breaking: List[Dict[str, str]] = []
+    warnings: List[Dict[str, str]] = []
+    info: List[Dict[str, str]] = []
+
+    old_paths = old_spec.get("paths", {})
+    new_paths = new_spec.get("paths", {})
+
+    # 1. Check for removed endpoints (Paths)
+    for path, old_methods in old_paths.items():
+        if path not in new_paths:
+            breaking.append({
+                "type": "REMOVED_ENDPOINT",
+                "path": path,
+                "detail": f"Entire endpoint path was deleted: '{path}'"
+            })
+            continue
+
+        new_methods = new_paths[path]
+
+        # 2. Check for removed HTTP methods on existing path
+        for method, old_op in old_methods.items():
+            if method.lower() in ("parameters", "$ref", "summary", "description"):
+                continue
+
+            if method not in new_methods:
+                breaking.append({
+                    "type": "REMOVED_HTTP_METHOD",
+                    "path": f"{method.upper()} {path}",
+                    "detail": f"HTTP method '{method.upper()}' was deleted from path '{path}'"
+                })
+                continue
+
+            new_op = new_methods[method]
+
+            # 3. Check Parameters
+            old_params = {p.get("name"): p for p in old_op.get("parameters", []) if isinstance(p, dict)}
+            new_params = {p.get("name"): p for p in new_op.get("parameters", []) if isinstance(p, dict)}
+
+            # Check for newly added REQUIRED parameters (Breaks existing clients)
+            for p_name, p_info in new_params.items():
+                if p_name not in old_params and p_info.get("required") is True:
+                    breaking.append({
+                        "type": "NEW_REQUIRED_PARAM",
+                        "path": f"{method.upper()} {path}",
+                        "detail": f"Added newly required parameter '{p_name}' in '{p_info.get('in', 'query')}'"
+                    })
+
+            # Check for changed parameter types or newly required existing parameters
+            for p_name, old_p in old_params.items():
+                if p_name in new_params:
+                    new_p = new_params[p_name]
+                    if not old_p.get("required") and new_p.get("required") is True:
+                        breaking.append({
+                            "type": "PARAM_NOW_REQUIRED",
+                            "path": f"{method.upper()} {path}",
+                            "detail": f"Parameter '{p_name}' was changed from optional to required"
+                        })
+                    
+                    old_type = old_p.get("type") or old_p.get("schema", {}).get("type")
+                    new_type = new_p.get("type") or new_p.get("schema", {}).get("type")
+                    if old_type and new_type and old_type != new_type:
+                        breaking.append({
+                            "type": "PARAM_TYPE_CHANGED",
+                            "path": f"{method.upper()} {path}",
+                            "detail": f"Parameter '{p_name}' type shifted from '{old_type}' to '{new_type}'"
+                        })
+
+            # 4. Check Responses (Removed expected status codes)
+            old_resps = old_op.get("responses", {})
+            new_resps = new_op.get("responses", {})
+            for status_code, old_resp in old_resps.items():
+                if status_code in ("200", "201", "204") and status_code not in new_resps:
+                    warnings.append({
+                        "type": "REMOVED_SUCCESS_RESPONSE",
+                        "path": f"{method.upper()} {path}",
+                        "detail": f"Success response code '{status_code}' was removed or modified"
+                    })
+
+    # Non-breaking additions
+    for path, new_methods in new_paths.items():
+        if path not in old_paths:
+            info.append({
+                "type": "NEW_ENDPOINT_ADDED",
+                "path": path,
+                "detail": f"New endpoint added: '{path}' (Backward compatible)"
+            })
+
+    health_score = 100.0 if not breaking else max(0.0, 100.0 - (len(breaking) * 20.0))
+    is_compatible = len(breaking) == 0
+
+    return {
+        "is_backward_compatible": is_compatible,
+        "contract_health_score": health_score,
+        "breaking_changes_count": len(breaking),
+        "warnings_count": len(warnings),
+        "additions_count": len(info),
+        "breaking_changes": breaking,
+        "warnings": warnings,
+        "additions": info
+    }
+
+
+def generate_markdown_report(analysis: Dict[str, Any], old_path: str, new_path: str) -> str:
+    status_icon = "✅ COMPATIBLE" if analysis["is_backward_compatible"] else "❌ BREAKING DRIFT DETECTED"
+    lines = [
+        "# API Contract Drift & Breaking Change Report",
+        f"- **Baseline Spec:** `{old_path}`",
+        f"- **Current Spec:** `{new_path}`",
+        f"- **Verdict:** {status_icon} (Health Score: `{analysis['contract_health_score']:.1f}%`)",
+        "",
+        "## Summary Metrics",
+        f"| Breaking Changes | Warnings | Compatible Additions |",
+        f"| :---: | :---: | :---: |",
+        f"| **{analysis['breaking_changes_count']}** | **{analysis['warnings_count']}** | **{analysis['additions_count']}** |",
+        ""
+    ]
+
+    if analysis["breaking_changes"]:
+        lines.append("## ❌ Breaking Changes (Action Required)")
+        lines.append("| Type | Endpoint / Method | Root Cause Detail |")
+        lines.append("| :--- | :--- | :--- |")
+        for b in analysis["breaking_changes"]:
+            lines.append(f"| `{b['type']}` | `{b['path']}` | {b['detail']} |")
+        lines.append("")
+
+    if analysis["warnings"]:
+        lines.append("## ⚠️ Warnings & Potential Regressions")
+        for w in analysis["warnings"]:
+            lines.append(f"- **{w['path']}**: {w['detail']}")
+        lines.append("")
+
+    if analysis["additions"]:
+        lines.append("## ℹ️ Compatible New Additions")
+        for a in analysis["additions"]:
+            lines.append(f"- **{a['path']}**: {a['detail']}")
+
+    return "\n".join(lines)
+
+
+def main():
+    parser = argparse.ArgumentParser(description="API Contract Drift & Schema Diff Sentinel")
+    parser.add_argument("--old", "--baseline", dest="old_spec", required=True, help="Path to baseline OpenAPI/Swagger JSON")
+    parser.add_argument("--new", "--current", dest="new_spec", required=True, help="Path to current OpenAPI/Swagger JSON")
+    parser.add_argument("--json", action="store_true", help="Output raw JSON results")
+    parser.add_argument("-o", "--output", dest="output_file", default=None, help="Save report to file")
+    args = parser.parse_args()
+
+    try:
+        old_data = load_spec(args.old_spec)
+        new_data = load_spec(args.new_spec)
+    except Exception as e:
+        print(f"❌ Error loading specs: {e}")
+        return 1
+
+    analysis = compare_specs(old_data, new_data)
+    md_report = generate_markdown_report(analysis, args.old_spec, args.new_spec)
+
+    if args.output_file:
+        with open(args.output_file, "w", encoding="utf-8") as f:
+            f.write(md_report)
+        print(f"✅ Drift report saved to: {args.output_file}")
+
+    if args.json:
+        print(json.dumps(analysis, indent=2))
+    else:
+        print(md_report)
+
+    return 0 if analysis["is_backward_compatible"] else 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/tools/auto_heal.py

@@ -0,0 +1,189 @@
+#!/usr/bin/env python3
+"""
+Enterprise Closed-Loop Autonomous Test Healer Engine
+-----------------------------------------------------
+Diagnoses test failures in 0.1s from JUnit XML and terminal logs, queries the 
+semantic memory cache for proven patches, and orchestrates targeted re-tests.
+Dispatched automatically by AI Agents when test runs encounter failures.
+"""
+
+import os
+import sys
+import re
+import json
+import argparse
+from pathlib import Path
+
+# Enforce UTF-8 stdout encoding for Windows console compatibility
+if hasattr(sys.stdout, 'reconfigure'):
+    try:
+        sys.stdout.reconfigure(encoding='utf-8')
+        sys.stderr.reconfigure(encoding='utf-8')
+    except Exception:
+        pass
+
+SCRIPT_DIR = os.path.dirname(os.path.abspath(__file__))
+HUB_ROOT = os.path.abspath(os.path.join(SCRIPT_DIR, ".."))
+sys.path.insert(0, SCRIPT_DIR)
+
+import pinpoint_failure
+import cache_resolver
+import project_state
+import heuristic_locator_matcher
+
+GREEN = "\033[92m"
+RED = "\033[91m"
+YELLOW = "\033[93m"
+CYAN = "\033[96m"
+BOLD = "\033[1m"
+RESET = "\033[0m"
+
+
+def diagnose_and_plan_heal(target_dir, junit_xml_path=None):
+    """
+    Parses test failure, checks memory cache, updates project state watchpoints,
+    and returns a structured healing plan.
+    """
+    print(f"\n{BOLD}{CYAN}======================================================================{RESET}")
+    print(f"{BOLD}{CYAN}           AUTONOMOUS CLOSED-LOOP TEST HEALING SENTINEL               {RESET}")
+    print(f"{BOLD}{CYAN}======================================================================{RESET}")
+    print(f"📁 Target Project  : {target_dir}")
+
+    # 1. Pinpoint failure from JUnit XML or logs
+    failure_info = None
+    if junit_xml_path and os.path.exists(junit_xml_path):
+        failures = pinpoint_failure.parse_junit_xml(junit_xml_path)
+        if failures:
+            failure_info = failures[0]
+
+    if not failure_info:
+        # Search for any recent report in Reports/
+        reports_dir = os.path.join(target_dir, "Reports")
+        if os.path.exists(reports_dir):
+            for root, _, files in os.walk(reports_dir):
+                for f in files:
+                    if f.endswith(".xml"):
+                        parsed = pinpoint_failure.parse_junit_xml(os.path.join(root, f))
+                        if parsed:
+                            failure_info = parsed[0]
+                            break
+                if failure_info:
+                    break
+
+    if not failure_info:
+        print("  [INFO] Zero active JUnit XML failures detected on disk.")
+        return {"status": "NO_FAILURE_DETECTED"}
+
+    err_sig = failure_info.get("message", failure_info.get("type", "UnknownError"))
+    test_name = failure_info.get("name", "UnknownTest")
+    failing_file = failure_info.get("file", "UnknownFile")
+    line_num = failure_info.get("line", "?")
+
+    print(f"  ❌ Failing Test   : {test_name}")
+    print(f"  📍 Source Location: {failing_file}:{line_num}")
+    print(f"  ⚠️ Error Signature: {err_sig[:120]}...\n")
+
+    # 2. Query 0-token memory cache & 3-layer heuristic matcher
+    print(f"{BOLD}[1/2] Checking 3-Layer Heuristic Matcher & Memory Cache...{RESET}")
+    cache_solution = cache_resolver.query_cache(err_sig, threshold=0.35)
+
+    # 2b. Query Episodic Reflexion Memory (Top 2 historical lessons)
+    lessons = cache_resolver.query_lessons(f"{test_name} {err_sig}", limit=2)
+
+    plan = {
+        "status": "HEALING_PLAN_READY",
+        "test_name": test_name,
+        "failing_file": failing_file,
+        "line": line_num,
+        "error_signature": err_sig,
+        "cache_match": bool(cache_solution),
+        "heuristic_match": None,
+        "recommended_patch": None,
+        "episodic_lessons": [l["lesson_summary"] for l in lessons]
+    }
+
+    if lessons:
+        print(f"  {CYAN}🧠 [EPISODIC REFLEXION] Top Historical Lessons for Context:{RESET}")
+        for idx, l in enumerate(lessons, 1):
+            print(f"     {idx}. [{l['page_context']}]: {l['lesson_summary']}")
+
+    if cache_solution:
+        print(f"  {GREEN}[MATCH] Found cached resolution (Score: {cache_solution['score']:.2f}):{RESET}")
+        print(f"  💡 Prescribed Fix : {cache_solution['solution']}")
+        plan["recommended_patch"] = cache_solution["solution"]
+    else:
+        # Check if error message contains broken locator pattern
+        loc_candidate_m = re.search(r"locator\(['\"]([^'\"]+)['\"]\)|By\.[a-zA-Z]+\(['\"]([^'\"]+)['\"]\)", err_sig)
+        if loc_candidate_m:
+            broken_loc = loc_candidate_m.group(1) or loc_candidate_m.group(2)
+            heuristic_res = heuristic_locator_matcher.HeuristicLocatorMatcher.match(broken_loc, dom_snapshot=[])
+            plan["heuristic_match"] = heuristic_res
+            if heuristic_res.get("matched"):
+                print(f"  {GREEN}[HEURISTIC L{heuristic_res['layer']}] 0-Token match ({heuristic_res['confidence']*100:.1f}%): {heuristic_res['healed_locator']}{RESET}")
+                plan["recommended_patch"] = f"Update locator to: {heuristic_res['healed_locator']}"
+            else:
+                print("  [MISS] Heuristic confidence < 85%. Fallback to Live DOM exploration.")
+                plan["recommended_patch"] = "Inspect element using Playwright Live Explorer and apply resilient locator / smart wait."
+        else:
+            print("  [MISS] No direct cache match. AI Agent will inspect live DOM/AOM via Playwright.")
+            plan["recommended_patch"] = "Inspect element using Playwright Live Explorer and apply resilient locator / smart wait."
+
+    # 3. Anchor watchpoint in PROJECT_STATE.md
+    print(f"\n{BOLD}[2/2] Anchoring Watchpoint in PROJECT_STATE.md...{RESET}")
+    try:
+        project_state.update_state(
+            target_dir=target_dir,
+            watchpoint=f"{test_name} -> {failing_file}:{line_num}",
+            gate_status="HEALING_IN_PROGRESS"
+        )
+        print("  [OK] Project state watchpoint updated.")
+    except Exception as e:
+        print(f"  ⚠️ Could not update PROJECT_STATE.md: {e}")
+
+    print(f"{BOLD}{CYAN}======================================================================{RESET}\n")
+    return plan
+
+
+def record_heal_lesson(page_context, error_signature, root_cause, failed_attempt, successful_fix, lesson_summary):
+    """Saves a 2-line practical lesson learned into SQLite after successful healing."""
+    return cache_resolver.record_lesson(
+        page_context=page_context,
+        error_signature=error_signature,
+        root_cause=root_cause,
+        failed_attempt=failed_attempt,
+        successful_fix=successful_fix,
+        lesson_summary=lesson_summary
+    )
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Autonomous Closed-Loop Test Healer")
+    parser.add_argument("target", nargs="?", default=os.getcwd(), help="Target project root directory")
+    parser.add_argument("--xml", default=None, help="Path to JUnit XML test report")
+    parser.add_argument("--record-lesson", default=None, help="Record a 2-line lesson learned after healing")
+    parser.add_argument("--context", default="GLOBAL", help="Page context for the recorded lesson")
+    parser.add_argument("--error", default="UnknownError", help="Error signature for the recorded lesson")
+    parser.add_argument("--fix", default="", help="Successful fix for the recorded lesson")
+    args = parser.parse_args()
+
+    if args.record_lesson:
+        ok = record_heal_lesson(
+            page_context=args.context,
+            error_signature=args.error,
+            root_cause="Autonomous Healer Diagnosis",
+            failed_attempt="",
+            successful_fix=args.fix,
+            lesson_summary=args.record_lesson
+        )
+        if ok:
+            print(f"✅ [EPISODIC REFLEXION] Lesson recorded for '{args.context}': {args.record_lesson}")
+        return 0
+
+    target_dir = os.path.abspath(args.target)
+    plan = diagnose_and_plan_heal(target_dir, junit_xml_path=args.xml)
+    print(json.dumps(plan, indent=2))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())