docs(methodology): Phase 0 of epic #150 — Known Limitations + pillar label clarification

[dackclup]

Summary

Closes Phase 0 of epic #150 — foundation reconciliation roadmap from the 2-round scrutinize session (2026-05-20).

Adds the honesty surface that the rest of METHODOLOGY.md glossed over. Pure docs + 1-line frontend label clarification — no compute logic change, no schema bump.

Files (+145 LOC)

docs/METHODOLOGY.md — new §"Known limitations"

7 sub-sections addressing the analytical-layer findings from the scrutinize:

1. Survivorship bias — universe = current Wikipedia SP500, not point-in-time. Cross-sectional statistics inflated upward
2. Score semantics — pillar 0-100 = percentile rank within current universe, NOT absolute quality. Universe shift renormalizes peers
3. Pillar correlation — Quality (ROE, ROIC, Piotroski) + Profitability (ROA, margins) double-count ROE-like signals. ~33% effective composite weight on ROE signals vs nominal 27%. No orthogonalization (compute/scoring/normalize.py:104-125)
4. extreme_*_estimate semantic — these are method-applicability signals (DCF fails on negative-FCF, RIM fails on negative-book), NOT manipulation signals. Currently incorrectly aggregated into manipulation_index (compute/scoring/loss_chance.py:74-75); Phase 2 of epic Foundation reconciliation roadmap — process + analytical scrutinize findings (2 rounds) #150 splits these surfaces
5. Pillar weight rationale — composite.py:17-28 weights are empirical / project-team judgment, NOT directly traceable to academic literature. Relative ordering follows multi-factor precedent; specific values are project decision. Sum-to-1.0 lock at composite.py:43-45 prevents drift
6. Top-decile vetoes — sloan_accruals_top_decile + net_issuance_top_decile fire on top 10% by construction. ~10% of universe always Top-5-suppressed regardless of genuine manipulation. Phase 3 of epic Foundation reconciliation roadmap — process + analytical scrutinize findings (2 rounds) #150 proposes joint-gating
7. Known calibration drift — cross-refs to _avg_3y_roe denominator bug inflates value_trap_risk to 44% of S&P 500 (221 stocks) #11 (_avg_3y_roe), Going-concern phrase scan: 10.8% false-positive rate due to negation phrases in risk-factor language #16 (going_concern FP), Phase 4.5d (loss_avoidance_pattern dead), and #130 quarterly audit

frontend/components/PillarRadarChart.tsx — 1-line sub-header clarification

Before: "8 dimensions, each scored 0–100 against the universe"

After: "0–100 percentile rank against current S&P 500 (sector-relative for Quality / Value / Growth / Profitability)"

Same data, clearer semantic. Number display unchanged.

CLAUDE.md + AGENTS.md — lockstep update per Rule from PR #142

What this PR does NOT do

Phase 0 is doc honesty only. The structural issues are tracked under epic #150 Phases 1-3:

• Phase 1: defense layer count reconcile (17 → 27) + smoke-test pre-merge-prod-sim workflow
• Phase 2: threshold recalibration + extreme-estimate split
• Phase 3: pillar correlation analysis + top-decile joint gates

Test plan

• ruff check . — All checks passed
• tsc --noEmit — pre-existing sandbox @types/node issue unrelated to this PR's 1-line change; CI will verify with proper deps
• No compute/ or tests/ paths touched
• No schema change
• CI green
• Vercel preview spot-check: METHODOLOGY page renders + PillarRadarChart sub-header reads correctly on /stock/[ticker] pages

Constraints honored

• ✅ No touch to compute/ / tests/ / schemas
• ✅ No workflow_dispatch trigger
• ✅ CLAUDE.md + AGENTS.md lockstep
• ✅ Pure docs + 1-line UI text — zero scoring logic change

---

Generated by Claude Code — Phase 0 of epic #150 foundation reconciliation

---

Generated by Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
quantrank	Ready	Preview, Comment	May 20, 2026 10:46am