docs: add a README.md to every trap folder

[bpostaci]

Each of the 42 trap folders now carries a short conceptual README next to its code and debugger notes, so the rule itself lives with the example instead of only in the root index table.

Division of labour inside a trap folder

File	Answers
README.md	What is the rule, why does this code break it, what is the correct direction
debug_analysis.md	How to see it in WinDbg/CDB — commands and evidence
debug_analysis.txt	Raw console transcript

Keeping the debugger commands out of the README is deliberate: it is the boundary that stops the two documents from drifting apart.

README template

Every file follows the same shape (~45–65 lines): **Rule:** one-liner → ## The rule → ## In this code → ## Why it fails → ## Correct direction → ## Detection → ## Next.

Two rules were enforced throughout:

• Honest classification. Each README says whether the trap is undefined behaviour, unspecified, IFNDR, or simply defined-but-wrong. 16 traps carry an explicit "this is not UB" note — e.g. slicing is a defined copy, std::terminate in Trap 42 is standard-mandated, Trap 27/28 are IFNDR. Trap 23 is called out as mixed: the moved-from value is unspecified, but the unique_ptr branch really is UB.
• Detection tables name a tool that fails. Every table lists at least one tool that does not catch the bug. A checklist that only shows successes teaches the wrong lesson.

Verification

Claims were checked against the repository rather than trusted:

• _unsafe target mentions verified against the RUN_UNSAFE_EXAMPLE marker CMake actually greps for (including Trap 27, whose marker lives in provider.cpp, not main.cpp).
• Every ctest -R name verified against CMakeLists.txt — no invented test names.
• All relative links resolve; each # Trap NN heading matches its folder.
• Quoted code and output strings traced back to the real sources; the Trap 13 and Trap 35 samples were compiled and run to confirm their documented output.

Also

Root README.md gains a "what is inside a trap folder" section, and TRAP_GUIDE.md notes that it is the index and each row is expanded by that folder's README.

No source or build changes.

Co-authored-by: Copilot App 223556219+Copilot@users.noreply.github.com
Copilot-Session: 7d5d2a61-df05-47bc-bd58-4248a591ae43