feat(reporting): add root cause analysis engine with failure pattern matching

Add declarative FailurePattern library (8 built-in patterns derived from
ErrorCategory) and RootCauseAnalyzer that reads structured.jsonl via
LogQueryEngine to produce ranked root-cause findings with log excerpts
and actionable suggestions.

Extend ExperimentReporter with optional RCA and artifact inventory
sections in both JSON and Markdown reports (gracefully skipped when
structured.jsonl is absent).

Add `panther report diagnose` CLI subcommand with --json/--human output.

Author: ElNiak

panther/core/reporting/experiment_reporter.py

@@ -44,7 +44,7 @@
 import logging
 from datetime import datetime
 from pathlib import Path
-from typing import Any, Dict, Optional
+from typing import Any, Dict, List, Optional
 
 try:
     from jinja2 import Environment, FileSystemLoader, Template
@@ -144,7 +144,7 @@ def __init__(self, experiment_dir: Path, experiment_name: Optional[str] = None):
                 loader=FileSystemLoader(templates_dir),
                 trim_blocks=True,
                 lstrip_blocks=True,
-                autoescape=False,
+                autoescape=True,
             )
         else:
             self.jinja_env = None
@@ -194,6 +194,16 @@ def _generate_json_report(self, summary: ExperimentSummary) -> bool:
                 "report_format_version": "1.0",
             }
 
+            # Add optional diagnosis section
+            diagnosis = self._get_diagnosis()
+            if diagnosis:
+                report_data["diagnosis"] = diagnosis
+
+            # Add optional artifacts section
+            artifacts = self._get_artifact_summary()
+            if artifacts:
+                report_data["artifacts"] = artifacts
+
             json_path = self.experiment_dir / "experiment_summary.json"
             with open(json_path, "w", encoding="utf-8") as f:
                 json.dump(report_data, f, indent=2, ensure_ascii=False)
@@ -304,52 +314,38 @@ def _generate_basic_markdown_report(self, summary: ExperimentSummary) -> bool:
                             lines.append("  - ⚡ Fast-fail triggered")
                     lines.append("")
 
-            # Service health summary (if available), grouped by test
+            # Service health summary (if available)
             if summary.services:
                 lines.extend(["## Service Health Summary", ""])
+                iut_svcs = [s for s in summary.services if s.service_type == "iut"]
+                tester_svcs = [
+                    s for s in summary.services if s.service_type == "tester"
+                ]
 
-                # Group services by test_name
-                from itertools import groupby as _groupby
-
-                sorted_services = sorted(
-                    summary.services, key=lambda s: s.test_name or ""
-                )
-                for test_name, test_services_iter in _groupby(
-                    sorted_services, key=lambda s: s.test_name or "Unknown"
-                ):
-                    test_services = list(test_services_iter)
-                    lines.append(f"### Test: {test_name}")
-                    lines.append("")
-
-                    iut_svcs = [s for s in test_services if s.service_type == "iut"]
-                    tester_svcs = [
-                        s for s in test_services if s.service_type == "tester"
-                    ]
-
-                    for label, svcs in [
-                        ("IUT Services", iut_svcs),
-                        ("Tester Services", tester_svcs),
-                    ]:
-                        if svcs:
-                            lines.append(f"#### {label} ({len(svcs)})")
-                            lines.append(
-                                "| Service | Status | Compilation | Exit Code | Errors |"
+                for label, svcs in [
+                    ("IUT Services", iut_svcs),
+                    ("Tester Services", tester_svcs),
+                ]:
+                    if svcs:
+                        lines.append(f"### {label} ({len(svcs)})")
+                        lines.append(
+                            "| Service | Status | Compilation | Exit Code | Errors |"
+                        )
+                        lines.append(
+                            "|---------|--------|-------------|-----------|--------|"
+                        )
+                        for svc in svcs:
+                            comp = "OK" if svc.compilation_succeeded else "FAIL"
+                            ec = (
+                                str(svc.exit_code)
+                                if svc.exit_code is not None
+                                else "N/A"
                             )
+                            err = svc.error_summary or "None"
                             lines.append(
-                                "|---------|--------|-------------|-----------|--------|"
+                                f"| {svc.service_name} | {svc.status} | {comp} | {ec} | {err} |"
                             )
-                            for svc in svcs:
-                                comp = "OK" if svc.compilation_succeeded else "FAIL"
-                                ec = (
-                                    str(svc.exit_code)
-                                    if svc.exit_code is not None
-                                    else "N/A"
-                                )
-                                err = svc.error_summary or "None"
-                                lines.append(
-                                    f"| {svc.service_name} | {svc.status} | {comp} | {ec} | {err} |"
-                                )
-                            lines.append("")
+                        lines.append("")
 
             # Fast-fail analysis
             lines.extend(
@@ -403,6 +399,18 @@ def _generate_basic_markdown_report(self, summary: ExperimentSummary) -> bool:
             else:
                 lines.append("- No resource usage data available")
 
+            # Root Cause Analysis section (optional)
+            rca_lines = self._format_rca_markdown()
+            if rca_lines:
+                lines.extend(["", ""])
+                lines.extend(rca_lines)
+
+            # Artifact Inventory section (optional)
+            artifact_lines = self._format_artifact_markdown()
+            if artifact_lines:
+                lines.extend(["", ""])
+                lines.extend(artifact_lines)
+
             lines.extend(
                 [
                     "",
@@ -529,6 +537,118 @@ def _get_panther_version(self) -> str:
 
         return "Development"
 
+    # -- RCA and artifact integration helpers ---------------------------------
+
+    def _has_structured_log(self) -> bool:
+        """Check whether a structured.jsonl file exists in the output dir."""
+        return (self.experiment_dir / "structured.jsonl").is_file() or any(
+            self.experiment_dir.rglob("structured.jsonl")
+        )
+
+    def _get_diagnosis(self) -> Optional[List[Dict[str, Any]]]:
+        """Run root-cause analysis if structured logs exist.
+
+        Returns:
+            List of serialized ``RootCause`` dicts, or None when
+            structured logs are unavailable.
+        """
+        if not self._has_structured_log():
+            return None
+        try:
+            from .root_cause_analyzer import RootCauseAnalyzer
+
+            analyzer = RootCauseAnalyzer(self.experiment_dir)
+            causes = analyzer.analyze_as_dicts()
+            return causes if causes else None
+        except Exception as exc:
+            self.logger.debug("RCA skipped: %s", exc)
+            return None
+
+    def _get_artifact_summary(self) -> Optional[List[Dict[str, Any]]]:
+        """Collect artifact inventory via ArtifactBrowser.
+
+        Returns:
+            List of artifact metadata dicts, or None on failure.
+        """
+        try:
+            from .artifact_browser import ArtifactBrowser
+
+            browser = ArtifactBrowser(self.experiment_dir)
+            artifacts = browser.list_artifacts()
+            return artifacts if artifacts else None
+        except Exception as exc:
+            self.logger.debug("Artifact browsing skipped: %s", exc)
+            return None
+
+    def _format_rca_markdown(self) -> List[str]:
+        """Format root-cause analysis as Markdown lines.
+
+        Returns:
+            List of Markdown-formatted strings.  Empty when RCA is
+            unavailable or found no issues.
+        """
+        diagnosis = self._get_diagnosis()
+        if not diagnosis:
+            return []
+
+        lines = ["## Root Cause Analysis", ""]
+        for cause in diagnosis:
+            rank = cause.get("rank", "?")
+            pattern = cause.get("pattern_name", "unknown")
+            category = cause.get("category", "unknown")
+            confidence = cause.get("confidence", 0.0)
+            suggestion = cause.get("suggestion", "")
+            event = cause.get("event", {})
+            excerpt = cause.get("log_excerpt", [])
+
+            lines.append(f"### #{rank}: {pattern} (confidence: {confidence:.0%})")
+            lines.append(f"- **Category**: {category}")
+            if event.get("message"):
+                lines.append(f"- **Trigger**: {event['message']}")
+            if event.get("service_id"):
+                lines.append(f"- **Service**: {event['service_id']}")
+            if suggestion:
+                lines.append(f"- **Suggestion**: {suggestion}")
+            if excerpt:
+                lines.append("- **Log excerpt**:")
+                for line in excerpt[:5]:
+                    lines.append(f"  - `{line}`")
+            lines.append("")
+
+        return lines
+
+    def _format_artifact_markdown(self) -> List[str]:
+        """Format artifact inventory as Markdown lines.
+
+        Returns:
+            List of Markdown-formatted strings.  Empty when artifact
+            browsing is unavailable.
+        """
+        artifacts = self._get_artifact_summary()
+        if not artifacts:
+            return []
+
+        lines = ["## Artifact Inventory", ""]
+
+        # Group by type
+        by_type: Dict[str, list] = {}
+        for art in artifacts:
+            t = art.get("type", "other")
+            by_type.setdefault(t, []).append(art)
+
+        for art_type, items in sorted(by_type.items()):
+            lines.append(f"### {art_type.title()} ({len(items)})")
+            for item in items[:20]:  # cap display
+                path = item.get("path", "?")
+                size = item.get("size_bytes", 0)
+                size_str = f"{size / 1024:.1f} KB" if size else "0 KB"
+                lines.append(f"- `{path}` ({size_str})")
+            if len(items) > 20:
+                lines.append(f"- ... and {len(items) - 20} more")
+            lines.append("")
+
+        return lines
+
     def generate_quick_summary(self) -> Optional[str]:
         """Generate a quick one-line summary for logging.