Add write abilities wrapping the bibliography write routes (Phase 05 M5)

[dknauss]

Summary

This adds Phase 05 M5: six write abilities on WordPress 6.9+, in the new includes/write-abilities.php.

Ability	Wraps
borges/add-citations	POST …/citations
borges/update-citation	PATCH …/citations/<id>
borges/delete-citation	DELETE …/citations/<id>
borges/reorder-citations	PUT …/citations/order
borges/update-bibliography-settings	PATCH …/bibliographies/<ref>
borges/reformat-bibliography	POST …/reformat

• Opt-in: they're registered only when bibliography_builder_enable_write_routes is true, the same flag as the routes. They join the existing bibliography category.
• One code path: each ability builds the request its route would get and calls the route's own callback. Permissions (edit_post), dry run (default true), validation, and the ETag check can't drift between REST and Abilities. The etag input is sent as If-Match, so a save is refused with 428 without one and 412 with a stale one.
• Annotations: all six are readonly: false. Only delete-citation is marked destructive. Update, reorder, settings and reformat are marked idempotent.
• Docs:
  • a new Abilities section in docs/rest-write-routes.md;
  • updates to CLAUDE.md, the design memo (M5 done; Tier 4 bulk is the only milestone left) and ROADMAP;
  • a CHANGELOG [Unreleased] entry;
  • updated metrics.

This PR is independent of the particle-sort PR, #147. Each has its own CHANGELOG [Unreleased] entry, so whichever merges second will need a one-line conflict fix.

Validation

• composer lint:php, composer analyze:php, npm run lint:i18n: pass
• PHPUnit full suite: 439 tests pass (only the known vendor deprecations reported). The new WriteAbilitiesTest covers:
  • off until the filter is on;
  • the registered names, annotations and schemas;
  • edit_post and the 404 for a missing post;
  • preview by default, then 428, 412 and a real save that changes only the target block;
  • ability output identical to the route response;
  • update and delete by bibliography_id and by index;
  • locked fields, numeric-only reorder (409), the settings refusal of citationStyle, and reformat.
• The test bootstrap's WP_REST_Request mock gains set_url_params() and set_body(), mirroring core.
• composer verify:metrics: pass

Not covered: the runtime matrix doesn't exercise any abilities over real WordPress yet, read or write.

Checklist

• Tests added
• CHANGELOG [Unreleased] entry
• Docs updated
• No new settings or options (persistence audit passes)

🤖 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 (1aad1b4) to head (ae290ac).

Additional details and impacted files

@@             Coverage Diff              @@
##               main     #148      +/-   ##
============================================
+ Coverage     87.88%   88.28%   +0.39%     
  Complexity       22       22              
============================================
  Files            60       61       +1     
  Lines          7060     7290     +230     
  Branches        690      690              
============================================
+ Hits           6205     6436     +231     
+ Misses          292      291       -1     
  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.