[NOTICKET] feat(correlation): pairwise n, p-value and a quality block (P0-8)

- Each pair now carries n (rows complete for both columns), p_value (scipy
pearsonr / spearmanr / kendalltau) and weak (n < 10 or p >= 0.05)
- Reserved `quality` block for the strongest pair, so CK7 surfaces a weak correlation;
a caveat says one point can drive r on few rows, or that a large-n r is not significant
- With no column_ids, `n_*` row-count columns (the repair's n_periods) are skipped
- ADT OB HAULER monthly means: PA-MTTR r=-0.42 now reads n=9, p=0.26, weak; unit-month
rows (n=2,379) stay strong; a ranking table no longer correlates n_periods
- Reported by Rifqi (audit P0-8, decision D4)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

src/tools/analytics/relationship.py

@@ -15,6 +15,7 @@ this function easy to unit-test in isolation and stable when wrapped.
 from __future__ import annotations
 
 import math
+from typing import Any
 
 import pandas as pd
 from pydantic import BaseModel, Field
@@ -24,6 +25,11 @@ from src.tools.analytics.descriptive import ColumnNotFoundError
 # Correlation methods supported by pandas .corr().
 SUPPORTED_METHODS = ("pearson", "spearman", "kendall")
 
+# A pair is weak evidence below this many complete rows or at/above this p-value.
+# Audit P0-8: an r of 0.953 came from only 8 monthly totals and read as strong.
+_WEAK_MIN_N = 10
+_ALPHA = 0.05
+
 
 class InvalidMethodError(ValueError):
     """The requested method is not supported (maps to error_code INVALID_METHOD)."""
@@ -41,10 +47,48 @@ def _clean(value: object) -> float | None:
     """Cast to plain float; NaN (e.g. a zero-variance column) -> None."""
     if value is None:
         return None
-    f = float(value)  # type: ignore[arg-type]
+    f = float(value)
     return None if math.isnan(f) else f
 
 
+def _p_value(a: pd.Series, b: pd.Series, method: str) -> float | None:
+    """Two-sided p-value of the pair's correlation on its complete rows; None if < 3."""
+    from scipy import stats  # lazy — keep module import light
+
+    if a.shape[0] < 3:
+        return None
+    test = {"pearson": stats.pearsonr, "spearman": stats.spearmanr,
+            "kendall": stats.kendalltau}[method]
+    return _clean(test(a, b).pvalue)
+
+
+def _is_weak(n: int, p_value: float | None) -> bool:
+    return n < _WEAK_MIN_N or p_value is None or p_value >= _ALPHA
+
+
+def _quality(top: dict[str, Any] | None) -> dict[str, object]:
+    """Reserved `quality` block (conventions §3) for the strongest pair; CK7 surfaces it."""
+    if top is None:
+        return {"metric": "p_value", "value": None, "floor": _ALPHA, "weak": True,
+                "note": "no pair had a defined correlation"}
+    n, p = top["n"], top["p_value"]
+    reasons = []
+    if n < _WEAK_MIN_N:
+        reasons.append(f"only {n} rows")
+    if p is None or p >= _ALPHA:
+        reasons.append("not significant at alpha=0.05")
+    return {
+        "metric": "p_value",
+        "value": None if p is None else round(p, 4),
+        "floor": _ALPHA,
+        "weak": top["weak"],
+        "note": (
+            f"strongest pair {top['a']}–{top['b']} (r={top['corr']:.3f}, n={n}): "
+            + ("; ".join(reasons) if reasons else f"significant at alpha={_ALPHA}")
+        ),
+    }
+
+
 # Prompt-style description read by the Planner to decide WHEN to pick this tool.
 # Final destination is ToolSpec.description once the wrapper layer is built.
 
@@ -94,7 +138,7 @@ def analyze_correlation(
         df: already-materialized data (in the real system the wrapper fetches
             this from a source_id).
         column_ids: numeric columns to correlate. If None, every numeric
-            column in df is used.
+            column in df is used except `n_*` row-count columns.
         method: "pearson" (linear), "spearman" (rank), or "kendall".
 
     Returns:
@@ -102,7 +146,11 @@ def analyze_correlation(
             method   — echo of the chosen method
             columns  — the numeric columns actually correlated
             matrix   — { col: { col: corr|None } } full square matrix
-            pairs    — [{"a", "b", "corr"}] unique pairs, strongest |corr| first
+            pairs    — [{"a", "b", "corr", "n", "p_value", "weak"}] unique pairs,
+                       strongest |corr| first; n = rows complete for both columns,
+                       weak = n < 10 or p >= 0.05
+            quality  — reserved block for the strongest pair (CK7 surfaces `weak`)
+            caveats  — a note when the strongest pair is weak evidence
 
     Raises:
         InvalidMethodError: if method is unknown.
@@ -116,7 +164,12 @@ def analyze_correlation(
         )
 
     if column_ids is None:
-        cols = [c for c in df.columns if pd.api.types.is_numeric_dtype(df[c])]
+        # `n_*` columns are row counts the IR repair adds to rankings (n_periods), not
+        # measures — correlating against them is noise.
+        cols = [
+            c for c in df.columns
+            if pd.api.types.is_numeric_dtype(df[c]) and not str(c).startswith("n_")
+        ]
     else:
         missing = [c for c in column_ids if c not in df.columns]
         if missing:
@@ -136,12 +189,38 @@ def analyze_correlation(
     corr = df[cols].corr(method=method)
     matrix = {a: {b: _clean(corr.loc[a, b]) for b in cols} for a in cols}
 
-    pairs = []
+    pairs: list[dict[str, Any]] = []
     for i in range(len(cols)):
         for j in range(i + 1, len(cols)):
             val = _clean(corr.iloc[i, j])
             if val is not None:
-                pairs.append({"a": cols[i], "b": cols[j], "corr": val})
+                both = df[[cols[i], cols[j]]].dropna()
+                n = int(both.shape[0])
+                p = _p_value(both.iloc[:, 0], both.iloc[:, 1], method)
+                pairs.append({"a": cols[i], "b": cols[j], "corr": val, "n": n,
+                              "p_value": p, "weak": _is_weak(n, p)})
     pairs.sort(key=lambda p: abs(p["corr"]), reverse=True)
 
-    return {"method": method, "columns": cols, "matrix": matrix, "pairs": pairs}
+    top = pairs[0] if pairs else None
+    caveats: list[str] = []
+    if top is not None and top["weak"]:
+        if top["n"] < _WEAK_MIN_N:
+            caveats.append(
+                f"The strongest correlation ({top['a']}–{top['b']}, r={top['corr']:.3f}) "
+                f"rests on {top['n']} rows — on so few points a single value can drive r, "
+                "so treat it as a lead to check, not an established relationship."
+            )
+        else:
+            caveats.append(
+                f"The strongest correlation ({top['a']}–{top['b']}, r={top['corr']:.3f}) "
+                f"is not significant (p >= {_ALPHA}) on {top['n']} rows — it may be noise."
+            )
+
+    return {
+        "method": method,
+        "columns": cols,
+        "matrix": matrix,
+        "pairs": pairs,
+        "quality": _quality(top),
+        "caveats": caveats,
+    }