docs: align docs with shipped 4.1.0 code and prep release (#113)

Pre-release documentation sweep aligning all docs with the shipped 4.1.0 code
(escalation guard #111, REST backstop #104), with code as the source of truth:
escalation guard documented (filters/action/constant) with its default-OFF
posture and blind spots stated in FAQ + security-model; corrected now-false
boundary claims (multisite cap-key regex; role/user-create coverage); analysis
doc + gate-completeness report marked implemented/closed; Gate architecture
description updated in CLAUDE.md/AGENTS.md; CHANGELOG dated and release-status
refreshed for the 4.1.0 line; blind spots logged as tracked future mitigation;
drift findings + external-claims audit recorded in llm-lies-log. Docs-only.

Author: dknauss

AGENTS.md

@@ -232,7 +232,7 @@ behavior that the model cannot hold in working memory.
 ### Core Classes (all in `includes/`, namespace `WP_Sudo`)
 
 - **Plugin** — Orchestrator. Creates and owns the component instances. Handles activation/deactivation hooks. Strips `unfiltered_html` from editors on activation and restores it on deactivation. Expires sudo session on password change (`after_password_reset`, `profile_update`).
-- **Gate** — Multi-surface interceptor. Matches incoming requests against the Action Registry and gates them via reauthentication (admin UI), error response (AJAX/REST), or policy (CLI/Cron/XML-RPC/App Passwords).
+- **Gate** — Multi-surface interceptor. Matches incoming requests against the Action Registry and gates them via reauthentication (admin UI), error response (AJAX/REST), or policy (CLI/Cron/XML-RPC/App Passwords). Beyond request-pattern matching it also arms **effect-level backstops** — interactive (`admin_init`) and REST (`register_rest_backstop`) — that hard-block unambiguous destructive effects reached through non-enumerated handlers (4.1.0), plus an opt-in, **default-OFF admin-escalation guard** (`arm_escalation_guard`, filter `wp_sudo_guard_escalation`) that blocks a newly-granted administrator/super-admin without an active sudo session by hooking the `{prefix}capabilities` meta write and `grant_super_admin`.
 - **Action_Registry** — Defines all built-in gated rules and rule categories. Extensible via `wp_sudo_gated_actions` filter. See `docs/current-metrics.md` for the current single-site/multisite totals.
 - **Challenge** — Interstitial reauthentication page. Handles password authentication, 2FA integration, request stash/replay.
 - **Sudo_Session** — Session management. Cryptographic token (user meta + httponly cookie), rate limiting (5 attempts → 5-min lockout), session binding. Two-tier expiry: `is_active()` for true session state; `is_within_grace()` for the 120 s grace window after expiry (token-verified). Cleanup deferred until grace window closes.

CHANGELOG.md

@@ -1,6 +1,6 @@
 # Changelog
 
-## 4.1.0 - unreleased
+## 4.1.0 - 2026-06-24
 
 - **Security (gate completeness):** Two coordinated-disclosure findings in the
   action-gating model are closed. Affected versions: ≤ 4.0.0 (both predate 4.0.0

CLAUDE.md

@@ -126,7 +126,6 @@ No build step. No production dependencies — only dev dependencies (PHPUnit 9.6
 - `docs/ROADMAP.md` — unified roadmap: integration tests, WP 7.0 prep, collaboration analysis, TDD strategy, core design features, feature backlog, accessibility appendix.
 - `docs/release-status.md` — canonical current release status: stable tag, unreleased `main` work, and WordPress forward-lane posture.
 - `docs/wporg-submission-checklist.md` — WordPress.org submission process: validation gates, asset specs, SVN trunk/tags layout, and the version-sync gate.
-- `docs/documentation-remediation-checklist.md` — audit-driven cleanup checklist for doc drift and archival labeling.
 
 ## Verification Requirements
 
@@ -273,7 +272,7 @@ Specifically, do **not** write:
 ### Core Classes (all in `includes/`, namespace `WP_Sudo`)
 
 - **Plugin** — Orchestrator. Creates and owns the component instances. Handles activation/deactivation hooks. Strips `unfiltered_html` from editors on activation and restores it on deactivation. Expires sudo session on password change (`after_password_reset`, `profile_update`).
-- **Gate** — Multi-surface interceptor. Matches incoming requests against the Action Registry and gates them via reauthentication (admin UI), error response (AJAX/REST), or policy (CLI/Cron/XML-RPC/App Passwords).
+- **Gate** — Multi-surface interceptor. Matches incoming requests against the Action Registry and gates them via reauthentication (admin UI), error response (AJAX/REST), or policy (CLI/Cron/XML-RPC/App Passwords). Beyond request-pattern matching it also arms **effect-level backstops** — interactive (`admin_init`) and REST (`register_rest_backstop`) — that hard-block unambiguous destructive effects reached through non-enumerated handlers (4.1.0), plus an opt-in, **default-OFF admin-escalation guard** (`arm_escalation_guard`, filter `wp_sudo_guard_escalation`) that blocks a newly-granted administrator/super-admin without an active sudo session by hooking the `{prefix}capabilities` meta write and `grant_super_admin`.
 - **Action_Registry** — Defines all built-in gated rules and rule categories. Extensible via `wp_sudo_gated_actions` filter. See `docs/current-metrics.md` for the current single-site/multisite totals.
 - **Challenge** — Interstitial reauthentication page. Handles password authentication, 2FA integration, request stash/replay.
 - **Sudo_Session** — Session management. Cryptographic token (user meta + httponly cookie), rate limiting (5 attempts → 5-min lockout), session binding. Two-tier expiry: `is_active()` for true session state; `is_within_grace()` for the 120 s grace window after expiry (token-verified). Cleanup deferred until grace window closes.

docs/FAQ.md

@@ -32,7 +32,9 @@ It depends entirely on where the exploit path goes.
 
 **Yes, if the attack crosses a covered surface.** An attacker who exploits a plugin vulnerability to gain a session and then tries to perform a covered high-risk operation — activate a plugin, create an admin user, change a role — through the standard admin UI, AJAX, or REST path that WP Sudo intercepts will hit the gate. The attacker has no sudo session, so the operation is blocked regardless of how they obtained their session. This is the core kill-chain interception: even with a valid session, covered destructive actions require credential proof.
 
-**No, if the exploit runs through the plugin's own path.** If the vulnerable plugin calls `wp_set_role()`, `wp_insert_user()`, or similar WordPress functions from inside its own AJAX handler or REST endpoint — without routing through a standard surface WP Sudo has been positioned to intercept — the gate never fires. WP Sudo cannot invent interception points for code it does not see.
+**Yes, even through the plugin's own path — if you enable the admin-escalation guard (4.1.0, opt-in, default OFF).** Turning on the `wp_sudo_guard_escalation` filter makes WP Sudo hook the *effect* of an administrator grant (the `{prefix}capabilities` user-meta write and `grant_super_admin`) rather than a surface, so it blocks a **newly granted** `administrator` (single-site) or super-admin (multisite) on *any* path — a plugin's own AJAX/REST handler, or even an unauthenticated request — whenever the actor has no active sudo session. Because an unauthenticated or low-privilege attacker cannot hold a sudo session, this neutralizes the most common privilege-escalation shape even when the vulnerable plugin's own permission check is broken. It is off by default and intentionally narrow: it fires only for *new* administrator/super-admin grants (never low-privilege roles, demotions, or idempotent re-grants), it defers on CLI/Cron/XML-RPC and on Unrestricted REST Application-Password surfaces, and it **cannot** see administrator capabilities conferred at runtime via the `user_has_cap`/`map_meta_cap` filters or written directly with `$wpdb`. Enable it with `add_filter( 'wp_sudo_guard_escalation', '__return_true' )`; allowlist trusted provisioners with `wp_sudo_allow_escalation` or the `WP_SUDO_ALLOW_ESCALATION` constant.
+
+**Otherwise, no, if the exploit runs through the plugin's own path.** Apart from that opt-in administrator/super-admin guard, if the vulnerable plugin calls `wp_set_role()` (to a non-admin role), `wp_insert_user()`, or similar WordPress functions from inside its own AJAX handler or REST endpoint — without routing through a standard surface WP Sudo has been positioned to intercept — the gate never fires. WP Sudo cannot invent interception points for code it does not see.
 
 **No, if the attack runs inside an already-active sudo session.** If the exploited browser session already has an active sudo window, WP Sudo will generally not re-challenge until that window expires. The outcome at that point depends entirely on the underlying authorization logic in the exploited code. See the next question.
 
@@ -113,7 +115,7 @@ change live gate state.
 
 Users with the `manage_wp_sudo` capability. On a new install, the activating admin receives all four governance capabilities automatically. Other administrators can be granted access from **Settings → Sudo → Access**.
 
-In compatibility mode (`wp_sudo_governance_mode = compatibility`), access falls back to `manage_options` (or `manage_network_options` on multisite). Compatibility mode is an opt-in fallback — the default is strict mode, which requires `manage_wp_sudo` explicitly.
+Governance is always strict since 4.0.0: access requires the `manage_wp_sudo` capability explicitly, with no `manage_options` fallback. (The `compatibility` governance mode and the `wp_sudo_governance_mode` option were removed in 4.0.0.) On multisite, super admins are always treated as holding the governance capabilities via the `is_super_admin()` short-circuit in `wp_sudo_can()`.
 
 ## What are the four governance capabilities?
 

docs/ROADMAP.md

@@ -197,7 +197,7 @@ The operator tooling tranche shipped in v2.12.0.
 - ~~Action Registry schema validation~~ — `normalize_filtered_rules()` validates and normalizes `wp_sudo_gated_actions` filter output; malformed rules dropped fail-closed.
 - ~~MU loader resilience~~ — basename/path resolution uses explicit fallback chain (`WP_SUDO_PLUGIN_BASENAME` → derived → canonical); diagnostic action on unresolved paths.
 - ~~WPGraphQL persisted-query strategy~~ — `wp_sudo_wpgraphql_classification` filter enables external mutation classification for persisted-query setups; `str_contains` heuristic preserved as fallback.
-- ~~WSAL sensor bridge~~ — `bridges/wp-sudo-wsal-sensor.php` now maps all 11 audit hooks to structured WSAL events (IDs 1900001–1900011); inert when WSAL absent.
+- ~~WSAL sensor bridge~~ — `bridges/wp-sudo-wsal-sensor.php` maps 11 audit hooks to structured WSAL events (IDs 1900001–1900011); inert when WSAL absent. (The audit-hook total has since grown — see `docs/current-metrics.md`; newer hooks like `wp_sudo_escalation_blocked` are not yet bridged.)
 
 ### ✓ Completed in v2.10.0
 
@@ -549,7 +549,7 @@ not context retrieval.
 With the WordPress 7.0 compatibility release and v3.4.0 hardening work closed,
 the recommended implementation order is:
 
-1. **Deprecate `compatibility` governance mode** (break-glass containment now ✅ shipped) — Two paired governance security-debt items. (a) *Still open:* fire `_doing_it_wrong()` + persistent admin notice when `wp_sudo_governance_mode = 'compatibility'` is active; update FAQ and developer reference; queue removal for the next major release. (b) ✅ *Shipped in v3.4.0:* the break-glass path that replaces it is hardened — the grant is role-gated to administrators, a non-dismissible notice renders, and the `wp_sudo_recovery_mode_active` audit hook fires (stored as a sampled `recovery_mode` event), so it is explicit, auditable, and bounded (see §12.1 Phase R3). `WP_SUDO_RECOVERY_MODE` is the only supported break-glass path going forward, and it is now sound; compatibility mode can be removed once (a) lands. **Effort:** Low (deprecation remaining)
+1. **Deprecate `compatibility` governance mode** (✅ resolved) — Two paired governance security-debt items. (a) ✅ *Resolved in v4.0.0:* rather than a deprecation cycle, the `compatibility` mode and the `wp_sudo_governance_mode` option were **removed outright** in 4.0.0 — governance is always strict, and the inert option is auto-removed with a one-time dismissible notice and a `wp_sudo_inert_governance_mode_detected` audit event. (b) ✅ *Shipped in v3.4.0:* the break-glass path that replaces it is hardened — the grant is role-gated to administrators, a non-dismissible notice renders, and the `wp_sudo_recovery_mode_active` audit hook fires (stored as a sampled `recovery_mode` event), so it is explicit, auditable, and bounded (see §12.1 Phase R3). `WP_SUDO_RECOVERY_MODE` is the only supported break-glass path going forward, and it is now sound; compatibility mode can be removed once (a) lands. **Effort:** Low (deprecation remaining)
 2. **Monitor and tune E2E CI acceleration without reducing release assurance**
    - Explicit CI groups now split the former long challenge shard across behavior-focused jobs
    - Keep the full Playwright suite available for release-grade confidence, but shorten normal feedback loops
@@ -1064,8 +1064,8 @@ SBOM, accessibility roadmap) are documented in the [CHANGELOG](../CHANGELOG.md).
 
 ### ✓ Shipped
 
-**~~WP Activity Log (WSAL) Sensor Extension~~** — shipped v2.11.0 as `bridges/wp-sudo-wsal-sensor.php`. It now maps all 11 audit hooks to WSAL events (IDs 1900001–1900011). Inert when WSAL absent.
-**~~Stream bridge~~** — implemented on `main` for v2.12.0 as `bridges/wp-sudo-stream-bridge.php`. Optional mu-plugin mapping for all 11 audit hooks.
+**~~WP Activity Log (WSAL) Sensor Extension~~** — shipped v2.11.0 as `bridges/wp-sudo-wsal-sensor.php`. It maps 11 audit hooks to WSAL events (IDs 1900001–1900011); the audit-hook total has since grown (see `docs/current-metrics.md`), so newer hooks such as the 4.1.0 `wp_sudo_escalation_blocked` are not yet mapped (tracked under Escalation guard follow-ups). Inert when WSAL absent.
+**~~Stream bridge~~** — implemented on `main` for v2.12.0 as `bridges/wp-sudo-stream-bridge.php`. Optional mu-plugin mapping for those 11 audit hooks (same coverage caveat as the WSAL bridge).
 **~~WP-CLI `wp sudo` commands~~** — implemented on `main` for v2.12.0 (`status`, `revoke --user`, `revoke --all`).
 **~~Public `wp_sudo_check()` / `wp_sudo_require()` API~~** — implemented on `main` for v2.12.0 for third-party action gating integrations.
 **~~Multi-Dimensional Rate Limiting (IP + User)~~** — shipped v2.13.0. Per-IP tracking via transients alongside per-user tracking, combined lockout policy, and the triggering IP address added as the third `wp_sudo_lockout` hook argument.
@@ -1083,8 +1083,34 @@ carries real risks (admin-file loading, multisite `wpmu_delete_user`, deletion /
 post-reassignment hooks firing during an attack). Backlog: design an **optional,
 opt-in sweep** (scheduled or `shutdown`-time) that reclaims never-completed roleless
 users left by a blocked escalation — scoped to rows provably created-and-left-roleless
-in a blocked request, reversible, and off by default. Only relevant once the guard
-ships and is enabled.
+in a blocked request, reversible, and off by default. The guard shipped in 4.1.0
+(opt-in, default OFF), so this sweep is relevant whenever the guard is enabled.
+
+**Escalation-guard blind spots (future mitigation — tracked, not yet scoped).**
+The 4.1.0 admin-escalation guard hooks the `{prefix}capabilities` meta write and
+`grant_super_admin`, so by construction it does **not** see three escalation
+shapes. Tracked here so they are not forgotten:
+
+1. **Runtime capability grants via `user_has_cap` / `map_meta_cap` filters.** A
+   plugin can confer administrator-equivalent capabilities per-request without ever
+   writing role/capabilities meta. A meta-write guard cannot observe this; a
+   capability-based check would catch custom admin-equivalent roles but carries a
+   high false-positive cost (it must distinguish legitimate per-request grants).
+   Needs a design before any attempt.
+2. **Direct `$wpdb` writes to the usermeta table.** Raw SQL that sets the
+   capabilities row bypasses the metadata filters entirely. Anything with direct DB
+   access has broader reach already, so this is low-priority; a periodic
+   capabilities-integrity audit (compare stored caps against a known-good baseline)
+   is the only plausible mitigation and is out of scope for now.
+3. **In-session residual window.** An escalation that fires *during* a legitimate
+   admin's own active sudo window (e.g. CSRF or stored XSS landing mid-session) is
+   allowed, because the actor holds a valid session. Mitigations would be
+   orthogonal (per-action re-prompt for the highest-risk grants, CSRF hardening) and
+   trade UX for coverage; tracked, not scheduled.
+
+Bridge coverage is also incomplete: the WSAL/Stream bridges do not yet map the
+4.1.0 `wp_sudo_escalation_blocked` event — adding it would let SIEM/audit tools
+alert on escalation blocks directly. See the bridge-coverage backlog below.
 
 ### Open — High Priority Security Bridge Coverage
 

docs/admin-escalation-guard-analysis.md

@@ -1,16 +1,20 @@
 # User Privilege-Escalation Guard — Implications Analysis
 
-> **Status: analysis / decision input.** Began as the deferred "Item 2"
-> (admin-surface escalation guard) from the gate-completeness work
-> (PRs #102/#104). Not implemented. **Scope has since evolved:** the analysis now
-> recommends an **effect-level** guard (hooked on the capabilities-meta write and
-> `grant_super_admin`) that covers *all* surfaces uniformly, rather than an
-> admin-`init`-only guard — because the exploit paths this defends against live on
-> REST/AJAX/unauthenticated surfaces, not the interactive admin (§1, §5). If
-> implemented, the guard ships **behind a filter defaulting OFF** (a recorded
-> decision), with a documented path to default-ON once escape hatches are proven
-> (§8). This document exists so the over-block surface is understood before any
-> code lands.
+> **Status: IMPLEMENTED — shipped in 4.1.0 (PR #111), opt-in / default OFF.**
+> Began as the deferred "Item 2" (admin-surface escalation guard) from the
+> gate-completeness work (PRs #102/#104). It is now the **effect-level** guard in
+> `includes/class-gate.php` (`arm_escalation_guard()`), hooked on the
+> capabilities-meta write (`add_user_metadata`/`update_user_metadata`) and
+> `grant_super_admin`, covering *all* surfaces uniformly — because the exploit
+> paths it defends against live on REST/AJAX/unauthenticated surfaces, not the
+> interactive admin (§1, §5). It ships **behind the `wp_sudo_guard_escalation`
+> filter, default `false` (OFF)**, with an allowlist filter
+> (`wp_sudo_allow_escalation`), the `WP_SUDO_ALLOW_ESCALATION` constant bypass, and
+> the high-severity `wp_sudo_escalation_blocked` action; the documented path to a
+> future default-ON is in §8. This document is the design rationale and over-block
+> analysis; the §7 scenarios were realized as tests in `tests/Unit/GateTest.php`.
+> Sections written in the future tense ("if implemented", "if approved") below
+> describe decisions that have since shipped as described.
 
 ## 1. The gap
 
@@ -321,7 +325,7 @@ human to send to the challenge, so the only available response is a **hard block
 (halt the request before the write — §6/§9, not a short-circuit return), not a
 reauth prompt (§6, §8).
 
-## 6. Implementation shape (if approved)
+## 6. Implementation shape (as shipped in 4.1.0)
 
 - **Hooks (effect-level, surface-agnostic):** reuse the `add_user_metadata` /
   `update_user_metadata` filter on the `{prefix}capabilities` key; additionally
@@ -500,9 +504,9 @@ fail-open violates `CLAUDE.md`, fail-closed bricks role writes); and documenting
 the `user_has_cap` runtime-filter blind spot (§3) in the shipped FAQ, since it
 narrows the security claim to *meta-backed* role grants.
 
-**Status:** design corrected; not approved for code. The three BLOCKERs are
-resolved at the design level here, but each must be proven by its §7 TDD scenario
-before and during implementation.
+**Status:** design corrected, approved, and **implemented in 4.1.0 (PR #111)**.
+The three BLOCKERs were resolved at the design level here and each was proven by
+its §7 TDD scenario in `tests/Unit/GateTest.php` during implementation.
 
 ## 10. Plain-language summary
 

docs/current-metrics.md

@@ -66,7 +66,7 @@ Source: `.github/workflows/phpunit.yml`, `.github/workflows/e2e.yml`, `.github/w
 
 ## Verification Notes
 
-- `composer test:unit` passed on 2026-06-23 (`834 tests`, `2399 assertions`).
+- `composer test:unit` passed on 2026-06-24 (`878 tests`, `2539 assertions`).
 - `composer lint` passed on 2026-06-20.
 - `composer analyse` passed on 2026-06-20 (PHPStan L6 `[OK] No errors`; Psalm `No errors found!`, 95.8% type coverage, baseline current).
 - `composer verify:metrics` passed on 2026-06-20 (after this update).