Add refactoring, architecture, and standards memo

[dknauss]

Summary

Adds docs/planning/refactor-and-standards-memo.md. It answers the pending leaner-root-file todo and the owner's questions on refactoring, architecture, coding standards, metrics and bloat.

What it measured:

• Size history from 1.0.0 to main:
  • PHP grew about 12×, almost all of it planned Phase 05 work and the lookup resolvers;
  • JS grew about 1.9×;
  • the ZIP is smaller than at 1.0.0.
• Runtime cost:
  • the plugin's PHP takes about 0.9 ms to load per request with OPcache, about 5 ms without;
  • visitors get 1.4 KB of JS;
  • the editor bundle is 24 KB gzipped, and citation-js loads on demand.
• Verdict: no runtime bloat. The cost that matters is maintaining the JS/PHP twin implementations; for example, the style table is kept in four places.

What it recommends:

• Split the root file into includes/, byte for byte with the same function names, for maintainability (not performance).
• Put the style table, particle list and labels in one shared JSON file read by both JS and PHP.
• Tighten Psalm one level at a time, from 6 to 5 to 4, with baselines.
• Add PHPCompatibilityWP checks for PHP 7.4.
• Pilot checkJs on src/lib/.
• Add abilities to the runtime-matrix smoke test.
• Decide once whether Prettier applies to the Markdown docs.
• Not recommended: namespaces/PSR-4, TypeScript, PHPStan alongside Psalm, child blocks.

It ends with a phased plan (A–E, 16 tickets), each item a no-behavior-change PR.

Also in this PR:

• the docs/planning/README.md table gets the memo;
• the pending todo points to the memo;
• docs/current-metrics.md now lists the ten includes/ files loaded on every request (it said eight, missing google-books-key.php and write-abilities.php).

Validation

• Docs only; no code changed.
• composer verify:metrics: pass.
• I checked the numbers in the memo against the repo:
  • release-tag line counts from git show;
  • ZIP sizes from the GitHub release assets;
  • bundle sizes from build/;
  • load timing from an in-process require of the plugin, 5–6 runs with and without OPcache.

Checklist

• Docs updated
• No behavior change

🤖 Generated with Claude Code

https://claude.ai/code/session_01KbVuMPN7YTcV27vwsG3LZ2

---

Generated by Claude Code

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 88.28%. Comparing base (ca8d3b3) to head (947915e).
⚠️ Report is 1 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff            @@
##               main     #149   +/-   ##
=========================================
  Coverage     88.28%   88.28%           
  Complexity       22       22           
=========================================
  Files            61       61           
  Lines          7290     7290           
  Branches        690      690           
=========================================
  Hits           6436     6436           
  Misses          291      291           
  Partials        563      563           

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.