docs(rec-31): Stage 2C — design doc for xml.y semantic-action RAII migration

[CryptoJones]

Closes audit finding #8 from the 2026-05-26 self-audit by replacing the "Stage 2C in flight" hand-wave with an honest scoping doc. The original assumption was "regenerate xml.cc with bison-3.0.4 to apply RAII to the semantic actions." Investigation showed:

• bison-3.0.4 doesn't build on modern glibc (gnulib fseterr.c portability bug). bison-3.0.5 builds cleanly and produces an ~615-line mostly-cosmetic diff against the in-tree xml.cc.
• The real blocker is not the bison version. The %union holds raw pointers (string*, Attributes*, NameValue*) and a C-style union can't hold non-trivially-destructible types like unique_ptr.
• Migrating to RAII therefore requires switching xml.y to bison's C++ variant mode (%define api.value.type variant), which makes yyparse a method of an xml::parser class, changes the yylex contract, and wholesale-rewrites the generated xml.cc.

That's a strategic sprint, not a multi-PR thread.

This doc lays out:

• What's left after Stage 2B (the seven specific raw-new sites and their exact line numbers in xml.y and xml.cc);
• Why hand-edit-parallel (the 2B technique) doesn't extend to these sites (they cross the %union boundary);
• Two architectural options:
  • A. switch to %define api.value.type variant — clean RAII, wholesale rewrite of xml.cc, full xml_parse shim needed;
  • B. keep %union of raw pointers, treat the five bison-value-stack sites as a documented exception in cppRaiiAudit, and clean up only the one obvious code-smell (a heap-allocated stack-scoped temporary in xml.y:208);
• Recommendation: B for the next PR (small, shipping-ready), A for a future strategic sprint;
• A four-step plan ordering Stage 2C-min, the Element parse-tree ownership migration, the Document return-value migration, and the eventual Option A sprint.

Also updates docs/decompiler/RAII_MIGRATION.md's #31-3 row to point at the new design doc and to reflect what's shipped (#46 marshal) vs. in-flight (#51, #52 xml epilogue) vs. scoped (the new doc).

No code change in this PR — design / scoping only.

Proudly Made in Nebraska. Go Big Red! 🌽 https://xkcd.com/2347/