docs(phase-3): Epic #150 Phase 3 — flag-correlation baseline analysis

AGENTS.md

@@ -371,17 +371,30 @@ note cross-tool-specific points only:
   provenance tiers and prefer evidence-backed recalibration over
   re-tuning gut-feel defaults blind. Doc-only, no compute / schema
   change.
-- **Phase 2.4 in flight (this PR)** — `compute/scoring/earnings_quality.py`
-  `LOSS_AVOID_NI_CEILING` and `LOSS_AVOID_EPS_CEILING` rescaled 10×
-  (`$5M → $50M` and `$0.05 → $0.50`) so the `loss_avoidance_pattern`
-  annotate-flag actually fires on the S&P 500 universe instead of
-  the documented 0%. Module + tests + CLAUDE.md gotcha updated; the
-  Phase 2.5 provenance comment in `manipulation_index.py` is the
-  forward link. Cross-tool agents extending earnings-quality
-  thresholds: the absolute-dollar bands are a stopgap — the
-  documented follow-up is a ratio-based threshold (NI/TotalAssets)
-  that survives universe market-cap inflation. Annotate-only
-  (composite rank unaffected); no schema / output-JSON change.
+- **Phase 2.4 merged via PR #163** (2026-05-20) —
+  `compute/scoring/earnings_quality.py` `LOSS_AVOID_NI_CEILING` and
+  `LOSS_AVOID_EPS_CEILING` rescaled 10× (`$5M → $50M` and `$0.05 →
+  $0.50`) so the `loss_avoidance_pattern` annotate-flag actually
+  fires on the S&P 500 universe instead of the documented 0%. Module
+  + tests + CLAUDE.md gotcha updated; the Phase 2.5 provenance
+  comment in `manipulation_index.py` is the forward link. Cross-tool
+  agents extending earnings-quality thresholds: the absolute-dollar
+  bands are a stopgap — the documented follow-up is a ratio-based
+  threshold (NI/TotalAssets) that survives universe market-cap
+  inflation. Annotate-only (composite rank unaffected); no schema /
+  output-JSON change.
+- **Phase 3 in flight (this PR)** — pairwise φ-coefficient analysis
+  on the 25 active production flags. `scripts/phase3_flag_correlation.py`
+  is reproducible one-shot; outputs land under `docs/phase3-correlation/`
+  (`summary.md` = raw firing rates + pair tables; `findings.md` =
+  interpreted decisions; `heatmap.png` = visual; CSVs = baseline for
+  Q3 audit diff). Headline: defense layer mostly orthogonal,
+  `restatement_history` independent of Sloan/Beneish (Phase 2.2 safe
+  to proceed), `manipulation_triple_flag` φ-locked to `dechow_high`
+  at current sample size (watch Q3 audit). Cross-tool agents
+  proposing new flags: target orthogonality vs `altman_distress` and
+  `restatement_history` baselines — overlap with either is redundant
+  with existing veto. Doc + script only.
 
 ## Claude-Code-specific tooling
 

CLAUDE.md

@@ -237,7 +237,7 @@ in the module docstring: literature-anchored / gut-feel / reserved.
 Doc-only — no compute / schema change. Future weight-recalibration
 PRs (Phase 2.2 / 2.4) now have a documented baseline to delta from.
 
-**Epic #150 Phase 2.4 in flight (this PR)** —
+**Epic #150 Phase 2.4 merged via PR #163** (2026-05-20) —
 `compute/scoring/earnings_quality.py` `LOSS_AVOID_NI_CEILING` rescaled
 `$5M → $50M` and `LOSS_AVOID_EPS_CEILING` rescaled `$0.05 → $0.50`
 (10× the original Burgstahler-Dichev 1997 Compustat-cohort thresholds)
@@ -248,6 +248,19 @@ Phase-2.5 provenance comment updated to match. New test
 `test_loss_avoidance_ni_just_above_new_ceiling_breaks_streak` pins the
 new upper bound. Tests: 945 → 946. No schema / output-JSON change.
 
+**Epic #150 Phase 3 in flight (this PR)** —
+`scripts/phase3_flag_correlation.py` + `docs/phase3-correlation/`
+produce a baseline pairwise-φ analysis of the 25 active flags on
+production output (502 stocks × 25 flags). Headline findings: defense
+layer is mostly orthogonal (35 diversity-confirmed pairs vs 15
+redundancy candidates); `restatement_history` is independent of the
+Sloan/Beneish manipulation cluster (φ ≈ 0) → Phase 2.2 safe to
+proceed; `TRIPLE_FLAG_WEIGHT` may be redundant with Dechow at current
+sample size (watch in Q3 audit). Doc + script only — no compute /
+schema / output change. Reproducible via the one-shot script;
+re-run after every quarterly cohort audit + after each Phase 2.x
+recalibration PR lands.
+
 **Next deliverables** (pick by appetite):
 - **Phase 4.5e** — Form 4 insider clustering (~3w → v1.3.0; weight
   slots already declared in `FLAG_WEIGHTS`)

docs/phase3-correlation/correlation_matrix.csv

@@ -0,0 +1,26 @@
+,accruals_momentum_high,altman_distress,auditor_change,beneish_high,beneish_manipulation_veto,cross_source_disagreement,data_quality_input_corruption,dechow_high,dechow_manipulation_veto,extreme_dcf_estimate,extreme_graham_estimate,extreme_multiples_ev_ebitda_estimate,extreme_multiples_pb_estimate,extreme_multiples_pe_estimate,extreme_rim_estimate,going_concern_disclosure,goodwill_heavy,late_filing_notification,manipulation_triple_flag,net_issuance_top_decile,non_reliance_filing,rem_suspect,restatement_history,sloan_accruals_top_decile,value_trap_risk
+accruals_momentum_high,1.0,-0.013411189363177478,0.005192833641699081,0.1623997647112351,0.17740455363341567,0.08618923263253174,0.01717662162459663,-0.02103515809558356,-0.01485925110381962,0.12384232896083497,0.04110063574259487,0.04779624355434561,0.06566178320539501,-0.01593444868153137,0.022604974729936528,-0.0333597350378606,-0.016719422761530465,-0.02103515809558356,-0.02103515809558356,0.10984414031420829,-0.01485925110381962,0.015388554320151106,0.002550994962448178,0.3047353973371503,-0.021327594086398668
+altman_distress,-0.013411189363177478,1.0,0.009121717555140038,0.019240227650865693,-0.00037580414464838066,-0.003552227302397774,-0.03776964605855168,-0.02008752777048048,-0.014189844347268677,0.02569149932579124,-0.08668219559292915,0.053549449573056976,0.021494595290306142,-0.0118618677682726,-0.07904768549249622,0.03767422874407427,-0.004446215263651989,-0.02008752777048048,-0.02008752777048048,-0.0103173317585475,-0.014189844347268677,-0.05762863742337031,-0.008712463292245985,-0.06867991700457411,0.15732837617302717
+auditor_change,0.005192833641699081,0.009121717555140038,1.0,0.10390964485175164,0.18487014259616646,0.04219350726657027,-0.016067348574309696,0.229773874398007,0.33066127954747226,-0.04642079344933689,-0.010335553836180277,-0.019262614963441557,-0.036989067001707246,-0.022885051912492474,0.024930557993775308,-0.013552037754405938,0.015124713362779141,-0.008545309378438276,0.229773874398007,0.0193425911354691,-0.006036412811211461,0.14641164188970207,0.09053823677849114,0.047496744903130224,-0.067813695596581
+beneish_high,0.1623997647112351,0.019240227650865693,0.10390964485175164,1.0,0.6404310783840154,-0.00822146870476645,-0.02779262823474761,0.27061184236978475,0.191160403889911,0.18296936987698198,0.06334154384993285,0.031012920385079405,0.07720043141914476,0.06960106656795603,0.02382465707507295,-0.023441748673685574,-0.03893193929767352,-0.014781319121038663,0.27061184236978475,0.0372804727424179,-0.010441534666255643,0.21345601681597476,-0.057380149840522914,0.14560905124165735,-0.039853753696853685
+beneish_manipulation_veto,0.17740455363341567,-0.00037580414464838066,0.18487014259616646,0.6404310783840154,1.0,0.03227978130627863,-0.017799262871505444,0.4225463933646275,0.2984870821264039,0.12569461451710406,0.09832339281171341,0.0760442580636298,0.11930978456105215,-0.025351852730063927,0.0484850321126289,-0.015012824382295514,-0.06995652739939663,-0.009466416144625057,0.4225463933646275,0.06193125830729932,-0.006687083306294182,0.1277659481450368,-0.012372355126854641,0.16307276806840437,-0.05294362695733943
+cross_source_disagreement,0.08618923263253174,-0.003552227302397774,0.04219350726657027,-0.00822146870476645,0.03227978130627863,1.0,0.13644080731125288,-0.013858816899198555,-0.009789878420276125,-0.07528542832552784,-0.03213426615872016,0.036944915529946845,0.014829583005654415,0.020747553901611232,0.037510350128157996,-0.02197874898751327,-0.0030675394173655876,-0.013858816899198555,-0.013858816899198555,-0.0253493258348799,-0.009789878420276125,-0.03975923485091402,0.008780651180862947,0.07366786580890082,-0.041206236115541174
+data_quality_input_corruption,0.01717662162459663,-0.03776964605855168,-0.016067348574309696,-0.02779262823474761,-0.017799262871505444,0.13644080731125288,1.0,-0.00752101433090355,-0.005312850038516498,-0.04085650235968202,-0.047470851047871285,-0.016953675610185813,-0.03255532253853099,-0.02014190426289559,-0.05100477000978158,-0.011927604449408553,-0.05558006716299374,-0.00752101433090355,-0.00752101433090355,0.09648889098906481,-0.005312850038516498,-0.021576861666797603,0.009352129636050704,0.011824413887198147,0.055035759965707004
+dechow_high,-0.02103515809558356,-0.02008752777048048,0.229773874398007,0.27061184236978475,0.4225463933646275,-0.013858816899198555,-0.00752101433090355,1.0,0.7064007333008538,-0.021729251168584682,-0.025247047251493956,-0.009016696346674324,-0.017314325491848862,-0.010712333936199699,-0.027126537866151913,-0.006343614796955511,-0.029559878344928795,-0.004,1.0,0.10318496721926447,-0.0028256029332034156,0.3485685011586675,-0.0230809743506458,0.17848569370440548,-0.04647051971362046
+dechow_manipulation_veto,-0.01485925110381962,-0.014189844347268677,0.33066127954747226,0.191160403889911,0.2984870821264039,-0.009789878420276125,-0.005312850038516498,0.7064007333008538,1.0,-0.015349558959566655,-0.017834532692136636,-0.006369400911241872,-0.012230852224051703,-0.00756720054789509,-0.01916220624056309,-0.00448113414434752,-0.02088111973914173,-0.0028256029332034156,0.7064007333008538,-0.012602465658152246,-0.001996007984031936,0.24622904482406227,-0.016304417206594393,0.12608242491650362,-0.032826809202573276
+extreme_dcf_estimate,0.12384232896083497,0.02569149932579124,-0.04642079344933689,0.18296936987698198,0.12569461451710406,-0.07528542832552784,-0.04085650235968202,-0.021729251168584682,-0.015349558959566655,1.0,0.2205573730974076,0.18298754625610264,0.05866509674299911,0.059918140145518065,0.19263003582536867,-0.034460499809949155,0.025315521165852374,-0.021729251168584682,-0.021729251168584682,0.10156016141075816,0.13003682967632885,0.011467938812571538,-0.024739800306961972,0.04298715808222144,-0.0486590301092378
+extreme_graham_estimate,0.04110063574259487,-0.08668219559292915,-0.010335553836180277,0.06334154384993285,0.09832339281171341,-0.03213426615872016,-0.047470851047871285,-0.025247047251493956,-0.017834532692136636,0.2205573730974076,1.0,0.10870871579305107,0.027015522723686482,0.14320665708355043,0.5154938772299879,-0.04003938563100301,0.41671401290771565,-0.025247047251493956,-0.025247047251493956,-0.0018965863631015658,0.1119181544303647,0.02637420840410026,0.0339601695584113,-0.012812624780129176,-0.08719138462019595
+extreme_multiples_ev_ebitda_estimate,0.04779624355434561,0.053549449573056976,-0.019262614963441557,0.031012920385079405,0.0760442580636298,0.036944915529946845,-0.016953675610185813,-0.009016696346674324,-0.006369400911241872,0.18298754625610264,0.10870871579305107,1.0,0.016949955958526806,0.40878209566521906,0.017560433683380332,-0.014299612091104485,-0.029466642760605847,-0.009016696346674324,-0.009016696346674324,0.06890954272793823,-0.006369400911241872,-0.0258677887322066,0.03650815794980204,-0.0052321959381598886,0.04463890965872074
+extreme_multiples_pb_estimate,0.06566178320539501,0.021494595290306142,-0.036989067001707246,0.07720043141914476,0.11930978456105215,0.014829583005654415,-0.03255532253853099,-0.017314325491848862,-0.012230852224051703,0.05866509674299911,0.027015522723686482,0.016949955958526806,1.0,-0.04636920913718503,0.012129039662544683,-0.027458852847349117,-0.025996665659101043,-0.017314325491848862,-0.017314325491848862,0.012582375862861187,-0.012230852224051703,-0.04967266243018162,-0.027045279653757606,0.027221295131968033,-0.11918875080982402
+extreme_multiples_pe_estimate,-0.01593444868153137,-0.0118618677682726,-0.022885051912492474,0.06960106656795603,-0.025351852730063927,0.020747553901611232,-0.02014190426289559,-0.010712333936199699,-0.00756720054789509,0.059918140145518065,0.14320665708355043,0.40878209566521906,-0.04636920913718503,1.0,-0.03925074037810424,-0.016988730016901273,0.015455793816329676,-0.010712333936199699,-0.010712333936199699,-0.0014757701282357549,-0.00756720054789509,0.03814105846437859,0.013320428770406189,-0.021588065974152353,0.027678432781844294
+extreme_rim_estimate,0.022604974729936528,-0.07904768549249622,0.024930557993775308,0.02382465707507295,0.0484850321126289,0.037510350128157996,-0.05100477000978158,-0.027126537866151913,-0.01916220624056309,0.19263003582536867,0.5154938772299879,0.017560433683380332,0.012129039662544683,-0.03925074037810424,1.0,-0.043020076749473814,0.44461951458000637,-0.027126537866151913,-0.027126537866151913,0.04737190780246307,0.10416378776921476,-0.04651901087922599,-0.03700588516324403,-0.012247599911976182,-0.3151460781678211
+going_concern_disclosure,-0.0333597350378606,0.03767422874407427,-0.013552037754405938,-0.023441748673685574,-0.015012824382295514,-0.02197874898751327,-0.011927604449408553,-0.006343614796955511,-0.00448113414434752,-0.034460499809949155,-0.04003938563100301,-0.014299612091104485,-0.027458852847349117,-0.016988730016901273,-0.043020076749473814,1.0,-0.046879120416273776,-0.006343614796955511,-0.006343614796955511,-0.028293142921020253,-0.00448113414434752,-0.018199047750639734,-0.03660420260472683,0.028179178952180067,0.010384685648640457
+goodwill_heavy,-0.016719422761530465,-0.004446215263651989,0.015124713362779141,-0.03893193929767352,-0.06995652739939663,-0.0030675394173655876,-0.05558006716299374,-0.029559878344928795,-0.02088111973914173,0.025315521165852374,0.41671401290771565,-0.029466642760605847,-0.025996665659101043,0.015455793816329676,0.44461951458000637,-0.046879120416273776,1.0,0.0528793379281504,-0.029559878344928795,-0.012590121427992755,-0.02088111973914173,0.06301381723458557,0.039060324169831184,-0.03364872796229166,-0.02779412641729518
+late_filing_notification,-0.02103515809558356,-0.02008752777048048,-0.008545309378438276,-0.014781319121038663,-0.009466416144625057,-0.013858816899198555,-0.00752101433090355,-0.004,-0.0028256029332034156,-0.021729251168584682,-0.025247047251493956,-0.009016696346674324,-0.017314325491848862,-0.010712333936199699,-0.027126537866151913,-0.006343614796955511,0.0528793379281504,1.0,-0.004,-0.01784039152856442,-0.0028256029332034156,-0.01147550621098494,-0.0230809743506458,-0.022410759747638356,0.0860760762877288
+manipulation_triple_flag,-0.02103515809558356,-0.02008752777048048,0.229773874398007,0.27061184236978475,0.4225463933646275,-0.013858816899198555,-0.00752101433090355,1.0,0.7064007333008538,-0.021729251168584682,-0.025247047251493956,-0.009016696346674324,-0.017314325491848862,-0.010712333936199699,-0.027126537866151913,-0.006343614796955511,-0.029559878344928795,-0.004,1.0,0.10318496721926447,-0.0028256029332034156,0.3485685011586675,-0.0230809743506458,0.17848569370440548,-0.04647051971362046
+net_issuance_top_decile,0.10984414031420829,-0.0103173317585475,0.0193425911354691,0.0372804727424179,0.06193125830729932,-0.0253493258348799,0.09648889098906481,0.10318496721926447,-0.012602465658152246,0.10156016141075816,-0.0018965863631015658,0.06890954272793823,0.012582375862861187,-0.0014757701282357549,0.04737190780246307,-0.028293142921020253,-0.012590121427992755,-0.01784039152856442,0.10318496721926447,1.0,-0.012602465658152246,-0.007781029198192554,0.015420290140098672,0.021129310692266097,0.04837835705869271
+non_reliance_filing,-0.01485925110381962,-0.014189844347268677,-0.006036412811211461,-0.010441534666255643,-0.006687083306294182,-0.009789878420276125,-0.005312850038516498,-0.0028256029332034156,-0.001996007984031936,0.13003682967632885,0.1119181544303647,-0.006369400911241872,-0.012230852224051703,-0.00756720054789509,0.10416378776921476,-0.00448113414434752,-0.02088111973914173,-0.0028256029332034156,-0.0028256029332034156,-0.012602465658152246,1.0,-0.008106306002438264,-0.016304417206594393,-0.015830977119560993,-0.032826809202573276
+rem_suspect,0.015388554320151106,-0.05762863742337031,0.14641164188970207,0.21345601681597476,0.1277659481450368,-0.03975923485091402,-0.021576861666797603,0.3485685011586675,0.24622904482406227,0.011467938812571538,0.02637420840410026,-0.0258677887322066,-0.04967266243018162,0.03814105846437859,-0.04651901087922599,-0.018199047750639734,0.06301381723458557,-0.01147550621098494,0.3485685011586675,-0.007781029198192554,-0.008106306002438264,1.0,0.004208673694646503,0.07979307804038219,0.03304548746854954
+restatement_history,0.002550994962448178,-0.008712463292245985,0.09053823677849114,-0.057380149840522914,-0.012372355126854641,0.008780651180862947,0.009352129636050704,-0.0230809743506458,-0.016304417206594393,-0.024739800306961972,0.0339601695584113,0.03650815794980204,-0.027045279653757606,0.013320428770406189,-0.03700588516324403,-0.03660420260472683,0.039060324169831184,-0.0230809743506458,-0.0230809743506458,0.015420290140098672,-0.016304417206594393,0.004208673694646503,1.0,0.008219208224264718,0.09482212191240476
+sloan_accruals_top_decile,0.3047353973371503,-0.06867991700457411,0.047496744903130224,0.14560905124165735,0.16307276806840437,0.07366786580890082,0.011824413887198147,0.17848569370440548,0.12608242491650362,0.04298715808222144,-0.012812624780129176,-0.0052321959381598886,0.027221295131968033,-0.021588065974152353,-0.012247599911976182,0.028179178952180067,-0.03364872796229166,-0.022410759747638356,0.17848569370440548,0.021129310692266097,-0.015830977119560993,0.07979307804038219,0.008219208224264718,1.0,-0.07470554326536495
+value_trap_risk,-0.021327594086398668,0.15732837617302717,-0.067813695596581,-0.039853753696853685,-0.05294362695733943,-0.041206236115541174,0.055035759965707004,-0.04647051971362046,-0.032826809202573276,-0.0486590301092378,-0.08719138462019595,0.04463890965872074,-0.11918875080982402,0.027678432781844294,-0.3151460781678211,0.010384685648640457,-0.02779412641729518,0.0860760762877288,-0.04647051971362046,0.04837835705869271,-0.032826809202573276,0.03304548746854954,0.09482212191240476,-0.07470554326536495,1.0