feat(stats): correlation_matrix 按方案 A 拆成三个函数，收口返回契约（L0 9/12）

用户 2026-10-03 拍板方案 A（见决策 41），由 Codex 落地。

拆成三个函数:
- correlation_matrix  -> 数值系数矩阵（对角线 1.0）
- correlation_pvalues -> 数值 p 值矩阵（对角线 NaN）
- correlation_table   -> 星标字符串表（对角线 1.000 不带星）
三者共用 _check_corr_args 守卫与成对删缺失口径；correlation_table 在最外层调另外两个。
理由: 字符串表做不了后续计算（挑高相关对、喂聚类/PCA、画热力图），反过来随时能格式化；
      一旦返回字符串，数值信息不可逆地丢失。

顺带修掉两处:
- 对角线 p 值由 0.0 改成 NaN —— 写 0 会被下游读成"极显著"，而"自己和自己"没有 p 值
- p 值与 r 现在用同一批观测: 先成对 dropna() 再算，并同样尊重 min_periods。
  此前 corr 是成对删缺失、pearsonr 不删，两者样本量不同，r 与 p 对不上
- p 值只算上三角再镜像（成对变量的 p 天然对称），省一半重复计算

tests: test_correlation_matrix_diagonal_is_one 摘掉 xfail 转正；新增 8 条
  （数值性+对称性、非数值列跳过、p 值对照解析式 t = r*sqrt((n-2)/(1-r^2))、
   对角线 NaN、成对删缺失口径、min_periods、对角线无星标、表格与数值输出一致）。
  测试 105 passed / 38 skipped / 1 xfail -> 114 passed / 38 skipped / 0 xfail。

验证: pytest 114 passed / 38 skipped；ruff All checks passed；pyright 0 errors。

docs: STATUS.md（L0 9/12 + 决策 41 + 下一步）；CHANGELOG；
      personal-pitfalls 追加第 14 条（把"能看的表"和"能算的表"塞进同一个返回值）；
      roadmap 记录 correlation_matrix 的两个伴随函数

CHANGELOG.md

@@ -46,6 +46,13 @@
   单列 DataFrame、均值为 0 抛 `ValueError`、空数组与二维输入。
 - `examples/01_clean_and_describe.py`：填掉末尾的 `TODO(L0)`，加一段 `describe` 输出（实测 exit 0）。
 
+### Added
+- `stats.correlation_pvalues` / `stats.correlation_table`：`correlation_matrix` 的伴随函数
+  （**方案 A**，用户 2026-10-03 拍板，见决策 41）——
+  `correlation_matrix` 只返回**数值**矩阵；`correlation_pvalues` 给数值 p 值矩阵、
+  `correlation_table` 给"系数 + 显著性星标"的论文表格。
+  三者共用 `_check_corr_args` 入参守卫与**成对删缺失**口径，`correlation_table` 在最外层调另外两个。
+
 ### Changed
 - `core.get_rng` / `core.set_seed`：实现（L0 第 2 项）。`get_rng` 收 `int` / `np.integer` /
   `Generator` / `None`，其余类型抛 `TypeError`；无参调用复用同一个会推进的共享生成器。
@@ -190,6 +197,21 @@
   另新增 2 条（多列数值表能跑通、非法输入报错）。
 - 测试计数：**103 passed / 39 skipped → 105 passed / 38 skipped / 1 xfail**。
 
+- `stats.correlation_matrix`：按**方案 A** 拆开 —— 只返回**数值**矩阵，不再返回带星标的字符串表。
+  字符串表做不了后续计算（挑高相关对、喂聚类 / PCA、画热力图），而反过来随时能格式化；
+  一旦返回字符串，数值信息不可逆地丢失（见易错点 14）。
+- `stats.correlation_pvalues`：**对角线由 `0.0` 改成 `NaN`** —— 写成 0 会被下游读成"极显著"，
+  而"自己和自己相关"根本没有 p 值可言。
+- `stats.correlation_pvalues`：p 值与 r 现在用**同一批观测** —— 先成对 `dropna()` 再算，
+  并同样尊重 `min_periods`（不足给 NaN）。此前 `corr` 是成对删缺失、`pearsonr` 不删，
+  两者基于不同的样本量，r 和 p 对不上。
+- `stats.correlation_pvalues`：只算上三角再镜像到对称位置（成对变量的 p 天然对称），
+  省掉一半重复计算。
+- `tests/test_stats.py`：`test_correlation_matrix_diagonal_is_one` 摘掉 `xfail` 转正；
+  新增 8 条（数值性 + 对称性、非数值列跳过、p 值对照**解析式** `t = r·sqrt((n-2)/(1-r²))`、
+  对角线 NaN、成对删缺失口径、`min_periods`、对角线无星标、表格与数值输出一致）。
+- 测试计数：**105 passed / 38 skipped / 1 xfail → 114 passed / 38 skipped / 0 xfail**。
+
 ### Notes
 - `detect_outliers` 原有的三个 bug 加一处设计空白**已全部收口**：`threshold` 范围校验挪进
   `clean_missing`、`is_series` / `is_ld_array` 提到类型转换**之前**、统计量与掩码都限制在数值列、
@@ -202,9 +224,10 @@
 - 新增易错点第 10 条：**把真报错当成"编辑器误报"** —— 红线先跑 CLI 与 `pytest` 再判断（`docs/dev/personal-pitfalls.md`）。
 - `stats` 这条线开工了：`describe` 落地，填掉 `examples/01_clean_and_describe.py` 的 `TODO(L0)`；
   `correlation_matrix` 功能上也能跑了（硬 bug 已修）。
-- `correlation_matrix` 的**返回契约待拍板**：带星标的字符串表（好贴论文）vs 数值矩阵
-  （能做后续计算）。另有两处一并待定：**对角线不该带 `***`**；`df_num` 含 NaN 时
-  `corr` 成对删失而 `pearsonr` 不删，r 与 p 会对不上。A/B/C 三个选项见 `STATUS.md`「下一步」第 1 条。
+- `correlation_matrix` 的返回契约已按**方案 A** 定案（决策 41）：数值归 `correlation_matrix`、
+  p 值归 `correlation_pvalues`、星标表归 `correlation_table`。对角线不带星、p 与 r 同批观测两条也一并修掉。
+- `correlation_matrix` 仍只收 `DataFrame`（`describe` / `zscore` / `transform` 都收 ndarray）——
+  要不要放开由用户决定，记在 `STATUS.md`「下一步」第 5 条。
 - 三处口径已拍板（2026-10-03）：`log_transform` 的 `offset` 维持现状（决策 35）；
   `describe` / `zscore` **默认丢掉**非数值列、与 `detect_outliers` 的"保留列"刻意不统一（决策 37）；
   变异系数改用 `σ/|μ|`（决策 38）。另立决策 39 明确分工：语义口径用户拍板、工程事务 Codex 顺手补。