docs: codebase improvement plan from full repo scan

[elhajjar1]

Summary

Adds IMPROVEMENT_PLAN.md — a detailed, prioritized improvement plan produced from a full scan of the codebase (every porosity_fe/ module, the Streamlit app, both CLIs, the validation runner, tests, CI workflows, packaging, and docs), grounded in measurements taken in a clean environment:

• Baseline health: 832 tests passing, 97% line coverage, clean ruff and mypy (even on numpy 2.4).
• Key measurement: a production-mesh (30×10×12) FE solve takes ~20 s, of which the sparse linear solve is only 2 s — Python-loop element assembly (11.5 s) and stress recovery that recomputes everything assembly already computed (9.2 s) dominate, with ~200k small np.linalg.inv calls per solve and zero reuse across load cases.

Plan structure

Six workstreams, each item tagged with effort and file:line references:

1. FE performance — cache B/C from assembly into recovery, reuse K + factorization across load cases, vectorize the knockdown loop, batch the Gauss-point math; target ≥5× end-to-end.
2. Correctness & physics fidelity — verified extrapolation-warning mislabel (mean labeled "max", nodal peaks unchecked), Hashin blind to interlaminar shear under ILSS, three inconsistent void-element thresholds, signed-mean knockdown instability, anisotropic MT tensor treated as isotropic, uncited SCF heuristics, the known ~33% f_md layup-scale error (Document or validate the _F_MD_FLOOR constants (0.15 / 0.80) in EmpiricalSolver #139/Validate the linear _layup_scale assumption (or replace with nonlinear fit) #140).
3. Missing capabilities — transverse_compression mode (sigma_2c currently unreachable), reaction forces / effective modulus, first-ply-failure load factor, UQ surfaced in CLI+app, thermal loading, locking mitigation.
4. App/CLI polish — verified FE-legend-vanishes bug and unreachable graceful-degradation UI in app.py, figure leak in FEVisualizer, CLI exit-code contract gaps, cross-Vp parallelism.
5. Architecture — split the 1,497-line fe/solver.py, single source of truth for the knockdown laws, misc dedup.
6. Tests/CI/packaging/docs/hygiene — verified validation/ gitignore trap and repo-identity split (elhajjar1 vs ranipdx-glitch URLs), CI coverage + editable install + pip caching, PyPI trusted publishing, api.rst covering ~10 of ~40 public symbols, property-based tests, golden MAE regression pin.

Ends with a four-phase sequencing proposal (quick wins → FE perf sprint → correctness/features → design-first physics work). Each item is scoped to become one issue/PR.

Notes for review

• One item needs a maintainer decision rather than code: which org (elhajjar1 vs ranipdx-glitch) is canonical — README/CITATION/CONTRIBUTING and pyproject.toml currently disagree.
• Findings marked "(verified)" were confirmed by direct code reading in this session; profiling numbers are reproducible with the snippet in the plan's Workstream 1 context.

🤖 Generated with Claude Code

https://claude.ai/code/session_012GBVCaDCFo5nvpWEtKVFXT

---

Generated by Claude Code