docs: edge-linker twist investigation report

[Sangwon91]

Draft for review (mobile-friendly). A research report investigating the edge/linker twist degeneracy (ROADMAP item 1), plus a link to it from ROADMAP.md.

TL;DR

• Diagnosis (verified in repo): the linker twist about the connection axis is a single under-determined scalar. Aligning only 2 connection points is a rank-deficient Kabsch/Wahba problem — scipy literally warns and returns rss=0; the RMSD objective is flat in the twist. Nothing in the pipeline sets it (locator.py:148-150, :87; builder.py:537-543).
• Enabling safety fact: both X atoms lie on the connection axis (Xoffaxis=0), so rotating about it leaves bond fusion unchanged — a fix is localized and low-risk.
• Prior art: the geonho42 fork keys off the ideal net space group (spglib) + a coarse angle sweep + m3gnet + magic thresholds — it violates both hard constraints (post-relaxation symmetry mismatch; genuine numerical optimization), which is why it was rejected. Salvage only the rotate-about-axis primitive.
• Adversarial finding: a local steric objective is flat in the twist for the canonical carboxylate-linker case → coplanarity/dihedral must be the primary signal, steric only a feasibility filter.
• Recommendation: per-edge, reading only post-relaxation coordinates (satisfies constraint 1 by construction): closed-form seed (atan2 / align_vectors(weights=[inf,w]), verified) + 1-D grid + minimize_scalar (satisfies constraint 2; a 1-D extension of Locator.locate). New edge_twist.py + a new Locator method + a one-line swap in builder.py:537-543, behind a resolve_edge_twist flag. PR-1 is ~180 lines, numpy-only.
• Mandatory pre-code gate: prove E(phi) is non-flat with a coplanar minimum on a built HKUST-1/MOF-5 before wiring the optimizer.

Full report: docs/research/edge-linker-twist-investigation.md (diagnosis, prior art, comparison table with adversarial verdicts, implementation sketch, validation plan, risks).

Not for merge — review/comments only. Implementation (PR-1) intentionally not started yet.