docs(roadmap): design-reviewed recovery-mode visibility item (Phase R3)

[dknauss]

Captures the outcome of a pre-implementation design review of the recovery-mode visibility gap: the warning notice (Admin::render_recovery_mode_notice()) and the wp_sudo_recovery_mode_active audit event both fire only inside render_settings_page(), so a permanent, security-degrading break-glass bypass can persist with no reminder and no SIEM signal if nobody revisits the Sudo settings page.

Design-review conclusion (recorded under Phase R3 §12.1):

• Ship: Site_Health::test_recovery_mode() → critical, keyed strictly on wp_sudo_is_recovery_mode(). Pull-based, REST-exposed (monitorable), live state, no cron dependence; must surface to the network operator on multisite.
• Dropped: a daily-cron audit heartbeat — unreliable exactly on the neglected sites where recovery is most likely left on (opportunistic / DISABLE_WP_CRON), redundant with the Site Health REST status, and would force a user_id = 0 row that corrupts the per-user sampling bucket and the documented "user accessing the Sudo surface" semantics of wp_sudo_recovery_mode_active. Would require a dedicated recovery_mode_heartbeat hook+event if ever needed.
• Deferred: broadening the notice to all_admin_notices (notice fatigue + multisite capability nuance).

Docs-only; no code. Implementation (the Site Health test) is a separate follow-up PR via TDD.

🤖 Generated with Claude Code

[github-actions]

🎮 Try in WordPress Playground

Open this PR in Playground →

Preview is pinned to WordPress 7.0.

Uses the checked-in blueprint.json from this PR, with the plugin install pinned to commit 10036e73a1164c5e289ccd6909d4b889de3f1dd0 through Playground's CORS-safe git:directory resource.

Logs in as admin / password; use password again for the WP Sudo reauthentication challenge.

✅ What you can test

Feature	Notes
Plugin activation & settings page	✅
Gate fires on dangerous actions (plugin activate/delete, user delete, etc.)	✅
Challenge / reauthentication page	✅
Password verification & session cookie	✅
Admin bar countdown timer	✅
Request stash & replay after auth	✅
Rate limiting / 5-attempt lockout	✅ within session
Session expiry by time	✅ wait out the configured duration (1–15 min)
Two Factor plugin (TOTP)	✅ installed automatically via blueprint
unfiltered_html removed from Editor role	✅

❌ What won't work

Feature	Why
WP-CLI / Cron entry point policies	No CLI in browser
REST / XML-RPC entry point policies	Network disabled in Playground
Two Factor email / magic-link providers	PHP outbound network is off
Multisite behaviour	Single-site only
State after refreshing Playground	Full reset on page reload

Transients and user meta persist across normal WP navigation within
a session, but are wiped if you reload the Playground page itself.
Use the integration test suite to verify
transient TTL, real bcrypt, and multisite isolation.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 89.35%. Comparing base (737cfba) to head (10036e7).

Additional details and impacted files

@@            Coverage Diff            @@
##               main      #61   +/-   ##
=========================================
  Coverage     89.35%   89.35%           
  Complexity     1284     1284           
=========================================
  Files            18       18           
  Lines          5231     5231           
=========================================
  Hits           4674     4674           
  Misses          557      557           

Flag	Coverage Δ
unit	89.35% <ø> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ 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.

[Copilot]

Pull request overview

This PR updates the project roadmap to record the Phase R3 design-review outcome for closing the “recovery-mode visibility gap” (where the recovery-mode notice and the wp_sudo_recovery_mode_active audit event only fire from Admin::render_settings_page()), and documents the chosen monitoring approach for a future implementation PR.

Changes:

• Added a new “Visibility / monitoring follow-up” item documenting the design decision to ship a Site_Health::test_recovery_mode() check keyed strictly on wp_sudo_is_recovery_mode().
• Documented why a daily-cron “audit heartbeat” was dropped (reliability + event semantics), and why expanding notices to all_admin_notices was deferred.
• Added acceptance-criteria notes for the planned Site Health test behavior (critical only when recovery mode is active; multisite visibility considerations).