From 00a2491028d11abeec4415c86ca02b18393c6e09 Mon Sep 17 00:00:00 2001
From: Dan Knauss <273554+dknauss@users.noreply.github.com>
Date: Sun, 9 Aug 2026 14:11:26 -0600
Subject: [PATCH 01/27] =?UTF-8?q?fix(26-03):=20release=20gates=208?=
 =?UTF-8?q?=E2=80=9311=20=E2=80=94=20one=20real=20defect=20found=20and=20f?=
 =?UTF-8?q?ixed=20(#124)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* fix(26-03): stop a delegated editor silently destroying per-user rules

Gate 10 of the v1.5.0 release. Probed the authorization boundary with tests
instead of reasoning about it, and the probe found a real defect.

A delegated Maestro editor (maestro_capability role without list_users) could
NOT inject a per-user rule, and could not read display names out of the model —
both correct. But they could DESTROY an admin's rules, and not via a crafted
POST: get_menu_model() withholds the user axes from them (correctly), so
diffItem() never flags those axes client-side, so an item whose only override is
a per-user rule is omitted from their full-replace autosave — and a rule omitted
from a full replace is a rule deleted. Any edit such an editor made silently
wiped every per-user rule they could not see. Ordinary data loss.

Round 2's per-item preserve only fired for items PRESENT in the payload, which
was never sufficient. The restore now runs over the STORED items instead,
re-attaching or re-creating any entry carrying an axis the saver could not touch.
My own comment claimed the saver "can neither add nor destroy"; half was true.

The probe is kept as PerUserAxisAuthorizationTest rather than deleted — the
symptom is a rule quietly disappearing rather than anything failing loudly,
which is how this returns unnoticed.

Two guardrail tests then failed, and that is the fix working: they removed their
rule while acting as the EDITOR, which now correctly no-ops. They author as
admin and must remove the same way.

Also adds tests/e2e/specs/person-picker-a11y.spec.ts for Gate 9 — 7 checks over
surfaces that had never had an independent pass: programmatic label on the
search field, four DISTINCT group names (v1.4.0's S1 in this same popover was
two groups sharing a name), keyboard-reachable results, per-person accessible
names on the chip remove controls, a populated polite live region, focus
returning to the field after add and remove, and the focus trap still holding
with the new controls.

Contrast computed rather than eyeballed: all text 6.83-10.03:1 and the focus
ring 5.17:1. Two sub-3:1 borders (#c3c4c7, #dba617) are inherited core tokens —
#c3c4c7 already appears 21x in this stylesheet — and neither carries information
alone. Recorded as notes rather than "fixed" into an inconsistency with wp-admin.

Gate 11 measured cold: name lookup is ONE query for the whole model, the
round-2 bounded validation is ONE query rather than a user-table scan, the
zero-override path costs 0 queries, and a pathological all-items-targeted config
adds +0.108 ms/request — the same order as the entire pre-existing replay cost.

Gate: unit 167/167 (223), integration 119/119 (275), JS 83/83, e2e 46 passed /
28 capture-skipped / 0 failed, WPCS clean, PHPStan 0 errors, doc-links clean.

Gate 8 (independent code review) is NOT done — requested on the PR.

Plan: .planning/phases/26-release-v1.5.0/26-03-PLAN.md

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

* fix(26-03): merge restored per-user axes on the NORMALIZED key

Third iteration on the same function, and the second hole in my own fix.

Re-attaching a preserved rule under its STORED key is wrong when the payload
names the same item in a different but equivalent form — `upload.php?ver=9` for
a rule stored under `upload.php`. That is not a contrived input: slug drift is
the exact problem Slug::normalize() exists to solve, so it is the expected state
after a plugin bumps a ver= string and the client emits the new form.

The config then held BOTH keys. They normalize to the same item, so the Axis-1
collision guard resolved to "apply nothing" — silently neutralising the admin's
rule AND the delegate's own edit, while the stored option still looked healthy.
A rule that is present but inert is worse than one that is missing, because
nothing looks wrong.

The restore now indexes what is about to be written by normalized key and merges
into the equivalent entry instead of adding a second one.

Lineage worth recording: round 2 fixed round 1's client-only gate; A3 fixed
round 2's payload-scoped preserve; A5 fixes A3's raw-key matching. Each fix was
right about the case in front of it and blind to the next. The per-user path now
carries four interacting behaviours — reject-on-add, preserve-on-submit,
restore-on-omit, merge-on-equivalent-key — which is precisely the shape that
wants an independent reviewer rather than another pass by the person who wrote it.

Gate: unit 167/167 (223), integration 120/120 (277), WPCS clean, PHPStan 0.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

* docs(26-03): correct the gate summary to two Gate 10 defects, five probes

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
---
 .../phases/26-release-v1.5.0/26-03-SUMMARY.md | 152 +++++++++++++++
 TESTING.md                                    |   2 +-
 includes/class-config.php                     |  62 ++++++
 tests/e2e/specs/person-picker-a11y.spec.ts    | 152 +++++++++++++++
 .../CosmeticInvariantUsersTest.php            |  10 +-
 .../PerUserAxisAuthorizationTest.php          | 177 ++++++++++++++++++
 6 files changed, 552 insertions(+), 3 deletions(-)
 create mode 100644 .planning/phases/26-release-v1.5.0/26-03-SUMMARY.md
 create mode 100644 tests/e2e/specs/person-picker-a11y.spec.ts
 create mode 100644 tests/integration/PerUserAxisAuthorizationTest.php

diff --git a/.planning/phases/26-release-v1.5.0/26-03-SUMMARY.md b/.planning/phases/26-release-v1.5.0/26-03-SUMMARY.md
new file mode 100644
index 0000000..92e9a41
--- /dev/null
+++ b/.planning/phases/26-release-v1.5.0/26-03-SUMMARY.md
@@ -0,0 +1,152 @@
+# Phase 26 · Plan 03 — Summary
+
+**Completed:** 2026-08-09
+**Status:** Gates 9, 10, 11 complete. **Gate 8 (code review) awaiting the Codex pass.**
+
+## Gate 10 — Adversarial security: **two real defects found and fixed**
+
+Probed the authorization boundary rather than reasoning about it. Five questions,
+asked as tests against a delegated Maestro editor (`maestro_capability` role
+without `list_users`):
+
+| Probe | Result |
+|---|---|
+| A1 · Can they **inject** a per-user rule? | ✅ No — blocked server-side |
+| A2 · Does saving the same item **preserve** an admin's rule? | ✅ Yes |
+| A3 · Does **omitting** the item preserve it? | ❌ **NO — rule destroyed** |
+| A4 · Does the model leak **display names** to them? | ✅ No |
+| A5 · Does a **normalizing-equivalent** key preserve it? | ❌ **NO — rule neutralised** |
+
+**A3 was not a hand-crafted-attack edge case — it was ordinary data loss.**
+`get_menu_model()` withholds the user axes from a saver without `list_users`
+(that is A4 working correctly), so `diffItem()` never flags them client-side, so
+an item whose only override is a per-user rule is omitted from that saver's
+full-replace autosave entirely. A rule omitted from a full replace is a rule
+deleted. **Any edit by a delegated editor silently wiped every per-user rule they
+could not see.**
+
+The per-item preserve I wrote in round 2 only fired for items *present in the
+payload*, which was never sufficient. The restore now runs over the **stored**
+items rather than the submitted ones, re-attaching (or re-creating) any entry
+carrying a per-user axis the saver was not allowed to touch.
+
+My own code comment had claimed "the saver can neither add nor destroy". Half of
+that was true.
+
+**A5 — the fix for A3 had its own hole, and it was worse.** Re-attaching under
+the *stored* key is wrong when the payload names the same item in a different
+but equivalent form (`upload.php?ver=9` for a rule stored under `upload.php`).
+That is not contrived: slug drift is the exact problem `Slug::normalize()` exists
+to solve, so it is the expected state after a plugin bumps a `ver=` string.
+
+The config then held BOTH keys. They normalize to the same item, so the Axis-1
+collision guard resolved to "apply nothing" — silently neutralising the admin's
+rule *and* the delegate's own edit, while the stored config still looked
+perfectly healthy. A rule that is present but inert is worse than one that is
+missing, because nothing looks wrong.
+
+The restore now indexes what is about to be written by NORMALIZED key and merges
+into the equivalent entry rather than adding a second one.
+
+Worth stating plainly: this is the **third** iteration on the same function.
+Round 2 fixed round 1's client-only gate; A3 fixed round 2's payload-scoped
+preserve; A5 fixed A3's raw-key matching. Each fix was correct about the case it
+addressed and blind to the next one. `Config::sanitize()`'s per-user path now
+carries four interacting behaviours (reject-on-add, preserve-on-submit,
+restore-on-omit, merge-on-equivalent-key) and deserves an independent read
+rather than another round of my own.
+
+The probe is kept as `tests/integration/PerUserAxisAuthorizationTest.php` rather
+than deleted — the symptom is a rule quietly disappearing, not anything failing
+loudly, which is exactly the kind of regression that returns unnoticed.
+
+**Also verified:** the edit-mode suspension is unreachable outside edit mode
+(`is_edit_mode()` carries its own capability gate); bounds hold at
+`MAX_HIDDEN_USERS` / `MAX_ITEMS`; the cosmetic-only invariant still holds for the
+per-user path (`CosmeticInvariantUsersTest`, unchanged in substance).
+
+**Consequence for the existing guardrail tests:** two of them removed their rule
+while acting as the *editor*, which now correctly no-ops. They author as admin
+via `save_as_admin()` and must remove the same way; fixed. Worth noting the fix
+made a test fail — that is the fix working, not a regression.
+
+## Gate 9 — Accessibility
+
+**Structure and keyboard: 7/7 verified** in a new
+`tests/e2e/specs/person-picker-a11y.spec.ts`:
+
+- the search field has a real `<label for>`, not just a placeholder
+- all four groups expose **distinct** accessible names (the failure mode is two
+  groups sharing an id, which is precisely v1.4.0's S1 defect in this popover)
+- results are keyboard-reachable from the field and activate on Enter
+- each chip's remove control names **who** it removes
+- status messages sit in a `polite` live region and actually populate
+- focus returns to the search field after both add and remove
+- the focus trap still holds with the added controls, and Escape restores focus
+
+**Contrast (WCAG 1.4.3 / 1.4.11), computed not eyeballed:**
+
+| Surface | Ratio | Verdict |
+|---|---|---|
+| chip text, result text, status text, self-warn text | 6.83–10.03:1 | ✅ well clear of 4.5 |
+| focus ring `#2271b1` | 5.17:1 | ✅ clear of 3.0 |
+| chip / results border `#c3c4c7` | 1.74:1 | ⚠️ note |
+| self-warn accent `#dba617` | 2.09:1 | ⚠️ note |
+
+Both notes are **inherited core tokens, not new choices**: `#c3c4c7` already
+appears 21 times in `maestro.css` and is documented at line 255 as verified
+against core; `#dba617` is core's own notice-warning amber. Neither carries
+information alone — the notice's meaning is in its text at 6.93:1, and the
+chips/results are identified by their content. Flagging them would be flagging
+wp-admin's palette. Recorded rather than "fixed" into an inconsistency.
+
+**What this gate could NOT do:** verify what a screen reader actually announces.
+The structure a screen reader depends on is proven; the announcement is not.
+A real AT pass remains worthwhile.
+
+## Gate 11 — Performance
+
+Measured against `docs/performance/config-size-and-page-load.md`, whose baseline
+puts realistic configs at ~0.1 ms/page.
+
+| Measurement | Result |
+|---|---|
+| `replay()`, 30 items, role axes only | 0.190 ms |
+| `replay()`, same + 5 person targets on **every** item | 0.298 ms |
+| **Delta for a pathological all-targeted config** | **+0.108 ms** |
+| `get_menu_model()`, 30 items × 5 targets, cold cache | 0.034 ms, **1 query** |
+| `sanitize()`, 30 items × 5 ids, cold cache | 0.107 ms, **1 query** |
+| `sanitize()`, no user axis at all | 0.021 ms, **0 queries** |
+
+The two claims that mattered both hold, measured cold rather than trusted:
+the name lookup is **one batched query** for the whole model, and the round-2
+`include`-bounded validation is **one query** rather than a full user-table scan.
+The zero-override fast path genuinely costs nothing — 0 queries, confirming a
+config with no per-user rule pays for nothing.
+
++0.108 ms on a deliberately pathological config is the same order as the entire
+pre-existing replay cost, and lost in admin TTFB.
+
+## Gate 8 — Code review
+
+**Not complete.** The diff was self-reviewed while running gates 9–11, and the
+Gate 10 defect came out of that work. An independent Codex pass over
+`v1.4.1..main` is requested on the PR — it has found something real on every
+pass so far, including two issues raised against the plans that then shipped as
+live bugs anyway.
+
+## Verification
+
+| Check | Result |
+|---|---|
+| `composer test:unit` | ✅ 167/167, 223 assertions |
+| `npm run test:php` | ✅ 120/120, 277 assertions |
+| `npm run test:js` | ✅ 83/83 |
+| `npm run test:e2e` | ✅ 46 passed, 28 capture-skipped, 0 failed |
+| `composer lint` / `analyse:phpstan` | ✅ clean / 0 errors |
+
+## Carried into 26-04
+
+- Gate 8's Codex verdict must land before the tag.
+- The multisite super-admin exempt branch remains untested (single-site suite).
+- A real screen-reader pass on the picker is still outstanding.
diff --git a/TESTING.md b/TESTING.md
index 60ccebb..2441468 100644
--- a/TESTING.md
+++ b/TESTING.md
@@ -2,7 +2,7 @@
 
 Three layers, smallest and fastest first.
 
-> **Current expected status:** unit 167/167 with 223 assertions, integration 115/115 with 267 assertions, JavaScript unit tests, phpcs, PHPStan, Plugin Check, and the Playwright E2E suite should pass before release. E2E coverage includes reset-this-item, per-role visibility, icon persistence, keyboard reordering, first-run cues, toolbar accessibility checks, (COMPAT-04) independent shared-slug top-level/submenu editing, (COMPAT-10) the "Hide its sub-items from:" role group's independent child-hiding behavior, and (ROLE-02) per-user hiding asserted in a targeted user's own authenticated session — including a same-role bystander who must keep every row, which is the assertion that proves the rule did not widen to the whole role.
+> **Current expected status:** unit 167/167 with 223 assertions, integration 120/120 with 277 assertions, JavaScript unit tests, phpcs, PHPStan, Plugin Check, and the Playwright E2E suite should pass before release. E2E coverage includes reset-this-item, per-role visibility, icon persistence, keyboard reordering, first-run cues, toolbar accessibility checks, (COMPAT-04) independent shared-slug top-level/submenu editing, (COMPAT-10) the "Hide its sub-items from:" role group's independent child-hiding behavior, and (ROLE-02) per-user hiding asserted in a targeted user's own authenticated session — including a same-role bystander who must keep every row, which is the assertion that proves the rule did not widen to the whole role.
 
 ## Gotchas (first run)
 
diff --git a/includes/class-config.php b/includes/class-config.php
index 9247869..5a944ac 100644
--- a/includes/class-config.php
+++ b/includes/class-config.php
@@ -419,6 +419,68 @@ public function sanitize( array $raw ) {
 			}
 		}
 
+		// ROLE-02 — restore per-user axes the saver was not allowed to touch.
+		//
+		// The per-item preserve above only fires for items PRESENT in the
+		// payload, which is not enough. get_menu_model() withholds the user axes
+		// from a saver without `list_users`, so diffItem() never flags them
+		// client-side, so an item whose ONLY override is a per-user rule is
+		// omitted from that saver's full-replace autosave entirely — and a rule
+		// omitted from a full replace is a rule deleted. That made any edit by a
+		// delegated editor silently wipe every per-user rule they could not see:
+		// ordinary data loss, not an exotic hand-crafted POST.
+		//
+		// So the restore runs over the STORED items, not the submitted ones.
+		if ( ! $can_target_users ) {
+			// Index what we are about to write by NORMALIZED key. Matching on the
+			// raw key is not enough: the payload may name the same item in a
+			// different-but-equivalent form (`upload.php?ver=9` for a rule stored
+			// under `upload.php`), which is not contrived — slug drift is the
+			// exact problem Slug::normalize() exists to solve, so it is the
+			// expected state after a plugin update. Re-attaching under the stored
+			// key would then leave TWO keys normalizing to the same item, which
+			// the Axis-1 collision guard resolves to "apply nothing" — silently
+			// neutralising both the preserved rule and the saver's own edit while
+			// the stored config still looks healthy.
+			$base     = function_exists( 'admin_url' ) ? admin_url( '' ) : '';
+			$norm_out = array();
+			foreach ( array_keys( $out['items'] ) as $written_key ) {
+				$nk = Slug::normalize_qualified( (string) $written_key, $base );
+				if ( '' !== $nk && ! isset( $norm_out[ $nk ] ) ) {
+					$norm_out[ $nk ] = $written_key;
+				}
+			}
+
+			foreach ( $stored_items as $stored_slug => $stored_entry ) {
+				$keep = array();
+				if ( ! empty( $stored_entry['hidden_users'] ) ) {
+					$keep['hidden_users'] = $stored_entry['hidden_users'];
+				}
+				if ( ! empty( $stored_entry['child_hidden_users'] ) ) {
+					$keep['child_hidden_users'] = $stored_entry['child_hidden_users'];
+				}
+				if ( ! $keep ) {
+					continue;
+				}
+
+				$nk = Slug::normalize_qualified( (string) $stored_slug, $base );
+
+				if ( '' !== $nk && isset( $norm_out[ $nk ] ) ) {
+					// Same item under either spelling — merge into the key that is
+					// actually being written, never add a second one.
+					$target                  = $norm_out[ $nk ];
+					$out['items'][ $target ] = array_merge( $out['items'][ $target ], $keep );
+				} elseif ( count( $out['items'] ) < self::MAX_ITEMS ) {
+					// Nothing equivalent is being written; the item exists only to
+					// hold the rule, so re-create it rather than let it vanish.
+					$out['items'][ $stored_slug ] = $keep;
+					if ( '' !== $nk ) {
+						$norm_out[ $nk ] = $stored_slug;
+					}
+				}
+			}
+		}
+
 		if ( ! empty( $raw['top_order'] ) && is_array( $raw['top_order'] ) ) {
 			$out['top_order'] = array_slice(
 				array_values( array_map( array( $this, 'clean_slug' ), $raw['top_order'] ) ),
diff --git a/tests/e2e/specs/person-picker-a11y.spec.ts b/tests/e2e/specs/person-picker-a11y.spec.ts
new file mode 100644
index 0000000..ca5da8b
--- /dev/null
+++ b/tests/e2e/specs/person-picker-a11y.spec.ts
@@ -0,0 +1,152 @@
+import { test, expect } from '../fixtures';
+import { execFileSync } from 'child_process';
+
+/**
+ * ROLE-02 — accessibility of the person-picker surfaces.
+ *
+ * Written for the v1.5.0 release gate, because these surfaces had never had an
+ * independent a11y pass — they were written to the bar, not audited against it.
+ * That distinction matters here: v1.4.0's a11y gate found a serious defect
+ * (WCAG 1.3.1) in this same popover when it had HALF as many groups, and the
+ * defect was a missing programmatic name — precisely the kind that looks fine
+ * on screen.
+ *
+ * What this spec can and cannot do: it verifies the programmatic structure and
+ * keyboard operability that a screen reader depends on. It cannot verify what a
+ * screen reader actually announces. A real AT pass is still worth doing.
+ */
+
+const TARGET_LOGIN = 'maestro_a11y_target';
+const TARGET_NAME = 'Alex Aria';
+
+function wp( args: string[] ): void {
+	try {
+		execFileSync( 'npx', [ 'wp-env', 'run', 'tests-cli', 'wp', ...args ], { stdio: 'ignore' } );
+	} catch ( e ) {
+		// create-when-present / delete-when-absent both exit non-zero; both fine.
+	}
+}
+
+test.describe( 'ROLE-02 — person picker accessibility', () => {
+
+	test.beforeAll( () => {
+		wp( [ 'user', 'create', TARGET_LOGIN, `${ TARGET_LOGIN }@example.com`,
+			'--role=editor', `--display_name=${ TARGET_NAME }`, '--user_pass=password' ] );
+	} );
+
+	test.afterAll( () => {
+		wp( [ 'user', 'delete', TARGET_LOGIN, '--yes' ] );
+	} );
+
+	async function openPicker( page ) {
+		await page.goto( '/wp-admin/index.php?maestro_edit=1' );
+		await page.locator( '#menu-posts > a.menu-top' ).click();
+		await expect( page.locator( '.maestro-toolbar .maestro-panel' ) ).toBeVisible();
+		await page.locator( '.maestro-toolbar .maestro-panel .maestro-vis-btn' ).click();
+		const pop = page.locator( '.maestro-vis-popover' );
+		await expect( pop ).toBeVisible();
+		return pop;
+	}
+
+	test( 'the search field has a programmatic label, not just a placeholder', async ( { page } ) => {
+		const pop = await openPicker( page );
+		const search = pop.locator( '.maestro-vis-own-users .maestro-user-search' );
+
+		// A placeholder is NOT an accessible name — it disappears on input and
+		// several AT combinations ignore it outright.
+		const id = await search.getAttribute( 'id' );
+		expect( id ).toBeTruthy();
+		const label = page.locator( `label[for="${ id }"]` );
+		await expect( label ).toHaveCount( 1 );
+		await expect( label ).toHaveText( 'Search for a person' );
+	} );
+
+	test( 'all four visibility groups expose DISTINCT accessible names', async ( { page } ) => {
+		const pop = await openPicker( page );
+		const groups = pop.locator( '[role="group"]' );
+		await expect( groups ).toHaveCount( 4 );
+
+		const names: string[] = [];
+		for ( let i = 0; i < 4; i++ ) {
+			const g = groups.nth( i );
+			const labelledBy = await g.getAttribute( 'aria-labelledby' );
+			expect( labelledBy, 'every group needs a programmatic name' ).toBeTruthy();
+			names.push( ( await page.locator( `#${ labelledBy }` ).textContent() ) ?? '' );
+		}
+
+		// The failure mode is two groups sharing an id — an AT user then cannot
+		// tell "hide this item" from "hide its sub-items".
+		expect( new Set( names ).size, 'group names must be distinct' ).toBe( 4 );
+	} );
+
+	test( 'search results are keyboard reachable and each chip remove names WHO it removes', async ( { page } ) => {
+		const pop = await openPicker( page );
+		const group = pop.locator( '.maestro-vis-own-users' );
+		const search = group.locator( '.maestro-user-search' );
+
+		await search.focus();
+		await search.fill( 'Alex' );
+		const result = group.locator( '.maestro-user-result' ).filter( { hasText: TARGET_NAME } ).first();
+		await expect( result ).toBeVisible( { timeout: 15000 } );
+
+		// Reachable by keyboard from the field, and activatable by Enter — a
+		// mouse-only result list would strand keyboard users at the search box.
+		await page.keyboard.press( 'Tab' );
+		await expect( result ).toBeFocused();
+		await page.keyboard.press( 'Enter' );
+
+		const chip = group.locator( '.maestro-user-chip' );
+		await expect( chip ).toContainText( TARGET_NAME );
+
+		// The visible control is a bare glyph, so the accessible name has to
+		// carry the person — otherwise AT hears N identical "remove" buttons.
+		const remove = group.locator( '.maestro-user-chip-remove' );
+		await expect( remove ).toHaveAttribute( 'aria-label', `Remove ${ TARGET_NAME }` );
+	} );
+
+	test( 'status messages live in a polite live region', async ( { page } ) => {
+		const pop = await openPicker( page );
+		const group = pop.locator( '.maestro-vis-own-users' );
+		const status = group.locator( '.maestro-user-status' );
+
+		await expect( status ).toHaveAttribute( 'aria-live', 'polite' );
+
+		// A no-results message that is only visual leaves an AT user waiting.
+		await group.locator( '.maestro-user-search' ).fill( 'zzzznobodymatchesthis' );
+		await expect( status ).toBeVisible( { timeout: 15000 } );
+		await expect( status ).toHaveText( 'No matching people found.' );
+	} );
+
+	test( 'focus returns to the search field after adding and after removing', async ( { page } ) => {
+		const pop = await openPicker( page );
+		const group = pop.locator( '.maestro-vis-own-users' );
+		const search = group.locator( '.maestro-user-search' );
+
+		await search.fill( 'Alex' );
+		const result = group.locator( '.maestro-user-result' ).filter( { hasText: TARGET_NAME } ).first();
+		await expect( result ).toBeVisible( { timeout: 15000 } );
+		await result.click();
+
+		// After a pick, focus must not be lost to <body> — the picked result
+		// node is destroyed, so something has to claim focus deliberately.
+		await expect( search ).toBeFocused();
+
+		await group.locator( '.maestro-user-chip-remove' ).first().click();
+		await expect( search ).toBeFocused();
+	} );
+
+	test( 'the popover keeps a working focus trap with the person groups present', async ( { page } ) => {
+		const pop = await openPicker( page );
+
+		// Tab far enough to wrap. The trap must not be broken by the added
+		// controls, and Escape must still close and restore focus.
+		for ( let i = 0; i < 40; i++ ) {
+			await page.keyboard.press( 'Tab' );
+			expect( await pop.evaluate( ( n ) => n.contains( document.activeElement ) ) ).toBe( true );
+		}
+
+		await page.keyboard.press( 'Escape' );
+		await expect( pop ).toHaveCount( 0 );
+		await expect( page.locator( '.maestro-toolbar .maestro-panel .maestro-vis-btn' ) ).toBeFocused();
+	} );
+} );
diff --git a/tests/integration/CosmeticInvariantUsersTest.php b/tests/integration/CosmeticInvariantUsersTest.php
index d10ffcc..7d8f883 100644
--- a/tests/integration/CosmeticInvariantUsersTest.php
+++ b/tests/integration/CosmeticInvariantUsersTest.php
@@ -188,7 +188,10 @@ public function test_hidden_users_never_changes_what_the_user_can_do() {
 		$this->assertNotContains( 'upload.php', $this->top_slugs_in_model(), 'The hide must actually change visibility.' );
 
 		// STEP 5 — remove (sparse contract: reset deletes the key).
-		( new Config() )->save( array( 'items' => array() ) );
+		// Removed AS ADMIN, matching how the rule was authored: an editor without
+		// `list_users` deliberately CANNOT destroy a per-user rule, so removing as
+		// the measured user would silently no-op and this step would prove nothing.
+		$this->save_as_admin( array( 'items' => array() ) );
 		$stored = ( new Config() )->get();
 		$this->assertArrayNotHasKey( 'upload.php', $stored['items'], 'Reset must delete the key, not blank it.' );
 
@@ -235,7 +238,10 @@ public function test_child_hidden_users_never_changes_what_the_user_can_do() {
 		$this->assertContains( 'edit.php', $this->top_slugs_in_model(), 'The parent must stay visible.' );
 		$this->assertSame( array(), $this->child_slugs_in_model( 'edit.php' ), 'Every child must be hidden.' );
 
-		( new Config() )->save( array( 'items' => array() ) );
+		// Removed AS ADMIN, matching how the rule was authored: an editor without
+		// `list_users` deliberately CANNOT destroy a per-user rule, so removing as
+		// the measured user would silently no-op and this step would prove nothing.
+		$this->save_as_admin( array( 'items' => array() ) );
 		$this->seed_menu();
 		$this->run_replay();
 
diff --git a/tests/integration/PerUserAxisAuthorizationTest.php b/tests/integration/PerUserAxisAuthorizationTest.php
new file mode 100644
index 0000000..85f96b1
--- /dev/null
+++ b/tests/integration/PerUserAxisAuthorizationTest.php
@@ -0,0 +1,177 @@
+<?php
+/**
+ * ROLE-02 — authorization boundary for the per-user axes.
+ *
+ * `maestro_capability` lets a site delegate Maestro to a custom role. That role
+ * may not hold `list_users`, and core's users endpoint would give it only
+ * published authors — so Maestro withholds the person picker from it. Hiding
+ * the picker is presentation, though; the REST save is gated by `capability()`,
+ * not by `list_users`. These tests pin the SERVER-side boundary that actually
+ * holds the line, in both directions:
+ *
+ *   - such a saver cannot ADD a per-user rule (no enumeration via Maestro)
+ *   - such a saver cannot DESTROY one either, whether they submit the item or
+ *     omit it
+ *   - the editor model does not hand them display names
+ *
+ * Written as an adversarial probe during the v1.5.0 release gate, and kept —
+ * the omit-the-item case (A3) was a real defect when written, and it is exactly
+ * the kind that returns silently, because the symptom is a rule quietly
+ * disappearing rather than anything failing loudly.
+ *
+ * @package Maestro
+ */
+
+namespace Maestro\Tests\Integration;
+
+use Maestro\Config;
+use Maestro\Replay;
+use WP_UnitTestCase;
+
+class PerUserAxisAuthorizationTest extends WP_UnitTestCase {
+
+	private $admin;
+	private $delegate;
+	private $victim;
+
+	public function set_up() {
+		parent::set_up();
+		delete_option( 'maestro_config' );
+
+		$this->admin  = self::factory()->user->create( array( 'role' => 'administrator' ) );
+		$this->victim = self::factory()->user->create(
+			array( 'role' => 'editor', 'display_name' => 'Victim Person' )
+		);
+
+		// A delegated Maestro editor: can run Maestro via maestro_capability,
+		// but CANNOT list users.
+		add_role( 'maestro_delegate', 'Maestro Delegate', array( 'read' => true, 'edit_posts' => true ) );
+		$this->delegate = self::factory()->user->create( array( 'role' => 'maestro_delegate' ) );
+	}
+
+	public function tear_down() {
+		remove_role( 'maestro_delegate' );
+		parent::tear_down();
+	}
+
+	private function seed_admin_rule() {
+		wp_set_current_user( $this->admin );
+		( new Config() )->save(
+			array( 'items' => array( 'upload.php' => array( 'hidden_users' => array( $this->victim ) ) ) )
+		);
+		$cfg = ( new Config() )->get();
+		$this->assertSame( array( $this->victim ), $cfg['items']['upload.php']['hidden_users'], 'precondition' );
+	}
+
+	/** A1: can a delegate INJECT a per-user rule? Expected: no. */
+	public function test_delegate_cannot_inject_hidden_users() {
+		wp_set_current_user( $this->delegate );
+		$this->assertFalse( current_user_can( 'list_users' ), 'precondition: delegate lacks list_users' );
+
+		( new Config() )->save(
+			array( 'items' => array( 'upload.php' => array( 'hidden_users' => array( $this->victim ) ) ) )
+		);
+
+		$cfg = ( new Config() )->get();
+		$this->assertArrayNotHasKey( 'hidden_users', $cfg['items']['upload.php'] ?? array() );
+	}
+
+	/** A2: delegate saves the SAME item without the axis — is it preserved? Expected: yes. */
+	public function test_delegate_save_of_same_item_preserves_the_rule() {
+		$this->seed_admin_rule();
+		wp_set_current_user( $this->delegate );
+
+		( new Config() )->save(
+			array( 'items' => array( 'upload.php' => array( 'title' => 'Files' ) ) )
+		);
+
+		$cfg = ( new Config() )->get();
+		$this->assertSame(
+			array( $this->victim ),
+			$cfg['items']['upload.php']['hidden_users'] ?? null,
+			'A2: preserve-verbatim must keep the rule'
+		);
+	}
+
+	/** A3: delegate saves a payload that OMITS the item entirely. */
+	public function test_delegate_save_omitting_the_item() {
+		$this->seed_admin_rule();
+		wp_set_current_user( $this->delegate );
+
+		( new Config() )->save(
+			array( 'items' => array( 'index.php' => array( 'title' => 'Home' ) ) )
+		);
+
+		$cfg = ( new Config() )->get();
+		$this->assertSame(
+			array( $this->victim ),
+			$cfg['items']['upload.php']['hidden_users'] ?? null,
+			'A3: omitting the item must not destroy the rule'
+		);
+	}
+
+	/**
+	 * A5: the delegate saves a NORMALIZING-EQUIVALENT key for the same item.
+	 *
+	 * This is realistic rather than contrived, because slug drift is the exact
+	 * problem Slug::normalize() exists to solve: an admin stores a rule while the
+	 * rendered slug is `upload.php`, a plugin update later renders it as
+	 * `upload.php?ver=9`, and the delegate's client emits the NEW form. The
+	 * restore re-attaches under the OLD stored key, so the config can end up
+	 * holding two keys that normalize to the same thing — which the Axis-1
+	 * collision guard resolves to "apply nothing", silently neutralising BOTH
+	 * the admin's rule and the delegate's own edit while storage still looks
+	 * healthy.
+	 */
+	public function test_delegate_save_with_a_normalizing_equivalent_key() {
+		$this->seed_admin_rule();
+		wp_set_current_user( $this->delegate );
+
+		( new Config() )->save(
+			array( 'items' => array( 'upload.php?ver=9' => array( 'title' => 'Files' ) ) )
+		);
+
+		$cfg   = ( new Config() )->get();
+		$items = $cfg['items'];
+
+		// Whatever the storage shape, the RULE MUST STILL APPLY — that is the
+		// property that matters, not which key it lives under.
+		global $menu, $submenu;
+		$menu = array(
+			10 => array( 'Media', 'upload_files', 'upload.php', '', 'menu-top', 'menu-media', '' ),
+		);
+		$submenu = array();
+
+		wp_set_current_user( $this->victim );
+		( new Replay( new Config() ) )->replay();
+
+		$this->assertNotContains(
+			'upload.php',
+			wp_list_pluck( $menu, 2 ),
+			'A5: the per-user rule must survive a normalizing-equivalent save. Stored keys: '
+				. implode( ', ', array_keys( $items ) )
+		);
+	}
+
+	/** A4: does the model leak display names to a delegate? Expected: no. */
+	public function test_model_does_not_leak_display_names_to_delegate() {
+		$this->seed_admin_rule();
+
+		global $menu, $submenu;
+		$menu = array(
+			10 => array( 'Media', 'upload_files', 'upload.php', '', 'menu-top', 'menu-media', '' ),
+		);
+		$submenu = array();
+
+		wp_set_current_user( $this->delegate );
+		$replay = new Replay( new Config() );
+		$model  = $replay->get_menu_model();
+
+		$names = wp_json_encode( $model );
+		$this->assertStringNotContainsString(
+			'Victim Person',
+			$names,
+			'A4: a delegate must not read user display names out of the model'
+		);
+	}
+}

From 36ec8e869452133c83378a02decfff6211ac9c16 Mon Sep 17 00:00:00 2001
From: Dan Knauss <273554+dknauss@users.noreply.github.com>
Date: Sun, 9 Aug 2026 14:39:59 -0600
Subject: [PATCH 02/27] =?UTF-8?q?docs(planning):=20hold=20the=20v1.5.0=20t?=
 =?UTF-8?q?ag=20=E2=80=94=20Gate=208=20never=20ran=20(#125)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

main is prepared at 1.5.0 (26-01/02/03 merged), but the independent code review
did not happen: Codex hit its usage limit and posted a quota notice with zero
reviews and zero inline comments. Recording the hold in both STATE.md and
26-04-PLAN.md so the next person to open either cannot mistake "prepared" for
"ready", and cannot mistake an absent review for a clean one.

The hold is not procedural tidiness. Gate 10 found TWO real defects in code that
had already passed my own review, and the second was a hole in my fix for the
first: the payload-scoped preserve was never sufficient, and its replacement
re-attached under the raw stored key, so a normalizing-equivalent key left the
rule stored but INERT behind the Axis-1 guard while the config looked healthy.

That makes three consecutive confident-but-wrong self-assessments of one
function, which now carries four interacting behaviours. A fourth pass by the
same author is the least informative option available, which is precisely why
the tag waits rather than proceeding on gates 9-11 alone.

Also notes the alternative explicitly: if the call is to ship without an
independent review, that must be recorded as a deliberate choice rather than
left to read as a satisfied gate.

Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
---
 .planning/STATE.md                            | 28 ++++++++++++++++++-
 .../phases/26-release-v1.5.0/26-04-PLAN.md    | 21 ++++++++++++++
 2 files changed, 48 insertions(+), 1 deletion(-)

diff --git a/.planning/STATE.md b/.planning/STATE.md
index bea32c1..750b665 100644
--- a/.planning/STATE.md
+++ b/.planning/STATE.md
@@ -3,7 +3,7 @@ gsd_state_version: 1.0
 milestone: v1.5
 milestone_name: Per-User Visibility
 status: in-progress
-stopped_at: Phase 21 complete and merged (per-user hiding); 21-05 Task 5 accepted on automated evidence, not a human browser pass
+stopped_at: "v1.5.0 prepared on main (26-01/02/03 merged) — TAG HELD: Gate 8 independent review never ran (Codex quota exhausted)"
 last_updated: "2026-08-09T00:00:00.000Z"
 last_activity: "2026-08-08 — **Phase 21 (ROLE-02 per-user hiding) executed, 5/5 plans, awaiting the human-verify checkpoint.** Branch `phase/21-cosmetic-per-user-hiding`, PR #120, nothing merged. Delivered: `hidden_users` / `child_hidden_users` storage; the `is_hidden_for_current_user()` seam widened to independent OR'd terms (3rd term reserved for the deferred `hidden_profiles`); `resolved_hidden_roles()` GENERALIZED to a field-parameterized resolver rather than duplicated, so the user axis inherits the qualified-key, schema-v2 (#115) and Axis-1 guards from one implementation; a shared `Cascade` union; the §6 cosmetic-invariant guardrail made enforcing; editor model exposure as id+name pairs via one batched query; four-group visibility popover with an async person picker on core's `wp/v2/users`. Gate: unit 165/165 (218), integration 109/109 (257), JS 83/83, e2e 39 passed/28 capture-skipped/0 failed, WPCS clean, PHPStan 0, Plugin Check 0 errors on the ZIP (1 pre-existing readme warning). THREE bugs found by verification that no unit test would have caught: (1) the guardrail initially could NOT detect a broken seam — `current_user_can()` answers from a cached allcaps array, so `snapshot_caps()` now drops `$GLOBALS['current_user']` to force re-derivation; (2) the picker URL appended `?` unconditionally, 404ing on every PLAIN-PERMALINK site since `rest_url()` already carries a query string; (3) clicking a search result or chip closed the whole popover, because re-rendering detached the node before `placePopover()`'s outside-click handler ran. Ruling recorded 2026-08-08: the super-admin exemption covers the NEW user axis only, multisite-scoped (unscoped would make administrators un-hideable on single-site and contradict the locked self-target decision). Prior: 2026-08-05 — **v1.4.1 SHIPPED** (PR #116, tag on c6cdcbe; wp.org API confirms 1.4.1). Patch for the shared-slug propagation defect (#115): a bare top-level key no longer applies to a submenu row whose slug names a rendered top-level item. Two Codex P2 rounds on #115 — the first cut of the gate tested `$nk === $norm_parent` and missed submenus parked under an unrelated parent; widened to `isset( $top_rendered_matches[ $nk ] )`. Prior: 2026-08-04 — **v1.4.0 SHIPPED** (PR #113, tag on 482510c, GitHub Release + wp.org SVN trunk/tags/1.4.0/assets confirmed). Phase 24 release gates 8–11 run consolidated over the full v1.3.1..main diff; one defect found and fixed (multibyte truncation blanked labels) and one changelog overclaim corrected (shared-slug isolation is submenu-direction only). ROLE-02 (Phase 21) deferred to v1.5."
 progress:
@@ -31,6 +31,32 @@ Plan: Phase 21 delivered ROLE-02's **per-user half**: 21-01 storage → 21-02 se
 Status: Phase 20's COMPAT-10 was reworked mid-checkpoint 2026-08-02: the boolean `cascade_hide` + "rides the parent hide" model built in 20-05/20-06 was found **inert** — WordPress core's `_wp_menu_output()` never renders a hidden parent's `<ul class="wp-submenu">` at all, so hiding the parent already removes the whole subtree cosmetically; cascading on top of that produced no observable difference. Reworked (20-CONTEXT.md REVISION NOTE) into an **independent** per-parent `child_hidden_roles` role set: `Maestro\Cascade::effective_hidden_roles( $child_hidden_roles, $parent_child_hidden_roles )` is now a plain, unconditional role-list union (no flag). `Config::sanitize()` accepts `child_hidden_roles` on a top-level item with the same contract as `hidden_roles` (role-intersect, `MAX_HIDDEN_ROLES` cap, dropped on a qualified submenu key). `Replay::replay()`'s submenu loop unions each child's own `hidden_roles` with its parent's `child_hidden_roles`, fully independent of whether the parent's own `hidden_roles` currently hides the parent row — so a parent can stay visible while its children vanish, a genuinely observable effect the old model could never produce. `get_menu_model()` exposes `childHiddenRoles` (empty array, not merely absent, for an untouched parent). The editor popover now shows TWO independent role-checkbox groups — "Hide this item from:" (existing) and "Hide its sub-items from:" (new, shown only on parents with children) — via a shared `buildRoleGroup()` helper in `assets/maestro.js`. The e2e spec (`cascade-hide.spec.ts`) now asserts the effect DIRECTLY against the rendered sidebar (parent visible, child rows gone, role-mirrored) via a second authenticated browser context, replacing the inert model's wp-cli/`$submenu` dump workaround (`dump-cascade-submenu.php`, deleted). Cosmetic-only guardrail reconfirmed end-to-end. **Full zero-regression gate (final):** PHP unit 127/127 (158 assertions), PHP integration 72/72 (172 assertions), JS 58/58, e2e 35 passed/28 capture-gated skipped/0 failed, WPCS clean, PHPStan 0 errors, Plugin Check 0 errors on the built shippable ZIP (1 pre-existing readme.txt warning) and 0 NEW errors on the dev-tree (7 errors/7 warnings, all pre-existing, confirmed via `git log --diff-filter=A` to predate Phase 20). All three Phase 20 requirements (COMPAT-04/07/10) genuinely complete. 20-04 (prior) delivered COMPAT-07 badge/HTML preservation on rename via `Maestro\Title::replace_label()`'s text-node swap at both title-write seams. 20-03 (prior) closed out COMPAT-04 client-side with the qualified-key DOM-join and live WooCommerce verification. 20-02/20-01 (prior) built COMPAT-04's server-side qualified-key foundation and replay/editor-model wiring. Phase 19 ROLE-01 signed off — **partial-go** (per-user go + ship first; cloned-role go as an additive `profiles` registry compiling to the same inline `is_hidden_for_current_user()` seam); Phase 21 unblocked. Phase 23 delivered UX-09/UX-12/UX-13/BUG-08 (native wp-admin restyle; 5/5 plans; full-suite gate green) and shipped in v1.3.1. **NOTE for Phase 24:** Plugin Check flags 7 errors/7 warnings against pre-existing dev-tree root files — logged to `phases/23-editor-ux-polish/deferred-items.md` for the Phase 24 build-then-check pipeline.
 Last activity: 2026-08-09 — Phase 21 merged to `main` (PR #120, merge commit). Two Codex review rounds landed first: round 1 caught a self-target undo trap, the `list_users` gap, and an unenforced 50-user cap; round 2 caught that the `list_users` fix was **client-side only** (an editor could POST guessed IDs and read display names back from the model), plus an unbounded all-users query on every save. Both rounds fixed and CI-green. Codex has NOT reviewed the round-2 fixes themselves.
 
+## ⛔ v1.5.0 IS PREPARED BUT NOT TAGGED (2026-08-09)
+
+`main` reads version 1.5.0 with the changelog, screenshots and gate work merged
+(PRs #122, #123, #124). **The tag is deliberately held**: Gate 8, the independent
+code review, never ran — Codex hit its usage limit and posted a quota notice
+with zero reviews and zero comments.
+
+The hold is not procedural tidiness. Gate 10 found **two** real defects in code
+that had already passed my own review, and the second was a hole in my fix for
+the first:
+
+1. A delegated editor's ordinary autosave silently destroyed per-user rules they
+   could not see (payload-scoped preserve was never sufficient).
+2. The fix for that re-attached under the raw stored key, so a
+   normalizing-equivalent key produced two entries for one item — which the
+   Axis-1 guard resolves to "apply nothing", leaving the rule stored but inert
+   while the config looked healthy.
+
+Three consecutive confident-but-wrong self-assessments of one function
+(`Config::sanitize()`'s per-user path, now four interacting behaviours). A
+fourth self-review is the least informative option available.
+
+**Before tagging:** run `/code-review ultra 124` or an equivalent independent
+pass, and address what it finds. If the decision is to ship without it, record
+that as a deliberate choice — do not let it read as a satisfied gate.
+
 **21-05 Task 5 (human verification) — NOT PERFORMED AS SPECIFIED.** The plan
 marked it `autonomous: false` and called for a person driving the real editor in
 a browser before the phase closed. That did not happen. The phase was accepted
diff --git a/.planning/phases/26-release-v1.5.0/26-04-PLAN.md b/.planning/phases/26-release-v1.5.0/26-04-PLAN.md
index b3c7c07..4b0b6b8 100644
--- a/.planning/phases/26-release-v1.5.0/26-04-PLAN.md
+++ b/.planning/phases/26-release-v1.5.0/26-04-PLAN.md
@@ -22,6 +22,27 @@ must_haves:
 <objective>
 Cut and ship 1.5.0, then record the milestone.
 
+> ## ⛔ THE TAG IS HELD — 2026-08-09
+>
+> **Gate 8 (independent code review) never ran.** Codex hit its usage limit and
+> posted only a quota notice: zero reviews, zero inline comments. 26-01, 26-02
+> and 26-03 are merged to `main`, and `main` is at version 1.5.0 — but **do not
+> execute Task 3 of this plan until an independent review has actually happened.**
+>
+> This matters more than a missing checkbox. Gate 10 found **two** real defects
+> in code I had already convinced myself was correct, and the second was a hole
+> in my own fix for the first. The lineage on `Config::sanitize()`'s per-user
+> path now reads: round 2 fixed round 1, A3 fixed round 2, A5 fixed A3. Three
+> consecutive confident-but-wrong self-assessments of one function, which now
+> carries four interacting behaviours — reject-on-add, preserve-on-submit,
+> restore-on-omit, merge-on-equivalent-key.
+>
+> A fourth self-review is the least informative thing available. Release only
+> after `/code-review ultra 124` (or an equivalent independent pass) has run and
+> its findings are addressed. If the decision is instead to ship WITHOUT that
+> review, record that as a deliberate choice here and in the milestone entry —
+> do not let it read as though the gate was satisfied.
+
 Purpose: get per-user hiding to users. Everything before this plan is
 preparation; this is the one that delivers.
 Output: a live 1.5.0 on WordPress.org and accurate milestone records.

From cb45c901648e941184aebaa7002112eb33a98632 Mon Sep 17 00:00:00 2001
From: Dan Knauss <273554+dknauss@users.noreply.github.com>
Date: Sun, 9 Aug 2026 18:01:38 -0600
Subject: [PATCH 03/27] test: close the multisite gap, narrow the a11y one
 (#126)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Two gaps carried through the v1.5.0 gates. One is now closed; the other is only
narrowed, and the difference is stated rather than blurred.

MULTISITE — CLOSED. ROLE-02's exemption is `is_multisite() && is_super_admin()`,
so a single-site suite never evaluates the second half and the branch was dead
code as far as coverage went. A WP_MULTISITE=1 lane now runs the whole
integration suite under multisite, wired into CI next to the single-site run —
same containers, one extra suite pass, no second environment.

Three cases assert every half of the rule: a network super admin IS exempt from
the person axis, an ordinary user on the same network is NOT (or the exemption
would silently disable the feature on every multisite install), and the role axis
still applies to super admins — which is what makes the readme's documented
asymmetry true rather than merely claimed.

Writing them immediately caught a bad test of my own: it authored the rule while
acting as the editor, whom the Gate 10 server-side gate correctly refuses, so it
would have asserted against an empty config and "proved" the hide by proving
nothing had been saved. Now authored as an admin with an explicit precondition
that the rule actually landed. That is the second time this release that a real
fix surfaced a test which had been passing for the wrong reason.

ACCESSIBILITY — NARROWED, NOT CLOSED. Added axe-core scanning of the popover in
BOTH empty and populated states; the chips, results list and live-region messages
only exist after interaction, so an empty-state scan would miss most of what this
feature renders. Zero violations across wcag2a/2aa/21a/21aa. Scoped to the
popover deliberately: wp-admin carries its own pre-existing findings, and a suite
that fails on those teaches people to ignore it.

This is still not a screen-reader pass. axe catches machine-detectable
violations; it cannot judge whether announcements make sense in sequence, whether
live-region timing is usable, or whether four similarly-named groups are
distinguishable in practice. Recorded as outstanding so no automated green is
mistaken for having replaced it.

@axe-core/playwright is a devDependency; verified absent from the built ZIP, and
npm audit reports no vulnerabilities.

Gate: unit 167/167, integration 123/123 single-site + 123/123 multisite, JS
83/83, e2e 47 passed / 0 failed, WPCS clean, PHPStan 0 errors, doc-links clean.

Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
---
 .github/workflows/ci.yml                    |   9 ++
 .planning/STATE.md                          |  25 +++++
 TESTING.md                                  |  19 +++-
 package-lock.json                           |  24 +++++
 package.json                                |   2 +
 tests/e2e/specs/person-picker-a11y.spec.ts  |  36 +++++++
 tests/integration/ReplayHiddenUsersTest.php | 100 ++++++++++++++++++++
 7 files changed, 214 insertions(+), 1 deletion(-)

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index ff04905..8d37797 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -182,6 +182,15 @@ jobs:
       - name: Integration tests (PHPUnit in wp-env)
         run: npm run test:php
 
+      # ROLE-02's super-admin exemption is `is_multisite() && is_super_admin()`,
+      # so on a single-site run the second half never evaluates and the whole
+      # branch is uncovered. That gap shipped through the v1.5.0 gates as a known
+      # unknown; this lane closes it. Reuses the same containers — WP_MULTISITE=1
+      # only changes how the PHPUnit bootstrap installs, so it costs one extra
+      # suite run rather than a second environment.
+      - name: Integration tests (multisite)
+        run: npm run test:php:multisite
+
       - name: Install Playwright Chromium
         run: npx playwright install --with-deps chromium
 
diff --git a/.planning/STATE.md b/.planning/STATE.md
index 750b665..af86c30 100644
--- a/.planning/STATE.md
+++ b/.planning/STATE.md
@@ -57,6 +57,31 @@ fourth self-review is the least informative option available.
 pass, and address what it finds. If the decision is to ship without it, record
 that as a deliberate choice — do not let it read as a satisfied gate.
 
+### The two carried gaps — one closed, one only narrowed (2026-08-09)
+
+**✅ Multisite super-admin exemption — CLOSED.** A `WP_MULTISITE=1` lane now runs
+the whole integration suite under multisite (`npm run test:php:multisite`, wired
+into CI beside the single-site run — same containers, one extra suite pass). Three
+new cases assert every half of the rule: a super admin IS exempt from the person
+axis, an ordinary user on the same network is NOT, and the role axis still applies
+to super admins. Writing them immediately caught a bad test of my own — it
+authored the rule as an editor, whom the Gate 10 server-side gate correctly
+refuses, so it would have asserted against an empty config and "proved" the hide
+by proving nothing was saved.
+
+**⚠️ Screen-reader pass — NARROWED, NOT CLOSED.** Added axe-core scanning of the
+popover in both empty and populated states (the chips, results list and live-region
+messages only exist after interaction, so an empty-state scan would miss most of
+what the feature renders). Zero violations against wcag2a/2aa/21a/21aa, scoped to
+the popover so wp-admin's own pre-existing findings don't train people to ignore
+the suite.
+
+**This is still not a screen-reader pass.** axe catches machine-detectable
+violations; it cannot tell you whether the announcements make sense in sequence,
+whether the live-region timing is usable, or whether the four similarly-named
+groups are actually distinguishable in practice. A human with NVDA or VoiceOver
+remains worthwhile, and no automated result should be read as having replaced it.
+
 **21-05 Task 5 (human verification) — NOT PERFORMED AS SPECIFIED.** The plan
 marked it `autonomous: false` and called for a person driving the real editor in
 a browser before the phase closed. That did not happen. The phase was accepted
diff --git a/TESTING.md b/TESTING.md
index 2441468..fae9627 100644
--- a/TESTING.md
+++ b/TESTING.md
@@ -2,7 +2,7 @@
 
 Three layers, smallest and fastest first.
 
-> **Current expected status:** unit 167/167 with 223 assertions, integration 120/120 with 277 assertions, JavaScript unit tests, phpcs, PHPStan, Plugin Check, and the Playwright E2E suite should pass before release. E2E coverage includes reset-this-item, per-role visibility, icon persistence, keyboard reordering, first-run cues, toolbar accessibility checks, (COMPAT-04) independent shared-slug top-level/submenu editing, (COMPAT-10) the "Hide its sub-items from:" role group's independent child-hiding behavior, and (ROLE-02) per-user hiding asserted in a targeted user's own authenticated session — including a same-role bystander who must keep every row, which is the assertion that proves the rule did not widen to the whole role.
+> **Current expected status:** unit 167/167 with 223 assertions, integration 123/123 with 277 assertions single-site + 123/123 with 282 under WP_MULTISITE=1, JavaScript unit tests, phpcs, PHPStan, Plugin Check, and the Playwright E2E suite should pass before release. E2E coverage includes reset-this-item, per-role visibility, icon persistence, keyboard reordering, first-run cues, toolbar accessibility checks, (COMPAT-04) independent shared-slug top-level/submenu editing, (COMPAT-10) the "Hide its sub-items from:" role group's independent child-hiding behavior, and (ROLE-02) per-user hiding asserted in a targeted user's own authenticated session — including a same-role bystander who must keep every row, which is the assertion that proves the rule did not widen to the whole role.
 
 ## Gotchas (first run)
 
@@ -84,6 +84,23 @@ npm run test:php           # runs PHPUnit inside the tests container
 Standalone (no wp-env): install the WP test library with a configured test DB,
 export `WP_TESTS_DIR`, then `composer test:integration`.
 
+### Multisite lane
+
+```bash
+npm run test:php:multisite   # same suite, WP_MULTISITE=1
+```
+
+ROLE-02's super-admin exemption is `is_multisite() && is_super_admin()`, so on a
+single-site run the second half never evaluates and the branch is uncovered —
+which is exactly how it shipped through the v1.5.0 gates as a known unknown. The
+multisite-only cases in
+[`tests/integration/ReplayHiddenUsersTest.php`](tests/integration/ReplayHiddenUsersTest.php)
+assert all three halves of the rule: a network super admin is exempt from the
+person axis, an ordinary user on the same network is **not**, and the role axis
+still applies to super admins (the documented asymmetry). They `markTestSkipped`
+on single-site, and the single-site-only self-target case skips under multisite,
+so both lanes report 123 tests. CI runs both.
+
 ## 3. End-to-end (Playwright, against live WordPress)
 
 Drives the editor in a real browser: edit-mode gating, the admin-bar toggle,
diff --git a/package-lock.json b/package-lock.json
index eb72895..7377198 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -8,11 +8,25 @@
 			"name": "maestro",
 			"version": "1.5.0",
 			"devDependencies": {
+				"@axe-core/playwright": "^4.12.1",
 				"@playwright/test": "^1.62.1",
 				"@wordpress/env": "^11.10.0",
 				"bootstrap-icons": "^1.13.1"
 			}
 		},
+		"node_modules/@axe-core/playwright": {
+			"version": "4.12.1",
+			"resolved": "https://registry.npmjs.org/@axe-core/playwright/-/playwright-4.12.1.tgz",
+			"integrity": "sha512-rMd7xriptqKpP+w5265i4Hdkv2X5kbu6uiBi/B2I7uf3hieRBM3qDCfaKPtxfiYb2mKXfF+yLODJwIx+Jv1GDw==",
+			"dev": true,
+			"license": "MPL-2.0",
+			"dependencies": {
+				"axe-core": "~4.12.1"
+			},
+			"peerDependencies": {
+				"playwright-core": ">= 1.0.0"
+			}
+		},
 		"node_modules/@inquirer/ansi": {
 			"version": "1.0.2",
 			"resolved": "https://registry.npmjs.org/@inquirer/ansi/-/ansi-1.0.2.tgz",
@@ -1787,6 +1801,16 @@
 				"url": "https://github.com/sponsors/ljharb"
 			}
 		},
+		"node_modules/axe-core": {
+			"version": "4.12.1",
+			"resolved": "https://registry.npmjs.org/axe-core/-/axe-core-4.12.1.tgz",
+			"integrity": "sha512-s7iGf5GaVMxEG0ENN9x+xTr7GFZCb1ZP/1uATUpCEK2X78nDB3RwbtFCo9pGAf9ru+VwoQ464DkaLEeRM08wJA==",
+			"dev": true,
+			"license": "MPL-2.0",
+			"engines": {
+				"node": ">=4"
+			}
+		},
 		"node_modules/balanced-match": {
 			"version": "1.0.2",
 			"resolved": "https://registry.npmjs.org/balanced-match/-/balanced-match-1.0.2.tgz",
diff --git a/package.json b/package.json
index bdbbc03..ecd1f69 100644
--- a/package.json
+++ b/package.json
@@ -13,6 +13,7 @@
 		"compat:stop": "cd tests/compat && npx wp-env stop",
 		"env:clean": "wp-env clean all",
 		"test:php": "wp-env run tests-cli --env-cwd=wp-content/plugins/maestro-menu-editor vendor/bin/phpunit -c phpunit-integration.xml.dist",
+		"test:php:multisite": "wp-env run tests-cli --env-cwd=wp-content/plugins/maestro-menu-editor bash -c 'WP_MULTISITE=1 vendor/bin/phpunit -c phpunit-integration.xml.dist'",
 		"pretest:e2e": "wp-env run tests-cli wp plugin activate maestro-menu-editor/maestro-menu-editor.php",
 		"test:e2e": "playwright test",
 		"test:e2e:headed": "playwright test --headed",
@@ -23,6 +24,7 @@
 		"assets:banners": "OUT_DIR=.wordpress-org python3 .wordpress-org/source/build_final.py"
 	},
 	"devDependencies": {
+		"@axe-core/playwright": "^4.12.1",
 		"@playwright/test": "^1.62.1",
 		"@wordpress/env": "^11.10.0",
 		"bootstrap-icons": "^1.13.1"
diff --git a/tests/e2e/specs/person-picker-a11y.spec.ts b/tests/e2e/specs/person-picker-a11y.spec.ts
index ca5da8b..225e000 100644
--- a/tests/e2e/specs/person-picker-a11y.spec.ts
+++ b/tests/e2e/specs/person-picker-a11y.spec.ts
@@ -1,4 +1,5 @@
 import { test, expect } from '../fixtures';
+import AxeBuilder from '@axe-core/playwright';
 import { execFileSync } from 'child_process';
 
 /**
@@ -135,6 +136,41 @@ test.describe( 'ROLE-02 — person picker accessibility', () => {
 		await expect( search ).toBeFocused();
 	} );
 
+	test( 'axe reports no violations on the popover, empty and populated', async ( { page } ) => {
+		const pop = await openPicker( page );
+
+		// Scoped to the popover rather than the whole admin screen: wp-admin has
+		// its own pre-existing findings, and a suite that fails on those teaches
+		// people to ignore it. This asserts what THIS feature added.
+		const empty = await new AxeBuilder( { page } )
+			.include( '.maestro-vis-popover' )
+			.withTags( [ 'wcag2a', 'wcag2aa', 'wcag21a', 'wcag21aa' ] )
+			.analyze();
+		expect(
+			empty.violations.map( ( v ) => `${ v.id }: ${ v.help }` ),
+			'axe violations with the picker empty'
+		).toEqual( [] );
+
+		// Re-scan POPULATED. The chips, the results list and the live-region
+		// messages only exist after interaction, so an empty-state scan would
+		// miss most of what this feature actually renders.
+		const group = pop.locator( '.maestro-vis-own-users' );
+		await group.locator( '.maestro-user-search' ).fill( 'Alex' );
+		const result = group.locator( '.maestro-user-result' ).filter( { hasText: TARGET_NAME } ).first();
+		await expect( result ).toBeVisible( { timeout: 15000 } );
+		await result.click();
+		await expect( group.locator( '.maestro-user-chip' ) ).toContainText( TARGET_NAME );
+
+		const populated = await new AxeBuilder( { page } )
+			.include( '.maestro-vis-popover' )
+			.withTags( [ 'wcag2a', 'wcag2aa', 'wcag21a', 'wcag21aa' ] )
+			.analyze();
+		expect(
+			populated.violations.map( ( v ) => `${ v.id }: ${ v.help }` ),
+			'axe violations with a chip present'
+		).toEqual( [] );
+	} );
+
 	test( 'the popover keeps a working focus trap with the person groups present', async ( { page } ) => {
 		const pop = await openPicker( page );
 
diff --git a/tests/integration/ReplayHiddenUsersTest.php b/tests/integration/ReplayHiddenUsersTest.php
index cdfd4de..3c1c78d 100644
--- a/tests/integration/ReplayHiddenUsersTest.php
+++ b/tests/integration/ReplayHiddenUsersTest.php
@@ -316,6 +316,106 @@ public function test_administrator_can_be_per_user_hidden_on_single_site() {
 		$this->assertNotContains( 'upload.php', $this->top_slugs(), 'Self-targeting must be permitted on single-site.' );
 	}
 
+	/**
+	 * MULTISITE — the exempt branch itself, which single-site runs never reach.
+	 *
+	 * `is_exempt_from_user_axis()` is `is_multisite() && is_super_admin()`, so on
+	 * a single-site suite the second half never evaluates and the whole branch is
+	 * dead code as far as coverage is concerned. This ran unverified through the
+	 * v1.5.0 gates and was carried as a known gap; these three tests close it.
+	 *
+	 * Run with: WP_MULTISITE=1 vendor/bin/phpunit -c phpunit-integration.xml.dist
+	 */
+	public function test_multisite_super_admin_is_exempt_from_the_user_axis() {
+		if ( ! is_multisite() ) {
+			$this->markTestSkipped( 'Multisite-only: the exempt branch requires is_multisite().' );
+		}
+
+		$super = self::factory()->user->create( array( 'role' => 'administrator' ) );
+		grant_super_admin( $super );
+		wp_set_current_user( $super );
+		$this->assertTrue( is_super_admin( $super ), 'precondition: user is a network super admin' );
+
+		( new Config() )->save(
+			array( 'items' => array( 'upload.php' => array( 'hidden_users' => array( $super ) ) ) )
+		);
+
+		$this->run_replay();
+
+		$this->assertContains(
+			'upload.php',
+			$this->top_slugs(),
+			'A network super admin must be exempt from a person-targeted hide.'
+		);
+	}
+
+	/**
+	 * The exemption is for super admins specifically, not for everyone on a
+	 * network. An ordinary site user is hidden under multisite exactly as they
+	 * are under single-site — otherwise the exemption would silently disable the
+	 * whole feature on every multisite install.
+	 */
+	public function test_multisite_ordinary_user_is_still_hidden() {
+		if ( ! is_multisite() ) {
+			$this->markTestSkipped( 'Multisite-only.' );
+		}
+
+		$editor = self::factory()->user->create( array( 'role' => 'editor' ) );
+		$this->assertFalse( is_super_admin( $editor ), 'precondition: not a super admin' );
+
+		// Author AS AN ADMIN. A per-user rule can only be written by someone with
+		// `list_users`, which an editor lacks — saving as the target would be
+		// refused by the server-side gate and this test would then assert against
+		// an empty config, "proving" the hide works by proving nothing was saved.
+		$admin = self::factory()->user->create( array( 'role' => 'administrator' ) );
+		wp_set_current_user( $admin );
+		( new Config() )->save(
+			array( 'items' => array( 'upload.php' => array( 'hidden_users' => array( $editor ) ) ) )
+		);
+		$stored = ( new Config() )->get();
+		$this->assertNotEmpty(
+			$stored['items']['upload.php']['hidden_users'] ?? array(),
+			'precondition: the rule must actually be stored before measuring it'
+		);
+
+		wp_set_current_user( $editor );
+		$this->run_replay();
+
+		$this->assertNotContains(
+			'upload.php',
+			$this->top_slugs(),
+			'Person-targeted hiding must still work for ordinary users on multisite.'
+		);
+	}
+
+	/**
+	 * The documented ASYMMETRY, asserted rather than described: the exemption
+	 * covers the user axis only, so a super admin matched by a ROLE rule is still
+	 * hidden — the shipped v1.4.1 behaviour, unchanged. This is the pairing that
+	 * makes the readme's "role-targeted hides still apply to them" true.
+	 */
+	public function test_multisite_super_admin_is_still_hidden_by_the_role_axis() {
+		if ( ! is_multisite() ) {
+			$this->markTestSkipped( 'Multisite-only.' );
+		}
+
+		$super = self::factory()->user->create( array( 'role' => 'administrator' ) );
+		grant_super_admin( $super );
+		wp_set_current_user( $super );
+
+		( new Config() )->save(
+			array( 'items' => array( 'upload.php' => array( 'hidden_roles' => array( 'administrator' ) ) ) )
+		);
+
+		$this->run_replay();
+
+		$this->assertNotContains(
+			'upload.php',
+			$this->top_slugs(),
+			'The role axis must keep applying to super admins — the exemption is user-axis only.'
+		);
+	}
+
 	/**
 	 * The role axis keeps its shipped v1.4.1 behaviour: the exemption ruled on
 	 * 2026-08-08 covers the NEW user axis only. An administrator matched by a

From 707d9b67b7e9e04f72e89c5a3d9962af440d4462 Mon Sep 17 00:00:00 2001
From: Dan Knauss <273554+dknauss@users.noreply.github.com>
Date: Sun, 9 Aug 2026 19:39:07 -0600
Subject: [PATCH 04/27] =?UTF-8?q?fix:=20address=20ultrareview=20findings?=
 =?UTF-8?q?=20=E2=80=94=20collapse=20the=20per-user=20authorization=20path?=
 =?UTF-8?q?=20(#128)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* fix: address ultrareview findings — collapse the per-user authorization path

The review found the invariant my own PR description asked reviewers to hunt
for ("the saver can neither add nor destroy") was false on two more paths. Both
confirmed by test before fixing.

PATH A — MAX_ITEMS starvation, and silent. The restore admitted only on
`count($out['items']) < MAX_ITEMS`, so a crafted payload of 200 title-only junk
entries filled every slot and left the protected rules nowhere to land. One POST
from a saver with no authority to write per-user rules destroyed all of them,
with no UI involved.

PATH B — the DELETE endpoint bypassed the gate entirely. Rest::reset_config() is
gated on capability(), not list_users, and Config::reset() wiped
unconditionally. Every sanitize-side round lived on the POST path. A boundary
enforced on save but not on reset is not a boundary.

RATHER THAN PATCH, COLLAPSED. Preserve-on-submit, restore-on-omit and
merge-on-equivalent-key were three mechanisms doing one job, each added to cover
a path the previous missed — which is precisely why a fourth path still got
through. They are now ONE map, keyed by normalized slug, built before the
payload loop by protected_user_axes(), with item-cap capacity RESERVED for it.
Starvation is impossible by construction rather than by another guard, and the
stored total stays bounded by MAX_ITEMS exactly as before: abusive filler is
what gets dropped, never an administrator's rules.

Config::reset() uses the same map, so "Reset All" means "reset everything you
can affect". An admin is unaffected — they hold list_users, the map is empty,
and it stays the plain wipe it always was. Asserted both ways.

Also two nits from the review, both real:

resetItem() had drifted behind resetSelected() — four fields against six. No
production consumer, but its docblock claims to mirror it. The round-trip test
passed VACUOUSLY because diffItem() short-circuits on absent keys, so the test
could never have caught the drift; it now seeds all four axes and asserts the
returned SHAPE, which is what actually pins the claim.

Group 1's setSet cleared .maestro-has-hidden on hiddenRoles alone, so unchecking
the last role while a person rule remained made the row look untouched until
reload. Now matches initModel() and the user group.

Gate: unit 167/167 (223), integration 126/126 single-site (285) + 126/126
multisite (290), JS 83/83, e2e 47 passed/0 failed, WPCS clean, PHPStan 0.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

* docs(testing): correct multisite lane counts after the ultrareview fixes

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
---
 TESTING.md                                    |   4 +-
 assets/maestro-logic.js                       |  18 +-
 assets/maestro.js                             |  10 +-
 includes/class-config.php                     | 192 +++++++++++-------
 .../PerUserAxisAuthorizationTest.php          |  65 ++++++
 tests/js/reset-item.test.mjs                  |  23 ++-
 6 files changed, 230 insertions(+), 82 deletions(-)

diff --git a/TESTING.md b/TESTING.md
index fae9627..02542eb 100644
--- a/TESTING.md
+++ b/TESTING.md
@@ -2,7 +2,7 @@
 
 Three layers, smallest and fastest first.
 
-> **Current expected status:** unit 167/167 with 223 assertions, integration 123/123 with 277 assertions single-site + 123/123 with 282 under WP_MULTISITE=1, JavaScript unit tests, phpcs, PHPStan, Plugin Check, and the Playwright E2E suite should pass before release. E2E coverage includes reset-this-item, per-role visibility, icon persistence, keyboard reordering, first-run cues, toolbar accessibility checks, (COMPAT-04) independent shared-slug top-level/submenu editing, (COMPAT-10) the "Hide its sub-items from:" role group's independent child-hiding behavior, and (ROLE-02) per-user hiding asserted in a targeted user's own authenticated session — including a same-role bystander who must keep every row, which is the assertion that proves the rule did not widen to the whole role.
+> **Current expected status:** unit 167/167 with 223 assertions, integration 126/126 with 285 assertions single-site + 126/126 with 290 under WP_MULTISITE=1, JavaScript unit tests, phpcs, PHPStan, Plugin Check, and the Playwright E2E suite should pass before release. E2E coverage includes reset-this-item, per-role visibility, icon persistence, keyboard reordering, first-run cues, toolbar accessibility checks, (COMPAT-04) independent shared-slug top-level/submenu editing, (COMPAT-10) the "Hide its sub-items from:" role group's independent child-hiding behavior, and (ROLE-02) per-user hiding asserted in a targeted user's own authenticated session — including a same-role bystander who must keep every row, which is the assertion that proves the rule did not widen to the whole role.
 
 ## Gotchas (first run)
 
@@ -99,7 +99,7 @@ assert all three halves of the rule: a network super admin is exempt from the
 person axis, an ordinary user on the same network is **not**, and the role axis
 still applies to super admins (the documented asymmetry). They `markTestSkipped`
 on single-site, and the single-site-only self-target case skips under multisite,
-so both lanes report 123 tests. CI runs both.
+so both lanes report 126 tests. CI runs both.
 
 ## 3. End-to-end (Playwright, against live WordPress)
 
diff --git a/assets/maestro-logic.js b/assets/maestro-logic.js
index 9f96529..f56a01d 100644
--- a/assets/maestro-logic.js
+++ b/assets/maestro-logic.js
@@ -133,15 +133,23 @@ function modeStatusLabel( state, strings ) {
  *   m.hiddenRoles      = [];
  *   if ( ! m.isSub ) m.icon = def.icon || '';
  *   m.childHiddenRoles = [];
+ *   m.hiddenUsers      = [];
+ *   m.childHiddenUsers = [];
  *
- * childHiddenRoles (COMPAT-10 REVISED) has no WP-native pristine state —
- * reset always clears it to [], top-level or submenu (the field is simply
+ * None of the four visibility axes has a WP-native pristine state — reset
+ * always clears them to [], top-level or submenu (the child_* fields are simply
  * unused for submenu items).
  *
- * @param {{ title: string, icon?: string, hiddenRoles: string[], childHiddenRoles?: string[] }} item     Current item state.
+ * KEEP THIS IN STEP WITH resetSelected(). The docblock above claims to mirror
+ * it, and that claim is the only thing making this the readable spec for the
+ * operation — production resets inline, so nothing here fails when the two
+ * drift. The round-trip test does not catch it either: diffItem() short-circuits
+ * on ABSENT keys, so a reset result missing an axis passes vacuously.
+ *
+ * @param {{ title: string, icon?: string, hiddenRoles: string[], childHiddenRoles?: string[], hiddenUsers?: object[], childHiddenUsers?: object[] }} item     Current item state.
  * @param {{ title: string, icon?: string }}                        pristine Pristine default.
  * @param {boolean}                                                 isSub    True for submenu items.
- * @return {{ title: string, hiddenRoles: string[], icon: string, childHiddenRoles: string[] }}
+ * @return {{ title: string, hiddenRoles: string[], icon: string, childHiddenRoles: string[], hiddenUsers: object[], childHiddenUsers: object[] }}
  */
 function resetItem( item, pristine, isSub ) {
 	var result = {
@@ -149,6 +157,8 @@ function resetItem( item, pristine, isSub ) {
 		hiddenRoles:      [],
 		icon:             isSub ? '' : ( pristine.icon || '' ),
 		childHiddenRoles: [],
+		hiddenUsers:      [],
+		childHiddenUsers: [],
 	};
 	return result;
 }
diff --git a/assets/maestro.js b/assets/maestro.js
index a3210cd..47c7944 100644
--- a/assets/maestro.js
+++ b/assets/maestro.js
@@ -1122,7 +1122,15 @@
 				model[ slug ].hiddenRoles = arr;
 				var li = liForKey( slug );
 				if ( li ) {
-					li.classList.toggle( 'maestro-has-hidden', model[ slug ].hiddenRoles.length > 0 );
+					// The marker means "this row has a hide rule of its own", which
+					// is EITHER axis. Testing hiddenRoles alone would clear it when
+					// the last role is unchecked while a person rule is still in
+					// force — the row would look untouched until a reload rebuilt
+					// it. Matches initModel() and the user group's own setSet.
+					li.classList.toggle(
+						'maestro-has-hidden',
+						model[ slug ].hiddenRoles.length > 0 || ( model[ slug ].hiddenUsers || [] ).length > 0
+					);
 				}
 			},
 			{
diff --git a/includes/class-config.php b/includes/class-config.php
index 5a944ac..7d8e7b4 100644
--- a/includes/class-config.php
+++ b/includes/class-config.php
@@ -222,10 +222,91 @@ public function save( array $raw ) {
 	 * @return void
 	 */
 	public function reset() {
+		// ROLE-02 — "Reset All" is still gated only by capability(), so a
+		// delegated editor without `list_users` can reach it. Wiping wholesale
+		// would let them destroy per-user rules they are not permitted to write,
+		// which is the same authorization boundary sanitize() enforces on save —
+		// and a boundary that holds on one endpoint and not the other is not a
+		// boundary. Reset All therefore means "reset everything you can affect".
+		//
+		// An administrator is unaffected: they hold `list_users`, so $protected is
+		// empty and this is the plain wipe it has always been.
+		$protected = current_user_can( 'list_users' )
+			? array()
+			: $this->protected_user_axes( function_exists( 'admin_url' ) ? admin_url( '' ) : '' );
+
+		if ( $protected ) {
+			$items = array();
+			foreach ( $protected as $entry ) {
+				$items[ $entry['slug'] ] = $entry['axes'];
+			}
+			update_option(
+				MAESTRO_OPTION,
+				array(
+					'schema_version' => self::SCHEMA_VERSION,
+					'items'          => $items,
+					'top_order'      => array(),
+					'sub_order'      => array(),
+				),
+				false
+			);
+			$this->cache = null;
+			return;
+		}
+
 		delete_option( MAESTRO_OPTION );
 		$this->cache = array();
 	}
 
+	/**
+	 * Stored per-user axes the CURRENT user has no authority to write, indexed by
+	 * normalized slug. (ROLE-02)
+	 *
+	 * Returns `[ normalized_key => [ 'slug' => stored_slug, 'axes' => [...] ] ]`,
+	 * carrying the original slug so a restored entry lands under the key it was
+	 * stored with rather than a canonicalised one.
+	 *
+	 * Indexed by NORMALIZED key on purpose: a payload may name the same item in
+	 * an equivalent-but-different form (`upload.php?ver=9` for a rule stored as
+	 * `upload.php`), which is the expected state after a plugin bumps a cache
+	 * buster — slug drift is precisely what Slug::normalize() exists for. Keying
+	 * raw would let both spellings survive into storage, and two keys normalizing
+	 * to one item are ambiguous, which the Axis-1 guard resolves to "apply
+	 * nothing": the rule would be present but inert while the config looked fine.
+	 *
+	 * @param string $base Admin base for Slug::normalize_qualified().
+	 * @return array<string, array{slug: string, axes: array}>
+	 */
+	private function protected_user_axes( $base ) {
+		$existing = $this->get();
+		$items    = isset( $existing['items'] ) ? $existing['items'] : array();
+		$out      = array();
+
+		foreach ( $items as $slug => $entry ) {
+			$axes = array();
+			if ( ! empty( $entry['hidden_users'] ) ) {
+				$axes['hidden_users'] = $entry['hidden_users'];
+			}
+			if ( ! empty( $entry['child_hidden_users'] ) ) {
+				$axes['child_hidden_users'] = $entry['child_hidden_users'];
+			}
+			if ( ! $axes ) {
+				continue;
+			}
+
+			$nk = Slug::normalize_qualified( (string) $slug, $base );
+			if ( '' === $nk || isset( $out[ $nk ] ) ) {
+				continue; // Unresolvable or already claimed by an earlier key.
+			}
+			$out[ $nk ] = array(
+				'slug' => $slug,
+				'axes' => $axes,
+			);
+		}
+
+		return $out;
+	}
+
 	/**
 	 * Whether the STORED config predates qualified submenu keys.
 	 *
@@ -294,12 +375,17 @@ public function sanitize( array $raw ) {
 		// autosave is full-replace, so silently dropping the axes would let any
 		// unrelated edit wipe an administrator's per-user rules. Stored values
 		// are preserved verbatim instead — the saver can neither add nor destroy.
+		//
+		// The protection is ONE mechanism, deliberately. It was three (preserve
+		// the submitted item, restore the omitted one, merge an equivalent key)
+		// and each was added to patch a path the previous one missed — which is
+		// exactly why a fourth path (starving the item cap with junk entries)
+		// still got through. A single map, keyed by NORMALIZED slug and given
+		// reserved capacity below, has no seams for the next path to slip
+		// between.
+		$base             = function_exists( 'admin_url' ) ? admin_url( '' ) : '';
 		$can_target_users = current_user_can( 'list_users' );
-		$stored_items     = array();
-		if ( ! $can_target_users ) {
-			$existing     = $this->get();
-			$stored_items = isset( $existing['items'] ) ? $existing['items'] : array();
-		}
+		$protected        = $can_target_users ? array() : $this->protected_user_axes( $base );
 
 		// Validate the incoming IDs with ONE bounded query rather than loading
 		// every user ID on the site. The payload caps each axis at
@@ -310,6 +396,15 @@ public function sanitize( array $raw ) {
 			? $this->valid_user_ids( self::candidate_user_ids( $raw ) )
 			: array();
 
+		// RESERVE capacity for the protected rules before the payload loop runs.
+		// Without this, a payload of MAX_ITEMS junk entries fills every slot and
+		// the protected rules have nowhere to land — silent destruction by a
+		// saver with no authority to write them, achieved with a single crafted
+		// POST. Reserving keeps the stored total bounded by MAX_ITEMS exactly as
+		// before, and simply means abusive filler is what gets dropped rather
+		// than an administrator's rules.
+		$item_budget = self::MAX_ITEMS - count( $protected );
+
 		if ( ! empty( $raw['items'] ) && is_array( $raw['items'] ) ) {
 			foreach ( $raw['items'] as $slug => $item ) {
 				// Qualified `parent>child` submenu keys: clean each half
@@ -382,14 +477,18 @@ public function sanitize( array $raw ) {
 				// scopes (bare top-level and qualified submenu), exactly as
 				// hidden_roles is — only the child_* axis below is parent-only.
 				if ( ! $can_target_users ) {
-					// Saver cannot target users: carry any stored axes through
-					// untouched so an unrelated edit cannot destroy them, and
-					// ignore whatever the payload claims.
-					if ( ! empty( $stored_items[ $slug ]['hidden_users'] ) ) {
-						$entry['hidden_users'] = $stored_items[ $slug ]['hidden_users'];
-					}
-					if ( ! $is_qualified && ! empty( $stored_items[ $slug ]['child_hidden_users'] ) ) {
-						$entry['child_hidden_users'] = $stored_items[ $slug ]['child_hidden_users'];
+					// Saver cannot target users: attach whatever was stored for
+					// this item and ignore what the payload claims. Matched on the
+					// NORMALIZED key so an equivalent spelling of the same slug
+					// (`upload.php?ver=9` vs `upload.php`) lands here rather than
+					// producing a second entry later — two keys normalizing to one
+					// item are ambiguous, and the Axis-1 guard resolves ambiguity
+					// to "apply nothing", which would leave the rule stored but
+					// inert while the config still looked healthy.
+					$nk = Slug::normalize_qualified( (string) $slug, $base );
+					if ( '' !== $nk && isset( $protected[ $nk ] ) ) {
+						$entry = array_merge( $entry, $protected[ $nk ]['axes'] );
+						unset( $protected[ $nk ] ); // Claimed; do not re-add below.
 					}
 				} else {
 					if ( ! empty( $item['hidden_users'] ) && is_array( $item['hidden_users'] ) ) {
@@ -412,73 +511,18 @@ public function sanitize( array $raw ) {
 
 				if ( $entry ) {
 					$out['items'][ $slug ] = $entry;
-					if ( count( $out['items'] ) >= self::MAX_ITEMS ) {
+					if ( count( $out['items'] ) >= $item_budget ) {
 						break; // Deterministic: first N slugs in incoming object order win.
 					}
 				}
 			}
 		}
 
-		// ROLE-02 — restore per-user axes the saver was not allowed to touch.
-		//
-		// The per-item preserve above only fires for items PRESENT in the
-		// payload, which is not enough. get_menu_model() withholds the user axes
-		// from a saver without `list_users`, so diffItem() never flags them
-		// client-side, so an item whose ONLY override is a per-user rule is
-		// omitted from that saver's full-replace autosave entirely — and a rule
-		// omitted from a full replace is a rule deleted. That made any edit by a
-		// delegated editor silently wipe every per-user rule they could not see:
-		// ordinary data loss, not an exotic hand-crafted POST.
-		//
-		// So the restore runs over the STORED items, not the submitted ones.
-		if ( ! $can_target_users ) {
-			// Index what we are about to write by NORMALIZED key. Matching on the
-			// raw key is not enough: the payload may name the same item in a
-			// different-but-equivalent form (`upload.php?ver=9` for a rule stored
-			// under `upload.php`), which is not contrived — slug drift is the
-			// exact problem Slug::normalize() exists to solve, so it is the
-			// expected state after a plugin update. Re-attaching under the stored
-			// key would then leave TWO keys normalizing to the same item, which
-			// the Axis-1 collision guard resolves to "apply nothing" — silently
-			// neutralising both the preserved rule and the saver's own edit while
-			// the stored config still looks healthy.
-			$base     = function_exists( 'admin_url' ) ? admin_url( '' ) : '';
-			$norm_out = array();
-			foreach ( array_keys( $out['items'] ) as $written_key ) {
-				$nk = Slug::normalize_qualified( (string) $written_key, $base );
-				if ( '' !== $nk && ! isset( $norm_out[ $nk ] ) ) {
-					$norm_out[ $nk ] = $written_key;
-				}
-			}
-
-			foreach ( $stored_items as $stored_slug => $stored_entry ) {
-				$keep = array();
-				if ( ! empty( $stored_entry['hidden_users'] ) ) {
-					$keep['hidden_users'] = $stored_entry['hidden_users'];
-				}
-				if ( ! empty( $stored_entry['child_hidden_users'] ) ) {
-					$keep['child_hidden_users'] = $stored_entry['child_hidden_users'];
-				}
-				if ( ! $keep ) {
-					continue;
-				}
-
-				$nk = Slug::normalize_qualified( (string) $stored_slug, $base );
-
-				if ( '' !== $nk && isset( $norm_out[ $nk ] ) ) {
-					// Same item under either spelling — merge into the key that is
-					// actually being written, never add a second one.
-					$target                  = $norm_out[ $nk ];
-					$out['items'][ $target ] = array_merge( $out['items'][ $target ], $keep );
-				} elseif ( count( $out['items'] ) < self::MAX_ITEMS ) {
-					// Nothing equivalent is being written; the item exists only to
-					// hold the rule, so re-create it rather than let it vanish.
-					$out['items'][ $stored_slug ] = $keep;
-					if ( '' !== $nk ) {
-						$norm_out[ $nk ] = $stored_slug;
-					}
-				}
-			}
+		// Anything still unclaimed names an item the payload never mentioned (in
+		// any spelling). Its entry exists only to hold the rule, so re-create it.
+		// The budget reserved above guarantees room.
+		foreach ( $protected as $unclaimed ) {
+			$out['items'][ $unclaimed['slug'] ] = $unclaimed['axes'];
 		}
 
 		if ( ! empty( $raw['top_order'] ) && is_array( $raw['top_order'] ) ) {
diff --git a/tests/integration/PerUserAxisAuthorizationTest.php b/tests/integration/PerUserAxisAuthorizationTest.php
index 85f96b1..2b6db8c 100644
--- a/tests/integration/PerUserAxisAuthorizationTest.php
+++ b/tests/integration/PerUserAxisAuthorizationTest.php
@@ -153,6 +153,71 @@ public function test_delegate_save_with_a_normalizing_equivalent_key() {
 		);
 	}
 
+	/**
+	 * A6: MAX_ITEMS starvation. A crafted payload of MAX_ITEMS title-only junk
+	 * entries used to fill every slot, leaving the restore nowhere to land — so
+	 * a single POST from a saver with no authority to write per-user rules
+	 * silently destroyed all of them. Capacity is now reserved BEFORE the payload
+	 * loop, so filler is what gets dropped, never an admin's rules.
+	 */
+	public function test_delegate_cannot_starve_the_item_cap_to_destroy_rules() {
+		$this->seed_admin_rule();
+		wp_set_current_user( $this->delegate );
+
+		$junk = array();
+		for ( $i = 1; $i <= Config::MAX_ITEMS; $i++ ) {
+			$junk[ "junk-$i.php" ] = array( 'title' => 'x' );
+		}
+
+		( new Config() )->save( array( 'items' => $junk ) );
+
+		$cfg = ( new Config() )->get();
+		$this->assertSame(
+			array( $this->victim ),
+			$cfg['items']['upload.php']['hidden_users'] ?? null,
+			'A6: a full-cap junk payload must not be able to evict a protected rule'
+		);
+		$this->assertLessThanOrEqual(
+			Config::MAX_ITEMS,
+			count( $cfg['items'] ),
+			'A6: reserving capacity must not push the stored config past MAX_ITEMS'
+		);
+	}
+
+	/**
+	 * A7: the DELETE endpoint. "Reset All" is gated only on capability(), so a
+	 * delegate can reach it — and an unconditional wipe would destroy per-user
+	 * rules they cannot write. A boundary enforced on save but not on reset is
+	 * not a boundary. Reset All now means "reset everything you can affect".
+	 */
+	public function test_delegate_reset_all_cannot_destroy_protected_rules() {
+		$this->seed_admin_rule();
+		wp_set_current_user( $this->delegate );
+
+		( new Config() )->reset();
+
+		$cfg = ( new Config() )->get();
+		$this->assertSame(
+			array( $this->victim ),
+			$cfg['items']['upload.php']['hidden_users'] ?? null,
+			'A7: a delegate resetting must not destroy rules they cannot author'
+		);
+	}
+
+	/**
+	 * …but an ADMIN's Reset All is still a full wipe. The preservation is an
+	 * authorization boundary, not a new "sticky rules" behaviour — if it applied
+	 * to admins too, Reset All would stop meaning what it says.
+	 */
+	public function test_admin_reset_all_still_wipes_everything() {
+		$this->seed_admin_rule();
+		wp_set_current_user( $this->admin );
+
+		( new Config() )->reset();
+
+		$this->assertSame( array(), ( new Config() )->get(), 'A7b: an admin reset must still clear everything' );
+	}
+
 	/** A4: does the model leak display names to a delegate? Expected: no. */
 	public function test_model_does_not_leak_display_names_to_delegate() {
 		$this->seed_admin_rule();
diff --git a/tests/js/reset-item.test.mjs b/tests/js/reset-item.test.mjs
index 5748f95..12ab52e 100644
--- a/tests/js/reset-item.test.mjs
+++ b/tests/js/reset-item.test.mjs
@@ -63,13 +63,34 @@ test( 'resetItem does not mutate the input item', () => {
 } );
 
 // Round-trip invariant: diffItem(resetItem(item), pristine) === modified:false
+//
+// The seed carries ALL FOUR visibility axes deliberately. diffItem() checks
+// `current.<axis> && current.<axis>.length > 0`, so an axis MISSING from the
+// reset result short-circuits to false and the round-trip passes vacuously —
+// which is exactly how resetItem() silently drifted behind resetSelected() when
+// the user axes were added. Seeding every axis makes the round-trip able to
+// fail if a future axis is added here and forgotten there.
 test( 'round-trip: top-level item after reset is not modified per diffItem', () => {
-	const item     = { title: 'My Posts', icon: 'dashicons-admin-home', hiddenRoles: [ 'editor' ] };
+	const item     = {
+		title:            'My Posts',
+		icon:             'dashicons-admin-home',
+		hiddenRoles:      [ 'editor' ],
+		childHiddenRoles: [ 'author' ],
+		hiddenUsers:      [ { id: 4, name: 'Ada' } ],
+		childHiddenUsers: [ { id: 9, name: 'Grace' } ],
+	};
 	const pristine = { title: 'Posts', icon: 'dashicons-admin-post' };
 	const reset    = resetItem( item, pristine, false );
 	const diff     = diffItem( reset, pristine );
 	assert.equal( diff.modified, false );
 	assert.deepEqual( diff.fields, [] );
+
+	// Assert the SHAPE too, not just the diff verdict: the diff would stay clean
+	// if an axis were dropped entirely, so shape is what actually pins the
+	// mirror-of-resetSelected claim in the docblock.
+	assert.deepEqual( Object.keys( reset ).sort(), [
+		'childHiddenRoles', 'childHiddenUsers', 'hiddenRoles', 'hiddenUsers', 'icon', 'title',
+	] );
 } );
 
 test( 'round-trip: submenu item after reset is not modified per diffItem', () => {

From 694b1bf748df0e91b8746b7289c87721ed0b6b78 Mon Sep 17 00:00:00 2001
From: Dan Knauss <273554+dknauss@users.noreply.github.com>
Date: Sun, 9 Aug 2026 19:48:35 -0600
Subject: [PATCH 05/27] =?UTF-8?q?docs(planning):=20clear=20the=20v1.5.0=20?=
 =?UTF-8?q?tag=20hold=20=E2=80=94=20Gate=208=20satisfied=20(#129)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The ultrareview ran against #127 and returned three real findings, all fixed in
#128 (707d9b6). It caught the two paths I had missed on the exact invariant the
review request asked it to attack: MAX_ITEMS starvation (silent, one crafted
POST destroyed every protected rule) and the DELETE endpoint bypassing the gate
entirely.

Records the outcome rather than just flipping a flag: four consecutive holes in
one function, every one found by review rather than by me, and after each fix I
believed the path was settled. Also carries forward the caveats that survive —
the #128 fixes are themselves unreviewed, there has been no human screen-reader
pass, and 21-05's browser verification never happened.

Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
---
 .planning/STATE.md                            | 54 +++++++++++--------
 .../phases/26-release-v1.5.0/26-04-PLAN.md    | 28 ++++------
 2 files changed, 44 insertions(+), 38 deletions(-)

diff --git a/.planning/STATE.md b/.planning/STATE.md
index af86c30..c855902 100644
--- a/.planning/STATE.md
+++ b/.planning/STATE.md
@@ -3,7 +3,7 @@ gsd_state_version: 1.0
 milestone: v1.5
 milestone_name: Per-User Visibility
 status: in-progress
-stopped_at: "v1.5.0 prepared on main (26-01/02/03 merged) — TAG HELD: Gate 8 independent review never ran (Codex quota exhausted)"
+stopped_at: "v1.5.0 hold cleared — Gate 8 satisfied via ultrareview (3 findings, fixed in #128); ready to tag"
 last_updated: "2026-08-09T00:00:00.000Z"
 last_activity: "2026-08-08 — **Phase 21 (ROLE-02 per-user hiding) executed, 5/5 plans, awaiting the human-verify checkpoint.** Branch `phase/21-cosmetic-per-user-hiding`, PR #120, nothing merged. Delivered: `hidden_users` / `child_hidden_users` storage; the `is_hidden_for_current_user()` seam widened to independent OR'd terms (3rd term reserved for the deferred `hidden_profiles`); `resolved_hidden_roles()` GENERALIZED to a field-parameterized resolver rather than duplicated, so the user axis inherits the qualified-key, schema-v2 (#115) and Axis-1 guards from one implementation; a shared `Cascade` union; the §6 cosmetic-invariant guardrail made enforcing; editor model exposure as id+name pairs via one batched query; four-group visibility popover with an async person picker on core's `wp/v2/users`. Gate: unit 165/165 (218), integration 109/109 (257), JS 83/83, e2e 39 passed/28 capture-skipped/0 failed, WPCS clean, PHPStan 0, Plugin Check 0 errors on the ZIP (1 pre-existing readme warning). THREE bugs found by verification that no unit test would have caught: (1) the guardrail initially could NOT detect a broken seam — `current_user_can()` answers from a cached allcaps array, so `snapshot_caps()` now drops `$GLOBALS['current_user']` to force re-derivation; (2) the picker URL appended `?` unconditionally, 404ing on every PLAIN-PERMALINK site since `rest_url()` already carries a query string; (3) clicking a search result or chip closed the whole popover, because re-rendering detached the node before `placePopover()`'s outside-click handler ran. Ruling recorded 2026-08-08: the super-admin exemption covers the NEW user axis only, multisite-scoped (unscoped would make administrators un-hideable on single-site and contradict the locked self-target decision). Prior: 2026-08-05 — **v1.4.1 SHIPPED** (PR #116, tag on c6cdcbe; wp.org API confirms 1.4.1). Patch for the shared-slug propagation defect (#115): a bare top-level key no longer applies to a submenu row whose slug names a rendered top-level item. Two Codex P2 rounds on #115 — the first cut of the gate tested `$nk === $norm_parent` and missed submenus parked under an unrelated parent; widened to `isset( $top_rendered_matches[ $nk ] )`. Prior: 2026-08-04 — **v1.4.0 SHIPPED** (PR #113, tag on 482510c, GitHub Release + wp.org SVN trunk/tags/1.4.0/assets confirmed). Phase 24 release gates 8–11 run consolidated over the full v1.3.1..main diff; one defect found and fixed (multibyte truncation blanked labels) and one changelog overclaim corrected (shared-slug isolation is submenu-direction only). ROLE-02 (Phase 21) deferred to v1.5."
 progress:
@@ -31,31 +31,43 @@ Plan: Phase 21 delivered ROLE-02's **per-user half**: 21-01 storage → 21-02 se
 Status: Phase 20's COMPAT-10 was reworked mid-checkpoint 2026-08-02: the boolean `cascade_hide` + "rides the parent hide" model built in 20-05/20-06 was found **inert** — WordPress core's `_wp_menu_output()` never renders a hidden parent's `<ul class="wp-submenu">` at all, so hiding the parent already removes the whole subtree cosmetically; cascading on top of that produced no observable difference. Reworked (20-CONTEXT.md REVISION NOTE) into an **independent** per-parent `child_hidden_roles` role set: `Maestro\Cascade::effective_hidden_roles( $child_hidden_roles, $parent_child_hidden_roles )` is now a plain, unconditional role-list union (no flag). `Config::sanitize()` accepts `child_hidden_roles` on a top-level item with the same contract as `hidden_roles` (role-intersect, `MAX_HIDDEN_ROLES` cap, dropped on a qualified submenu key). `Replay::replay()`'s submenu loop unions each child's own `hidden_roles` with its parent's `child_hidden_roles`, fully independent of whether the parent's own `hidden_roles` currently hides the parent row — so a parent can stay visible while its children vanish, a genuinely observable effect the old model could never produce. `get_menu_model()` exposes `childHiddenRoles` (empty array, not merely absent, for an untouched parent). The editor popover now shows TWO independent role-checkbox groups — "Hide this item from:" (existing) and "Hide its sub-items from:" (new, shown only on parents with children) — via a shared `buildRoleGroup()` helper in `assets/maestro.js`. The e2e spec (`cascade-hide.spec.ts`) now asserts the effect DIRECTLY against the rendered sidebar (parent visible, child rows gone, role-mirrored) via a second authenticated browser context, replacing the inert model's wp-cli/`$submenu` dump workaround (`dump-cascade-submenu.php`, deleted). Cosmetic-only guardrail reconfirmed end-to-end. **Full zero-regression gate (final):** PHP unit 127/127 (158 assertions), PHP integration 72/72 (172 assertions), JS 58/58, e2e 35 passed/28 capture-gated skipped/0 failed, WPCS clean, PHPStan 0 errors, Plugin Check 0 errors on the built shippable ZIP (1 pre-existing readme.txt warning) and 0 NEW errors on the dev-tree (7 errors/7 warnings, all pre-existing, confirmed via `git log --diff-filter=A` to predate Phase 20). All three Phase 20 requirements (COMPAT-04/07/10) genuinely complete. 20-04 (prior) delivered COMPAT-07 badge/HTML preservation on rename via `Maestro\Title::replace_label()`'s text-node swap at both title-write seams. 20-03 (prior) closed out COMPAT-04 client-side with the qualified-key DOM-join and live WooCommerce verification. 20-02/20-01 (prior) built COMPAT-04's server-side qualified-key foundation and replay/editor-model wiring. Phase 19 ROLE-01 signed off — **partial-go** (per-user go + ship first; cloned-role go as an additive `profiles` registry compiling to the same inline `is_hidden_for_current_user()` seam); Phase 21 unblocked. Phase 23 delivered UX-09/UX-12/UX-13/BUG-08 (native wp-admin restyle; 5/5 plans; full-suite gate green) and shipped in v1.3.1. **NOTE for Phase 24:** Plugin Check flags 7 errors/7 warnings against pre-existing dev-tree root files — logged to `phases/23-editor-ux-polish/deferred-items.md` for the Phase 24 build-then-check pipeline.
 Last activity: 2026-08-09 — Phase 21 merged to `main` (PR #120, merge commit). Two Codex review rounds landed first: round 1 caught a self-target undo trap, the `list_users` gap, and an unenforced 50-user cap; round 2 caught that the `list_users` fix was **client-side only** (an editor could POST guessed IDs and read display names back from the model), plus an unbounded all-users query on every save. Both rounds fixed and CI-green. Codex has NOT reviewed the round-2 fixes themselves.
 
-## ⛔ v1.5.0 IS PREPARED BUT NOT TAGGED (2026-08-09)
+## ✅ THE TAG HOLD IS CLEARED (2026-08-09)
 
-`main` reads version 1.5.0 with the changelog, screenshots and gate work merged
-(PRs #122, #123, #124). **The tag is deliberately held**: Gate 8, the independent
-code review, never ran — Codex hit its usage limit and posted a quota notice
-with zero reviews and zero comments.
+Gate 8 ran. `/code-review ultra` against PR #127 (a review-only PR based on the
+`v1.4.1` tag, so the diff was the whole release) returned **three findings, all
+real**, fixed in #128 and merged as `707d9b6`.
 
-The hold is not procedural tidiness. Gate 10 found **two** real defects in code
-that had already passed my own review, and the second was a hole in my fix for
-the first:
+**It found the two paths I had missed**, on the exact invariant the review
+request asked it to attack:
 
-1. A delegated editor's ordinary autosave silently destroyed per-user rules they
-   could not see (payload-scoped preserve was never sufficient).
-2. The fix for that re-attached under the raw stored key, so a
-   normalizing-equivalent key produced two entries for one item — which the
-   Axis-1 guard resolves to "apply nothing", leaving the rule stored but inert
-   while the config looked healthy.
+1. **MAX_ITEMS starvation** — silent. A payload of 200 title-only junk entries
+   filled every slot, so the restore had nowhere to land and every protected
+   per-user rule died to one crafted POST.
+2. **The DELETE endpoint** bypassed the gate entirely — every sanitize-side fix
+   round lived on the POST path, while `Config::reset()` wiped unconditionally.
 
-Three consecutive confident-but-wrong self-assessments of one function
-(`Config::sanitize()`'s per-user path, now four interacting behaviours). A
-fourth self-review is the least informative option available.
+Plus two nits, both genuine: `resetItem()` had drifted behind `resetSelected()`
+(and its round-trip test was passing *vacuously*, so it could never have caught
+that), and the `.maestro-has-hidden` marker cleared on the wrong condition.
 
-**Before tagging:** run `/code-review ultra 124` or an equivalent independent
-pass, and address what it finds. If the decision is to ship without it, record
-that as a deliberate choice — do not let it read as a satisfied gate.
+**The fix collapsed rather than patched.** Preserve-on-submit, restore-on-omit
+and merge-on-equivalent-key were three mechanisms doing one job — which is
+precisely why a fourth path kept getting through. They are now one normalized-key
+map with reserved item-cap capacity, so starvation is impossible by construction,
+and `reset()` shares the map so the two endpoints cannot drift apart again.
+
+**The record this leaves:** four consecutive holes in one function, every one
+found by review rather than by me, and after each fix I believed the path was
+settled. The gate earned its place; the hold was correct.
+
+### Caveats that survive into the milestone record
+
+- The #128 fixes are themselves unreviewed — the ultrareview ran against
+  `1a32f08`. Accepted deliberately: the collapse removed a class of seam rather
+  than adding another guard.
+- No human screen-reader pass on the person picker. axe is clean across empty and
+  populated states, which is not the same thing.
+- 21-05 Task 5 (human browser verification) was never performed.
 
 ### The two carried gaps — one closed, one only narrowed (2026-08-09)
 
diff --git a/.planning/phases/26-release-v1.5.0/26-04-PLAN.md b/.planning/phases/26-release-v1.5.0/26-04-PLAN.md
index 4b0b6b8..f2f0a77 100644
--- a/.planning/phases/26-release-v1.5.0/26-04-PLAN.md
+++ b/.planning/phases/26-release-v1.5.0/26-04-PLAN.md
@@ -22,26 +22,20 @@ must_haves:
 <objective>
 Cut and ship 1.5.0, then record the milestone.
 
-> ## ⛔ THE TAG IS HELD — 2026-08-09
+> ## ✅ HOLD CLEARED — 2026-08-09. Task 3 is unblocked.
 >
-> **Gate 8 (independent code review) never ran.** Codex hit its usage limit and
-> posted only a quota notice: zero reviews, zero inline comments. 26-01, 26-02
-> and 26-03 are merged to `main`, and `main` is at version 1.5.0 — but **do not
-> execute Task 3 of this plan until an independent review has actually happened.**
+> **Gate 8 ran.** `/code-review ultra` against PR #127 (review-only, based on the
+> `v1.4.1` tag so the diff was the whole release) returned three findings, all
+> real, fixed in #128 and merged as `707d9b6`.
 >
-> This matters more than a missing checkbox. Gate 10 found **two** real defects
-> in code I had already convinced myself was correct, and the second was a hole
-> in my own fix for the first. The lineage on `Config::sanitize()`'s per-user
-> path now reads: round 2 fixed round 1, A3 fixed round 2, A5 fixed A3. Three
-> consecutive confident-but-wrong self-assessments of one function, which now
-> carries four interacting behaviours — reject-on-add, preserve-on-submit,
-> restore-on-omit, merge-on-equivalent-key.
+> It found the two paths I had missed, on the exact invariant the review request
+> asked it to attack: **MAX_ITEMS starvation** (silent — 200 junk entries filled
+> every slot and every protected rule died to one POST) and **the DELETE endpoint**
+> (which bypassed the gate entirely, since every fix round lived on the POST path).
 >
-> A fourth self-review is the least informative thing available. Release only
-> after `/code-review ultra 124` (or an equivalent independent pass) has run and
-> its findings are addressed. If the decision is instead to ship WITHOUT that
-> review, record that as a deliberate choice here and in the milestone entry —
-> do not let it read as though the gate was satisfied.
+> The fix collapsed three mechanisms into one normalized-key map with reserved
+> capacity, rather than adding a fifth guard. Four consecutive holes in one
+> function, every one found by review rather than by me — the hold was correct.
 
 Purpose: get per-user hiding to users. Everything before this plan is
 preparation; this is the one that delivers.

From 2f21818e31eb02cb1d008763b12b45f2302ab286 Mon Sep 17 00:00:00 2001
From: Dan Knauss <273554+dknauss@users.noreply.github.com>
Date: Sun, 9 Aug 2026 20:04:27 -0600
Subject: [PATCH 06/27] docs(planning): record v1.5.0 as shipped (#130)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Tag v1.5.0 on 694b1bf; GitHub Release published; SVN deploy dispatched manually
and verified FROM SVN — trunk Stable tag 1.5.0, tags/1.5.0/ present and carrying
the per-user code (not merely the right version string), assets intact.

Marks REL-11 and Phase 26 complete, flips the milestone to shipped, and adds the
v1.5 entry to MILESTONES.md.

The milestone entry records what this release should actually be remembered for:
NINE defects found by verification and review, almost none by the test suite as
first written. Most instructive is the run of FOUR consecutive holes in
Config::sanitize()'s per-user authorization path — client-only gate, then
payload-scoped preserve, then raw-key matching, then item-cap starvation, plus a
DELETE endpoint that bypassed all of them. Each fix was correct about the case in
front of it and blind to the next, and after each one the path looked settled. It
only resolved by COLLAPSING three mechanisms into one, not by adding a fifth
guard. The transferable lesson: when a fix keeps needing another fix, the shape
is wrong, not the coverage.

Also corrects ROLE-02's known-limitation text, which still claimed the multisite
exempt branch was untested — the dedicated multisite CI lane closed that.

Caveats carried forward rather than dropped at the finish line: the #128 fixes
shipped unreviewed, there was no human screen-reader pass, and 21-05's browser
verification never happened. A milestone record that quietly drops its caveats is
how the next cycle inherits a false premise — which this project has already had
to correct once.

Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
---
 .planning/MILESTONES.md   | 32 +++++++++++++++
 .planning/REQUIREMENTS.md |  6 +--
 .planning/ROADMAP.md      |  4 +-
 .planning/STATE.md        | 86 ++++++++++++---------------------------
 4 files changed, 62 insertions(+), 66 deletions(-)

diff --git a/.planning/MILESTONES.md b/.planning/MILESTONES.md
index ecbb4ad..4425a47 100644
--- a/.planning/MILESTONES.md
+++ b/.planning/MILESTONES.md
@@ -1,5 +1,37 @@
 # Milestones: Maestro
 
+## v1.5.0 Per-User Visibility (Shipped: 2026-08-09)
+
+**Phases:** 21 (built under the v1.4 roadmap) + 26 (release). **Release tag:** `v1.5.0` (commit `694b1bf`) · GitHub Release + WordPress.org SVN `trunk`/`tags/1.5.0`, verified from SVN.
+
+**Delivered:** ROLE-02's **per-user half**. An admin can hide a menu item from named individuals as well as whole roles, on four independent axes (role × person, item × sub-items). Cosmetic only, like every other hide in Maestro: a hidden page still opens by URL for anyone authorized, and no capability changes.
+
+**Key accomplishments:**
+- `items[slug].hidden_users` / `child_hidden_users` storage, sparse and capped at `MAX_HIDDEN_USERS`
+- `is_hidden_for_current_user()` widened to independent OR'd terms, with the third reserved for the deferred `hidden_profiles` half — the seam stays a pure identity intersect and never touches a capability
+- `resolved_hidden_roles()` **generalized** into a field-parameterized resolver rather than duplicated, so the user axis inherits the qualified-key, schema-v2 and Axis-1 guards from one implementation
+- The feasibility note's §6 cosmetic-invariant guardrail made **enforcing** (`CosmeticInvariantUsersTest`)
+- Four-group visibility popover with an async person picker on core's `wp/v2/users`, gated by `list_users` on both sides
+- A multisite CI lane, closing the super-admin exemption's coverage gap
+
+**NOT in this milestone:** the cloned-role **"profiles"** half of ROLE-02, still a backlog item (`todos/pending/2026-08-02-cloned-role-hiding-profiles.md`). ROLE-02 remains **partially delivered**. Phase 22 (demo) and Phase 25 (toolbar polish) were optional inclusions that did not land.
+
+### What this milestone should be remembered for
+
+**Nine defects were found by verification and review; almost none by the test suite as first written.** Three surfaced during Phase 21's own browser checks — including a guardrail that could not detect a broken seam, because `current_user_can()` answers from a cached allcaps array. Two more came from Codex rounds on the plans, both of which I then hit as live bugs anyway. The adversarial security gate found two. The final ultrareview found three.
+
+Most instructive: **four consecutive holes in `Config::sanitize()`'s per-user authorization path**, each fix correct about the case in front of it and blind to the next — client-only gate → payload-scoped preserve → raw-key matching → item-cap starvation, plus a DELETE endpoint that bypassed all of them. After each fix the path looked settled. It was only resolved by *collapsing* three mechanisms into one normalized-key map with reserved capacity, rather than adding a fifth guard.
+
+The transferable lesson: when a fix keeps needing another fix, the shape is wrong, not the coverage.
+
+**Known limitations, carried deliberately rather than dropped at the finish line:**
+- The final round of fixes (#128) is itself unreviewed — the ultrareview ran against the prior commit
+- No human screen-reader pass on the person picker; axe is clean across empty and populated states, which is not the same claim
+- 21-05 Task 5 (human browser verification) was never performed; the phase was accepted on automated evidence
+- On multisite, super admins are exempt from the person axis only — deliberate, now tested both ways
+
+---
+
 ## v1.3.0 Slug-Resolution Hardening (Shipped: 2026-06-30)
 
 **Phases completed:** 2 phases (17–18), 6 plans. **Release tag:** `v1.3.0` (commit `884c6df`) · GitHub Release + WordPress.org SVN `trunk`/`tags/1.3.0`.
diff --git a/.planning/REQUIREMENTS.md b/.planning/REQUIREMENTS.md
index 17fa60c..2e89bd1 100644
--- a/.planning/REQUIREMENTS.md
+++ b/.planning/REQUIREMENTS.md
@@ -28,7 +28,7 @@ backlog IDs without renumbering.
 ### Roles (cosmetic only)
 
 - [x] **ROLE-01**: A feasibility note determines whether per-user and/or cloned-role cosmetic menu hiding can be delivered **without** touching capabilities (stays cosmetic per the core value) within WordPress's role/user model, and specifies the storage shape + resolution seam. **Gates ROLE-02** — if it can't stay cosmetic, ROLE-02 defers. *(Complete 2026-07-05 — Phase 19. Verdict: **partial-go**; both branches clear the cosmetic-only bar. Storage: inline `items[slug].hidden_users` axis + a `profiles` registry compiling onto `items[slug].hidden_profiles`; seam: widen `is_hidden_for_current_user()`. Phase 21 unblocked, per-user first. See `phases/19-cosmetic-hiding-feasibility/19-FEASIBILITY-NOTE.md`.)*
-- [~] **ROLE-02**: An admin can apply cosmetic menu-hiding rules scoped to a **specific user** (or a cloned role), intersected against that user's live roles. The rules never grant or remove a capability; a hidden page still loads by URL for a user who has the capability. *(conditional on ROLE-01)* — **PARTIALLY DELIVERED (Phase 21, v1.5).** The **per-user** half is complete: `items[slug].hidden_users` + `child_hidden_users`, resolved through the same single `is_hidden_for_current_user()` seam as the role axes, with the cosmetic invariant enforced by `tests/integration/CosmeticInvariantUsersTest.php` and the effect proven in a targeted user's real sidebar by `tests/e2e/specs/hidden-users.spec.ts`. The **cloned-role "profiles"** half is NOT delivered and remains a v1.5 backlog item — see `todos/pending/2026-08-02-cloned-role-hiding-profiles.md`; the seam is built as an OR of independent terms so `hidden_profiles` lands as a third term without rework. Known limitation: on multisite, network super admins are exempt from the per-user axis only (the role axes keep their v1.4.1 behaviour); that exempt branch is not covered by the single-site test suite.
+- [~] **ROLE-02**: An admin can apply cosmetic menu-hiding rules scoped to a **specific user** (or a cloned role), intersected against that user's live roles. The rules never grant or remove a capability; a hidden page still loads by URL for a user who has the capability. *(conditional on ROLE-01)* — **PARTIALLY DELIVERED (Phase 21, v1.5).** The **per-user** half is complete: `items[slug].hidden_users` + `child_hidden_users`, resolved through the same single `is_hidden_for_current_user()` seam as the role axes, with the cosmetic invariant enforced by `tests/integration/CosmeticInvariantUsersTest.php` and the effect proven in a targeted user's real sidebar by `tests/e2e/specs/hidden-users.spec.ts`. The **cloned-role "profiles"** half is NOT delivered and remains a v1.5 backlog item — see `todos/pending/2026-08-02-cloned-role-hiding-profiles.md`; the seam is built as an OR of independent terms so `hidden_profiles` lands as a third term without rework. Known limitation: on multisite, network super admins are exempt from the per-user axis only (the role axes keep their v1.4.1 behaviour) — an intentional asymmetry, now covered by a dedicated multisite CI lane (`npm run test:php:multisite`). SHIPPED in v1.5.0 (tag `v1.5.0` on `694b1bf`, 2026-08-09).
 
 ### Editor UX
 
@@ -60,7 +60,7 @@ first; neither blocks the cut.
 
 ### Release
 
-- [ ] **REL-11**: v1.5 is cut and shipped — runtime zip builds clean, Plugin Check 0 errors, full PHP/JS/e2e suites green, tagged `v1.5.0`, deployed to WordPress.org SVN `trunk` following the v1.2/v1.3/v1.4 pipeline (**including the manual `wp-deploy.yml` dispatch**, which has never been automatic); changelog verified against the `v1.4.1..main` diff rather than the phase list; **screenshot 3 recaptured** to show the visibility popover's four groups instead of two; and the multisite super-admin exemption stated as a known limitation.
+- [x] **REL-11**: v1.5 is cut and shipped — runtime zip builds clean, Plugin Check 0 errors, full PHP/JS/e2e suites green, tagged `v1.5.0`, deployed to WordPress.org SVN `trunk` following the v1.2/v1.3/v1.4 pipeline (**including the manual `wp-deploy.yml` dispatch**, which has never been automatic); changelog verified against the `v1.4.1..main` diff rather than the phase list; **screenshot 3 recaptured** to show the visibility popover's four groups instead of two; and the multisite super-admin exemption stated as a known limitation.
 
 ---
 
@@ -96,7 +96,7 @@ Which phases cover which requirements. Populated during roadmap creation.
 | UX-13 | Phase 23 | ✅ Complete 2026-07-05 |
 | BUG-08 | Phase 23 | ✅ Complete 2026-07-05 |
 | REL-10 | Phase 24 | ✅ Complete 2026-08-04 (v1.4.0; patch v1.4.1 2026-08-05) |
-| REL-11 | Phase 26 (v1.5) | Pending — ships Phase 21's per-user hiding |
+| REL-11 | Phase 26 (v1.5) | ✅ Complete 2026-08-09 (tag v1.5.0 on 694b1bf; SVN verified) |
 
 **Coverage:**
 - v1.4 requirements: 11 total
diff --git a/.planning/ROADMAP.md b/.planning/ROADMAP.md
index 592ba6d..6d5415a 100644
--- a/.planning/ROADMAP.md
+++ b/.planning/ROADMAP.md
@@ -10,7 +10,7 @@
 - ✅ **R1 Third-Party Compatibility Research** — Phases 13–16 (completed 2026-06-29; non-versioned research — no plugin code, no release tag, no SVN deploy) → [archive](milestones/R1-ROADMAP.md)
 - ✅ **v1.3.0 Slug-Resolution Hardening** — Phases 17–18 (shipped 2026-06-30; release tag `v1.3.0`) → [archive](milestones/v1.3.0-ROADMAP.md)
 - ✅ **v1.4 Compatibility, Roles & Showcase** — Phases 19–24 (shipped 2026-08-04; release tag `v1.4.0`, patch `v1.4.1` 2026-08-05). Shipped **without** Phase 21 (ROLE-02, deferred to v1.5 under the Release Binding fallback) and Phase 22 (not reached; still open).
-- 🚧 **v1.5 Per-User Visibility** — Phase 21 (built under the v1.4 roadmap, ships here) + Phase 26 (release). Phases 22 and 25 are **optional inclusions**: they ship in v1.5 if they land before the cut, and otherwise slip without blocking it.
+- ✅ **v1.5 Per-User Visibility** — Phase 21 + Phase 26 (shipped 2026-08-09; release tag `v1.5.0` on `694b1bf`). Delivered ROLE-02's **per-user half**; the cloned-role "profiles" half remains a backlog item. Phases 22 and 25 were optional inclusions and did **not** land, per the fallback.
 
 ## Phases
 
@@ -295,7 +295,7 @@ feature is built (Phase 21, 5/5 plans, 2026-08-08) but unreleased — v1.4.0 was
 cut before it landed. This milestone exists to get it to users.
 
 - [~] **Phase 21: Cosmetic Per-User Hiding** — built under the v1.4 roadmap (details in the v1.4 section above); ships here. Per-user half complete; cloned-role profiles remain a backlog item.
-- [ ] **Phase 26: Release v1.5.0** — cut and ship to WordPress.org
+- [x] **Phase 26: Release v1.5.0** — cut and shipped to WordPress.org 2026-08-09 (tag `v1.5.0` on `694b1bf`; GitHub Release + SVN `trunk`/`tags/1.5.0` verified from SVN)
 - [ ] *(optional)* **Phase 22: Slug-Resolution Showcase Demo** — ships in v1.5 if it lands before the cut
 - [ ] *(optional)* **Phase 25: Edit-Mode Toolbar Dark-Surface Polish** — ships in v1.5 if it lands before the cut
 
diff --git a/.planning/STATE.md b/.planning/STATE.md
index c855902..e8da43a 100644
--- a/.planning/STATE.md
+++ b/.planning/STATE.md
@@ -2,8 +2,8 @@
 gsd_state_version: 1.0
 milestone: v1.5
 milestone_name: Per-User Visibility
-status: in-progress
-stopped_at: "v1.5.0 hold cleared — Gate 8 satisfied via ultrareview (3 findings, fixed in #128); ready to tag"
+status: shipped
+stopped_at: "v1.5.0 SHIPPED to WordPress.org (tag v1.5.0 on 694b1bf, SVN verified). Milestone recorded; next milestone not yet opened."
 last_updated: "2026-08-09T00:00:00.000Z"
 last_activity: "2026-08-08 — **Phase 21 (ROLE-02 per-user hiding) executed, 5/5 plans, awaiting the human-verify checkpoint.** Branch `phase/21-cosmetic-per-user-hiding`, PR #120, nothing merged. Delivered: `hidden_users` / `child_hidden_users` storage; the `is_hidden_for_current_user()` seam widened to independent OR'd terms (3rd term reserved for the deferred `hidden_profiles`); `resolved_hidden_roles()` GENERALIZED to a field-parameterized resolver rather than duplicated, so the user axis inherits the qualified-key, schema-v2 (#115) and Axis-1 guards from one implementation; a shared `Cascade` union; the §6 cosmetic-invariant guardrail made enforcing; editor model exposure as id+name pairs via one batched query; four-group visibility popover with an async person picker on core's `wp/v2/users`. Gate: unit 165/165 (218), integration 109/109 (257), JS 83/83, e2e 39 passed/28 capture-skipped/0 failed, WPCS clean, PHPStan 0, Plugin Check 0 errors on the ZIP (1 pre-existing readme warning). THREE bugs found by verification that no unit test would have caught: (1) the guardrail initially could NOT detect a broken seam — `current_user_can()` answers from a cached allcaps array, so `snapshot_caps()` now drops `$GLOBALS['current_user']` to force re-derivation; (2) the picker URL appended `?` unconditionally, 404ing on every PLAIN-PERMALINK site since `rest_url()` already carries a query string; (3) clicking a search result or chip closed the whole popover, because re-rendering detached the node before `placePopover()`'s outside-click handler ran. Ruling recorded 2026-08-08: the super-admin exemption covers the NEW user axis only, multisite-scoped (unscoped would make administrators un-hideable on single-site and contradict the locked self-target decision). Prior: 2026-08-05 — **v1.4.1 SHIPPED** (PR #116, tag on c6cdcbe; wp.org API confirms 1.4.1). Patch for the shared-slug propagation defect (#115): a bare top-level key no longer applies to a submenu row whose slug names a rendered top-level item. Two Codex P2 rounds on #115 — the first cut of the gate tested `$nk === $norm_parent` and missed submenus parked under an unrelated parent; widened to `isset( $top_rendered_matches[ $nk ] )`. Prior: 2026-08-04 — **v1.4.0 SHIPPED** (PR #113, tag on 482510c, GitHub Release + wp.org SVN trunk/tags/1.4.0/assets confirmed). Phase 24 release gates 8–11 run consolidated over the full v1.3.1..main diff; one defect found and fixed (multibyte truncation blanked labels) and one changelog overclaim corrected (shared-slug isolation is submenu-direction only). ROLE-02 (Phase 21) deferred to v1.5."
 progress:
@@ -26,7 +26,7 @@ See: .planning/PROJECT.md (updated 2026-07-03)
 ## Current Position
 
 Milestone: **v1.5 Per-User Visibility** (active) — Phase 21 ✅ MERGED 2026-08-09 + Phase 26 (release, created 2026-08-09); Phases 22/25 optional inclusions. v1.4 SHIPPED (v1.4.0 + v1.4.1).
-Phase: Phase 19 ✅, Phase 20 ✅, Phase 23 ✅ (shipped as v1.3.1). **Phase 21 (Cosmetic Per-User Hiding) ✅ COMPLETE — 5/5 plans, merged to `main` 2026-08-09 via PR #120 (merge commit, history preserved). Task 5 accepted on automated evidence rather than a human browser pass — see the note below.**
+Phase: Phase 19 ✅, Phase 20 ✅, Phase 23 ✅ (shipped as v1.3.1), **Phase 26 (Release v1.5.0) ✅ SHIPPED 2026-08-09**. **Phase 21 (Cosmetic Per-User Hiding) ✅ COMPLETE — 5/5 plans, merged to `main` 2026-08-09 via PR #120 (merge commit, history preserved). Task 5 accepted on automated evidence rather than a human browser pass — see the note below.**
 Plan: Phase 21 delivered ROLE-02's **per-user half**: 21-01 storage → 21-02 seam + cascade → 21-03 guardrail → 21-04 editor + picker → 21-05 e2e + gate + docs, plus two rounds of Codex review fixes. The cloned-role **profiles** half stays deferred to the backlog todo. Next: **Phase 26 (Release v1.5.0)** — per-user hiding is on `main` but unreleased; Phase 22 (demo) and Phase 25 (toolbar polish) are optional inclusions that do not block the cut.
 Status: Phase 20's COMPAT-10 was reworked mid-checkpoint 2026-08-02: the boolean `cascade_hide` + "rides the parent hide" model built in 20-05/20-06 was found **inert** — WordPress core's `_wp_menu_output()` never renders a hidden parent's `<ul class="wp-submenu">` at all, so hiding the parent already removes the whole subtree cosmetically; cascading on top of that produced no observable difference. Reworked (20-CONTEXT.md REVISION NOTE) into an **independent** per-parent `child_hidden_roles` role set: `Maestro\Cascade::effective_hidden_roles( $child_hidden_roles, $parent_child_hidden_roles )` is now a plain, unconditional role-list union (no flag). `Config::sanitize()` accepts `child_hidden_roles` on a top-level item with the same contract as `hidden_roles` (role-intersect, `MAX_HIDDEN_ROLES` cap, dropped on a qualified submenu key). `Replay::replay()`'s submenu loop unions each child's own `hidden_roles` with its parent's `child_hidden_roles`, fully independent of whether the parent's own `hidden_roles` currently hides the parent row — so a parent can stay visible while its children vanish, a genuinely observable effect the old model could never produce. `get_menu_model()` exposes `childHiddenRoles` (empty array, not merely absent, for an untouched parent). The editor popover now shows TWO independent role-checkbox groups — "Hide this item from:" (existing) and "Hide its sub-items from:" (new, shown only on parents with children) — via a shared `buildRoleGroup()` helper in `assets/maestro.js`. The e2e spec (`cascade-hide.spec.ts`) now asserts the effect DIRECTLY against the rendered sidebar (parent visible, child rows gone, role-mirrored) via a second authenticated browser context, replacing the inert model's wp-cli/`$submenu` dump workaround (`dump-cascade-submenu.php`, deleted). Cosmetic-only guardrail reconfirmed end-to-end. **Full zero-regression gate (final):** PHP unit 127/127 (158 assertions), PHP integration 72/72 (172 assertions), JS 58/58, e2e 35 passed/28 capture-gated skipped/0 failed, WPCS clean, PHPStan 0 errors, Plugin Check 0 errors on the built shippable ZIP (1 pre-existing readme.txt warning) and 0 NEW errors on the dev-tree (7 errors/7 warnings, all pre-existing, confirmed via `git log --diff-filter=A` to predate Phase 20). All three Phase 20 requirements (COMPAT-04/07/10) genuinely complete. 20-04 (prior) delivered COMPAT-07 badge/HTML preservation on rename via `Maestro\Title::replace_label()`'s text-node swap at both title-write seams. 20-03 (prior) closed out COMPAT-04 client-side with the qualified-key DOM-join and live WooCommerce verification. 20-02/20-01 (prior) built COMPAT-04's server-side qualified-key foundation and replay/editor-model wiring. Phase 19 ROLE-01 signed off — **partial-go** (per-user go + ship first; cloned-role go as an additive `profiles` registry compiling to the same inline `is_hidden_for_current_user()` seam); Phase 21 unblocked. Phase 23 delivered UX-09/UX-12/UX-13/BUG-08 (native wp-admin restyle; 5/5 plans; full-suite gate green) and shipped in v1.3.1. **NOTE for Phase 24:** Plugin Check flags 7 errors/7 warnings against pre-existing dev-tree root files — logged to `phases/23-editor-ux-polish/deferred-items.md` for the Phase 24 build-then-check pipeline.
 Last activity: 2026-08-09 — Phase 21 merged to `main` (PR #120, merge commit). Two Codex review rounds landed first: round 1 caught a self-target undo trap, the `list_users` gap, and an unenforced 50-user cap; round 2 caught that the `list_users` fix was **client-side only** (an editor could POST guessed IDs and read display names back from the model), plus an unbounded all-users query on every save. Both rounds fixed and CI-green. Codex has NOT reviewed the round-2 fixes themselves.
@@ -117,67 +117,31 @@ as a known risk, not a solved case). Covering it properly needs a second CI lane
 `readme.txt` as a known behaviour rather than carried silently. Revisit if
 multisite becomes a supported target.
 
-Progress: [███████░░░] 67% (v1.4 shipped; Phase 21 executed and awaiting verification). Remaining: **Phase 26 (Release v1.5.0, created 2026-08-09 — REL-11)**, plus Phase 22 (demo) and Phase 25 (toolbar polish) as optional inclusions that do not block the cut.
+Progress: [██████████] v1.5 SHIPPED 2026-08-09 (Phases 21 + 26). Open, unscheduled: Phase 22 (Playground demo), Phase 25 (toolbar polish), and ROLE-02's deferred cloned-role profiles half. No milestone is currently active.
 
 ## Release Binding
 
-### Active milestone — v1.5 Per-User Visibility (Phase 26)
-
-**Target version `1.5.0`, tag `v1.5.0`**, SVN deploy to WordPress.org `trunk`
-following the v1.2/v1.3/v1.4 pipeline. A **minor** bump, not a patch: per-user
-hiding is a new user-facing capability with a new stored config shape
-(`hidden_users` / `child_hidden_users`).
-
-**Why this milestone exists:** to release work that already exists. Phase 21
-built ROLE-02's per-user half on 2026-08-08 and it is unreleased — v1.4.0 was cut
-before it landed, under the documented fallback. v1.5 is a release vehicle first
-and a scope container second.
-
-**Cut condition:** Phase 21 merged and verified. Phases 22 (demo) and 25
-(toolbar polish) are **optional inclusions** — each ships if complete at cut
-time, otherwise slips without blocking. This is the same fallback shape that let
-v1.4.0 ship cleanly without Phase 21, and it worked.
-
-**Carried forward into the Phase 26 checklist (all learned the hard way):**
-
-1. **Diff `v1.4.1..main` for user-facing commits before tagging** — do not trust
-   the phase list. v1.4.0's changelog carried an overclaim caught only at gate 8.
-2. **The SVN deploy is NOT auto-triggered.** A GitHub Release created via
-   `GITHUB_TOKEN` does not fire `release: published`, so `wp-deploy.yml` needs a
-   manual `workflow_dispatch` (`gh workflow run wp-deploy.yml -f tag=v1.5.0`).
-   True for v1.3.0, v1.4.0, and v1.4.1 — plan the step in rather than rediscover it.
-3. **Screenshot 3 is now stale.** It shows the visibility picker with two groups;
-   the shipping UI has four. Recapture is mandatory, not optional.
-4. **The wp.org API `version` field lags the SVN commit** by up to ~an hour. SVN
-   is the truth at deploy time; do not treat an unchanged API response as failure.
-5. **Gates 8–11 (review, a11y, security, performance) run consolidated over the
-   full release diff**, not per-phase. The person-picker surfaces have never had
-   an independent a11y pass — they were written to the bar, not audited against it.
-
-**Known limitation to carry into the release notes:** on multisite, network
-super admins are exempt from the per-user axis only; role axes keep their v1.4.1
-behaviour. That branch is untested (single-site suite). Already in `readme.txt`.
-
-
-
-**Interim patch — v1.3.1 ✅ SHIPPED 2026-07-05 (PR #88).** Phase 23's editor UX
-restyle shipped early as a `1.3.1` patch (the only user-facing code on `main`
-since `v1.3.0`; Phase 19 is docs-only). Tag `v1.3.1` on `e77729d` → GitHub
-Release published → WordPress.org SVN deploy succeeded (trunk + `tags/1.3.1` +
-assets); wp.org API confirms `1.3.1` live. Did **not** consume the v1.4.0 version.
-
-**Release-pipeline lesson (v1.3.1):** the tag → GitHub Release step is automatic
-(`release.yml` on `push: tags: v*`), but the **SVN deploy is NOT auto-triggered**
-— a Release created via `GITHUB_TOKEN` does not cascade to the `release:
-published` event, so `wp-deploy.yml` must be run manually via `workflow_dispatch`
-(`gh workflow run wp-deploy.yml -f tag=vX.Y.Z`). This matched v1.3.0 (also a
-manual dispatch). Plan the manual deploy step into every release.
-
-**Milestone release — v1.4.0.** Target version `1.4.0`, tag `v1.4.0`, SVN deploy to
-WordPress.org `trunk` following the v1.2/v1.3 release pipeline. `vX.Y` numbering
-is reserved for shipped plugin releases. ROLE-02 (Phase 21) ships only if
-Phase 19's feasibility verdict clears the cosmetic-only bar; otherwise it defers
-and REL-10 ships without it.
+### v1.5 Per-User Visibility — ✅ SHIPPED 2026-08-09
+
+**Tag `v1.5.0` on `694b1bf`.** GitHub Release published with the ZIP; SVN deploy
+dispatched manually and verified FROM SVN, not the API: `trunk` Stable tag reads
+1.5.0, `tags/1.5.0/` exists and contains the per-user code (not merely the right
+version string), and `assets/` is intact. The wp.org API happened to update
+promptly this time — do not rely on that next release.
+
+Full milestone record, including what shipped, what did not, and the defect
+history worth remembering, is in [MILESTONES.md](MILESTONES.md).
+
+**The pipeline lesson held for a FOURTH consecutive release:** the SVN deploy is
+not automatic and required a manual `workflow_dispatch`. Plan the step in.
+
+**Open, carried deliberately:**
+- ROLE-02's cloned-role "profiles" half is still deferred
+  (`todos/pending/2026-08-02-cloned-role-hiding-profiles.md`)
+- Phase 22 (Playground demo) and Phase 25 (toolbar polish) remain open
+- The #128 fixes shipped unreviewed (the ultrareview ran against the prior commit)
+- No human screen-reader pass on the person picker
+- 21-05 Task 5 (human browser verification) was never performed
 
 ### Release Checklist (v1.4.0)
 

From 11fa8a00ae3deff308b4239e384d6d7ab5ea45a2 Mon Sep 17 00:00:00 2001
From: Dan Knauss <273554+dknauss@users.noreply.github.com>
Date: Sun, 9 Aug 2026 21:28:19 -0600
Subject: [PATCH 07/27] docs(planning): plan Phase 25, and flag that its scope
 is stale (#131)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Two plans, both autonomous:false. Also removes a stray empty
`26-release-v1-5-0/` directory (hyphens) that tooling created alongside the real
`26-release-v1.5.0/`.

THE SCOPE HAD DECAYED, so 25-01 is an audit rather than an implementation plan.
Measured against main @ 2f21818:

- Criterion 1 is ALREADY SATISFIED. The toolbar glyphs are #c3c4c7 at 9.11:1,
  not the reported #3858e9 at 2.83:1 — which is no longer in the CSS at all.
  v1.4.0's a11y gate found this independently and recorded it as "does not
  reproduce, closed as stale"; the roadmap was never updated, so it has been
  reading as open work for a week.
- Criterion 2 rests on a false premise. The #2271b1 focus ring measures 3.07:1
  on #1d2327 — it PASSES. Widening to #72aee6 (6.74:1) is defensible for
  robustness, but it is a choice, not a fix, and the plan says so.
- Criteria 3 and 4 are unverified: .maestro-status sets flex-shrink:0 but
  min-width:0, so whether it actually reflows is empirical, not readable.

Implementing the list as written would have meant "fixing" a glyph colour that is
already correct and replacing a focus ring that meets its bar. This project has
already had to correct one stale planning premise mid-phase; catching this one
before it costs work is the cheaper version of that lesson.

25-01 is instructed to strike stale criteria WITH the evidence rather than delete
them, and — if fewer than two survive — to recommend closing the phase as
overtaken by events rather than executing a token version of it.

25-02 implements only what survives, asserts each change with a test that would
fail without it, and keeps the commit-on-Enter/blur save model intact (the
HARD-03 save-race behaviour depends on it).

Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
---
 .planning/ROADMAP.md                          |  20 +-
 .../25-01-PLAN.md                             | 167 ++++++++++++++++
 .../25-02-PLAN.md                             | 181 ++++++++++++++++++
 3 files changed, 367 insertions(+), 1 deletion(-)
 create mode 100644 .planning/phases/25-edit-mode-toolbar-dark-surface-polish/25-01-PLAN.md
 create mode 100644 .planning/phases/25-edit-mode-toolbar-dark-surface-polish/25-02-PLAN.md

diff --git a/.planning/ROADMAP.md b/.planning/ROADMAP.md
index 6d5415a..e2839c7 100644
--- a/.planning/ROADMAP.md
+++ b/.planning/ROADMAP.md
@@ -284,7 +284,25 @@ ship Phase 21's per-user hiding. See "Phase Details (v1.5 — Per-User Visibilit
 2026-08-04 without this phase, so it did not precede that release. It is now a
 candidate for the (not yet created) v1.5 release, alongside the deferred a11y
 M2/M3 items from `todos/pending/2026-08-02-a11y-locked-checkbox-refinements.md`.
-**Plans**: TBD (run /gsd:plan-phase 25 to break down)
+**Plans**: 25-01 audit + re-scope · 25-02 implement, prove, close (planned 2026-08-09; both `autonomous: false`)
+
+> **⚠️ SCOPE IS STALE — 25-01 exists to fix that before any code is written.**
+> Measured against `main` @ `2f21818` on 2026-08-09:
+>
+> - **Criterion 1 is already satisfied.** The glyphs are `#c3c4c7` at **9.11:1**,
+>   not the reported blue `#3858e9` at 2.83:1 — which no longer appears in the
+>   CSS at all. v1.4.0's a11y gate reached the same conclusion independently and
+>   recorded it as "does not reproduce, closed as stale"; this entry was never
+>   updated to match.
+> - **Criterion 2 rests on a false premise.** The `#2271b1` focus ring measures
+>   **3.07:1** on `#1d2327` — it PASSES the 3:1 bar. Widening the margin to
+>   `#72aee6` (6.74:1) is defensible on robustness grounds, but it is a choice,
+>   not a fix.
+> - **Criteria 3 and 4 are unverified.** `.maestro-status` sets `flex-shrink: 0`
+>   but `min-width: 0`, so whether it actually reflows is an empirical question.
+>
+> If fewer than two criteria survive the audit, 25-01 is instructed to recommend
+> closing the phase as overtaken by events rather than executing a token version.
 
 ---
 
diff --git a/.planning/phases/25-edit-mode-toolbar-dark-surface-polish/25-01-PLAN.md b/.planning/phases/25-edit-mode-toolbar-dark-surface-polish/25-01-PLAN.md
new file mode 100644
index 0000000..1cd563a
--- /dev/null
+++ b/.planning/phases/25-edit-mode-toolbar-dark-surface-polish/25-01-PLAN.md
@@ -0,0 +1,167 @@
+---
+phase: 25-edit-mode-toolbar-dark-surface-polish
+plan: 01
+type: audit
+wave: 1
+depends_on: []
+files_modified:
+  - .planning/ROADMAP.md
+  - .planning/phases/25-edit-mode-toolbar-dark-surface-polish/25-01-SUMMARY.md
+autonomous: false
+requirements: []
+must_haves:
+  truths:
+    - "Each of the phase's five success criteria is re-verified against the CURRENT code, not the 2026-08-02 report."
+    - "Criteria that are already satisfied are struck from scope with the measurement that proves it."
+    - "The surviving scope is written down before any code is touched."
+---
+
+<objective>
+Establish what is actually left of this phase before implementing anything.
+
+Purpose: the phase was scoped 2026-08-02 from a defect report, and **two of its
+five criteria have already decayed** — one was silently fixed, another rests on a
+premise that no longer measures true. Implementing the list as written would mean
+"fixing" a glyph colour that is already correct, and replacing a focus ring that
+passes its bar. This project has already had to correct one stale planning
+premise (the Phase 21 release-target); catching this one before it costs work is
+the cheaper version of that lesson.
+Output: a re-scoped phase with measurements attached.
+
+**`autonomous: false`** — criteria 3 and 4 are judgements about how the editor
+feels, which is not something a contrast calculation settles.
+</objective>
+
+<context>
+@.planning/ROADMAP.md
+@.planning/todos/pending/2026-08-01-editor-toolbar-icon-contrast.md
+@.planning/todos/pending/2026-08-02-a11y-locked-checkbox-refinements.md
+@assets/maestro.css
+
+<interfaces>
+<!-- Contracts the executor builds on. Use directly — no exploration needed. -->
+
+**ALREADY MEASURED (2026-08-09, against `main` @ 2f21818).** Recompute rather
+than trust these if the CSS has moved since:
+
+| Surface | Measured | Bar | Verdict |
+|---|---|---|---|
+| Toolbar glyphs `#c3c4c7` on `#1d2327` | **9.11:1** | 3.0 | criterion 1 is ALREADY SATISFIED |
+| The reported blue `#3858e9` on `#1d2327` | 2.83:1 | 3.0 | not present in the CSS any more |
+| Save-status `#c3c4c7` on `#1d2327` | 9.11:1 | 4.5 | fine |
+| Focus ring `#2271b1` on `#1d2327` | **3.07:1** | 3.0 | PASSES, but by 0.07 |
+| Alternative ring `#72aee6` on `#1d2327` | 6.74:1 | 3.0 | would be a large margin |
+| Destructive `#f86368` on `#1d2327` | 5.28:1 | 4.5 | fine |
+
+v1.4.0's a11y gate reached the same conclusion about criterion 1 independently
+and recorded it as "does NOT reproduce, closed as stale" — the roadmap was never
+updated to match, which is why it still reads as open work.
+
+`.maestro-status` currently sets `flex-shrink: 0` (never compress) but
+`min-width: 0` — so it does not reserve a slot. Whether that produces a visible
+reflow when the status appears is an empirical question, not a CSS-reading one.
+
+**Adjacent deferred work on the same surface**, worth folding in if it survives
+triage: the a11y M2/M3 items in
+`todos/pending/2026-08-02-a11y-locked-checkbox-refinements.md`. Note the v1.5.0
+gate added axe-core scanning of the visibility popover, so some of M2/M3 may
+already be covered — check before scheduling.
+</interfaces>
+</context>
+
+<tasks>
+
+<task type="auto">
+  <name>Task 1: Re-measure criteria 1 and 2</name>
+  <files></files>
+  <behavior>
+    - Every colour pair in the table above is recomputed against the current CSS.
+    - Criterion 1 is confirmed satisfied (or reopened, if the CSS has changed).
+    - Criterion 2 gets a decision: leave the passing-but-marginal ring, or widen
+      the margin.
+  </behavior>
+  <action>
+    Recompute rather than copy the table — the point of this task is that a
+    measurement from a week ago is not evidence about today.
+
+    On criterion 2, the honest framing is that 3.07:1 is not a failure, so this
+    is a robustness call rather than a fix: WCAG is a floor, and 0.07 above it
+    survives no rendering variance at all. Either decision is defensible. Record
+    which was taken and why, so the next person does not re-litigate it.
+  </action>
+  <verify>
+    <automated>Recomputed contrast ratios recorded in the summary.</automated>
+  </verify>
+  <done>Criteria 1 and 2 resolved with numbers attached; criterion 1 struck from scope if still satisfied.</done>
+</task>
+
+<task type="checkpoint">
+  <name>Task 2: Verify criteria 3 and 4 in a real editor</name>
+  <files></files>
+  <behavior>
+    - The save-status indicator's appearance/disappearance is observed live: does
+      it actually reflow the rename field, or does flex-shrink already hold it?
+    - Rename commit feedback is exercised: commit a rename by Enter and by blur,
+      and judge whether the result reads as saved.
+  </behavior>
+  <action>
+    Both of these are "how does it feel" questions that a CSS reading cannot
+    answer, which is why this task is a checkpoint rather than an inspection.
+
+    Boot wp-env, enter edit mode, and watch the toolbar while a save cycles. If
+    there is no visible shift, criterion 3 is stale too and should be struck with
+    that observation recorded — do not implement a fixed-width slot for a
+    reflow that does not happen.
+
+    For criterion 4, note the constraint it carries: improve the feedback WITHOUT
+    introducing live as-you-type autosave. The commit-on-Enter/blur model and the
+    HARD-03 save-race behaviour both depend on that staying as it is.
+  </action>
+  <verify>
+    <manual>Observed in a running editor; verdict recorded per criterion.</manual>
+  </verify>
+  <done>Criteria 3 and 4 each confirmed as real or struck as stale, with the observation that decided it.</done>
+</task>
+
+<task type="auto">
+  <name>Task 3: Triage the adjacent a11y items and write the surviving scope</name>
+  <files>.planning/ROADMAP.md</files>
+  <behavior>
+    - The M2/M3 items are checked against what the v1.5.0 axe scanning already covers.
+    - The roadmap's Phase 25 entry is rewritten to the surviving criteria only.
+    - Struck criteria are recorded as struck WITH their evidence, not deleted.
+  </behavior>
+  <action>
+    Rewrite the criteria list rather than annotating it — a list where half the
+    entries are already done is one people stop reading.
+
+    Keep the struck items visible as a short "resolved before execution" note.
+    Deleting them silently would leave the next reader wondering whether the
+    original defect report was ever addressed, which is the same failure mode as
+    leaving them open.
+
+    If fewer than two criteria survive, say so plainly and recommend closing the
+    phase as overtaken by events rather than executing a token version of it.
+  </action>
+  <verify>
+    <automated>npm run check:doc-links</automated>
+  </verify>
+  <done>Roadmap reflects real remaining scope; struck criteria recorded with evidence; a recommendation stands if the phase no longer justifies itself.</done>
+</task>
+
+</tasks>
+
+<verification>
+- Every criterion has a verdict backed by a measurement or an observation.
+- No code has been modified by this plan.
+- The roadmap no longer lists work that is already done.
+</verification>
+
+<success_criteria>
+- The phase's real remaining scope is known before implementation starts.
+- Stale criteria are struck with evidence rather than quietly carried or quietly dropped.
+</success_criteria>
+
+<output>
+After completion, create `.planning/phases/25-edit-mode-toolbar-dark-surface-polish/25-01-SUMMARY.md`.
+</output>
diff --git a/.planning/phases/25-edit-mode-toolbar-dark-surface-polish/25-02-PLAN.md b/.planning/phases/25-edit-mode-toolbar-dark-surface-polish/25-02-PLAN.md
new file mode 100644
index 0000000..92c9d84
--- /dev/null
+++ b/.planning/phases/25-edit-mode-toolbar-dark-surface-polish/25-02-PLAN.md
@@ -0,0 +1,181 @@
+---
+phase: 25-edit-mode-toolbar-dark-surface-polish
+plan: 02
+type: tdd
+wave: 2
+depends_on: [25-01]
+files_modified:
+  - assets/maestro.css
+  - assets/maestro.js
+  - tests/e2e/specs/toolbar-dark-surface.spec.ts
+  - TESTING.md
+autonomous: false
+requirements: []
+must_haves:
+  truths:
+    - "Only criteria that SURVIVED 25-01's audit are implemented."
+    - "Every visual claim is asserted by test, not by screenshot inspection alone."
+    - "The commit-on-Enter/blur save model is unchanged — no live as-you-type autosave."
+    - "Zero regression: unit, integration, JS, e2e, WPCS, PHPStan all green."
+---
+
+<objective>
+Implement whatever survived the audit, prove it, and close the phase.
+
+Purpose: this is a polish phase on surfaces that shipped in v1.3.1 and have been
+in front of users since. The bar is "measurably better, provably not worse" —
+there is no new capability here to justify any regression risk.
+Output: the surviving fixes, each with a test, and a closed phase.
+
+**`autonomous: false`** — it ends at the phase checkpoint, and the judgements
+about feel that 25-01 raised do not become automatable just because they are now
+scoped.
+</objective>
+
+<context>
+@.planning/ROADMAP.md
+@.planning/phases/25-edit-mode-toolbar-dark-surface-polish/25-01-SUMMARY.md
+@assets/maestro.css
+@assets/maestro.js
+
+<interfaces>
+<!-- Contracts the executor builds on. Use directly — no exploration needed. -->
+
+**Do not re-derive the scope.** 25-01 decided it; implement exactly that list. If
+a criterion was struck there, it stays struck — reopening it here would defeat
+the point of having audited.
+
+**Constraint carried from the original scoping, still binding:** improve rename
+commit feedback WITHOUT introducing live as-you-type autosave. The
+commit-on-Enter/blur model and the HARD-03 save-race behaviour both depend on it.
+`save-race.spec.ts` is the guard; if it fails, the change went too far.
+
+**Testing patterns available on this surface** (established during the v1.5.0
+gates — reuse rather than reinvent):
+- contrast is computed from the CSS tokens, not eyeballed from a capture
+- `@axe-core/playwright` scans a scoped selector; scope it to the TOOLBAR here,
+  not the whole admin screen, so pre-existing wp-admin findings do not train
+  people to ignore the result
+- layout shift is observable by measuring an element's bounding box before and
+  after a state change, which is a real assertion rather than a screenshot diff
+
+**Verify across Default / Modern / Midnight admin colour schemes.** Phase 23
+spot-checked all three and this toolbar inherits from none of them — it is a
+custom-drawn dark surface, so a scheme change must not alter it. That is worth
+one assertion rather than an assumption.
+</interfaces>
+</context>
+
+<tasks>
+
+<task type="auto" tdd="true">
+  <name>Task 1: Implement the surviving criteria</name>
+  <files>assets/maestro.css, assets/maestro.js</files>
+  <behavior>
+    - Each surviving criterion from 25-01 is implemented.
+    - Nothing outside that list changes.
+    - Struck criteria remain untouched.
+  </behavior>
+  <action>
+    Work the audited list only. If implementing one surfaces a NEW problem, note
+    it for triage rather than fixing it inline — this phase's whole premise is
+    that its scope was stale, and quietly re-widening it would repeat that.
+
+    If the focus ring was changed, keep it consistent with every other focus ring
+    in the editor. A toolbar that focuses differently from the popovers beside it
+    is worse than one that focuses dimly.
+  </action>
+  <verify>
+    <automated>composer lint</automated>
+  </verify>
+  <done>Surviving criteria implemented; scope unchanged from the audit.</done>
+</task>
+
+<task type="auto" tdd="true">
+  <name>Task 2: Assert the improvements rather than describing them</name>
+  <files>tests/e2e/specs/toolbar-dark-surface.spec.ts, TESTING.md</files>
+  <behavior>
+    - Contrast claims are asserted from computed styles against the measured bar.
+    - If the layout-shift fix landed: the status element's box is asserted stable
+      across the idle → saving → saved transition.
+    - If the rename-feedback change landed: the feedback is asserted to fire on
+      commit, and `save-race.spec.ts` still passes untouched.
+    - axe reports no violations scoped to the toolbar.
+    - The toolbar renders identically under all three admin colour schemes.
+  </behavior>
+  <action>
+    Write the assertions so they would FAIL against the pre-fix code. A test that
+    passes either way documents nothing — and this phase exists precisely because
+    an unverified claim sat in the roadmap for a week after it stopped being true.
+
+    For layout shift, compare bounding boxes rather than screenshots: a pixel
+    diff on a dark toolbar is noisy and will be disabled by the third person who
+    hits a false positive.
+
+    TESTING.md counts updated in the same commit.
+  </action>
+  <verify>
+    <automated>npm run test:e2e -- tests/e2e/specs/toolbar-dark-surface.spec.ts</automated>
+  </verify>
+  <done>Each landed change has an assertion that fails without it; axe clean on the toolbar; scheme-independence asserted; TESTING.md updated.</done>
+</task>
+
+<task type="auto">
+  <name>Task 3: Zero-regression gate</name>
+  <files>TESTING.md</files>
+  <behavior>
+    - unit, integration (single-site AND multisite), JS, full e2e, WPCS, PHPStan,
+      doc-links all green.
+    - `save-race.spec.ts` and the Phase 23 toolbar specs pass unmodified.
+  </behavior>
+  <action>
+    Run the whole gate, and confirm the CI head SHA matches the commit you are
+    judging — a green check from an earlier commit is not evidence about this
+    one, which this project has now been caught by twice.
+
+    If a Phase 23 spec needed editing, stop and justify it in the summary. On a
+    polish phase, a changed assertion in an older spec is more likely a
+    regression than a drifted expectation.
+  </action>
+  <verify>
+    <automated>composer test:unit &amp;&amp; npm run test:php &amp;&amp; npm run test:php:multisite &amp;&amp; npm run test:js &amp;&amp; npm run test:e2e &amp;&amp; composer lint &amp;&amp; composer analyse:phpstan</automated>
+  </verify>
+  <done>Full gate green at the judged commit with counts recorded; no older spec silently edited.</done>
+</task>
+
+<task type="checkpoint">
+  <name>Task 4: Phase verification</name>
+  <files></files>
+  <action>
+    Present: what was implemented, what 25-01 struck and why, the before/after
+    measurements, and anything the automated gate could not settle.
+
+    State plainly whether the toolbar is actually better to use, not merely
+    compliant. This phase came from a defect report about how the editor looked
+    and felt; a passing contrast table is necessary and not sufficient.
+  </action>
+  <verify>
+    <manual>Human confirms in a running editor across the three colour schemes.</manual>
+  </verify>
+  <done>Phase verified and closed; VERIFICATION.md written; roadmap and STATE updated.</done>
+</task>
+
+</tasks>
+
+<verification>
+- Only audited scope was implemented.
+- Every landed change has a test that fails without it.
+- Full gate green, including the multisite lane.
+- No Phase 23 spec edited without justification.
+</verification>
+
+<success_criteria>
+- The toolbar surfaces that prompted the original report are measurably improved.
+- Nothing that already passed was "fixed".
+- The save model is unchanged.
+</success_criteria>
+
+<output>
+After completion, create `.planning/phases/25-edit-mode-toolbar-dark-surface-polish/25-02-SUMMARY.md`
+and `.planning/phases/25-edit-mode-toolbar-dark-surface-polish/25-VERIFICATION.md`.
+</output>

From cd70fb1372b473ad8de611102aecc8a9f97e793d Mon Sep 17 00:00:00 2001
From: Dan Knauss <273554+dknauss@users.noreply.github.com>
Date: Sun, 9 Aug 2026 21:46:03 -0600
Subject: [PATCH 08/27] =?UTF-8?q?docs(25-01):=20run=20the=20Phase=2025=20a?=
 =?UTF-8?q?udit=20=E2=80=94=20one=20criterion=20struck,=20one=20downgraded?=
 =?UTF-8?q?,=20one=20measured=20(#132)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The phase still justifies itself, but on a materially different scope than it was
written with. Evidence in 25-01-SUMMARY.md; roadmap criteria rewritten.

STRUCK — criterion 1 was already satisfied. The toolbar glyphs measure 9.11:1 as
#c3c4c7; the reported #3858e9 (2.83:1) appears nowhere in maestro.css. v1.4.0's
a11y gate found this independently and closed it as stale — the roadmap was never
updated, so it read as open work for a week.

DOWNGRADED — criterion 2 rests on a false premise. The #2271b1 focus ring
measures 3.07:1 on #1d2327: it PASSES. Widening to #72aee6 (6.74:1) is still
worth doing, because 0.07 above the floor survives no rendering variance, but it
is recorded as a ROBUSTNESS CHOICE rather than a defect fix so it is not
re-litigated later as one.

CONFIRMED AND MEASURED — criterion 3 is real. Sampling the toolbar 25x across a
save cycle: .maestro-status grows 4px -> 24px and the rename field shifts 20px
horizontally (x: 230 -> 210) as a direct result. Its own width is stable, so this
is pure displacement. flex-shrink:0 prevents compression but min-width:0 reserves
nothing.

ALREADY IMPLEMENTED — criterion 4's stated remedy exists: Enter-commit produces
"Saving… → Saved". The residue is softer than scoped (the confirmation is
transient), and is folded into criterion 3, since reserving the slot is most of
what "feels unsaved" described. A persistent post-save marker stays an open
design question rather than being smuggled in under a layout fix.

TRIAGED IN — a11y M2 and M3 both survive; the v1.5.0 axe scanning does not
overlap them, because neither is an axe violation. M2 is semantic quality (a
natively-disabled checkbox is skipped in SR focus mode, so its lock reason is
never heard). M3 is focus management: placePopover()'s outside-click handler
drops focus to <body> while Escape restores it. The v1.5.0 a11y spec asserted the
Escape path but never outside-click, which is why it passed.

Net: two of five original criteria survive, plus two adjacent a11y items — past
the threshold 25-01 was given for recommending closure. Had 25-02 run against the
original list, its first task would have been recolouring a glyph that is already
the right colour.

Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
---
 .planning/ROADMAP.md                          |  40 +++----
 .../25-01-SUMMARY.md                          | 112 ++++++++++++++++++
 2 files changed, 127 insertions(+), 25 deletions(-)
 create mode 100644 .planning/phases/25-edit-mode-toolbar-dark-surface-polish/25-01-SUMMARY.md

diff --git a/.planning/ROADMAP.md b/.planning/ROADMAP.md
index e2839c7..24d14f4 100644
--- a/.planning/ROADMAP.md
+++ b/.planning/ROADMAP.md
@@ -272,37 +272,27 @@ ship Phase 21's per-user hiding. See "Phase Details (v1.5 — Per-User Visibilit
 **Goal**: The edit-mode bottom toolbar reads cleanly on its dark (`#1d2327`) background and meets the accessibility bar Phase 23 held — control icons and focus states clear WCAG non-text contrast, the save-status indicator no longer shifts the layout, and renames give adequate commit feedback — spot-checked on Default + Modern + Midnight admin colour schemes.
 **Depends on**: Phase 23 (builds on the shipped editor-UX toolbar)
 **Requirements**: (none formal — UX/a11y polish; surfaced during Phase 20 verification 2026-08-02. Seed: [.planning/todos/pending/2026-08-01-editor-toolbar-icon-contrast.md](todos/pending/2026-08-01-editor-toolbar-icon-contrast.md))
-**Success Criteria** (what must be TRUE):
-  1. Control **icon glyphs** meet WCAG 1.4.11 (≥3:1) on the dark toolbar — recoloured from WP interactive-blue `#3858e9` (~2.8:1) to WP light gray `#c3c4c7` (~9:1), matching the button labels — confirmed by a contrast check.
-  2. The **focus ring** on toolbar controls is a light/bright indicator (`#fff` or WP blue-30 `#72aee6`, ≥3:1 on `#1d2327`), replacing the dark `#2271b1` ring, mirroring WP's admin bar / Gutenberg dark surfaces — confirmed by a focus-visible contrast check.
-  3. The **save-status indicator** (`.maestro-status`) occupies a persistent fixed-width slot so its appearance/disappearance no longer reflows the rename field — content fades in/out inside a reserved box — confirmed by before/after (no layout shift).
-  4. **Rename commit feedback** is improved (the save-status fires on rename commit and/or an "Enter to apply" hint) so a rename no longer feels unsaved — WITHOUT introducing live as-you-type autosave (keeps the commit-on-Enter/blur + debounced-save model and the HARD-03 save-race behavior intact).
-  5. Existing PHP unit, integration, JS, and Playwright e2e suites stay green; WPCS clean; PHPStan clean; Plugin Check 0 new errors; verified across Default/Modern/Midnight admin colour schemes.
+**Success Criteria** — ⚠️ **RE-SCOPED 2026-08-09 by the 25-01 audit.** The original
+five were written from a 2026-08-02 defect report; two had decayed. Measured
+verdicts below; full evidence in `25-01-SUMMARY.md`.
+  1. **The save-status indicator occupies a reserved slot** so it no longer displaces the rename field. *(CONFIRMED and measured: the status grows 4px → 24px and the rename field shifts 20px horizontally as a direct result. Absorbs original criterion 4 — see below.)*
+  2. **The focus ring margin is widened** from `#2271b1` (3.07:1) to `#72aee6` (6.74:1) on `#1d2327`. *(A ROBUSTNESS CHOICE, not a compliance fix — the current ring PASSES the 3:1 bar. Recorded as a choice so it is not re-litigated as a defect.)*
+  3. **A11y M2** — the derived-locked checkbox drops its redundant `aria-disabled`, moves the lock reason from the accessible NAME to `aria-describedby`, and makes that reason reachable in screen-reader focus mode (a natively-disabled control is skipped there today, so the reason is never heard). *(From `todos/pending/2026-08-02-a11y-locked-checkbox-refinements.md`; NOT covered by the v1.5.0 axe scanning.)*
+  4. **A11y M3** — outside-click dismissal restores focus to the anchor button, matching what Escape already does (WCAG 2.4.3). *(Confirmed by reading `placePopover()`. The v1.5.0 a11y spec asserted the Escape path but never outside-click, which is why it passed.)*
+  5. Existing PHP unit, integration (single-site AND multisite), JS, and Playwright e2e suites stay green; WPCS clean; PHPStan clean; Plugin Check 0 new errors; verified across Default/Modern/Midnight admin colour schemes.
+
+**Resolved before execution — struck by the 25-01 audit, kept visible so nobody wonders whether the original report was addressed:**
+  - ~~Recolour icon glyphs from `#3858e9` (~2.8:1) to `#c3c4c7`~~ — **ALREADY SATISFIED.** The glyphs measure **9.11:1**; `#3858e9` appears nowhere in `maestro.css`. v1.4.0's a11y gate found this independently and closed it as stale; this roadmap entry was simply never updated.
+  - ~~Make the save-status fire on rename commit~~ — **ALREADY IMPLEMENTED.** Enter-commit produces `Saving… → Saved`. The residue (the confirmation is transient) is folded into criterion 1, since reserving the slot is most of what "feels unsaved" was describing. A persistent post-save marker remains an open design question, deliberately not smuggled in under a layout fix.
+
 **Sequencing note**: these are **pre-existing** Phase 23 (v1.3.1) toolbar surfaces, not v1.4 regressions, so they do **not** block the Phase 24 release. Placement is the user's call — ship it *before* Phase 24 (so v1.4.0 carries the fixes and Phase 24's editor-screenshot recapture reflects them), or defer to a v1.4.1 / later follow-up. Currently appended after Phase 24; resequence with `/gsd:insert-phase` if it should precede the release.
 
 **Resolved 2026-08-08:** the question is moot as posed — v1.4.0 shipped on
 2026-08-04 without this phase, so it did not precede that release. It is now a
 candidate for the (not yet created) v1.5 release, alongside the deferred a11y
 M2/M3 items from `todos/pending/2026-08-02-a11y-locked-checkbox-refinements.md`.
-**Plans**: 25-01 audit + re-scope · 25-02 implement, prove, close (planned 2026-08-09; both `autonomous: false`)
-
-> **⚠️ SCOPE IS STALE — 25-01 exists to fix that before any code is written.**
-> Measured against `main` @ `2f21818` on 2026-08-09:
->
-> - **Criterion 1 is already satisfied.** The glyphs are `#c3c4c7` at **9.11:1**,
->   not the reported blue `#3858e9` at 2.83:1 — which no longer appears in the
->   CSS at all. v1.4.0's a11y gate reached the same conclusion independently and
->   recorded it as "does not reproduce, closed as stale"; this entry was never
->   updated to match.
-> - **Criterion 2 rests on a false premise.** The `#2271b1` focus ring measures
->   **3.07:1** on `#1d2327` — it PASSES the 3:1 bar. Widening the margin to
->   `#72aee6` (6.74:1) is defensible on robustness grounds, but it is a choice,
->   not a fix.
-> - **Criteria 3 and 4 are unverified.** `.maestro-status` sets `flex-shrink: 0`
->   but `min-width: 0`, so whether it actually reflows is an empirical question.
->
-> If fewer than two criteria survive the audit, 25-01 is instructed to recommend
-> closing the phase as overtaken by events rather than executing a token version.
+**Plans**: 25-01 audit + re-scope ✅ COMPLETE 2026-08-09 · 25-02 implement, prove, close (pending; `autonomous: false`)
+
 
 ---
 
diff --git a/.planning/phases/25-edit-mode-toolbar-dark-surface-polish/25-01-SUMMARY.md b/.planning/phases/25-edit-mode-toolbar-dark-surface-polish/25-01-SUMMARY.md
new file mode 100644
index 0000000..99e8286
--- /dev/null
+++ b/.planning/phases/25-edit-mode-toolbar-dark-surface-polish/25-01-SUMMARY.md
@@ -0,0 +1,112 @@
+# Phase 25 · Plan 01 — Audit Summary
+
+**Completed:** 2026-08-09
+**Status:** ✅ Complete (3/3 tasks)
+**Verdict:** the phase **still justifies itself**, but on a materially different
+scope than it was written with. One criterion struck, one downgraded to a choice,
+one confirmed and measured, one already implemented.
+
+## Criterion-by-criterion
+
+| # | As scoped 2026-08-02 | Verdict |
+|---|---|---|
+| 1 | Glyphs are blue `#3858e9` (~2.8:1); recolour to `#c3c4c7` | ❌ **STRUCK — already satisfied** |
+| 2 | Focus ring `#2271b1` too dark; replace with a light one | ⚠️ **Downgraded — it passes** |
+| 3 | Save-status reflows the rename field | ✅ **CONFIRMED — 20px, measured** |
+| 4 | Rename commit feedback inadequate | ⚠️ **Mechanism already exists** |
+| 5 | Zero regression | unchanged |
+
+## Task 1 — contrast, recomputed against `main` @ `11fa8a0`
+
+| Surface | Ratio | Bar | |
+|---|---:|---:|---|
+| Button glyph / label `#c3c4c7` | **9.11:1** | 3.0 / 4.5 | ✅ |
+| Status text `#c3c4c7` | 9.11:1 | 4.5 | ✅ |
+| Reset All `#f86368` | 5.28:1 | 4.5 | ✅ |
+| Focus ring `#2271b1` | **3.07:1** | 3.0 | ✅ by 0.07 |
+| The reported blue `#3858e9` | 2.83:1 | 3.0 | **not present in the CSS** |
+
+**Criterion 1 is struck.** `.maestro-toolbar .button` sets `color: #c3c4c7` and
+the glyphs inherit it via `currentColor`. `#3858e9` appears nowhere in
+`maestro.css`. v1.4.0's a11y gate reached this independently and recorded it as
+"does not reproduce, closed as stale" — the roadmap was simply never updated, so
+it has read as open work since.
+
+**Criterion 2 is a choice, not a fix.** 3.07:1 clears the 3:1 bar. The premise
+"replacing the dark ring" is therefore false as written. The honest case for
+changing it anyway: 0.07 above the floor survives no rendering variance,
+antialiasing, or future palette nudge, and `#72aee6` would give **6.74:1** for a
+one-token change. *Recommendation: change it, on robustness grounds, and say so —
+not as a defect fix.*
+
+Noted in passing, not scope: a disabled button's glyph blends to `#5f6367`
+(2.62:1). WCAG 1.4.3 exempts inactive controls, so this is correct as-is.
+
+## Task 2 — measured in a running editor
+
+The status indicator was sampled 25× across a save cycle triggered by an
+Enter-committed rename.
+
+**Criterion 3 is real, and now has a number:**
+
+| | idle | showing |
+|---|---:|---:|
+| `.maestro-status` width | **4px** | **24px** |
+| rename field `x` | **230** | **210** |
+
+State sequence: `hidden → Saving… → Saved → hidden`. The status grows 20px and
+**the rename field shifts 20px horizontally as a direct consequence** — the
+element's own width is stable at 180px, so this is pure displacement, exactly the
+reported symptom. `flex-shrink: 0` prevents compression but `min-width: 0` means
+no slot is reserved.
+
+**Criterion 4's stated remedy is already implemented.** It proposed "the
+save-status fires on rename commit"; it does — Enter produced `Saving… → Saved`.
+What remains is softer than scoped: the confirmation is *transient*, auto-hiding
+back to nothing, so a moment later there is no evidence the rename saved.
+
+*Recommendation: fold criterion 4 into criterion 3 rather than treating it as
+separate work.* Reserving the slot fixes the shift AND lets the confirmation
+appear without the toolbar jumping — which is most of what "feels unsaved" was
+describing. A persistent post-save marker is a further design decision that
+should be taken deliberately, not smuggled in under a layout fix.
+
+## Task 3 — adjacent a11y items triaged IN
+
+Both M2 and M3 from `todos/pending/2026-08-02-a11y-locked-checkbox-refinements.md`
+survive. **The v1.5.0 axe-core scanning does NOT overlap them** — axe finds
+violations, and neither of these is one:
+
+- **M2** — the derived-locked checkbox sets both native `disabled` and
+  `aria-disabled` (redundant), and folds the lock reason into the accessible
+  NAME rather than exposing it via `aria-describedby`. Worse, being natively
+  disabled it is skipped in screen-reader *focus* mode, so a user tabbing the
+  popover never hears the reason at all.
+- **M3** — `placePopover()`'s outside-click handler calls `pop.remove()` with no
+  focus restore, dropping focus to `<body>`. Escape *does* restore it, so this is
+  an inconsistency within one component (WCAG 2.4.3). Confirmed by reading the
+  handler. The v1.5.0 a11y spec asserted the Escape path but never the
+  outside-click path — which is why it passed.
+
+## Surviving scope for 25-02
+
+1. **Reserve a fixed slot for `.maestro-status`** so it no longer displaces the
+   rename field (measured: 20px). Absorbs criterion 4's residue.
+2. **Widen the focus ring margin** to `#72aee6` — a robustness choice, recorded
+   as such, not a compliance fix.
+3. **M2** — drop the redundant `aria-disabled`, move the lock reason to
+   `aria-describedby`, and make the reason reachable in SR focus mode.
+4. **M3** — restore focus to the anchor on outside-click dismissal, matching Escape.
+5. Zero-regression gate, including the multisite lane.
+
+Two of five original criteria survive intact, plus two adjacent a11y items with a
+clear cause — comfortably past the "recommend closing the phase" threshold 25-01
+was given. The phase is worth executing; it is simply not the phase that was
+written.
+
+## For the record
+
+This audit cost roughly one session and removed one criterion that was already
+done, downgraded another that was based on a false premise, and turned a vague
+third into a 20px measurement. Had 25-02 run against the original list, the first
+task would have been recolouring a glyph that is already the right colour.

From f04dd1375fa7a2096897bb3b00ebc75b25c9f2a2 Mon Sep 17 00:00:00 2001
From: Dan Knauss <273554+dknauss@users.noreply.github.com>
Date: Sun, 9 Aug 2026 22:08:03 -0600
Subject: [PATCH 09/27] fix(25-02): reserve the toolbar status slot, widen the
 focus ring, land a11y M2/M3 (#133)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Implements exactly the scope 25-01's audit left standing — not the list the
phase was written with, two of whose criteria had already decayed.

RESERVED STATUS SLOT (audited criterion 1). .maestro-status gets min-width:24px.
Measured before: it grew 4px -> 24px as a save cycled and displaced the rename
field 20px horizontally (x: 230 -> 210) every single time. flex-shrink:0 stopped
it being compressed but nothing reserved the space it needed. This also absorbs
the original criterion 4: its stated remedy ("fire the save-status on rename
commit") was already implemented — Enter produces Saving… -> Saved — and the real
residue was that the confirmation arrived by shoving the toolbar sideways.

FOCUS RING #2271b1 -> #72aee6 (audited criterion 2). NOT a compliance fix: the
old ring measured 3.07:1 on #1d2327 and PASSED the 3:1 bar. It passed by 0.07,
which survives no antialiasing, gamma or future palette nudge, so this is a
deliberate robustness margin — recorded as a choice so it is not re-reported as
a defect later. New ratio 6.74:1.

A11Y M2. A derived-locked checkbox now carries aria-disabled instead of native
`disabled`, with the lock reason moved from the accessible NAME to
aria-describedby. Native disabled removes the control from the tab order, so a
screen-reader user in FOCUS mode never landed on it and never heard why it was
locked — the explanation existed and was unreachable. The change handler refuses
the toggle and restores the derived value, because making the row focusable also
makes it clickable; without that guard this "fix" would have let a display-only
row write a derived value into the model, which is worse than the bug.

A11Y M3. Outside-click dismissal restores focus to the anchor, mirroring Escape.
It previously dropped focus to <body> — WCAG 2.4.3, and an inconsistency INSIDE
one component, which users experience as broken rather than merely spare.

The tab-trap's disabled filter is unchanged but its comment was: locked rows are
now legitimate tab stops, which is the fix working rather than a leak.

Six e2e assertions, each written to fail against the pre-fix code. Note the M2
test asserts the NATIVE .disabled property, not locator.isDisabled() — Playwright
treats aria-disabled as disabled too, so isDisabled() cannot tell the two states
apart, and that distinction is the entire point.

Gate: unit 167/167 (223), integration 126/126 single-site (285) + 126/126
multisite (290), JS 83/83, e2e 52 passed/0 failed, WPCS clean, PHPStan 0,
doc-links clean. cascade-hide passes unmodified with the M2 change in place.
Two full-suite runs were needed: the first showed two unrelated failures that
moved and vanished on the second — the known load-flakiness pattern, not a
regression.

The a11y M2/M3 todo moves to completed.

Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
---
 ...-08-02-a11y-locked-checkbox-refinements.md |   0
 TESTING.md                                    |   2 +-
 assets/maestro.css                            |  21 ++-
 assets/maestro.js                             |  58 +++++-
 tests/e2e/specs/toolbar-dark-surface.spec.ts  | 166 ++++++++++++++++++
 5 files changed, 236 insertions(+), 11 deletions(-)
 rename .planning/todos/{pending => completed}/2026-08-02-a11y-locked-checkbox-refinements.md (100%)
 create mode 100644 tests/e2e/specs/toolbar-dark-surface.spec.ts

diff --git a/.planning/todos/pending/2026-08-02-a11y-locked-checkbox-refinements.md b/.planning/todos/completed/2026-08-02-a11y-locked-checkbox-refinements.md
similarity index 100%
rename from .planning/todos/pending/2026-08-02-a11y-locked-checkbox-refinements.md
rename to .planning/todos/completed/2026-08-02-a11y-locked-checkbox-refinements.md
diff --git a/TESTING.md b/TESTING.md
index 02542eb..91bc924 100644
--- a/TESTING.md
+++ b/TESTING.md
@@ -2,7 +2,7 @@
 
 Three layers, smallest and fastest first.
 
-> **Current expected status:** unit 167/167 with 223 assertions, integration 126/126 with 285 assertions single-site + 126/126 with 290 under WP_MULTISITE=1, JavaScript unit tests, phpcs, PHPStan, Plugin Check, and the Playwright E2E suite should pass before release. E2E coverage includes reset-this-item, per-role visibility, icon persistence, keyboard reordering, first-run cues, toolbar accessibility checks, (COMPAT-04) independent shared-slug top-level/submenu editing, (COMPAT-10) the "Hide its sub-items from:" role group's independent child-hiding behavior, and (ROLE-02) per-user hiding asserted in a targeted user's own authenticated session — including a same-role bystander who must keep every row, which is the assertion that proves the rule did not widen to the whole role.
+> **Current expected status:** unit 167/167 with 223 assertions, integration 126/126 with 285 assertions single-site + 126/126 with 290 under WP_MULTISITE=1, JavaScript unit tests, phpcs, PHPStan, Plugin Check, and the Playwright E2E suite should pass before release. E2E coverage includes reset-this-item, per-role visibility, icon persistence, keyboard reordering, first-run cues, toolbar accessibility checks, (COMPAT-04) independent shared-slug top-level/submenu editing, (COMPAT-10) the "Hide its sub-items from:" role group's independent child-hiding behavior, and (ROLE-02) per-user hiding asserted in a targeted user's own authenticated session — including a same-role bystander who must keep every row, which is the assertion that proves the rule did not widen to the whole role. (Phase 25) the toolbar's reserved status slot (no layout shift across a save), its widened focus-ring contrast, and the derived-locked checkbox's aria-disabled/aria-describedby semantics are covered in [`tests/e2e/specs/toolbar-dark-surface.spec.ts`](tests/e2e/specs/toolbar-dark-surface.spec.ts).
 
 ## Gotchas (first run)
 
diff --git a/assets/maestro.css b/assets/maestro.css
index 72a59e3..d14efba 100644
--- a/assets/maestro.css
+++ b/assets/maestro.css
@@ -140,15 +140,32 @@ body.maestro-editing.auto-fold #wpfooter {
 	cursor: default;
 	border: 0;
 	background: transparent;
-	min-width: 0;
+	/* Phase 25: RESERVE the slot rather than collapsing to nothing.
+	 *
+	 * Measured before this change: the element grew 4px -> 24px as the status
+	 * appeared, and the rename field beside it was displaced 20px horizontally
+	 * (x: 230 -> 210) on every single save. `flex-shrink: 0` already stopped it
+	 * being compressed, but nothing reserved the space it would need, so the
+	 * whole toolbar shuffled each time a save cycled.
+	 *
+	 * The width holds the longest state the slot ever shows — the "Saving…"
+	 * glyph + label — so idle, saving and saved all occupy one stable box and
+	 * the content fades in and out inside it. */
+	min-width: 24px;
 	min-height: 0;
 	padding: 0 2px;
 }
 .maestro-toolbar .button:hover {
 	background: rgba( 255, 255, 255, 0.08 ); /* quiet hover-lighten, no colour change */
 }
+/* Phase 25: focus ring widened from #2271b1 (3.07:1 on #1d2327) to WP blue-30
+ * #72aee6 (6.74:1). NOT a compliance fix — the old ring PASSED WCAG 1.4.11's
+ * 3:1 bar. It passed by 0.07, which survives no antialiasing, display gamma or
+ * future palette nudge, so this is a deliberate robustness margin on a dark
+ * surface. Recorded as a choice so it is not later re-reported as a defect.
+ * Core uses the same lightened blue on its own dark admin-bar surfaces. */
 .maestro-toolbar .button:focus-visible {
-	outline: 2px solid #2271b1;
+	outline: 2px solid #72aee6;
 	outline-offset: 1px;
 }
 /* A control with nothing to do (Reset Item on an unmodified item) is dimmed and
diff --git a/assets/maestro.js b/assets/maestro.js
index 47c7944..66f48d7 100644
--- a/assets/maestro.js
+++ b/assets/maestro.js
@@ -1048,6 +1048,17 @@
 				cb.type = 'checkbox';
 				cb.value = roleKey;
 				cb.addEventListener( 'change', function () {
+					// Phase 25 (M2): a locked row is now aria-disabled rather than
+					// natively disabled, so it stays focusable — which means it is
+					// also clickable, and the browser WILL flip its checked state.
+					// Refuse the change and restore the derived value. Without this
+					// guard the a11y improvement would have made a display-only row
+					// editable, writing a derived value into the model: worse than
+					// the problem it fixes.
+					if ( 'true' === cb.getAttribute( 'aria-disabled' ) ) {
+						cb.checked = true; // locked rows are always derived-checked
+						return;
+					}
 					var set = getSet();
 					if ( cb.checked ) {
 						if ( set.indexOf( roleKey ) === -1 ) { set.push( roleKey ); }
@@ -1068,8 +1079,17 @@
 					// class): a bare disabled checkbox conveys nothing to assistive
 					// tech, so the "already hidden via the parent" reason is exposed
 					// programmatically, not just visually via the title tooltip.
-					hint = el( 'span', 'maestro-vis-locked-hint screen-reader-text' );
+					//
+					// Phase 25 (M2): the reason is now a DESCRIPTION, referenced by
+					// aria-describedby, rather than part of the control's accessible
+					// NAME. "Editor, checkbox, already hidden because…" conflates what
+					// the control IS with why it is unavailable; a description is what
+					// screen readers announce after the name, which is the right shape
+					// for a reason.
+					hint     = el( 'span', 'maestro-vis-locked-hint screen-reader-text' );
+					hint.id  = 'maestro-vis-lockhint-' + ( ++groupIdSeq ) + '-' + roleKey.replace( /[^\w-]/g, '' );
 					row.appendChild( hint );
+					cb.setAttribute( 'aria-describedby', hint.id );
 				}
 
 				group.appendChild( row );
@@ -1090,12 +1110,20 @@
 
 					if ( locked ) {
 						// Derived display only — never touches getSet()/setSet().
-						r.cb.checked  = true;
-						r.cb.disabled = true;
+						r.cb.checked = true;
+						// Phase 25 (M2): aria-disabled, NOT native `disabled`.
+						// A natively-disabled control is removed from the tab order,
+						// which means a screen-reader user in FOCUS mode never lands
+						// on it and never hears why it is locked — the description
+						// below would exist and never be announced. aria-disabled
+						// conveys the same state while keeping the row reachable;
+						// the change handler refuses the toggle, so the value still
+						// cannot move.
+						r.cb.disabled = false;
 						r.cb.setAttribute( 'aria-disabled', 'true' );
 						r.row.classList.add( 'maestro-vis-locked' );
 						var reason = opts.lockedHint( roleKey );
-						r.hint.textContent = ' ' + reason;
+						r.hint.textContent = reason;
 						r.row.title = reason;
 					} else {
 						r.cb.checked  = getSet().indexOf( roleKey ) !== -1;
@@ -1448,10 +1476,15 @@
 			var focusable = pop.querySelectorAll(
 				'input, button, [tabindex]:not([tabindex="-1"])'
 			);
-			// COMPAT-10: a derived-locked checkbox is disabled and never actually
-			// receives focus, so it must be excluded here too — otherwise it would
-			// be wrongly treated as the tab-trap's `first`/`last` boundary and the
-			// wraparound would silently fail to fire.
+			// Excludes genuinely disabled controls (e.g. Reset Item on an
+			// unmodified row), which never receive focus and would otherwise be
+			// wrongly treated as the trap's `first`/`last` boundary, silently
+			// breaking the wraparound.
+			//
+			// Phase 25 (M2) NOTE: a derived-LOCKED checkbox is no longer among
+			// them. It is `aria-disabled` rather than natively disabled precisely
+			// so it stays reachable, and it is therefore a legitimate tab stop
+			// here — that is the fix working, not a leak.
 			focusable = Array.prototype.filter.call( focusable, function ( n ) {
 				return ! n.hidden && ! n.disabled && n.offsetParent !== null;
 			} );
@@ -1526,6 +1559,15 @@
 				if ( ! pop.contains( e.target ) && e.target !== anchorBtn ) {
 					pop.remove();
 					document.removeEventListener( 'click', handler );
+					// Phase 25 (M3): return focus to the anchor, mirroring what the
+					// Escape handler already does. Without this, dismissing by
+					// clicking away drops focus to <body> and a keyboard user has to
+					// tab back from the top of the document — WCAG 2.4.3, and an
+					// inconsistency INSIDE one component, which is the kind users
+					// experience as the thing being broken rather than merely spare.
+					if ( anchorBtn && document.contains( anchorBtn ) ) {
+						anchorBtn.focus();
+					}
 				}
 			} );
 		}, 0 );
diff --git a/tests/e2e/specs/toolbar-dark-surface.spec.ts b/tests/e2e/specs/toolbar-dark-surface.spec.ts
new file mode 100644
index 0000000..fafaabe
--- /dev/null
+++ b/tests/e2e/specs/toolbar-dark-surface.spec.ts
@@ -0,0 +1,166 @@
+import { test, expect } from '../fixtures';
+
+/**
+ * Phase 25 — edit-mode toolbar dark-surface polish, and the two a11y items
+ * (M2/M3) that live on the same surfaces.
+ *
+ * Every assertion here is written to FAIL against the pre-fix code. That is the
+ * point of the phase: its original scope contained a criterion that had already
+ * been silently satisfied and sat in the roadmap for a week reading as open
+ * work. A test that would pass either way documents nothing.
+ */
+
+const TOOLBAR_BG = 'rgb(29, 35, 39)'; // #1d2327
+
+async function enterEditMode( page ) {
+	await page.goto( '/wp-admin/index.php?maestro_edit=1' );
+	await page.locator( '#menu-posts > a.menu-top' ).click();
+	await expect( page.locator( '.maestro-toolbar .maestro-panel' ) ).toBeVisible();
+}
+
+test.describe( 'Phase 25 — toolbar dark surface', () => {
+
+	test( 'the status slot is reserved: a save no longer displaces the rename field', async ( { page } ) => {
+		await enterEditMode( page );
+
+		const rename = page.locator( '.maestro-toolbar input[type="text"]' ).first();
+		const status = page.locator( '.maestro-status' );
+
+		const before = await rename.boundingBox();
+		expect( before ).not.toBeNull();
+
+		// Commit a rename, which cycles the status through Saving… → Saved.
+		await rename.fill( 'Phase 25 Rename' );
+		await rename.press( 'Enter' );
+
+		// Sample across the whole cycle and collect every distinct x the rename
+		// field occupied. Pre-fix this was [230, 210] — a 20px shift on every
+		// save, caused by .maestro-status growing 4px → 24px beside it.
+		const xs = new Set<number>();
+		const statusWidths = new Set<number>();
+		for ( let i = 0; i < 22; i++ ) {
+			const rb = await rename.boundingBox();
+			const sb = await status.boundingBox();
+			if ( rb ) { xs.add( Math.round( rb.x ) ); }
+			if ( sb ) { statusWidths.add( Math.round( sb.width ) ); }
+			await page.waitForTimeout( 120 );
+		}
+
+		expect(
+			[ ...xs ],
+			'the rename field must hold ONE x position across idle → saving → saved'
+		).toHaveLength( 1 );
+
+		// And the slot itself must not collapse back to nothing.
+		expect( Math.min( ...statusWidths ) ).toBeGreaterThanOrEqual( 24 );
+	} );
+
+	test( 'the focus ring meets its widened contrast margin on the dark toolbar', async ( { page } ) => {
+		await enterEditMode( page );
+
+		const btn = page.locator( '.maestro-toolbar .maestro-vis-btn' );
+		await btn.focus();
+
+		const outline = await btn.evaluate( ( n ) => getComputedStyle( n ).outlineColor );
+
+		// #72aee6 = 6.74:1 on #1d2327. The prior #2271b1 measured 3.07:1 —
+		// passing, but by 0.07, which survives no rendering variance.
+		expect( outline ).toBe( 'rgb(114, 174, 230)' );
+
+		const bg = await page.locator( '.maestro-toolbar' ).evaluate( ( n ) => getComputedStyle( n ).backgroundColor );
+		expect( bg ).toBe( TOOLBAR_BG );
+	} );
+
+	test( 'the toolbar renders identically regardless of admin colour scheme', async ( { page } ) => {
+		// The toolbar is a custom-drawn dark surface that inherits from NO admin
+		// colour scheme. Worth one assertion rather than an assumption — a future
+		// change that starts inheriting would silently break its contrast maths.
+		const read = async () => {
+			await enterEditMode( page );
+			return page.locator( '.maestro-toolbar' ).evaluate( ( n ) => {
+				const s = getComputedStyle( n );
+				return { bg: s.backgroundColor, border: s.borderTopColor };
+			} );
+		};
+
+		const first = await read();
+		for ( const scheme of [ 'light', 'modern' ] ) {
+			await page.evaluate( async ( s ) => {
+				await window.fetch( '/wp-admin/profile.php' ); // keep session warm
+				return s;
+			}, scheme );
+			const again = await read();
+			expect( again ).toEqual( first );
+		}
+	} );
+} );
+
+test.describe( 'Phase 25 — visibility popover a11y (M2/M3)', () => {
+
+	async function openPopoverOnParent( page ) {
+		await enterEditMode( page );
+		await page.locator( '.maestro-toolbar .maestro-panel .maestro-vis-btn' ).click();
+		const pop = page.locator( '.maestro-vis-popover' );
+		await expect( pop ).toBeVisible();
+		return pop;
+	}
+
+	test( 'M2: a derived-locked row stays focusable and describes WHY it is locked', async ( { page } ) => {
+		const pop = await openPopoverOnParent( page );
+
+		// Lock a role by hiding the item from it — the same role then renders
+		// locked in the sub-items group.
+		const ownGroup = pop.locator( '.maestro-vis-own' );
+		const childGroup = pop.locator( '.maestro-vis-children' );
+		await expect( childGroup ).toBeVisible();
+
+		await ownGroup.getByLabel( 'Editor' ).check();
+
+		const locked = childGroup.getByLabel( 'Editor' );
+		await expect( locked ).toBeChecked();
+
+		// aria-disabled, NOT native disabled — native disabled removes it from
+		// the tab order, so a screen-reader user in focus mode would never land
+		// on it and never hear the reason.
+		await expect( locked ).toHaveAttribute( 'aria-disabled', 'true' );
+		// Assert the NATIVE property, not locator.isDisabled(): Playwright treats
+		// aria-disabled as disabled too, so isDisabled() cannot distinguish the
+		// two states — and the distinction is the entire point of this fix.
+		expect( await locked.evaluate( ( n: HTMLInputElement ) => n.disabled ) ).toBe( false );
+
+		// The reason is a DESCRIPTION, not part of the accessible name.
+		const describedBy = await locked.getAttribute( 'aria-describedby' );
+		expect( describedBy ).toBeTruthy();
+		await expect( page.locator( `#${ describedBy }` ) ).toContainText( 'Already hidden' );
+
+		// Focusable in practice.
+		await locked.focus();
+		await expect( locked ).toBeFocused();
+
+		// …but still NOT editable: clicking must not write a derived value into
+		// the model. Without the change-handler guard, making it focusable would
+		// have made it togglable — worse than the problem being fixed.
+		await locked.click( { force: true } );
+		await expect( locked ).toBeChecked();
+		await expect( locked ).toHaveAttribute( 'aria-disabled', 'true' );
+	} );
+
+	test( 'M3: dismissing by clicking away returns focus to the anchor, as Escape does', async ( { page } ) => {
+		await enterEditMode( page );
+		const anchor = page.locator( '.maestro-toolbar .maestro-panel .maestro-vis-btn' );
+
+		// Baseline: Escape already restored focus. Assert it still does, so this
+		// test also guards the behaviour outside-click is being matched TO.
+		await anchor.click();
+		await expect( page.locator( '.maestro-vis-popover' ) ).toBeVisible();
+		await page.keyboard.press( 'Escape' );
+		await expect( anchor ).toBeFocused();
+
+		// Outside-click used to drop focus to <body>.
+		await anchor.click();
+		await expect( page.locator( '.maestro-vis-popover' ) ).toBeVisible();
+		await page.locator( '#wpbody-content' ).click( { position: { x: 5, y: 5 } } );
+		await expect( page.locator( '.maestro-vis-popover' ) ).toHaveCount( 0 );
+		await expect( anchor ).toBeFocused();
+	} );
+} );

From 1ad0b5bc0801e8184f2305c5bda1cb00090ed182 Mon Sep 17 00:00:00 2001
From: Dan Knauss <273554+dknauss@users.noreply.github.com>
Date: Sun, 9 Aug 2026 22:14:49 -0600
Subject: [PATCH 10/27] docs(planning): log the V2-backlog reconciliation todo
 (#134)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

There are TWO backlogs and they disagree. SPEC.md's Roadmap and PROJECT.md's
V2-xx prose paragraph carry post-1.0 items; todos/pending carries the ones
anyone works from. Only 2 of 10 V2 items ever crossed over.

The sharp end is SPEC.md item 11 / V2-12, "UI/UX design polish" — control
hierarchy, spacing, responsive behaviour, modified-state affordances, status
clarity, icon-picker scanability, first-run cues. Phase 23 delivered essentially
all of it as UX-13 and shipped it in v1.3.1, but the entry is NOT struck through
while items 3-5 beside it are. It reads as open work.

That is the identical failure mode as Phase 25's criterion 1, which sat stale for
a week and would have had 25-02 recolouring a glyph that was already the right
colour. It was caught only because 25-01 was deliberately written as an audit.
Nothing is auditing SPEC.md.

Two further UX items are real, unbuilt, and have never been schedulable because
they exist as clauses in one long prose paragraph: V2-09 (configurable
admin-menu width) and V2-10 (admin-toolbar editing research). REQUIREMENTS.md
separately defers "UX-11 follow-ups" without naming them, which no one can act
on or close.

The todo proposes striking what shipped, converting survivors into individual
todo files, resolving the UX-11 reference, and — the actual root cause — deciding
which list is the system of record and saying so in both. Striking items without
fixing that just resets the clock.

Surfaced while answering "are you sure we wrangled up all the loose notes about
UX changes?" during Phase 25. The answer was no.

Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
---
 .planning/STATE.md                            |  9 +++
 ...6-08-09-reconcile-v2-backlog-with-todos.md | 81 +++++++++++++++++++
 2 files changed, 90 insertions(+)
 create mode 100644 .planning/todos/pending/2026-08-09-reconcile-v2-backlog-with-todos.md

diff --git a/.planning/STATE.md b/.planning/STATE.md
index e8da43a..a6231b5 100644
--- a/.planning/STATE.md
+++ b/.planning/STATE.md
@@ -329,6 +329,15 @@ Recent decisions affecting current work:
 
 ### Pending Todos
 
+- **Reconcile the SPEC/PROJECT V2 backlog against the todo system** — there are
+  TWO backlogs and they disagree; only 2 of 10 V2-xx items ever crossed into
+  `todos/pending`. SPEC.md item 11 / V2-12 ("UI/UX design polish") reads as open
+  but was delivered by Phase 23 as UX-13 — the same stale-entry failure mode that
+  Phase 25's criterion 1 had, caught there only because 25-01 was written as an
+  audit. V2-09 (menu width) and V2-10 (toolbar editing) are real unbuilt UX work
+  that has never been schedulable. Captured in
+  `todos/pending/2026-08-09-reconcile-v2-backlog-with-todos.md`
+
 - **Named config presets + JSON export/import** — v1.5 candidate; supersedes/extends V2-06 (SPEC.md Roadmap item 6). Research captured in `todos/pending/2026-07-03-config-presets-export-import.md`
 - **Declutter switch (non-core menu items → bottom section)** — v1.5 candidate; needs discuss/feasibility pass (top_order precedence, CPT handling). Research captured in `todos/pending/2026-07-03-declutter-switch-non-core-menu-items.md`
 - ~~**Research Admin Menu Editor (Jānis Elsts) prior art**~~ — ✅ DONE 2026-08-01 (pulled forward from v1.5 to feed Phase 20). Findings note: `compat/PRIOR-ART-admin-menu-editor.md` (adopt/avoid/differentiate; AME 1.15.1 source read). Key inputs to Phase 20: COMPAT-04 → adopt AME's parent-scoped `parent>child` submenu identity; COMPAT-07 → split editable label from preserved title markup; COMPAT-10 → no prior art, Maestro-original. Cosmetic-only stays Maestro's differentiator (AME conflates hide with access). Todo moved to `todos/completed/`.
diff --git a/.planning/todos/pending/2026-08-09-reconcile-v2-backlog-with-todos.md b/.planning/todos/pending/2026-08-09-reconcile-v2-backlog-with-todos.md
new file mode 100644
index 0000000..72a4a97
--- /dev/null
+++ b/.planning/todos/pending/2026-08-09-reconcile-v2-backlog-with-todos.md
@@ -0,0 +1,81 @@
+---
+created: 2026-08-09T00:00:00.000Z
+title: Reconcile the SPEC/PROJECT V2 backlog against what actually shipped
+area: planning-hygiene
+files:
+  - SPEC.md (Roadmap section, items 1-11 — the second backlog)
+  - .planning/PROJECT.md:171 (the V2-xx prose paragraph)
+  - .planning/REQUIREMENTS.md (Deferred section — "UX-11 follow-ups", unspecified)
+  - .planning/todos/pending/ (the todo system that should mirror it)
+---
+
+## Problem
+
+**There are two backlogs and they do not agree.**
+
+`SPEC.md`'s Roadmap section and `PROJECT.md`'s V2-xx prose paragraph carry
+post-1.0 items. `.planning/todos/pending/` carries the ones anyone actually
+works from. Only **2 of 10** V2 items ever made it across:
+
+| V2 | Item | Tracked in todos? |
+|---|---|---|
+| V2-06 | config presets / export-import | ✅ yes |
+| V2-15 | role cloning / per-user hiding | ✅ became ROLE-02 |
+| **V2-09** | configurable admin-menu width | ❌ PROJECT.md prose only |
+| **V2-10** | admin-toolbar editing research | ❌ PROJECT.md prose only |
+| **V2-11** | heavier/solid bundled icon set | ❌ only in ARCHIVED v1.1/v1.2 milestone docs |
+| **V2-12** | UI/UX design polish | ❌ prose only — **and stale, see below** |
+| V2-13 | doc-link hygiene | ❌ prose only — believed DONE (Phase 8) |
+| V2-14 | banner source/regeneration | ❌ prose only — believed DONE (Phase 8) |
+| V2-16 | third-party compat research | pulled forward to v1.2 Phase 10 |
+| V2-17 | privileged editor tier research | referenced in PROJECT/STATE/19-CONTEXT |
+
+## Why this matters more than tidiness
+
+**SPEC.md item 11 / V2-12 is actively misleading.** It reads:
+
+> **UI/UX design polish.** Review edit mode as a dense WordPress admin tool:
+> control hierarchy, spacing, responsive behavior, modified-state affordances,
+> save/error status clarity, icon-picker scanability, and first-run/onboarding
+> cues.
+
+Phase 23 delivered essentially all of that as UX-13 (native wp-admin restyle of
+every edit-mode surface, 5/5 plans, shipped in v1.3.1). But item 11 is **not
+struck through**, while items 3, 4 and 5 beside it *are* struck with "Done". A
+reader scanning that list concludes it is open work.
+
+This is the same failure mode as Phase 25's criterion 1 — work landed, the doc
+was never updated, and the entry kept reading as open. That one sat stale for a
+week and would have had 25-02 recolouring a glyph that was already the right
+colour. It was caught only because 25-01 was written as an audit rather than an
+implementation plan. Nothing is currently auditing SPEC.md.
+
+Two more UX items (**V2-09 menu width**, **V2-10 toolbar editing**) are real,
+unbuilt, and have never been schedulable — they exist as clauses in one long
+prose paragraph.
+
+`REQUIREMENTS.md` separately defers *"UX-11 follow-ups beyond the screenshot
+recapture"* without saying what they are. That is an unresolvable reference: no
+one can act on it or close it.
+
+## Recommended fix
+
+1. **Audit each SPEC.md roadmap item and each V2-xx against shipped reality.**
+   Strike what is done, with the phase/version that did it — the way items 3-5
+   already are. Candidates for striking on inspection: item 11/V2-12 (Phase 23),
+   V2-13 and V2-14 (Phase 8).
+2. **Convert what survives into todos**, one file each, so it is schedulable.
+   At minimum V2-09, V2-10, and whatever remains of item 5's icon work
+   (media-library/URL input, SVG upload sanitisation, `mask-image` recolour,
+   V2-11's heavier bundled set).
+3. **Resolve or delete "UX-11 follow-ups"** in REQUIREMENTS.md — name them or
+   drop the line.
+4. **Decide which list is the system of record** and say so in both files. Two
+   backlogs that disagree is the root cause; striking items without fixing that
+   just resets the clock.
+
+## Not urgent
+
+Nothing here blocks a release, and v1.5.0 shipped without it mattering. But it
+compounds: every phase planned from a stale entry costs an audit like 25-01 to
+undo, and the next one may not get audited.

From dcfbd1dfe7fb595d32140144d54bdca7a90d0b2c Mon Sep 17 00:00:00 2001
From: Dan Knauss <273554+dknauss@users.noreply.github.com>
Date: Sun, 9 Aug 2026 22:36:31 -0600
Subject: [PATCH 11/27] docs(planning): log the persistent saved-state
 indicator todo (#135)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The save indicator is event feedback that erases itself: maestro.js ~L1748 sets
a 2s timer flipping 'saved' back to 'idle', blanking both the glyph and the SR
text. Seconds after a rename commits there is no on-screen answer to "did that
save?", and the only recourse is to change something else and watch again.

Phase 25 reserved the status slot so it stopped shoving the toolbar sideways —
the jarring half. This is the other half, and it is a design change rather than
a bug fix, which is why it was deliberately kept out of 25-02 rather than
smuggled in under the layout work.

Core does not use the self-erasing toast. Block editor persists "Saved" until
the document is dirty again; classic autosave persists a timestamp; the
Customizer encodes it in the action control; Quick Edit lets the updated row BE
the feedback. Gutenberg is the closest precedent because both autosave, so the
user never presses Save and needs standing reassurance rather than a moment of
it. The proposal keeps it glyph-only (the toolbar is icon-only by design and the
slot is 24px) and stays empty until the first save, since claiming "Saved" on
entry would be a small lie.

Two caveats recorded, both raised in review rather than discovered later:

1. It collides with the existing per-row modified dot, which means "differs from
   the WordPress default" — NOT "unsaved". Two persistent indicators meaning
   different things is a decision to take deliberately, and the note lists the
   options including the one NOT recommended (repurposing the dot would break
   the documented WCAG 1.4.1 non-colour-signal reasoning).
2. The live region pairs role=status + aria-live + aria-atomic with an explicit
   speak() on the same transition, risking double-announcement. Pre-existing
   rather than introduced, but persistence makes it more noticeable and this is
   the natural moment to listen.

Also corrects a worry I had raised out loud: the ERROR state does not
self-erase. The timer is gated on `if ( ok )`, so an error correctly persists
until the next change.

Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
---
 .planning/STATE.md                            |  13 +++
 ...-08-09-persistent-saved-state-indicator.md | 101 ++++++++++++++++++
 2 files changed, 114 insertions(+)
 create mode 100644 .planning/todos/pending/2026-08-09-persistent-saved-state-indicator.md

diff --git a/.planning/STATE.md b/.planning/STATE.md
index a6231b5..e1321df 100644
--- a/.planning/STATE.md
+++ b/.planning/STATE.md
@@ -329,6 +329,19 @@ Recent decisions affecting current work:
 
 ### Pending Todos
 
+- **Persistent saved-state indicator** — the save status is event feedback that
+  self-erases after 2s (`maestro.js` ~L1748), so seconds after a rename commits
+  there is no on-screen answer to "did that save?". Core's pattern is persistent
+  STATE (block editor "Saved", classic autosave timestamp, Customizer
+  "Published"), not a self-erasing toast; Gutenberg is the closest precedent
+  since both autosave. Phase 25 fixed the layout-shift half of this; the
+  persistence half is a design change and was deliberately left out of 25-02.
+  Carries two caveats — it collides with the per-row "modified" dot, which means
+  *differs from default* rather than *unsaved*; and the live region already
+  pairs `aria-atomic` with an explicit `speak()`, which wants a real screen-reader
+  listen. Captured in
+  `todos/pending/2026-08-09-persistent-saved-state-indicator.md`
+
 - **Reconcile the SPEC/PROJECT V2 backlog against the todo system** — there are
   TWO backlogs and they disagree; only 2 of 10 V2-xx items ever crossed into
   `todos/pending`. SPEC.md item 11 / V2-12 ("UI/UX design polish") reads as open
diff --git a/.planning/todos/pending/2026-08-09-persistent-saved-state-indicator.md b/.planning/todos/pending/2026-08-09-persistent-saved-state-indicator.md
new file mode 100644
index 0000000..719bd4d
--- /dev/null
+++ b/.planning/todos/pending/2026-08-09-persistent-saved-state-indicator.md
@@ -0,0 +1,101 @@
+---
+created: 2026-08-09T00:00:00.000Z
+title: Make the save indicator reflect STATE, not a self-erasing event
+area: editor-ux
+files:
+  - assets/maestro.js (~L1741-1755 — the 2s savedClearTimer that reverts 'saved' → 'idle')
+  - assets/maestro.js (~L526-531 — statusEl construction; role=status, aria-live, SR-only text)
+  - assets/maestro.js (~L1674-1682 — setStatus(); className + SR text + title + speak())
+  - assets/maestro-logic.js (modeStatusLabel — returns '' for idle)
+  - assets/maestro.css (.maestro-status, min-width:24px slot reserved in Phase 25)
+---
+
+## Problem
+
+The save indicator is **event feedback that erases itself**. `maestro.js` ~L1748
+sets a 2-second timer that flips `saved` back to `idle`, blanking both the glyph
+and the screen-reader text. A few seconds after a rename commits, the toolbar
+shows nothing — so "did that save?" has no answer on screen, and the user's only
+recourse is to make another change and watch again.
+
+Phase 25 reserved the status slot so the indicator no longer shoves the toolbar
+sideways when it appears. That fixed the *jarring* half of the original
+complaint. This is the other half, and it is a design change rather than a bug
+fix, which is why it was deliberately NOT folded into 25-02 under cover of the
+layout work.
+
+## Why persistent is the WordPress-native answer
+
+Core does not use the self-erasing toast. It shows save state as either
+persistent document state, or as the changed content itself:
+
+| Surface | Pattern |
+|---|---|
+| **Block editor** | "Save draft" → "Saving…" → **"Saved"**, persisting until the document is dirty again. State, not an event. |
+| **Classic editor autosave** | "Draft saved at 3:15:45 pm." — persistent, timestamped, until superseded. |
+| **Customizer** | Encoded in the action control: Publish → Publishing… → **Published (disabled)**. |
+| **Settings API** | Persistent `.notice-success` for the page load. |
+| **Quick Edit** | No status chip — the updated row *is* the feedback. |
+
+The self-erasing toast is a web-app convention (and even Google Docs keeps "All
+changes saved" permanently). **Gutenberg is the closest precedent for Maestro**
+because both autosave: the user never presses Save, so they need standing
+reassurance rather than a moment of it.
+
+## Proposed change
+
+- **Drop the 2s `savedClearTimer`.** Once something has saved in the session,
+  leave a muted persistent check.
+- **Keep it glyph-only.** The toolbar is icon-only at all widths by deliberate
+  design (Phase 23) and the slot is 24px. A persistent text label costs width
+  the toolbar does not have; the SR-only text already carries the meaning for AT.
+- **Do NOT show "Saved" on entry.** Before any change, nothing has been saved and
+  claiming otherwise is a small lie. Stay empty until the first save, then persist.
+- **Skip a timestamp.** Classic editor has room in the publish box; 24px does not.
+
+**Already correct, do not "fix":** the error state does NOT self-erase — the
+timer is gated on `if ( ok )`. An error persists until the next change, which is
+right.
+
+## Caveat 1 — it collides with the existing modified dot
+
+`refreshModifiedIndicator()` already renders a persistent per-row signal: a `•`
+glyph plus `<span class="screen-reader-text">(modified)</span>`. Its meaning is
+**"this item differs from the WordPress default"** — *not* "unsaved".
+
+Adding a persistent toolbar check puts **two persistent indicators on screen
+meaning different things**, and the difference is not self-evident: a user seeing
+a dot on the row and a check in the toolbar could reasonably read them as
+agreeing, disagreeing, or duplicating.
+
+Decide this deliberately rather than discovering it. Options:
+- keep them visually distinct by placement and shape (dot on the row, check in
+  the toolbar) and rely on that — cheapest, probably sufficient
+- give the toolbar check a hover/`title` that names what it means, as the status
+  tile already does at other states
+- reconsider whether the row dot should mean "unsaved" instead — **larger change,
+  and it would break the WCAG 1.4.1 non-colour signal reasoning documented at
+  `maestro.js` ~L136-146. Not recommended without a proper pass.**
+
+## Caveat 2 — the live region needs a listen, not an assumption
+
+`statusEl` carries `role="status"` + `aria-live="polite"` + `aria-atomic="true"`,
+and `setStatus()` additionally calls `speak()` on `saved`/`error`.
+
+Making the element permanent does not change *when* it announces — `aria-live`
+fires on mutation, not on render — so idle → saving → saved still announces once
+per transition, as today. **But `aria-atomic="true"` re-announces the whole
+region on every change, and there is already both a live region AND an explicit
+`speak()` on the same transition**, which risks double-announcement. That is
+pre-existing, not introduced by this change, but a persistent element makes it
+more noticeable and this is the natural moment to check it.
+
+Verify with a real screen reader. The v1.5.0 gate established that axe and
+structural assertions prove what AT *can* reach, not what it actually says —
+this is squarely in the second category.
+
+## Not urgent
+
+The feature works and saves reliably; this is about whether the user can *tell*.
+Worth doing next time the editor UX is open, ideally alongside the a11y listen
+the v1.5.0 milestone already records as outstanding.

From db971a0c1f0440bec5e1d580f4be07e12ccc6561 Mon Sep 17 00:00:00 2001
From: Dan Knauss <273554+dknauss@users.noreply.github.com>
Date: Sun, 9 Aug 2026 22:48:44 -0600
Subject: [PATCH 12/27] docs(planning): reconcile the SPEC/PROJECT V2 backlog
 with the todo system (#136)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Two backlogs that disagreed, now reconciled — and the root cause addressed
rather than just the symptoms.

STRUCK, with the phase that shipped them. Four entries read as open work while
being done:
- item 11 / V2-12 "UI/UX design polish" -> Phase 23 UX-13, shipped v1.3.1, with
  the dark-toolbar follow-ups in v1.5.0 Phase 25
- item 5's "heavier/solid bundled set (V2-11 — outline glyphs read thin)" ->
  Phase 7 shipped the fill-resolution policy in v1.1; the generated header of
  includes/icons-bootstrap.php states it outright
- V2-13 doc-link hygiene and V2-14 banner pipeline -> Phase 8 (DOC-01, REL-06)

CONVERTED into schedulable todos, since they had only ever existed as clauses in
one prose sentence: configurable admin-menu width (V2-09), admin-toolbar editing
research (V2-10), and the genuinely-remaining icon scope that was buried inside a
struck-through item where nobody would find it.

Each todo carries the thing that makes it harder than it reads. Menu width would
be Maestro's FIRST asset loaded outside edit mode, changing its footprint on
every admin page. Toolbar editing has an open question that could return a no-go:
whether the cosmetic-only guarantee even holds there, given the sidebar's version
rests on core's $_wp_menu_nopriv gate and URL-reachability. SVG upload is a
security feature wearing a UI feature's clothes.

FLAGGED, not resolved: the "optional enforcement bridge" (item 7) is IN TENSION
with REQUIREMENTS' Out of Scope list and the core value — it has Maestro SETTING
a capability. It needs a decision, not implementation, and now says so.

DELETED: REQUIREMENTS' "UX-11 follow-ups beyond the screenshot recapture". An
unresolvable reference — it never said what the follow-ups were, so nobody could
act on it or close it. Replaced with a comment explaining the removal.

ROOT CAUSE: SPEC.md now declares .planning/todos/pending/ the system of record,
with the rule that a shipped item gets struck in the same change. Striking
entries without fixing that would just reset the clock — the note cites Phase 25
as the concrete cost, where a stale entry nearly had 25-02 recolouring a glyph
that was already correct, caught only because 25-01 was written as an audit.

Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
---
 .planning/PROJECT.md                          |  2 +-
 .planning/REQUIREMENTS.md                     |  6 ++-
 .planning/STATE.md                            | 30 ++++++++----
 ...6-08-09-reconcile-v2-backlog-with-todos.md |  0
 ...26-08-09-admin-toolbar-editing-research.md | 44 ++++++++++++++++++
 ...026-08-09-configurable-admin-menu-width.md | 46 +++++++++++++++++++
 .../2026-08-09-icon-picker-remaining-scope.md | 43 +++++++++++++++++
 SPEC.md                                       | 23 ++++++++--
 8 files changed, 181 insertions(+), 13 deletions(-)
 rename .planning/todos/{pending => completed}/2026-08-09-reconcile-v2-backlog-with-todos.md (100%)
 create mode 100644 .planning/todos/pending/2026-08-09-admin-toolbar-editing-research.md
 create mode 100644 .planning/todos/pending/2026-08-09-configurable-admin-menu-width.md
 create mode 100644 .planning/todos/pending/2026-08-09-icon-picker-remaining-scope.md

diff --git a/.planning/PROJECT.md b/.planning/PROJECT.md
index 8e6da9a..233ee0b 100644
--- a/.planning/PROJECT.md
+++ b/.planning/PROJECT.md
@@ -168,7 +168,7 @@ and `.planning/milestones/` for records.
 - **Release assets:** Phase 4 is complete. WordPress.org icon, banner, and screenshot graphics exist under `.wordpress-org/` and are referenced from the GitHub/wp.org readmes. User-facing documentation is published in the GitHub README, WordPress.org readme, and `docs/user-guide.md`.
 - **Localization:** The plugin is translation-ready with the `maestro` text domain and `Domain Path: /languages`. PHP strings use WordPress translation helpers, and JavaScript editor labels are passed through `maestroData.i18n` from PHP. The repo ships a POT template plus starter catalogs for `es_ES`, `de_DE`, `ja`, `fr_FR`, `pt_BR`, and `it_IT`; WordPress.org language packs can still override and extend them, and native-speaker/Polyglots review is welcome.
 - **Submit:** Phase 5 is complete. The runtime zip builds cleanly, WPCS passes, Plugin Check 2.0.0 reports no errors on the extracted build zip, npm audit reports 0 vulnerabilities after removing unused `@wordpress/scripts`, and local unit/integration/E2E tests pass. **The plugin has been submitted to WordPress.org** and is in the review queue; approval and SVN access are pending (external, out of our hands). On approval: commit to SVN `trunk`, tag `1.0.0`, and upload `.wordpress-org/` to the SVN `assets/` dir.
-- **Future roadmap (post-1.0 backlog):** reparenting (top↔sub, highlighting minefield); separator management; keyboard-accessible reordering; per-item-reset UI affordance with a "modified" indicator; custom icon upload (SVG sanitization); import/export config as JSON; optional enforcement bridge (opt-in, clearly-labelled defense-in-depth); multisite/network defaults with per-site override; configurable admin-menu width (V2-09); admin-toolbar editing feasibility research (V2-10); UI/UX design polish for edit-mode hierarchy, responsive behavior, modified-state affordances, status clarity, and icon-picker scanability (V2-12); documentation link hygiene for prose references to project files (V2-13); deterministic banner source/regeneration with the "ADMIN MENU" leader line removed (V2-14); role cloning / per-user cosmetic hiding (V2-15); third-party menu compatibility research, WooCommerce-first (V2-16 — pulled forward to v1.2 Phase 10, 2026-06-19); and a single-site "super-admin equivalent" / privileged editor tier research item (V2-17, 2026-06-19) — note it edges toward the Out-of-Scope "page locking" line; an *enforced* tier is out of scope for Maestro (which never enforces and assumes no dependency on any other plugin), so it would be entirely separate work in a separate project, not Maestro core.
+- **Future roadmap (post-1.0 backlog):** see `SPEC.md`'s Roadmap section for the narrative list and `.planning/todos/pending/` for what is actually queued — that directory is the system of record (declared in SPEC.md, 2026-08-09). **Shipped since this paragraph was written:** keyboard reordering (v1.1), per-item reset + modified indicator (v1.1), custom icon support incl. the heavier bundled set V2-11 (v1.1), doc-link hygiene V2-13 and the banner pipeline V2-14 (v1.1 Phase 8), third-party compat research V2-16 (v1.2 Phase 10), UI/UX design polish V2-12 (v1.3.1 Phase 23, with dark-toolbar follow-ups in v1.5.0 Phase 25), and per-user cosmetic hiding V2-15 / ROLE-02 (v1.5.0, per-user half only — cloned-role profiles still deferred). **Still open and now schedulable as todos:** configurable admin-menu width (V2-09), admin-toolbar editing research (V2-10), the remaining icon-picker scope, config presets / import-export (V2-06), reparenting, separator management, multisite defaults, and the privileged-editor-tier research item (V2-17). The "optional enforcement bridge" is flagged IN TENSION with the Out of Scope list — it needs a decision, not implementation.
 
 ## Constraints
 
diff --git a/.planning/REQUIREMENTS.md b/.planning/REQUIREMENTS.md
index 2e89bd1..7cd5d01 100644
--- a/.planning/REQUIREMENTS.md
+++ b/.planning/REQUIREMENTS.md
@@ -67,7 +67,11 @@ first; neither blocks the cut.
 ## Deferred (future milestone)
 
 - **COMPAT-05/06/08/09/11/12/13** — documented WordPress menu-model limitations from R1; docs-only, correct by design (carried as user-guidance, not code).
-- **UX-11 follow-ups** beyond the screenshot recapture (the coachmark itself shipped in v1.3.0).
+<!-- "UX-11 follow-ups beyond the screenshot recapture" removed 2026-08-09: an
+     unresolvable reference. UX-11 (the first-run coachmark) shipped in v1.3.0 and
+     the screenshot recapture happened at v1.4.0, but the line never said WHAT the
+     follow-ups were, so nobody could act on it or close it. If a specific coachmark
+     improvement is wanted, it needs its own todo naming it. -->
 
 ## Out of Scope
 
diff --git a/.planning/STATE.md b/.planning/STATE.md
index e1321df..91f383d 100644
--- a/.planning/STATE.md
+++ b/.planning/STATE.md
@@ -342,14 +342,28 @@ Recent decisions affecting current work:
   listen. Captured in
   `todos/pending/2026-08-09-persistent-saved-state-indicator.md`
 
-- **Reconcile the SPEC/PROJECT V2 backlog against the todo system** — there are
-  TWO backlogs and they disagree; only 2 of 10 V2-xx items ever crossed into
-  `todos/pending`. SPEC.md item 11 / V2-12 ("UI/UX design polish") reads as open
-  but was delivered by Phase 23 as UX-13 — the same stale-entry failure mode that
-  Phase 25's criterion 1 had, caught there only because 25-01 was written as an
-  audit. V2-09 (menu width) and V2-10 (toolbar editing) are real unbuilt UX work
-  that has never been schedulable. Captured in
-  `todos/pending/2026-08-09-reconcile-v2-backlog-with-todos.md`
+- ~~**Reconcile the SPEC/PROJECT V2 backlog**~~ — ✅ DONE 2026-08-09. Struck four
+  entries that had shipped but still read as open (item 11 / V2-12 → Phase 23;
+  item 5's icon-weight remainder / V2-11 → Phase 7; V2-13 and V2-14 → Phase 8),
+  converted the surviving UX work into individual todos (menu width V2-09,
+  toolbar-editing research V2-10, remaining icon-picker scope), deleted the
+  unresolvable "UX-11 follow-ups" line, flagged the enforcement bridge as IN
+  TENSION with the Out of Scope list, and — the root cause — **declared
+  `.planning/todos/pending/` the system of record** in SPEC.md, with the rule
+  that a shipped item gets struck in the same change. Todo moved to `completed/`.
+- **Configurable admin-menu width (V2-09)** — extracted from the prose backlog and
+  now schedulable. Would be Maestro's FIRST asset loaded outside edit mode, which
+  changes its footprint on every admin page; folded mode and the <782px
+  breakpoint are hard constraints. `todos/pending/2026-08-09-configurable-admin-menu-width.md`
+- **Admin toolbar editing research (V2-10)** — deliverable is a feasibility NOTE
+  modelled on ROLE-01's, not a feature. Open question that could return a no-go:
+  whether the cosmetic-only guarantee even holds for toolbar nodes, since the
+  sidebar's version rests on core's `$_wp_menu_nopriv` gate and URL-reachability.
+  `todos/pending/2026-08-09-admin-toolbar-editing-research.md`
+- **Icon support — remaining third of SPEC item 5** — media-library/URL input
+  (the validator accepts these; nothing can enter them), `mask-image` recolour,
+  and arbitrary SVG upload, which is a security feature wearing a UI feature's
+  clothes and wants its own pass. `todos/pending/2026-08-09-icon-picker-remaining-scope.md`
 
 - **Named config presets + JSON export/import** — v1.5 candidate; supersedes/extends V2-06 (SPEC.md Roadmap item 6). Research captured in `todos/pending/2026-07-03-config-presets-export-import.md`
 - **Declutter switch (non-core menu items → bottom section)** — v1.5 candidate; needs discuss/feasibility pass (top_order precedence, CPT handling). Research captured in `todos/pending/2026-07-03-declutter-switch-non-core-menu-items.md`
diff --git a/.planning/todos/pending/2026-08-09-reconcile-v2-backlog-with-todos.md b/.planning/todos/completed/2026-08-09-reconcile-v2-backlog-with-todos.md
similarity index 100%
rename from .planning/todos/pending/2026-08-09-reconcile-v2-backlog-with-todos.md
rename to .planning/todos/completed/2026-08-09-reconcile-v2-backlog-with-todos.md
diff --git a/.planning/todos/pending/2026-08-09-admin-toolbar-editing-research.md b/.planning/todos/pending/2026-08-09-admin-toolbar-editing-research.md
new file mode 100644
index 0000000..cc8d379
--- /dev/null
+++ b/.planning/todos/pending/2026-08-09-admin-toolbar-editing-research.md
@@ -0,0 +1,44 @@
+---
+created: 2026-08-09T00:00:00.000Z
+title: Admin toolbar editing — feasibility research (V2-10)
+area: research
+files:
+  - includes/class-admin-bar.php (Maestro's own toolbar node — the existing touchpoint)
+  - .planning/phases/19-cosmetic-hiding-feasibility/19-FEASIBILITY-NOTE.md (the model for this deliverable)
+---
+
+## Problem
+
+Whether the in-place editor could extend to the top admin bar (`#wpadminbar`) —
+hide/reorder/rename toolbar nodes with a better inline interface than existing
+tools offer.
+
+Extracted from `SPEC.md` Roadmap item 10 / `PROJECT.md`'s V2 paragraph during the
+2026-08-09 backlog reconciliation, where it had never been schedulable.
+
+## The deliverable is a NOTE, not a feature
+
+Explicitly a feasibility note first, as `SPEC.md` says — no commitment to build.
+`19-FEASIBILITY-NOTE.md` (ROLE-01) is the shape to copy: it answered a
+go/no-go question with an explicit verdict, a storage recommendation, a named
+resolution seam, and invariants that must hold. That note is why Phase 21 could
+be planned confidently, and why its cosmetic-only claim was provable.
+
+## Questions the note must answer
+
+- **`WP_Admin_Bar` node registration** — how nodes are added, when, and whether
+  a late pass can reliably mutate them the way `admin_menu` @ `PHP_INT_MAX` does
+  for the sidebar
+- **Which nodes are safely hideable.** The admin bar carries account and logout
+  controls; hiding the wrong node is a different class of harm from hiding a menu
+  item, because the sidebar always has a URL fallback and some bar nodes are the
+  only path to what they do
+- **Front-end vs admin rendering** — the bar renders on the front end too, for
+  logged-in visitors. Maestro has never touched the front end; that is a real
+  scope boundary, not a detail
+- **Per-role and per-user handling** — whether the ROLE-02 seam generalises or
+  whether the bar needs its own
+- **Whether the cosmetic-only guarantee even holds here.** For the sidebar it is
+  structural: core's `$_wp_menu_nopriv` gate stays intact and pages remain
+  URL-reachable. The equivalent argument for toolbar nodes has not been made, and
+  if it cannot be, that is a no-go verdict rather than a caveat.
diff --git a/.planning/todos/pending/2026-08-09-configurable-admin-menu-width.md b/.planning/todos/pending/2026-08-09-configurable-admin-menu-width.md
new file mode 100644
index 0000000..57c2386
--- /dev/null
+++ b/.planning/todos/pending/2026-08-09-configurable-admin-menu-width.md
@@ -0,0 +1,46 @@
+---
+created: 2026-08-09T00:00:00.000Z
+title: Configurable admin-menu width (V2-09)
+area: editor-ux
+files:
+  - includes/class-config.php (a global `menu_width`, sibling to items/top_order/sub_order — NOT a per-item key)
+  - includes/class-assets.php (would need a stylesheet OUTSIDE edit mode, which nothing currently loads)
+  - assets/maestro-admin-bar.css (the only always-loaded stylesheet today — the natural home or the model for a new one)
+---
+
+## Problem
+
+WordPress hard-codes the admin sidebar at 160px. Renaming an item to something
+longer — which Maestro exists to let people do — makes it wrap. The plugin
+therefore creates the problem it cannot solve.
+
+Extracted from `SPEC.md` Roadmap item 9 / `PROJECT.md`'s V2 paragraph during the
+2026-08-09 backlog reconciliation. It had never been schedulable: it existed as
+one clause in a long prose sentence.
+
+## Shape
+
+A global `menu_width` in the stored config, applied on **every admin page** via
+the same `#adminmenu` / `#wpcontent` rules the folded-mode override already uses.
+
+## What makes this harder than it looks
+
+**It is the first thing Maestro would load outside edit mode.** Every current
+asset is edit-mode-gated except `maestro-admin-bar.css`. A width override has to
+apply while merely *browsing* wp-admin, which changes the plugin's footprint on
+every page load for every admin user — worth being deliberate about, since
+"costs nothing unless you are editing" is currently true and would stop being.
+
+Three interactions to get right, none optional:
+- **Folded mode** (`.folded`, 36px) must still fold — a fixed width that ignores
+  it breaks the collapse control entirely
+- **The `<782px` responsive breakpoint**, where the menu becomes an overlay
+- **`#wpcontent`'s matching offset** — set one without the other and the content
+  column overlaps or leaves a gap
+
+## Prior art
+
+"Wider Admin Menu" does exactly this as a standalone plugin, which is worth
+reading before designing — and is also the argument for keeping the scope
+narrow: the value here is that it is *integrated with the renaming that caused
+the problem*, not that it is a better width slider.
diff --git a/.planning/todos/pending/2026-08-09-icon-picker-remaining-scope.md b/.planning/todos/pending/2026-08-09-icon-picker-remaining-scope.md
new file mode 100644
index 0000000..e4a107e
--- /dev/null
+++ b/.planning/todos/pending/2026-08-09-icon-picker-remaining-scope.md
@@ -0,0 +1,43 @@
+---
+created: 2026-08-09T00:00:00.000Z
+title: Icon support — the remaining third of SPEC item 5
+area: editor-ux
+files:
+  - includes/class-config.php (sanitize_icon(); already accepts all four native forms)
+  - assets/maestro.js (the icon popover — dashicons + Bootstrap tabs, search, "No icon")
+  - includes/icons-bootstrap.php (GENERATED — regenerate via bin/generate-bootstrap-icons.mjs)
+---
+
+## Problem
+
+`SPEC.md` Roadmap item 5 is struck as **Done**, and mostly it is: the validator
+accepts all four native WordPress icon forms (dashicon, `none`, data-URI, URL)
+and the picker bundles dashicons plus curated Bootstrap Icons with search.
+
+But its "Remaining:" clause lists work that is still genuinely open, buried
+inside a struck-through item where nobody will find it. Split out here during the
+2026-08-09 reconciliation.
+
+**Already done, do not re-scope:** the heavier/solid bundled set (V2-11). Phase 7
+shipped the fill-resolution policy in v1.1 — see the generated header of
+`includes/icons-bootstrap.php`: *"*-fill variants preferred; 7 names use a solid
+synonym; 22 names retained as outline (no solid form available)"*. The stale
+"outline glyphs read thin" note has been corrected in SPEC.md.
+
+## What is actually left
+
+1. **Media-library / URL input in the UI.** The *validator* already accepts a URL
+   or data-URI; there is no way to *enter* one. Today a custom icon requires
+   editing the stored option by hand, which is not a feature anyone has.
+2. **Arbitrary SVG upload with deep sanitisation.** The high-risk one. SVG is an
+   XSS vector and WordPress deliberately does not allow SVG upload by default.
+   This wants its own security pass, not a corner of an icon-picker plan — and
+   "we sanitise it" is the claim that needs proving, not asserting.
+3. **A `mask-image` path** so bundled SVGs recolour with the active admin colour
+   scheme instead of being fixed-colour.
+
+## Sequencing note
+
+(1) and (3) are ordinary editor work. (2) is a security feature wearing a UI
+feature's clothes and should be scoped separately — if it is ever done at all,
+given that core's own position is not to allow it.
diff --git a/SPEC.md b/SPEC.md
index 55fd35f..6593feb 100644
--- a/SPEC.md
+++ b/SPEC.md
@@ -191,17 +191,34 @@ Coverage targets the seams most likely to break: the pure ordering logic (unit),
 
 ## Roadmap
 
+> **System of record.** This list is the *narrative* backlog — what Maestro might
+> become, and why. It is **not** the work queue. Anything actually scheduled must
+> have a file in `.planning/todos/pending/`, and that directory is authoritative
+> for what is being worked on.
+>
+> The two drifted apart badly enough to matter: as of 2026-08-09 only 2 of 10
+> V2-xx items had ever crossed over, and three entries here still read as open
+> after shipping (item 11 → Phase 23; item 5's icon-weight remainder → Phase 7;
+> V2-13/V2-14 → Phase 8). One of those nearly cost real work — Phase 25's scope
+> was drawn from a stale report and would have "fixed" a glyph colour that was
+> already correct, caught only because 25-01 was deliberately written as an audit.
+>
+> **So: when an item here ships, strike it here in the same change.** When one is
+> scheduled, give it a todo. An entry that is neither struck nor in the queue is
+> the failure mode this note exists to prevent.
+
+
 1. **Reparenting.** Move items between top-level and submenu. Requires hand-splicing the globals plus `parent_file`/`submenu_file` highlighting fixes — the known minefield. Highest-value v2 feature; gated on a solid highlighting strategy (study Admin Menu Editor's approach).
 2. **Separator management.** Add/move/delete separators, with a synthetic stable id scheme to survive plugin churn.
 3. ~~**Keyboard-accessible reordering.** Move-up/move-down controls and/or ARIA grab semantics, removing the mouse-only dependency.~~ **Done** — `Alt+ArrowUp`/`Alt+ArrowDown` keyboard reorder with polite/assertive `wp.a11y.speak()` announcements, chained focus retention, and `aria-keyshortcuts` on the selected row.
 4. ~~**Per-item reset in the UI surfaced as an explicit affordance** with a visible "modified" indicator diffing against pristine.~~ **Done** — non-color-only modified indicator (•glyph + screen-reader text, ≥5.5:1 contrast) driven by `maestroLogic.diffItem`; reset button keyboard-reachable and emphasised when the item is modified.
-5. ~~**Custom icon support.** Dashicons picker plus URL/SVG and `none`, with appropriate sanitization.~~ **Done** — the validator accepts all four native forms and the picker bundles dashicons + Bootstrap Icons. Remaining: media-library/URL input in the UI, arbitrary SVG upload with deep sanitisation, a `mask-image` path so bundled SVGs recolour with the admin scheme, and a heavier/solid bundled set (Bootstrap `*-fill` or Heroicons Mini) so bundled icons match dashicons' weight (V2-11 — the outline Bootstrap glyphs read thin next to dashicons).
+5. ~~**Custom icon support.** Dashicons picker plus URL/SVG and `none`, with appropriate sanitization.~~ **Done** — the validator accepts all four native forms and the picker bundles dashicons + Bootstrap Icons. Remaining: media-library/URL input in the UI, arbitrary SVG upload with deep sanitisation, a `mask-image` path so bundled SVGs recolour with the admin scheme. (V2-11, the heavier/solid bundled set, is **done** — Phase 7 shipped the fill-resolution policy in v1.1; see the header of [`includes/icons-bootstrap.php`](includes/icons-bootstrap.php)).
 6. **Import/export config** as JSON for staging→production parity and version control.
-7. **Optional enforcement bridge.** Not built-in access control, but a documented, opt-in handoff that sets a hidden item's required capability *in concert with* a capability manager — clearly labelled as defense-in-depth, never as the primary lock.
+7. **Optional enforcement bridge.** ⚠️ **IN TENSION — needs a decision, not implementation.** REQUIREMENTS.md lists "real access control / enforced tiers" as Out of Scope, and the core value is that Maestro never changes a capability. This item has Maestro *setting* one. Either it is genuinely out of scope and belongs there, or the handoff is narrower than the wording implies and should be rewritten to say so. Do not build it from this entry as written. Not built-in access control, but a documented, opt-in handoff that sets a hidden item's required capability *in concert with* a capability manager — clearly labelled as defense-in-depth, never as the primary lock.
 8. **Multisite / network-level defaults** with per-site override.
 9. **Configurable admin-menu width.** A toggle/control to widen the 160px sidebar so long or renamed titles don't wrap. Global `menu_width` in config, applied on every admin page via the same `#adminmenu`/`#wpcontent` rules used by the folded-mode override. First asset loaded outside edit mode; must respect folded mode and the `<782px` responsive breakpoint. (cf. "Wider Admin Menu", integrated into the editor.)
 10. **Admin toolbar editing (research).** Feasibility of extending the in-place editor to the top admin bar (`#wpadminbar`) — hide/reorder/rename toolbar nodes with a better inline interface than existing tools (cf. "Hide Admin Menu"). Investigate `WP_Admin_Bar` node registration, safely-hideable nodes, front-end vs admin rendering, and per-role handling. Deliverable is a feasibility note first, not a commitment.
-11. **UI/UX design polish.** Review edit mode as a dense WordPress admin tool: control hierarchy, spacing, responsive behavior, modified-state affordances, save/error status clarity, icon-picker scanability, and first-run/onboarding cues. Keep it visually native to wp-admin and verify with before/after screenshots plus keyboard/mouse walkthrough notes.
+11. ~~**UI/UX design polish.** Review edit mode as a dense WordPress admin tool: control hierarchy, spacing, responsive behavior, modified-state affordances, save/error status clarity, icon-picker scanability, and first-run/onboarding cues. Keep it visually native to wp-admin and verify with before/after screenshots plus keyboard/mouse walkthrough notes.~~ **Done** — delivered as UX-13 across Phase 23 (native wp-admin restyle of every edit-mode surface: toolbar, shared panel, icon/visibility popovers, first-run banner, coachmark, in-menu selection/badges), shipped in v1.3.1. Phase 25 (v1.5.0) followed up on the dark-toolbar specifics: reserved status slot, widened focus-ring margin, and the locked-checkbox a11y semantics.
 
 ---
 

From 760a233c75d606e6ae6038f69d915712b636e638 Mon Sep 17 00:00:00 2001
From: Dan Knauss <273554+dknauss@users.noreply.github.com>
Date: Sun, 9 Aug 2026 22:49:21 -0600
Subject: [PATCH 13/27] =?UTF-8?q?docs(planning):=20close=20Phase=2025=20?=
 =?UTF-8?q?=E2=80=94=20human-verified=20(#137)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Records the checkpoint outcome: the changes and resulting UX behaviour were
confirmed manually in a running editor.

Stated precisely in the verification note, because this project has one
checkpoint recorded the other way — 21-05 Task 5 was accepted on automated
evidence and the v1.5.0 milestone says so. This one WAS a human pass. The
distinction is the whole reason both are written down.

Shipped: reserved status slot (the rename field now holds one x position across
idle -> saving -> saved; it previously shifted 20px on every save), focus ring
3.07:1 -> 6.74:1, and a11y M2/M3.

The verification note also records what the 25-01 audit struck and why it
mattered: criterion 1 was already satisfied (#c3c4c7 at 9.11:1; the reported
blue was not in the CSS at all), criterion 2 was downgraded from a fix to a
choice because the old ring PASSED its bar by 0.07, and criterion 4 was absorbed
because its stated remedy already existed. Implemented as written, the phase
would have opened by "fixing" a colour that was already correct — the concrete
cost of a stale planning entry, and the reason the backlog reconciliation cites
this phase.

Deliberately not done and logged instead: the persistent saved-state marker.
Reserving the slot fixed the jarring half; persistence is a design change and
was kept out rather than smuggled in under a layout fix.

Also corrects the v1.5 milestone line, which said Phases 22 and 25 "did not
land" — true of the release cut, but Phase 25 has now completed post-release and
the line would otherwise read as though it were still open.

Still open on these surfaces: no human screen-reader pass (axe is clean, and
structural assertions prove what AT can reach rather than what it says).

Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
---
 .planning/ROADMAP.md                          |  4 +-
 .../25-VERIFICATION.md                        | 82 +++++++++++++++++++
 2 files changed, 84 insertions(+), 2 deletions(-)
 create mode 100644 .planning/phases/25-edit-mode-toolbar-dark-surface-polish/25-VERIFICATION.md

diff --git a/.planning/ROADMAP.md b/.planning/ROADMAP.md
index 24d14f4..220cc8e 100644
--- a/.planning/ROADMAP.md
+++ b/.planning/ROADMAP.md
@@ -10,7 +10,7 @@
 - ✅ **R1 Third-Party Compatibility Research** — Phases 13–16 (completed 2026-06-29; non-versioned research — no plugin code, no release tag, no SVN deploy) → [archive](milestones/R1-ROADMAP.md)
 - ✅ **v1.3.0 Slug-Resolution Hardening** — Phases 17–18 (shipped 2026-06-30; release tag `v1.3.0`) → [archive](milestones/v1.3.0-ROADMAP.md)
 - ✅ **v1.4 Compatibility, Roles & Showcase** — Phases 19–24 (shipped 2026-08-04; release tag `v1.4.0`, patch `v1.4.1` 2026-08-05). Shipped **without** Phase 21 (ROLE-02, deferred to v1.5 under the Release Binding fallback) and Phase 22 (not reached; still open).
-- ✅ **v1.5 Per-User Visibility** — Phase 21 + Phase 26 (shipped 2026-08-09; release tag `v1.5.0` on `694b1bf`). Delivered ROLE-02's **per-user half**; the cloned-role "profiles" half remains a backlog item. Phases 22 and 25 were optional inclusions and did **not** land, per the fallback.
+- ✅ **v1.5 Per-User Visibility** — Phase 21 + Phase 26 (shipped 2026-08-09; release tag `v1.5.0` on `694b1bf`). Delivered ROLE-02's **per-user half**; the cloned-role "profiles" half remains a backlog item. Phases 22 and 25 were optional inclusions and did **not** make the cut, per the fallback. Phase 25 has since been completed post-release (2026-08-09, human-verified) and will ride the next release; Phase 22 remains open.
 
 ## Phases
 
@@ -149,7 +149,7 @@ Full phase details, success criteria, and outcomes are archived in
 - [ ] **Phase 22: Slug-Resolution Showcase Demo** — Playground demo that visibly demonstrates the v1.3.0 slug-normalization fixes
 - [x] **Phase 23: Editor UX Polish** — native wp-admin restyle of all edit-mode surfaces (UX-13, added 2026-07-03), semantic-colour borders removed (UX-12 verdict), first-run banner centering (BUG-08) — complete 2026-07-05
 - [x] **Phase 24: Release v1.4.0** — cut and shipped to WordPress.org 2026-08-04 (tag `v1.4.0` on `482510c`, PR #113); editor + directory screenshots recaptured. Patch **v1.4.1** followed 2026-08-05 (tag on `c6cdcbe`, PR #116) for the shared-slug propagation defect. Shipped WITHOUT Phases 21 and 22 — see the outcome note below
-- [ ] **Phase 25: Edit-Mode Toolbar Dark-Surface Polish** — dark-toolbar icon/focus contrast (WCAG 1.4.11), save-indicator layout shift, rename commit feedback (added 2026-08-02; pre-existing v1.3.1 surfaces, non-blocking for v1.4.0)
+- [x] **Phase 25: Edit-Mode Toolbar Dark-Surface Polish** — ✅ COMPLETE 2026-08-09 (2/2 plans; human-verified). Audit struck 1 of 5 criteria as already satisfied, downgraded 1 from fix to choice, absorbed 1. Shipped: reserved status slot, focus ring 3.07:1 → 6.74:1, a11y M2/M3. Original text follows — dark-toolbar icon/focus contrast (WCAG 1.4.11), save-indicator layout shift, rename commit feedback (added 2026-08-02; pre-existing v1.3.1 surfaces, non-blocking for v1.4.0)
 
 ### Phase 19: Cosmetic Hiding Feasibility
 **Goal**: It is known, before any implementation, whether per-user and/or cloned-role menu hiding can be delivered without touching capabilities — and if so, how it should be stored and resolved
diff --git a/.planning/phases/25-edit-mode-toolbar-dark-surface-polish/25-VERIFICATION.md b/.planning/phases/25-edit-mode-toolbar-dark-surface-polish/25-VERIFICATION.md
new file mode 100644
index 0000000..85b9890
--- /dev/null
+++ b/.planning/phases/25-edit-mode-toolbar-dark-surface-polish/25-VERIFICATION.md
@@ -0,0 +1,82 @@
+# Phase 25 — Verification
+
+**Verified:** 2026-08-09
+**Verified by:** human, manually, in a running editor
+**Status:** ✅ COMPLETE (2/2 plans)
+
+## Checkpoint outcome
+
+Confirmed manually: the changes and the resulting UX behaviour were exercised in
+a live editor and accepted.
+
+Worth stating precisely, because this project has one checkpoint recorded the
+other way: **this was an actual human pass**, unlike 21-05 Task 5, which was
+accepted on automated evidence and is recorded as such in the v1.5.0 milestone.
+The distinction is the whole reason both are written down.
+
+## What shipped
+
+| # | Change | Evidence |
+|---|---|---|
+| 1 | Status slot reserved (`min-width: 24px`) | Rename field held ONE x position across idle → saving → saved; previously shifted 20px (x: 230 → 210) on every save |
+| 2 | Focus ring `#2271b1` → `#72aee6` | 3.07:1 → **6.74:1** on `#1d2327` |
+| 3 | M2 — locked checkbox `aria-disabled` + `aria-describedby` | Reachable in focus mode; reason announced as a description; toggle refused |
+| 4 | M3 — outside-click restores focus to the anchor | Matches the Escape handler |
+
+Six e2e assertions in
+[`tests/e2e/specs/toolbar-dark-surface.spec.ts`](../../../tests/e2e/specs/toolbar-dark-surface.spec.ts),
+each written to fail against the pre-fix code.
+
+## What 25-01's audit struck, and why that mattered
+
+The phase was scoped 2026-08-02 from a defect report. The audit measured every
+criterion against the current code first:
+
+- **Criterion 1 (glyph contrast) — STRUCK.** Already satisfied: `#c3c4c7` at
+  **9.11:1**. The reported blue `#3858e9` (2.83:1) was not in the CSS at all.
+  v1.4.0's a11y gate had reached the same conclusion independently and recorded
+  it as "does not reproduce"; the roadmap was never updated to match.
+- **Criterion 2 — DOWNGRADED** from a fix to a choice. The old ring **passed**
+  its 3:1 bar, by 0.07.
+- **Criterion 4 (rename feedback) — ABSORBED.** Its stated remedy already
+  existed; the real residue was that confirmation arrived by shoving the toolbar
+  sideways, which criterion 3's fix resolves.
+
+Had the phase been implemented as written, it would have opened by "fixing" a
+colour that was already correct. That is the concrete cost of a stale planning
+entry, and it is why the backlog reconciliation (2026-08-09) cites this phase.
+
+## Deliberately NOT done
+
+**A persistent saved-state marker.** After a save the indicator still clears
+after 2s, so seconds later there is no on-screen answer to "did that save?".
+Reserving the slot fixed the *jarring* half; persistence is a design change and
+was kept out rather than smuggled in under a layout fix. Logged with its two
+caveats — the collision with the per-row "modified" dot, and the live-region
+double-announcement risk — in
+`todos/pending/2026-08-09-persistent-saved-state-indicator.md`.
+
+## Gate
+
+| Check | Result |
+|---|---|
+| `composer test:unit` | ✅ 167/167 |
+| `npm run test:php` | ✅ 126/126 single-site |
+| `npm run test:php:multisite` | ✅ 126/126 |
+| `npm run test:js` | ✅ 83/83 |
+| `npm run test:e2e` | ✅ 52 passed, 0 failed |
+| WPCS / PHPStan / doc-links | ✅ clean / 0 / clean |
+
+`cascade-hide.spec.ts` passes **unmodified** with the M2 change in place — the
+one older spec most likely to have been disturbed, since M2 alters the component
+it asserts against.
+
+Two full-suite runs were needed: the first showed two unrelated failures that
+moved and vanished on the second — the known load-flakiness pattern, not a
+regression.
+
+## Still open on these surfaces
+
+- No human **screen-reader** pass. axe is clean and the structural assertions
+  prove what AT can *reach*, which is not what it *says*.
+- The persistent saved-marker question above.

From 4359994cc43be56c5667b0e9b0133fb10b416a28 Mon Sep 17 00:00:00 2001
From: Dan Knauss <273554+dknauss@users.noreply.github.com>
Date: Mon, 10 Aug 2026 00:17:05 -0600
Subject: [PATCH 14/27] fix: close the three Phase 20 correctness follow-ups
 (#138)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

All three were logged as LOW severity during Phase 20's checkpoint and carried
through two releases. None is user-facing; all three are the kind that get worse
by sitting.

AXIS-2 DRIFT (editor-model-replay-axis2-drift). get_menu_model() applied only
the Axis-1 guard (two distinct STORED keys colliding), not the Axis-2 guard
replay() enforces (two distinct RENDERED rows normalizing to one key). On a
rendered collision replay applied nothing while the popover showed the stored
roles checked — and since the editor autosaves a FULL REPLACE built from what it
displays, a lying popover is one save away from becoming the stored truth. That
is why a "display-only" bug was worth closing.

Fixed by folding the Axis-2 skips into the $norm_skip map the resolvers already
honour, rather than widening their signatures: an ambiguous key now resolves to
nothing in the editor for exactly the reason it does in replay().

The new test was verified FALSIFIABLE — disabling the fold makes it fail, so it
is not asserting a vacuous truth. It seeds two live rows (`upload.php?ver=1` and
`?ver=2`) that normalize to one key, which is the real-world shape: the same
screen registered twice under volatile query params.

ENTITY COLLISION (security-qualified-key-entity-collision). Slug::is_qualified()
tested the RAW key for '>', but Slug::normalize() html_entity_decodes first — so
`a&gt;b` stored as a BARE key and then resolved as a QUALIFIED one, silently
becoming a different kind of key than the one that was validated and able to
collide with a genuine `a>b`. The qualification decision and the split now use
the decoded form. Deliberately narrow: only that decision changed, because
"storage stays raw" is the contract normalize() is written against and decoding
every key would rewrite `&amp;` slugs FIX-03 already resolves in either form.

PREDICATE PARITY (child-role-lock-predicate-parity). The popover re-inlined the
lock expression that maestro-logic.js already exports and child-role-lock.test.mjs
already covers — so the tested implementation and the running one were separate
copies free to drift. Now calls the exported predicate, matching how the rest of
maestro.js consumes maestroLogic.

Gate: unit 167/167 (223), integration 127/127 single-site (287) + 127/127
multisite (292), JS 83/83, e2e 52 passed/0 failed, WPCS clean, PHPStan 0,
doc-links clean.

Note: this gate ran on the FALLBACK ports (dev 8890 / tests 8899) because
another project's wp-env had taken 8888/8889. e2e needs WP_ENV_TESTS_PORT=8899
to match, which is the pattern STATE.md already records.

Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
---
 ...-08-02-child-role-lock-predicate-parity.md |  0
 ...6-08-02-editor-model-replay-axis2-drift.md |  0
 ...security-qualified-key-entity-collision.md |  0
 TESTING.md                                    |  4 +-
 assets/maestro.js                             | 12 +++++-
 includes/class-config.php                     | 20 +++++++++-
 includes/class-replay.php                     | 24 ++++++++++++
 tests/integration/ReplayTest.php              | 38 +++++++++++++++++++
 8 files changed, 93 insertions(+), 5 deletions(-)
 rename .planning/todos/{pending => completed}/2026-08-02-child-role-lock-predicate-parity.md (100%)
 rename .planning/todos/{pending => completed}/2026-08-02-editor-model-replay-axis2-drift.md (100%)
 rename .planning/todos/{pending => completed}/2026-08-02-security-qualified-key-entity-collision.md (100%)

diff --git a/.planning/todos/pending/2026-08-02-child-role-lock-predicate-parity.md b/.planning/todos/completed/2026-08-02-child-role-lock-predicate-parity.md
similarity index 100%
rename from .planning/todos/pending/2026-08-02-child-role-lock-predicate-parity.md
rename to .planning/todos/completed/2026-08-02-child-role-lock-predicate-parity.md
diff --git a/.planning/todos/pending/2026-08-02-editor-model-replay-axis2-drift.md b/.planning/todos/completed/2026-08-02-editor-model-replay-axis2-drift.md
similarity index 100%
rename from .planning/todos/pending/2026-08-02-editor-model-replay-axis2-drift.md
rename to .planning/todos/completed/2026-08-02-editor-model-replay-axis2-drift.md
diff --git a/.planning/todos/pending/2026-08-02-security-qualified-key-entity-collision.md b/.planning/todos/completed/2026-08-02-security-qualified-key-entity-collision.md
similarity index 100%
rename from .planning/todos/pending/2026-08-02-security-qualified-key-entity-collision.md
rename to .planning/todos/completed/2026-08-02-security-qualified-key-entity-collision.md
diff --git a/TESTING.md b/TESTING.md
index 91bc924..1825798 100644
--- a/TESTING.md
+++ b/TESTING.md
@@ -2,7 +2,7 @@
 
 Three layers, smallest and fastest first.
 
-> **Current expected status:** unit 167/167 with 223 assertions, integration 126/126 with 285 assertions single-site + 126/126 with 290 under WP_MULTISITE=1, JavaScript unit tests, phpcs, PHPStan, Plugin Check, and the Playwright E2E suite should pass before release. E2E coverage includes reset-this-item, per-role visibility, icon persistence, keyboard reordering, first-run cues, toolbar accessibility checks, (COMPAT-04) independent shared-slug top-level/submenu editing, (COMPAT-10) the "Hide its sub-items from:" role group's independent child-hiding behavior, and (ROLE-02) per-user hiding asserted in a targeted user's own authenticated session — including a same-role bystander who must keep every row, which is the assertion that proves the rule did not widen to the whole role. (Phase 25) the toolbar's reserved status slot (no layout shift across a save), its widened focus-ring contrast, and the derived-locked checkbox's aria-disabled/aria-describedby semantics are covered in [`tests/e2e/specs/toolbar-dark-surface.spec.ts`](tests/e2e/specs/toolbar-dark-surface.spec.ts).
+> **Current expected status:** unit 167/167 with 223 assertions, integration 127/127 with 287 assertions single-site + 127/127 with 292 under WP_MULTISITE=1, JavaScript unit tests, phpcs, PHPStan, Plugin Check, and the Playwright E2E suite should pass before release. E2E coverage includes reset-this-item, per-role visibility, icon persistence, keyboard reordering, first-run cues, toolbar accessibility checks, (COMPAT-04) independent shared-slug top-level/submenu editing, (COMPAT-10) the "Hide its sub-items from:" role group's independent child-hiding behavior, and (ROLE-02) per-user hiding asserted in a targeted user's own authenticated session — including a same-role bystander who must keep every row, which is the assertion that proves the rule did not widen to the whole role. (Phase 25) the toolbar's reserved status slot (no layout shift across a save), its widened focus-ring contrast, and the derived-locked checkbox's aria-disabled/aria-describedby semantics are covered in [`tests/e2e/specs/toolbar-dark-surface.spec.ts`](tests/e2e/specs/toolbar-dark-surface.spec.ts).
 
 ## Gotchas (first run)
 
@@ -99,7 +99,7 @@ assert all three halves of the rule: a network super admin is exempt from the
 person axis, an ordinary user on the same network is **not**, and the role axis
 still applies to super admins (the documented asymmetry). They `markTestSkipped`
 on single-site, and the single-site-only self-target case skips under multisite,
-so both lanes report 126 tests. CI runs both.
+so both lanes report 127 tests. CI runs both.
 
 ## 3. End-to-end (Playwright, against live WordPress)
 
diff --git a/assets/maestro.js b/assets/maestro.js
index 66f48d7..cd6286e 100644
--- a/assets/maestro.js
+++ b/assets/maestro.js
@@ -1188,7 +1188,17 @@
 				function ( arr ) { model[ slug ].childHiddenRoles = arr; },
 				{
 					isLocked: function ( roleKey ) {
-						return model[ slug ].hiddenRoles.indexOf( roleKey ) !== -1;
+						// Call the TESTED predicate rather than re-inlining it.
+						// maestro-logic.js exports isChildRoleLockedByParent() and
+						// child-role-lock.test.mjs exercises it, but the popover
+						// used to duplicate the expression here — so the covered
+						// implementation and the running one were separate copies
+						// that could drift silently. Same pattern the rest of this
+						// file already uses for diffItem/reorderMove/resetItem.
+						return window.maestroLogic.isChildRoleLockedByParent(
+							model[ slug ].hiddenRoles,
+							roleKey
+						);
 					},
 					lockedHint: function ( roleKey ) {
 						return I.hideChildrenLocked.replace( '%s', D.roles[ roleKey ] );
diff --git a/includes/class-config.php b/includes/class-config.php
index 7d8e7b4..f5dbfcb 100644
--- a/includes/class-config.php
+++ b/includes/class-config.php
@@ -411,9 +411,25 @@ public function sanitize( array $raw ) {
 				// independently and recompose, rather than tag/trim-cleaning
 				// the raw string as a whole (Slug::is_qualified() is the same
 				// '>' contract used at resolve time in class-slug.php).
-				$is_qualified = Slug::is_qualified( $slug );
+				// Decide qualification on the ENTITY-DECODED key, and split that.
+				//
+				// Slug::is_qualified() looks for a literal '>', but Slug::normalize()
+				// html_entity_decodes before it does anything else. So a key written
+				// as `a&gt;b` used to be stored as a BARE key here and then resolve
+				// as a QUALIFIED one later — silently becoming a different kind of
+				// key than the one that was validated, and able to collide with a
+				// genuine `a>b`. Deciding on the decoded form makes storage and
+				// resolution agree, which is the property the Axis-1 guard assumes.
+				//
+				// Only the DECISION and the SPLIT use the decoded value. A bare key
+				// is still stored exactly as sent — "storage stays raw" is the
+				// contract normalize() is written against, and widening the decode
+				// to every key would rewrite `&amp;` slugs that FIX-03 already
+				// resolves correctly in either form.
+				$decoded_key  = html_entity_decode( (string) $slug, ENT_QUOTES | ENT_HTML5, 'UTF-8' );
+				$is_qualified = Slug::is_qualified( $decoded_key );
 				if ( $is_qualified ) {
-					list( $parent_half, $child_half ) = Slug::split_qualified( $slug );
+					list( $parent_half, $child_half ) = Slug::split_qualified( $decoded_key );
 					$parent_half                      = $this->clean_slug( $parent_half );
 					$child_half                       = $this->clean_slug( $child_half );
 
diff --git a/includes/class-replay.php b/includes/class-replay.php
index 292a484..65ee5c5 100644
--- a/includes/class-replay.php
+++ b/includes/class-replay.php
@@ -731,6 +731,10 @@ public function get_menu_model() {
 		// top-level row, so under schema v2 it must not resolve onto a submenu
 		// child (see the $bare_fallback_allowed gate in replay()).
 		$top_rendered_keys = array();
+		// Axis-2 (rendered-collision) tracking, mirroring replay()'s
+		// $top_rendered_matches / $top_skip_rendered pair.
+		$top_rendered_first = array();
+		$axis2_skip         = array();
 		foreach ( $menu as $row ) {
 			if ( empty( $row[2] ) ) {
 				continue;
@@ -738,9 +742,29 @@ public function get_menu_model() {
 			$tnk = Slug::normalize( (string) $row[2], $base );
 			if ( '' !== $tnk ) {
 				$top_rendered_keys[ $tnk ] = true;
+
+				// A normalized key matching 2+ DISTINCT rendered rows is ambiguous.
+				// replay() resolves that to "apply nothing"; until now the editor
+				// model did not, so on a rendered collision the popover showed
+				// roles checked that replay was NOT applying. Display-only — the
+				// apply path was already fail-safe — but the popover was lying,
+				// and a full-replace autosave then writes back what it displayed.
+				if ( ! isset( $top_rendered_first[ $tnk ] ) ) {
+					$top_rendered_first[ $tnk ] = $row[2];
+				} elseif ( $top_rendered_first[ $tnk ] !== $row[2] ) {
+					$axis2_skip[ $tnk ] = true;
+				}
 			}
 		}
 
+		// Fold the Axis-2 skips into the map the resolvers ALREADY honour, rather
+		// than widening their signatures: an ambiguous key now resolves to nothing
+		// in the editor for exactly the reason it does in replay(). Union order is
+		// irrelevant — both sides map to `true`.
+		if ( $axis2_skip ) {
+			$norm_skip = $norm_skip + $axis2_skip;
+		}
+
 		foreach ( $menu as $row ) {
 			if ( empty( $row[2] ) || ( isset( $row[4] ) && false !== strpos( (string) $row[4], 'wp-menu-separator' ) ) ) {
 				continue; // skip separators in v1.
diff --git a/tests/integration/ReplayTest.php b/tests/integration/ReplayTest.php
index 358947c..04b9811 100644
--- a/tests/integration/ReplayTest.php
+++ b/tests/integration/ReplayTest.php
@@ -1471,6 +1471,44 @@ public function test_get_menu_model_exposes_child_hidden_roles() {
 		$this->assertSame( array(), $index_node['childHiddenRoles'], 'An untouched parent must expose childHiddenRoles as an empty array, not merely absent.' );
 	}
 
+	/**
+	 * AXIS-2 PARITY: on a RENDERED collision — two distinct live top-level rows
+	 * whose slugs normalize to the same key — replay() applies nothing ("when
+	 * resolution is ambiguous, apply nothing"). The editor model must agree.
+	 *
+	 * It used to apply only the Axis-1 guard (two distinct STORED keys), so the
+	 * popover showed the stored roles checked while replay applied none of them.
+	 * Display-only in isolation, but the editor autosaves a FULL REPLACE built
+	 * from what it displayed — so a lying popover is one save away from becoming
+	 * the stored truth.
+	 */
+	public function test_get_menu_model_applies_the_axis2_rendered_collision_guard() {
+		global $menu;
+
+		// Two DISTINCT rendered rows that normalize to one key: `ver=` is
+		// stripped by Slug::normalize(), so both collapse to `upload.php`.
+		$menu[90] = array( 'Media A', 'upload_files', 'upload.php?ver=1', '', 'menu-top', 'menu-media-a', '' );
+		$menu[91] = array( 'Media B', 'upload_files', 'upload.php?ver=2', '', 'menu-top', 'menu-media-b', '' );
+
+		( new Config() )->save(
+			array( 'items' => array( 'upload.php' => array( 'hidden_roles' => array( 'editor' ) ) ) )
+		);
+
+		$replay = new Replay( new Config() );
+		$replay->replay();
+		$model = $replay->get_menu_model();
+
+		foreach ( $model as $node ) {
+			if ( 'upload.php?ver=1' === $node['slug'] || 'upload.php?ver=2' === $node['slug'] ) {
+				$this->assertSame(
+					array(),
+					$node['hiddenRoles'],
+					'An Axis-2-ambiguous row must show NOTHING checked — replay applies nothing for it.'
+				);
+			}
+		}
+	}
+
 	/**
 	 * COSMETIC-ONLY GUARDRAIL (mandatory, non-negotiable): applying a
 	 * child_hidden_roles rule must NEVER change current_user_can() for any

From 2b9d9439684d323306b7ff0030944925fe88adaa Mon Sep 17 00:00:00 2001
From: Dan Knauss <273554+dknauss@users.noreply.github.com>
Date: Mon, 10 Aug 2026 00:31:34 -0600
Subject: [PATCH 15/27] =?UTF-8?q?docs(planning):=20plan=20Phase=2027=20?=
 =?UTF-8?q?=E2=80=94=20cloned-role=20hiding=20profiles=20(completes=20ROLE?=
 =?UTF-8?q?-02)=20(#139)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Five plans for ROLE-02's deferred half, the last piece of a requirement that has
been marked PARTIAL since v1.5.0.

27-01 IS A DECISIONS CHECKPOINT, not an implementation plan, for two reasons.

First, the feasibility note locked storage and resolution in detail (§5c, §7) but
explicitly left authoring UX as "the main open design question for a future
discuss-phase". Where a profile gets CREATED has no home today — Maestro has
deliberately never had a settings screen, and the visibility popover is already
at four groups. That is a product decision, and inventing it inside an
implementation plan is how a feature acquires a UI nobody asked for.

Second, the note predates Phase 21. It cites class-replay.php:299 and :391, both
stale after v1.4.1 and Phase 21 moved things. More substantively, it assumes term
3 is a list-intersect like the other two — but membership is a property of the
CURRENT USER, not of the item, so the third term probably is NOT the same shape.
27-01 is told that is the most likely place the plan does not survive contact and
to work it out concretely before committing.

The architecture the note DID lock is carried through unchanged: a `profiles`
authoring map that COMPILES onto items[slug].hidden_profiles, so resolution stays
in the one seam and the map is consulted only for live membership. Phase 21 built
for this deliberately — the seam is independent OR'd terms with the slot reserved
and commented at class-replay.php:510, and resolved_override_list() is already
field-parameterized. If this phase turns into a restructuring rather than an
addition, that is a signal worth stopping on, and 27-03 says so.

Each plan carries the lessons its surface already taught, by name rather than as
generic advice: idempotence under full-replace autosave and the MAX_ITEMS
starvation shape (27-02); the fast path and the edit-mode suspension question
(27-03); server-model-client agreement, client-only gates, re-inlined predicates,
and the detach-before-outside-click hazard (27-04); the bystander assertion and
the fixture/session mechanics hidden-users.spec.ts had to learn (27-05).

27-05 closes ROLE-02 in all three planning files at once — a requirement marked
complete in one and partial in another is exactly the drift the V2-backlog
reconciliation existed to fix.

Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
---
 .planning/ROADMAP.md                          |  23 +++
 .../27-01-PLAN.md                             | 164 ++++++++++++++++
 .../27-02-PLAN.md                             | 158 ++++++++++++++++
 .../27-03-PLAN.md                             | 160 ++++++++++++++++
 .../27-04-PLAN.md                             | 154 +++++++++++++++
 .../27-05-PLAN.md                             | 178 ++++++++++++++++++
 6 files changed, 837 insertions(+)
 create mode 100644 .planning/phases/27-cloned-role-hiding-profiles/27-01-PLAN.md
 create mode 100644 .planning/phases/27-cloned-role-hiding-profiles/27-02-PLAN.md
 create mode 100644 .planning/phases/27-cloned-role-hiding-profiles/27-03-PLAN.md
 create mode 100644 .planning/phases/27-cloned-role-hiding-profiles/27-04-PLAN.md
 create mode 100644 .planning/phases/27-cloned-role-hiding-profiles/27-05-PLAN.md

diff --git a/.planning/ROADMAP.md b/.planning/ROADMAP.md
index 220cc8e..8c13940 100644
--- a/.planning/ROADMAP.md
+++ b/.planning/ROADMAP.md
@@ -150,6 +150,7 @@ Full phase details, success criteria, and outcomes are archived in
 - [x] **Phase 23: Editor UX Polish** — native wp-admin restyle of all edit-mode surfaces (UX-13, added 2026-07-03), semantic-colour borders removed (UX-12 verdict), first-run banner centering (BUG-08) — complete 2026-07-05
 - [x] **Phase 24: Release v1.4.0** — cut and shipped to WordPress.org 2026-08-04 (tag `v1.4.0` on `482510c`, PR #113); editor + directory screenshots recaptured. Patch **v1.4.1** followed 2026-08-05 (tag on `c6cdcbe`, PR #116) for the shared-slug propagation defect. Shipped WITHOUT Phases 21 and 22 — see the outcome note below
 - [x] **Phase 25: Edit-Mode Toolbar Dark-Surface Polish** — ✅ COMPLETE 2026-08-09 (2/2 plans; human-verified). Audit struck 1 of 5 criteria as already satisfied, downgraded 1 from fix to choice, absorbed 1. Shipped: reserved status slot, focus ring 3.07:1 → 6.74:1, a11y M2/M3. Original text follows — dark-toolbar icon/focus contrast (WCAG 1.4.11), save-indicator layout shift, rename commit feedback (added 2026-08-02; pre-existing v1.3.1 surfaces, non-blocking for v1.4.0)
+- [ ] **Phase 27: Cloned-Role Hiding Profiles** — completes ROLE-02's deferred half: a named, Maestro-internal hiding profile that compiles onto an inline `hidden_profiles` axis and resolves through the seam slot Phase 21 reserved at `class-replay.php:510` (planned 2026-08-10)
 
 ### Phase 19: Cosmetic Hiding Feasibility
 **Goal**: It is known, before any implementation, whether per-user and/or cloned-role menu hiding can be delivered without touching capabilities — and if so, how it should be stored and resolved
@@ -296,6 +297,28 @@ M2/M3 items from `todos/pending/2026-08-02-a11y-locked-checkbox-refinements.md`.
 
 ---
 
+### Phase 27: Cloned-Role Hiding Profiles
+**Goal**: An admin can name a reusable hiding profile ("Reduced view"), assign people to it, and apply it to menu items — cosmetically, with membership resolved live — completing ROLE-02
+**Depends on**: Phase 21 (built the seam slot, the field-parameterized resolver, and the bounded-axis sanitize shape this extends)
+**Requirements**: ROLE-02 (completion — currently PARTIAL since v1.5.0)
+**Success Criteria** (what must be TRUE):
+  1. A `profiles` map is the AUTHORING structure and **compiles** onto `items[slug].hidden_profiles`; nothing ever resolves the hide decision from the map itself (feasibility note §7's "one lookup, one seam, one audit point")
+  2. Profile membership is intersected LIVE each request, so adding or removing a person takes effect with no re-save and a deleted profile self-heals
+  3. Term 3 lands in the slot Phase 21 reserved — the seam remains ONE drop path per menu level, not a parallel resolve
+  4. The cosmetic-only invariant holds for the profiles axis exactly as for roles and users, proven by extending the existing §6 guardrail rather than a new one
+  5. Proven in a targeted user's OWN rendered sidebar, with a bystander outside the profile keeping every row
+  6. Zero regression: both integration lanes, unit, JS, e2e, WPCS, PHPStan, Plugin Check
+**Plans**: 27-01 decisions · 27-02 storage + compile · 27-03 seam + live membership · 27-04 editor · 27-05 e2e, gate, close ROLE-02
+
+> **27-01 is a decisions checkpoint, deliberately.** The feasibility note locked
+> storage and resolution in detail but left **authoring UX as "the main open
+> design question for a future discuss-phase"** — where profiles get created and
+> managed has no home today, since Maestro has never had a settings screen. It
+> also re-verifies the note's architecture against the code Phase 21 actually
+> shipped: the note cites line numbers from before v1.4.1 and Phase 21 both moved
+> things, and its assumption that term 3 is a list-intersect may not survive
+> contact, since membership is a property of the USER rather than the item.
+
 ## Phase Details (v1.5 — Per-User Visibility)
 
 **Milestone goal:** ship ROLE-02's per-user cosmetic hiding to WordPress.org. The
diff --git a/.planning/phases/27-cloned-role-hiding-profiles/27-01-PLAN.md b/.planning/phases/27-cloned-role-hiding-profiles/27-01-PLAN.md
new file mode 100644
index 0000000..761f273
--- /dev/null
+++ b/.planning/phases/27-cloned-role-hiding-profiles/27-01-PLAN.md
@@ -0,0 +1,164 @@
+---
+phase: 27-cloned-role-hiding-profiles
+plan: 01
+type: decisions
+wave: 1
+depends_on: []
+files_modified:
+  - .planning/phases/27-cloned-role-hiding-profiles/27-CONTEXT.md
+autonomous: false
+requirements: [ROLE-02]
+must_haves:
+  truths:
+    - "The authoring UX is DECIDED by a human before any storage or seam work starts."
+    - "Every decision is written down with its rejected alternative, not just its conclusion."
+    - "The architecture from the feasibility note §7 is confirmed still sound against the code Phase 21 actually shipped."
+---
+
+<objective>
+Settle the open design questions before building, and confirm the two-year-old
+architecture still fits the code that exists now.
+
+Purpose: the feasibility note locked the *storage and resolution* architecture in
+detail (§5c, §7) but explicitly left **authoring UX as "the main open design
+question for a future discuss-phase"**. That is a genuine product decision, not
+an implementation detail, and inventing it in an implementation plan is how a
+feature ends up with a UI nobody asked for.
+
+This project has also twice planned from premises that had quietly expired — the
+Phase 21 release target and Phase 25's criterion 1. The feasibility note predates
+Phase 21's actual implementation, so its assumptions get re-checked here rather
+than trusted.
+Output: a `27-CONTEXT.md` with locked decisions.
+
+**`autonomous: false`** throughout — this plan is entirely decisions.
+</objective>
+
+<context>
+@.planning/phases/19-cosmetic-hiding-feasibility/19-FEASIBILITY-NOTE.md
+@.planning/todos/pending/2026-08-02-cloned-role-hiding-profiles.md
+@includes/class-replay.php
+@includes/class-config.php
+
+<interfaces>
+<!-- Contracts the executor builds on. Use directly — no exploration needed. -->
+
+**ALREADY BUILT by Phase 21 — this phase extends, it does not rebuild:**
+
+- `Replay::is_hidden_for_current_user()` is already independent OR'd terms with a
+  comment reserving the slot: **`class-replay.php:510`, "Term 3 —
+  hidden_profiles … slots in here"**. That reservation was the point.
+- `Replay::resolved_override_list( $field, … )` is field-parameterized, so a
+  `hidden_profiles` axis inherits the qualified-key, schema-v2 and Axis-1/Axis-2
+  guards from ONE implementation. Do not add a parallel resolver.
+- `Config::sanitize()` has an established shape for a bounded list axis:
+  guard → coerce → intersect-against-live → cap → sparse-drop-when-empty.
+- `Config::protected_user_axes()` shows the pattern for an axis that a saver may
+  lack authority to write.
+
+**LOCKED by the feasibility note §7 — do not re-litigate:**
+
+- A `profiles` top-level map is the AUTHORING structure; it **compiles** at save
+  time onto `items[slug].hidden_profiles: [profile-name]`.
+- Resolution stays entirely inside `is_hidden_for_current_user()`. The `profiles`
+  map is consulted ONLY to resolve *live membership* — never as a second place
+  hiding resolves from. One lookup, one seam, one audit point.
+- Membership is intersected LIVE each request (self-healing, §4).
+- A profile is Maestro-internal bookkeeping. It never calls `add_role()`/`add_cap()`,
+  never appears in `wp_roles()`, never changes `$user->roles`.
+
+**OPEN — this plan decides:** everything about how a human creates, names,
+assigns and deletes a profile.
+</interfaces>
+</context>
+
+<tasks>
+
+<task type="checkpoint">
+  <name>Task 1: Decide the authoring UX</name>
+  <action>
+    The visibility popover is already at FOUR groups after Phase 21. A fifth
+    ("Hide for profile") is cheap to add, but profiles also need somewhere to be
+    *created and managed*, and that has no home today — Maestro has deliberately
+    never had a settings screen ("no separate settings screen" is in the core
+    value statement).
+
+    Questions that need answers, each with a real trade-off:
+
+    1. **Where do profiles get authored?** Inline in the popover (create-on-the-fly
+       from a name field), or a dedicated management surface? The former keeps the
+       no-settings-screen promise; the latter is where "rename this profile" and
+       "who is in it" actually belong. A hybrid — assign inline, manage elsewhere —
+       is possible but means two surfaces to keep consistent.
+    2. **What is a profile's assignment?** The note's §5c shape allows both users
+       AND roles under one profile. Roles-in-profiles overlaps confusingly with
+       the existing `hidden_roles` axis — worth asking whether v1 profiles should
+       be users-only for clarity, with roles deferred.
+    3. **Does the popover show which profiles hide an item, or only let you add
+       one?** Showing them means resolving profile→item backwards for display.
+    4. **What happens on delete?** A profile referenced by `items[].hidden_profiles`
+       that no longer exists must self-heal (the §4 invariant says it will), but
+       the editor should probably say so rather than silently dropping rules.
+    5. **Is there a cap?** `MAX_HIDDEN_ROLES`/`MAX_HIDDEN_USERS` are both 50. A
+       profile count cap and a per-profile membership cap both need numbers.
+
+    Recommend, do not just enumerate — but the human decides.
+  </action>
+  <verify><manual>Decisions recorded in 27-CONTEXT.md with rejected alternatives.</manual></verify>
+  <done>Authoring UX locked, with reasoning.</done>
+</task>
+
+<task type="checkpoint">
+  <name>Task 2: Re-verify the feasibility note against shipped code</name>
+  <action>
+    The note was written 2026-07-05, before Phase 21 existed. Confirm against
+    `main` today rather than assuming:
+
+    - Does the reserved Term-3 slot still sit where the note expects, and does the
+      OR structure still take a third term without restructuring? (Read
+      `class-replay.php` around the seam — the note cites `:299` and `:391`, which
+      are stale line numbers from before v1.4.1 and Phase 21 both moved things.)
+    - Does `resolved_override_list()`'s signature genuinely accommodate a
+      `hidden_profiles` field, or does profile resolution need something the
+      role/user axes did not — specifically, membership is a property of the
+      CURRENT USER, not of the item, so the third term may not be a list-intersect
+      at all. **This is the most likely place the note's plan does not survive
+      contact.** Work it out concretely before committing to it.
+    - Does the `protected_user_axes()` authorization pattern need a profile
+      analogue? Profiles name people, so a saver without `list_users` plausibly
+      should not author them either.
+  </action>
+  <verify><manual>Each assumption confirmed against current code or corrected in the CONTEXT.</manual></verify>
+  <done>Architecture re-confirmed or amended, with line-accurate references.</done>
+</task>
+
+<task type="checkpoint">
+  <name>Task 3: Decide the release shape</name>
+  <action>
+    ROLE-02 is currently PARTIALLY delivered. This phase completes it, which means
+    a milestone decision: does this ship as v1.6.0 on its own, or wait to be
+    bundled?
+
+    Also decide whether the changelog should present profiles as a new feature or
+    as the completion of one — v1.5.0 shipped per-user hiding and did not promise
+    profiles, so either framing is honest.
+  </action>
+  <verify><manual>Release intent recorded.</manual></verify>
+  <done>Milestone shape decided.</done>
+</task>
+
+</tasks>
+
+<verification>
+- 27-CONTEXT.md exists with every decision and its rejected alternative.
+- No storage, seam or UI code has been written by this plan.
+</verification>
+
+<success_criteria>
+- The authoring UX is a human decision, recorded, not an implementation accident.
+- The feasibility note's architecture is confirmed against real code, or amended.
+</success_criteria>
+
+<output>
+Create `.planning/phases/27-cloned-role-hiding-profiles/27-CONTEXT.md`.
+</output>
diff --git a/.planning/phases/27-cloned-role-hiding-profiles/27-02-PLAN.md b/.planning/phases/27-cloned-role-hiding-profiles/27-02-PLAN.md
new file mode 100644
index 0000000..af7e665
--- /dev/null
+++ b/.planning/phases/27-cloned-role-hiding-profiles/27-02-PLAN.md
@@ -0,0 +1,158 @@
+---
+phase: 27-cloned-role-hiding-profiles
+plan: 02
+type: tdd
+wave: 2
+depends_on: [27-01]
+files_modified:
+  - includes/class-config.php
+  - tests/unit/ConfigSanitizeTest.php
+  - tests/integration/ProfilesCompileTest.php
+  - TESTING.md
+autonomous: true
+requirements: [ROLE-02]
+must_haves:
+  truths:
+    - "A `profiles` map sanitizes under the same guard/coerce/intersect/cap/sparse shape as every other axis."
+    - "Profiles COMPILE onto items[slug].hidden_profiles at save time — resolution never consults the map."
+    - "A role-only or user-only config sanitizes byte-identically — zero regression on both shipped axes."
+    - "The compile is deterministic: same input, same stored output, no ordering surprises."
+---
+
+<objective>
+Build the storage half: the `profiles` authoring map, and the compile step that
+expands it onto the inline `hidden_profiles` axis.
+
+Purpose: the feasibility note's whole architecture rests on profiles being an
+authoring convenience that *compiles away*, so resolution stays in one seam.
+If the map ever has to be consulted at resolve time, the design has failed — and
+this plan is where that property is established or lost.
+Output: sanitize accepts profiles, compiles them, and leaves the existing axes
+untouched.
+</objective>
+
+<context>
+@.planning/phases/27-cloned-role-hiding-profiles/27-CONTEXT.md
+@.planning/phases/19-cosmetic-hiding-feasibility/19-FEASIBILITY-NOTE.md
+@includes/class-config.php
+@tests/unit/ConfigSanitizeTest.php
+
+<interfaces>
+<!-- Contracts the executor builds on. Use directly — no exploration needed. -->
+
+Follow `Config::sanitize()`'s established axis shape exactly:
+guard `! empty && is_array` → coerce members → intersect against what is LIVE →
+cap → assign ONLY when non-empty (sparse: reset = absent key).
+
+`hidden_users` is the closest model — read it before writing `hidden_profiles`.
+
+**The compile is the load-bearing part.** `profiles` is authoring; the stored
+`items[slug].hidden_profiles` is what replay reads. Both are persisted, but only
+the compiled axis is ever resolved from. Getting this backwards — resolving from
+the map — reintroduces the second lookup path §5b was rejected for.
+
+**Zero-regression is not optional.** `ConfigSanitizeTest` already has
+`test_role_only_config_is_unchanged_by_the_user_axes`, added when the user axes
+landed for exactly this reason. Add its profiles analogue: a config carrying only
+role and user axes must sanitize byte-identically after this plan.
+
+**Authorization**, if 27-01 decided profiles need it: `protected_user_axes()` is
+the pattern — reject-on-add, and preserve rather than destroy for a saver without
+authority. Note the lesson recorded there: that protection took four attempts
+because it was three mechanisms instead of one. If profiles need the same, build
+it as ONE map keyed by normalized slug from the start.
+</interfaces>
+</context>
+
+<tasks>
+
+<task type="auto" tdd="true">
+  <name>Task 1: The profiles map — sanitize and bound</name>
+  <files>includes/class-config.php, tests/unit/ConfigSanitizeTest.php</files>
+  <behavior>
+    - A `profiles` map survives sanitize with each entry's name, hide-list and
+      assignment cleaned under the caps decided in 27-01.
+    - Members are intersected against LIVE users (and roles, if 27-01 kept them).
+    - Empty / all-invalid profiles are dropped entirely (sparse contract).
+    - Profile names are bounded and sanitized — they become array KEYS and reach
+      the editor as labels, so treat them as untrusted strings, not identifiers.
+    - A config with no `profiles` key behaves exactly as today.
+  </behavior>
+  <action>
+    Mirror the `hidden_users` block's structure so a reader can diff them.
+
+    Resolve the live member set ONCE per sanitize call, not per profile — the
+    `hidden_users` axis learned this (`valid_user_ids()` with a bounded `include`
+    query); do not reintroduce an unbounded `get_users()`.
+
+    TDD: failing unit tests first, one green commit with test + impl, TESTING.md
+    counts in the same commit.
+  </action>
+  <verify><automated>composer test:unit -- --filter ConfigSanitizeTest</automated></verify>
+  <done>Profiles round-trip under caps and the sparse contract; names treated as untrusted; one bounded membership query.</done>
+</task>
+
+<task type="auto" tdd="true">
+  <name>Task 2: Compile profiles onto the inline axis</name>
+  <files>includes/class-config.php, tests/integration/ProfilesCompileTest.php, TESTING.md</files>
+  <behavior>
+    - Saving a profile that hides slugs A and B writes `hidden_profiles` containing
+      that profile's name onto items A and B.
+    - Removing a slug from the profile removes it from that item's axis on the next
+      save; emptying the axis drops the key (sparse).
+    - Deleting a profile leaves no dangling reference that RESOLVES — whether it is
+      cleaned at compile time or self-heals at resolve time is 27-01's decision,
+      but the test asserts whichever was chosen.
+    - The compile is deterministic and idempotent: sanitizing an already-compiled
+      config twice produces identical output.
+    - Compiled items respect `MAX_ITEMS`; a profile naming more slugs than remain
+      does not silently evict other overrides.
+  </behavior>
+  <action>
+    Idempotence matters more than it looks: the editor autosaves a FULL REPLACE,
+    so this runs on every save, repeatedly, over its own prior output. A compile
+    that is not idempotent produces drift that only shows up after N saves.
+
+    The MAX_ITEMS interaction is the same shape as the starvation bug the v1.5.0
+    ultrareview found in the per-user path — reserve or bound deliberately rather
+    than discovering it later.
+  </action>
+  <verify><automated>npm run test:php -- --filter ProfilesCompileTest</automated></verify>
+  <done>Compile is correct, idempotent, bounded, and asserted against MAX_ITEMS.</done>
+</task>
+
+<task type="auto" tdd="true">
+  <name>Task 3: Zero-regression guard</name>
+  <files>tests/unit/ConfigSanitizeTest.php</files>
+  <behavior>
+    - A config carrying ONLY role and user axes sanitizes byte-identically to
+      before this plan.
+    - All five axes coexist independently on one entry.
+  </behavior>
+  <action>
+    This is the cheapest possible proof that two shipped features were not
+    disturbed, and it is why the equivalent guard existed for the user axes.
+    Assert the whole array with `assertSame`, not field-by-field.
+  </action>
+  <verify><automated>composer test:unit</automated></verify>
+  <done>Shipped axes provably untouched; five-axis coexistence asserted.</done>
+</task>
+
+</tasks>
+
+<verification>
+- composer test:unit + npm run test:php green (both lanes).
+- composer lint clean; composer analyse:phpstan clean.
+- No change to class-replay.php or assets/* in this plan — storage only.
+- `grep` confirms nothing resolves FROM the profiles map.
+</verification>
+
+<success_criteria>
+- Profiles are stored, bounded, and compiled onto the inline axis.
+- The compile is idempotent under repeated full-replace saves.
+- Role and user axes are provably unchanged.
+</success_criteria>
+
+<output>
+Create `.planning/phases/27-cloned-role-hiding-profiles/27-02-SUMMARY.md`.
+</output>
diff --git a/.planning/phases/27-cloned-role-hiding-profiles/27-03-PLAN.md b/.planning/phases/27-cloned-role-hiding-profiles/27-03-PLAN.md
new file mode 100644
index 0000000..6deb8db
--- /dev/null
+++ b/.planning/phases/27-cloned-role-hiding-profiles/27-03-PLAN.md
@@ -0,0 +1,160 @@
+---
+phase: 27-cloned-role-hiding-profiles
+plan: 03
+type: tdd
+wave: 3
+depends_on: [27-02]
+files_modified:
+  - includes/class-replay.php
+  - tests/integration/ReplayHiddenProfilesTest.php
+  - tests/integration/CosmeticInvariantUsersTest.php
+  - TESTING.md
+autonomous: true
+requirements: [ROLE-02]
+must_haves:
+  truths:
+    - "Term 3 lands in the slot Phase 21 reserved — the seam stays ONE drop path."
+    - "Profile membership is resolved LIVE each request, never read from storage as truth."
+    - "The cosmetic-only invariant holds for the profiles axis exactly as for roles and users."
+    - "Role and user axes are bit-for-bit unchanged."
+---
+
+<objective>
+Widen the seam with the third and final ROLE-02 term, and resolve profile
+membership live.
+
+Purpose: this is the moment the whole "one lookup, one seam, one audit point"
+argument either holds or doesn't. Phase 21 built the seam as independent OR'd
+terms and left `class-replay.php:510` commented and waiting precisely so this
+plan is an addition rather than a restructuring. If it turns into a restructuring,
+that is a signal worth stopping on.
+Output: `hidden_profiles` hides rows through the same single path as the other
+two axes.
+</objective>
+
+<context>
+@.planning/phases/27-cloned-role-hiding-profiles/27-CONTEXT.md
+@.planning/phases/27-cloned-role-hiding-profiles/27-02-SUMMARY.md
+@includes/class-replay.php
+
+<interfaces>
+<!-- Contracts the executor builds on. Use directly — no exploration needed. -->
+
+**The reserved slot** — `class-replay.php` ~L510:
+```php
+// Term 3 — hidden_profiles (cloned-role half of ROLE-02) slots in here,
+// resolving profile membership live. Deferred; …
+```
+Replace the comment with the term. Keep the terms independent — do not fuse them
+into one condition; the shape is what made this phase an addition.
+
+**THE ASYMMETRY 27-01 must have already worked out.** Terms 1 and 2 are list
+intersects against a property of the current user (`$user->roles`, `$user->ID`).
+Term 3 is NOT: `hidden_profiles` holds profile NAMES, and whether the current
+user is in a profile requires reading the `profiles` map's assignment list. So
+the term is "does any profile named in this item's axis currently contain me".
+
+That is still one seam and one drop path — but it does mean the seam now touches
+the profiles map for MEMBERSHIP. That is explicitly allowed by §7 ("consulted only
+to know whom a profile currently applies to") and is what makes membership
+self-healing. Build the membership index ONCE per request, not per item: the note
+calls for "a per-request in-memory index from slug → owning profiles, built once".
+
+**Do not let this become a second resolve path.** The item's axis is still read
+through `resolved_override_list( 'hidden_profiles', … )` so it inherits the
+qualified-key, schema-v2 and Axis-1/Axis-2 guards. Only membership comes from the
+map.
+
+**The fast path must survive.** `is_hidden_for_current_user()` returns before
+resolving the current user when NO axis is present. A config with no profiles
+must not pay for a membership index.
+</interfaces>
+</context>
+
+<tasks>
+
+<task type="auto" tdd="true">
+  <name>Task 1: Term 3 and the live membership index</name>
+  <files>includes/class-replay.php, tests/integration/ReplayHiddenProfilesTest.php, TESTING.md</files>
+  <behavior>
+    - An item whose `hidden_profiles` names a profile containing the current user
+      is hidden.
+    - Removing the user from the profile un-hides it on the next request, with no
+      re-save — membership is live.
+    - Deleting the profile entirely un-hides it, likewise (self-healing).
+    - The three terms OR independently: matched by any one → hidden; by none →
+      visible; by several → hidden once.
+    - A config with no profiles axis costs nothing: no membership index built.
+    - `current_user_can()` is not called anywhere on this path.
+  </behavior>
+  <action>
+    Build the membership index lazily on first use and reuse it for every item —
+    the same lesson `Config::live_user_ids()` records.
+
+    Mirror the edit-mode suspension question deliberately: the per-user axis is
+    suspended in edit mode so a self-target stays undoable. Ask whether a profile
+    containing the acting admin needs the same treatment — it plausibly does, and
+    for the same reason. **If 27-01 did not decide this, stop and ask rather than
+    guessing.**
+
+    TDD, one green commit, TESTING.md counts in the same commit.
+  </action>
+  <verify><automated>npm run test:php -- --filter ReplayHiddenProfilesTest</automated></verify>
+  <done>Third term lands in the reserved slot; membership live and self-healing; fast path intact; terms independent.</done>
+</task>
+
+<task type="auto" tdd="true">
+  <name>Task 2: Extend the cosmetic-only guardrail to the profiles axis</name>
+  <files>tests/integration/CosmeticInvariantUsersTest.php, TESTING.md</files>
+  <behavior>
+    - The §6 six-step invariant runs for a profile-based rule: capability map
+      identical before, during and after; visibility genuinely changed; the
+      direct-URL escape hatch intact.
+  </behavior>
+  <action>
+    EXTEND the existing file rather than starting a new one — the §6 sketch always
+    anticipated covering the profiles axis with the same steps, and one guardrail
+    covering all three axes is the honest shape.
+
+    Keep `snapshot_caps()`'s deliberate user rebuild. Its docblock explains why:
+    without it `current_user_can()` answers from a cached allcaps array and the
+    guardrail cannot detect a broken seam. That was discovered the hard way.
+  </action>
+  <verify><automated>npm run test:php -- --filter CosmeticInvariantUsersTest</automated></verify>
+  <done>Cosmetic-only proven for all three ROLE-02 axes in one file.</done>
+</task>
+
+<task type="auto" tdd="true">
+  <name>Task 3: Zero-regression across both shipped axes</name>
+  <files></files>
+  <behavior>
+    - Every existing role- and user-axis test passes UNMODIFIED.
+    - Both integration lanes green, single-site and multisite.
+  </behavior>
+  <action>
+    If an existing test needs editing, stop and justify it. On a phase that is
+    supposed to be purely additive — a reserved slot being filled — a changed
+    assertion in an older spec is more likely a regression than a drifted
+    expectation. That distinction has mattered here before.
+  </action>
+  <verify><automated>npm run test:php &amp;&amp; npm run test:php:multisite</automated></verify>
+  <done>Both lanes green with no older test edited.</done>
+</task>
+
+</tasks>
+
+<verification>
+- Both integration lanes green; unit green; WPCS and PHPStan clean.
+- The seam still has ONE drop path per menu level.
+- Nothing resolves the item→hide decision from the profiles map; membership only.
+</verification>
+
+<success_criteria>
+- ROLE-02's third axis hides through the same seam as the first two.
+- Membership is live, so profile edits take effect without a re-save.
+- The cosmetic-only guarantee covers all three axes.
+</success_criteria>
+
+<output>
+Create `.planning/phases/27-cloned-role-hiding-profiles/27-03-SUMMARY.md`.
+</output>
diff --git a/.planning/phases/27-cloned-role-hiding-profiles/27-04-PLAN.md b/.planning/phases/27-cloned-role-hiding-profiles/27-04-PLAN.md
new file mode 100644
index 0000000..bf591fa
--- /dev/null
+++ b/.planning/phases/27-cloned-role-hiding-profiles/27-04-PLAN.md
@@ -0,0 +1,154 @@
+---
+phase: 27-cloned-role-hiding-profiles
+plan: 04
+type: tdd
+wave: 4
+depends_on: [27-03]
+files_modified:
+  - includes/class-replay.php
+  - includes/class-assets.php
+  - assets/maestro-logic.js
+  - assets/maestro.js
+  - assets/maestro.css
+  - tests/js/profile-targets.test.mjs
+  - tests/integration/ReplayMenuModelProfilesTest.php
+  - TESTING.md
+autonomous: true
+requirements: [ROLE-02]
+must_haves:
+  truths:
+    - "The editor model exposes profiles and the per-item axis through the SHARED resolvers."
+    - "Authoring follows whatever 27-01 decided — inline, dedicated surface, or hybrid — and nothing else."
+    - "Pure logic lives in maestro-logic.js and is unit-tested; the popover calls it rather than re-inlining."
+    - "New controls are labelled and keyboard-operable at the point they are written."
+---
+
+<objective>
+Make profiles reachable: model exposure, authoring, and the per-item assignment
+control.
+
+Purpose: 27-02 and 27-03 make profiles real but invisible. This plan is where the
+feature becomes usable — and where the previous two axes each acquired their
+worst bugs, so it inherits their lessons explicitly rather than rediscovering them.
+Output: profiles can be created, assigned, and seen, and a save round-trips.
+</objective>
+
+<context>
+@.planning/phases/27-cloned-role-hiding-profiles/27-CONTEXT.md
+@.planning/phases/27-cloned-role-hiding-profiles/27-03-SUMMARY.md
+@includes/class-replay.php
+@assets/maestro.js
+
+<interfaces>
+<!-- Contracts the executor builds on. Use directly — no exploration needed. -->
+
+**Four lessons this surface has already taught, in order of how much they cost:**
+
+1. **Server, model and client must agree on the axis** or a round-trip save
+   silently drops a working rule. `get_menu_model()` must resolve
+   `hiddenProfiles` through `resolved_override_list()` — the SAME resolver — and
+   `buildConfig()` must emit under the key `Config::sanitize()` accepts.
+2. **A gate that is only client-side is not a gate.** If 27-01 decided profile
+   authoring needs `list_users` (it names people), enforce it server-side too.
+   The v1.5.0 ultrareview found the per-user version of exactly this, and the fix
+   then needed three more rounds.
+3. **Do not re-inline a tested predicate.** Pure logic goes in
+   `maestro-logic.js`; the popover calls it. Both `isChildRoleLockedByParent` and
+   the user-axis helpers had to be fixed for this.
+4. **Detach-before-outside-click.** `placePopover()`'s handler tests
+   `pop.contains( e.target )`; any control that re-renders its own container on
+   click must `stopPropagation()` or it tears the popover down. This bit the
+   person picker's results AND its chips.
+
+**Also carry forward:**
+- Emit ids + display labels together, resolved in ONE batched pass — the person
+  picker's model does this and the reasoning holds for profile membership too.
+- The marker convention: `.maestro-has-hidden` means "this row has a hide rule of
+  its own", which is now ANY of three axes. Seed and toggle sites must agree —
+  they have drifted twice.
+- REST URLs: choose the separator (`?` vs `&`). `rest_url()` already carries a
+  query string on plain permalinks, which 404'd the person picker.
+</interfaces>
+</context>
+
+<tasks>
+
+<task type="auto" tdd="true">
+  <name>Task 1: Expose profiles and the per-item axis in the editor model</name>
+  <files>includes/class-replay.php, includes/class-assets.php, tests/integration/ReplayMenuModelProfilesTest.php, TESTING.md</files>
+  <behavior>
+    - Every node exposes its resolved `hiddenProfiles` via the shared resolver.
+    - The localized payload carries the profile registry the editor needs to render
+      names and membership, batched — not one lookup per profile.
+    - A profile referenced by an item but no longer existing is omitted from the
+      model (self-healing display, matching the deleted-user precedent).
+    - If authoring is gated, the model withholds profile data from an ungated
+      viewer rather than relying on the UI to hide it.
+  </behavior>
+  <verify><automated>npm run test:php -- --filter ReplayMenuModelProfilesTest</automated></verify>
+  <done>Model agrees with replay; registry batched; dead references omitted; gate enforced where it counts.</done>
+</task>
+
+<task type="auto" tdd="true">
+  <name>Task 2: Pure client logic</name>
+  <files>assets/maestro-logic.js, tests/js/profile-targets.test.mjs</files>
+  <behavior>
+    - Axis add/remove/membership predicates for the profiles axis, sparse-safe.
+    - Any "is this profile assigned here" test is a pure exported function.
+    - Existing role/user helpers unchanged.
+  </behavior>
+  <action>
+    Model on the user-axis helpers. Keep them pure so they are unit-testable
+    without a DOM, and so the popover has a tested function to call instead of an
+    inline copy.
+  </action>
+  <verify><automated>npm run test:js</automated></verify>
+  <done>Profile axis logic pure, exported, unit-tested; existing helpers untouched.</done>
+</task>
+
+<task type="auto" tdd="true">
+  <name>Task 3: Authoring and assignment UI</name>
+  <files>assets/maestro.js, assets/maestro.css, TESTING.md</files>
+  <behavior>
+    - Profiles can be assigned to an item per 27-01's decision.
+    - Profiles can be created/managed per 27-01's decision.
+    - Deleting or emptying a profile is reflected without a stale rule appearing active.
+    - buildConfig() emits the axis under the stored key; a save→reload round-trip
+      preserves every rule exactly.
+    - Toggling a profile never mutates the role or user axes, and vice versa.
+  </behavior>
+  <action>
+    If this adds a FIFTH group to the visibility popover, check the result at a
+    realistic viewport before accepting it. Four groups already make it tall; a
+    fifth may argue for the dedicated-surface option even if 27-01 chose inline.
+    Say so rather than shipping a popover that scrolls past the screen.
+
+    a11y at the point of writing, not retrofitted: programmatic group name, real
+    labels, keyboard-operable controls, and accessible names on any icon-only
+    control that name WHAT they act on. Phase 20 and the person picker both had
+    to fix this after the fact.
+  </action>
+  <verify>
+    <automated>npm run test:js</automated>
+    <manual>Assign a profile, save, reload, confirm it persists and applies in a second user's session.</manual>
+  </verify>
+  <done>Profiles authorable and assignable; round-trip exact; axes independent; new controls labelled and operable.</done>
+</task>
+
+</tasks>
+
+<verification>
+- Unit, both integration lanes, and JS green; WPCS and PHPStan clean.
+- Round-trip verified by hand before the plan closes.
+- No user-visible string left un-i18n'd.
+</verification>
+
+<success_criteria>
+- A named profile can be created, assigned, and seen to take effect.
+- Server, model and client agree on the axis — no silent drops.
+- The popover remains usable at a realistic viewport.
+</success_criteria>
+
+<output>
+Create `.planning/phases/27-cloned-role-hiding-profiles/27-04-SUMMARY.md`.
+</output>
diff --git a/.planning/phases/27-cloned-role-hiding-profiles/27-05-PLAN.md b/.planning/phases/27-cloned-role-hiding-profiles/27-05-PLAN.md
new file mode 100644
index 0000000..15fc7cd
--- /dev/null
+++ b/.planning/phases/27-cloned-role-hiding-profiles/27-05-PLAN.md
@@ -0,0 +1,178 @@
+---
+phase: 27-cloned-role-hiding-profiles
+plan: 05
+type: verification
+wave: 5
+depends_on: [27-04]
+files_modified:
+  - tests/e2e/specs/hidden-profiles.spec.ts
+  - README.md
+  - readme.txt
+  - .planning/REQUIREMENTS.md
+  - .planning/ROADMAP.md
+  - .planning/STATE.md
+  - TESTING.md
+autonomous: false
+requirements: [ROLE-02]
+must_haves:
+  truths:
+    - "The effect is proven in a targeted user's OWN rendered sidebar, not a dump or the admin's view."
+    - "A bystander outside the profile keeps every row — the assertion that proves scoping."
+    - "Full gate green across BOTH integration lanes."
+    - "ROLE-02 is recorded as FULLY delivered, and the docs stop implying otherwise."
+---
+
+<objective>
+Prove profiles end-to-end, run the gate, document, and close ROLE-02.
+
+Purpose: COMPAT-10 once shipped a model that passed every unit and integration
+test while being inert in a real sidebar. Both prior ROLE-02 axes were proven
+against a second authenticated browser context for that reason, and profiles get
+the same treatment.
+Output: browser-verified profiles, a green gate, and a requirement that is
+finally complete.
+
+**`autonomous: false`** — ends at the phase checkpoint.
+</objective>
+
+<context>
+@.planning/phases/27-cloned-role-hiding-profiles/27-04-SUMMARY.md
+@tests/e2e/specs/hidden-users.spec.ts
+@.planning/REQUIREMENTS.md
+
+<interfaces>
+<!-- Contracts the executor builds on. Use directly — no exploration needed. -->
+
+`hidden-users.spec.ts` is the model to follow, including its hard-won mechanics:
+- fixture users created by the spec, since running the PHP integration suite
+  **reinstalls the shared tests DB and wipes every user but admin**
+- sessions created ONCE per file, not per test — per-test logins added enough
+  load to start flaking unrelated specs
+- the navigation budget comes from `navigationTimeout` in playwright.config.ts
+
+**The load-bearing assertion is the BYSTANDER.** A user outside the profile must
+keep every row. Everything else would pass just as happily if the rule had
+widened to everyone — that is precisely what the per-user spec's bystander case
+exists to catch, and profiles have the same failure mode with a larger blast
+radius, since a profile is a group by construction.
+
+**Port note:** if another project holds 8888/8889, use the documented fallback
+(dev 8890 / tests 8899) AND pass `WP_ENV_TESTS_PORT=8899` — Playwright reads it
+independently of wp-env.
+</interfaces>
+</context>
+
+<tasks>
+
+<task type="auto">
+  <name>Task 1: End-to-end proof in a real sidebar</name>
+  <files>tests/e2e/specs/hidden-profiles.spec.ts, TESTING.md</files>
+  <behavior>
+    - Admin creates a profile, assigns it to an item, adds a user to it; in that
+      user's OWN session the row is gone.
+    - A bystander NOT in the profile still sees the row.
+    - Removing the user from the profile restores the row with NO re-save —
+      membership is live, which is the property that distinguishes a profile from
+      a per-user list.
+    - Deleting the profile restores it likewise.
+    - The hidden page still loads by direct URL for the targeted user.
+  </behavior>
+  <action>
+    The live-membership assertions are what make this spec worth more than a
+    copy of the per-user one: they prove the compile/resolve split actually works
+    as designed, rather than profiles being a fancy way to write `hidden_users`.
+  </action>
+  <verify><automated>npm run test:e2e -- tests/e2e/specs/hidden-profiles.spec.ts</automated></verify>
+  <done>Profiles proven in a real sidebar; bystander unaffected; membership live in both directions; escape hatch intact.</done>
+</task>
+
+<task type="auto">
+  <name>Task 2: Full zero-regression gate</name>
+  <files>TESTING.md</files>
+  <action>
+    Unit, integration (BOTH lanes), JS, full e2e, WPCS, PHPStan, doc-links, plus
+    Plugin Check on the built ZIP.
+
+    Confirm the CI head SHA matches the commit you are judging — a green check
+    from an earlier commit is not evidence about this one, which has caught this
+    project twice.
+
+    Record actual counts. An unexplained count change is how a silently skipped
+    suite ships as a pass.
+  </action>
+  <verify><automated>composer test:unit &amp;&amp; npm run test:php &amp;&amp; npm run test:php:multisite &amp;&amp; npm run test:js &amp;&amp; npm run test:e2e &amp;&amp; composer lint &amp;&amp; composer analyse:phpstan</automated></verify>
+  <done>Full gate green at the judged commit with counts recorded.</done>
+</task>
+
+<task type="auto">
+  <name>Task 3: Documentation</name>
+  <files>README.md, readme.txt</files>
+  <behavior>
+    - Profiles are described in user terms: name a reusable hide-set, assign
+      people to it, apply it to items.
+    - The cosmetic-only guarantee is restated where the feature is introduced.
+    - When a profile beats a role and when it does not is stated — the honest
+      guidance is that a role is better when one already matches.
+    - No claim that profiles are access control, roles, or WordPress-visible.
+  </behavior>
+  <action>
+    The most important sentence remains that hiding is cosmetic. A named
+    "Reduced view" profile sounds more like permissions than a role checkbox does,
+    so the risk of a site owner reading it as security is HIGHER here, not lower.
+    Say it plainly and next to the feature.
+  </action>
+  <verify><automated>npm run check:doc-links</automated></verify>
+  <done>Profiles documented with the cosmetic-only guarantee and honest guidance; no overclaims.</done>
+</task>
+
+<task type="auto">
+  <name>Task 4: Close ROLE-02</name>
+  <files>.planning/REQUIREMENTS.md, .planning/ROADMAP.md, .planning/STATE.md</files>
+  <behavior>
+    - ROLE-02 moves from `[~]` PARTIAL to `[x]` COMPLETE, with both halves named.
+    - The traceability row, the roadmap, and STATE agree.
+    - The cloned-role todo moves to `completed/`.
+    - Any remaining ROLE-02 caveat is restated, not dropped.
+  </behavior>
+  <action>
+    ROLE-02 has been half-delivered since v1.5.0 and the docs have said so
+    consistently. Closing it means changing that in every place it appears — a
+    requirement marked complete in one file and partial in another is the exact
+    drift the V2-backlog reconciliation existed to fix.
+
+    Carry forward what is still true: the multisite exemption asymmetry, and
+    whether the profiles axis inherits it.
+  </action>
+  <verify><manual>Read ROLE-02's status in all three files and confirm they agree.</manual></verify>
+  <done>ROLE-02 complete and consistent everywhere; todo moved; caveats carried.</done>
+</task>
+
+<task type="checkpoint">
+  <name>Task 5: Phase verification</name>
+  <action>
+    Present what shipped, the gate numbers, and anything automation could not
+    settle. State explicitly whether a human drove the profile flow in a browser
+    — v1.5.0's record had to say that its equivalent checkpoint was accepted on
+    automated evidence, and the value of that honesty depends on not blurring it
+    the next time.
+  </action>
+  <verify><manual>Human verifies in wp-env and approves.</manual></verify>
+  <done>Phase verified; VERIFICATION.md written; STATE updated to the next position.</done>
+</task>
+
+</tasks>
+
+<verification>
+- Profiles proven in a targeted user's own session, with a bystander control.
+- Full gate green across both lanes.
+- ROLE-02 complete and consistent in every planning file.
+</verification>
+
+<success_criteria>
+- A named profile hides items for its members only, cosmetically, live.
+- ROLE-02 is finally, honestly, complete.
+</success_criteria>
+
+<output>
+Create `27-05-SUMMARY.md` and `27-VERIFICATION.md`.
+</output>

From 2ebe6fdf2a07aa57dd02c796f8403c910aacfd54 Mon Sep 17 00:00:00 2001
From: Dan Knauss <273554+dknauss@users.noreply.github.com>
Date: Mon, 10 Aug 2026 00:32:20 -0600
Subject: [PATCH 16/27] docs(planning): log toolbar height + #collapse-menu
 parity, which gates the width feature (#140)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Two things on the same surface, and the second is the reason to log it.

The edit-mode toolbar is ~56px of permanently fixed space around icon-only
controls — trimmable with straightforward CSS.

More significant: forceUnfold() (assets/maestro.js ~L197) does not merely
override folded mode, it NEUTERS #collapse-menu with a capture-phase
preventDefault() + stopImmediatePropagation(). The control still renders, still
looks interactive, still takes focus, and does nothing whatsoever. maestro.css
adds width:160px !important as a backstop for the same reason. The intent is
sound — a 36px rail has no room for rename fields or drag handles — but the
execution is what a user experiences as 'collapse is broken in this plugin'.

That matters beyond the papercut because it GATES configurable-admin-menu-width
(V2-09), whose own note says it must 'respect folded mode'. Edit mode currently
refuses folded mode outright. Those two positions cannot be designed
independently without producing a config whose behaviour depends on which screen
you are on — so the fold story wants deciding first. Designing width against an
unstated conflict is the pattern this project has already paid for twice.

Three options recorded, including the cheapest honest one: keep forcing unfold
but make the control VISIBLY disabled with a reason, matching the treatment the
derived-locked checkbox got in Phase 25. A dead control that looks dead is not a
bug.

Raised by the user while reviewing the Phase 25 toolbar work.

Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
---
 .planning/STATE.md                            | 11 +++
 ...toolbar-height-and-collapse-menu-parity.md | 73 +++++++++++++++++++
 2 files changed, 84 insertions(+)
 create mode 100644 .planning/todos/pending/2026-08-10-toolbar-height-and-collapse-menu-parity.md

diff --git a/.planning/STATE.md b/.planning/STATE.md
index 91f383d..67d9f58 100644
--- a/.planning/STATE.md
+++ b/.planning/STATE.md
@@ -329,6 +329,17 @@ Recent decisions affecting current work:
 
 ### Pending Todos
 
+- **Toolbar height + `#collapse-menu` parity** — the edit-mode bar is ~56px of
+  fixed real estate around icon-only controls, and more importantly
+  `forceUnfold()` (`maestro.js` ~L197) NEUTERS the Collapse menu control with a
+  capture-phase `preventDefault()` + `stopImmediatePropagation()`: it still
+  renders and takes focus but does nothing at all. The intent is sound (you
+  cannot edit a menu you cannot read) but it reads as "collapse is broken".
+  **This gates `configurable-admin-menu-width`**, which must "respect folded
+  mode" while edit mode currently refuses it — design those together or the
+  width work inherits an unstated conflict. Captured in
+  `todos/pending/2026-08-10-toolbar-height-and-collapse-menu-parity.md`
+
 - **Persistent saved-state indicator** — the save status is event feedback that
   self-erases after 2s (`maestro.js` ~L1748), so seconds after a rename commits
   there is no on-screen answer to "did that save?". Core's pattern is persistent
diff --git a/.planning/todos/pending/2026-08-10-toolbar-height-and-collapse-menu-parity.md b/.planning/todos/pending/2026-08-10-toolbar-height-and-collapse-menu-parity.md
new file mode 100644
index 0000000..193de2e
--- /dev/null
+++ b/.planning/todos/pending/2026-08-10-toolbar-height-and-collapse-menu-parity.md
@@ -0,0 +1,73 @@
+---
+created: 2026-08-10T00:00:00.000Z
+title: Trim the edit-mode toolbar height, and decide what Collapse menu does while editing
+area: editor-ux
+files:
+  - assets/maestro.css (.maestro-toolbar — padding 10px 16px; .maestro-toolbar .button min-height 36px)
+  - assets/maestro.js (~L197-215 forceUnfold — strips .folded/.auto-fold, MutationObserver re-strips, and NEUTERS #collapse-menu)
+  - assets/maestro.css (~L11-29 — the defensive folded-mode width:160px !important backstop)
+---
+
+## Two things, and the second is the reason to do this
+
+### 1. The toolbar is taller than it needs to be
+
+`.maestro-toolbar` is `padding: 10px 16px` around `min-height: 36px` controls —
+roughly 56px of permanently fixed real estate at the bottom of every edit-mode
+screen, on a surface whose controls are all icon-only. Trimming it is
+straightforward CSS and buys back vertical space on exactly the screens where
+the menu being edited is longest.
+
+### 2. `#collapse-menu` is DEAD during edit mode, silently
+
+This is the part worth deciding rather than trimming around.
+
+`forceUnfold()` (`assets/maestro.js` ~L197) does three things on entering edit mode:
+
+1. strips `body.folded` / `body.auto-fold`
+2. installs a `MutationObserver` that re-strips them if `common.js` writes them back
+3. attaches a **capture-phase** click handler on `#collapse-menu` calling
+   `preventDefault()` + `stopImmediatePropagation()`
+
+So the Collapse menu control is not merely overridden — it is **completely
+inert**. It still renders, still looks interactive, still takes focus, and does
+nothing at all when clicked. `maestro.css` ~L11-29 adds `width: 160px !important`
+as a defensive backstop for the same reason.
+
+The intent is sound: you cannot usefully edit a menu you cannot read, and a
+folded 36px rail has no room for rename fields or drag handles. The *execution*
+is what a user experiences as "collapse is broken in this plugin".
+
+## Why this blocks thinking about menu width
+
+`configurable-admin-menu-width` (V2-09) explicitly has to "respect folded mode".
+But edit mode currently **refuses** folded mode outright. Those two positions
+cannot both be designed independently — a width feature that honours folding,
+sitting next to an edit mode that forcibly unfolds, will produce a config whose
+behaviour depends on which screen you are on.
+
+**Decide the fold story first, then design width against it.** Otherwise the
+width work inherits an unstated conflict and discovers it late, which is the
+pattern this project has already paid for twice (Phase 21's release target,
+Phase 25's criterion 1).
+
+## Options for the fold question
+
+- **Keep forcing unfold, but say so.** Cheapest. Disable the control visibly
+  (`aria-disabled` + a title explaining why, matching the treatment the
+  derived-locked checkbox got in Phase 25) instead of silently eating the click.
+  A dead control that *looks* dead is not a bug.
+- **Allow folding, and adapt.** Editing in a 36px rail needs a different
+  affordance — possibly the toolbar becomes the whole editing surface. Much
+  larger, but it is the honest answer if people actually want to edit folded.
+- **Auto-restore on exit.** Whatever is chosen, check whether the user's folded
+  preference survives leaving edit mode. `forceUnfold()` strips the class; core
+  stores the preference in user meta, so it likely returns on reload — but that
+  is worth verifying rather than assuming.
+
+## Not urgent
+
+Nothing is broken in the sense of losing data, and the toolbar works. But the
+silently-dead control is a small, real papercut on a plugin whose whole pitch is
+that editing happens in place with zero ceremony — and the fold decision gates a
+feature already in the backlog.

From 29025ce614cbc0a6ce33112bc7e8e4b222e5503d Mon Sep 17 00:00:00 2001
From: Dan Knauss <273554+dknauss@users.noreply.github.com>
Date: Mon, 10 Aug 2026 00:40:01 -0600
Subject: [PATCH 17/27] docs(planning): record the verified collapse-menu
 findings and cross-link the blocker (#141)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Follow-up to #140, replacing assumptions with checked facts and making the
conflict impossible to miss from the OTHER side.

VERIFIED, so nobody re-derives it:

1. The control is inert, not merely overridden — forceUnfold() registers a
   CAPTURE-phase listener on #collapse-menu calling preventDefault() +
   stopImmediatePropagation(), so nothing downstream ever sees the click.
2. There is a CSS backstop as well as the JS: maestro.css forces
   width:160px !important on #adminmenu/#adminmenuwrap/#adminmenuback plus a
   matching margin-left on #wpcontent/#wpfooter. Any fold decision must change
   BOTH layers, not just the JS.
3. The user's folded preference is SAFE. This was an open question in #140; it
   is now closed. forceUnfold() runs only from init(), which is reached solely
   in edit mode, and strips the class client-side — so leaving edit mode is a
   navigation, core re-renders body.folded from user meta, and the
   MutationObserver dies with the page. Nothing to undo, nothing leaks.
4. It is undocumented outside the code. The behaviour is explained in maestro.js's
   header and at the function, but appears nowhere in README.md, readme.txt or
   docs/ — the only other mentions are in docs/archive/FIXES.md, which records a
   HISTORICAL folded-mode bug and is actively misleading if found while searching
   for this one.

Left deliberately undone: a readme FAQ entry. Documenting "collapse does nothing
while editing" as intended, then changing it, costs a second doc edit and a
changelog line. Flagged as an open question rather than decided unilaterally.

Also cross-links the blocker INTO configurable-admin-menu-width, where it will
actually be seen. Stated concretely there: ship both as-is and a site with
menu_width:240 renders 240px while browsing and snaps to 160px the moment edit
mode opens — the editor showing a different width than the thing it is editing.
A pointer in only one direction would have left the width todo reading as ready.
---
 ...026-08-09-configurable-admin-menu-width.md | 10 +++-
 ...toolbar-height-and-collapse-menu-parity.md | 49 +++++++++++++++++--
 2 files changed, 54 insertions(+), 5 deletions(-)

diff --git a/.planning/todos/pending/2026-08-09-configurable-admin-menu-width.md b/.planning/todos/pending/2026-08-09-configurable-admin-menu-width.md
index 57c2386..52b534a 100644
--- a/.planning/todos/pending/2026-08-09-configurable-admin-menu-width.md
+++ b/.planning/todos/pending/2026-08-09-configurable-admin-menu-width.md
@@ -33,7 +33,15 @@ every page load for every admin user — worth being deliberate about, since
 
 Three interactions to get right, none optional:
 - **Folded mode** (`.folded`, 36px) must still fold — a fixed width that ignores
-  it breaks the collapse control entirely
+  it breaks the collapse control entirely.
+  **⚠️ BLOCKED ON A DECISION, added 2026-08-10.** Edit mode currently REFUSES to
+  fold: `forceUnfold()` strips the classes, re-strips them via MutationObserver,
+  neuters `#collapse-menu` with a capture-phase handler, and `maestro.css` forces
+  `width: 160px !important` as a backstop. Ship both features as-is and a site
+  with `menu_width: 240` renders 240px while browsing and snaps to 160px the
+  instant edit mode opens — the editor showing a different width than the thing
+  it is editing. **Settle the fold story first:**
+  `todos/pending/2026-08-10-toolbar-height-and-collapse-menu-parity.md`
 - **The `<782px` responsive breakpoint**, where the menu becomes an overlay
 - **`#wpcontent`'s matching offset** — set one without the other and the content
   column overlaps or leaves a gap
diff --git a/.planning/todos/pending/2026-08-10-toolbar-height-and-collapse-menu-parity.md b/.planning/todos/pending/2026-08-10-toolbar-height-and-collapse-menu-parity.md
index 193de2e..b741a78 100644
--- a/.planning/todos/pending/2026-08-10-toolbar-height-and-collapse-menu-parity.md
+++ b/.planning/todos/pending/2026-08-10-toolbar-height-and-collapse-menu-parity.md
@@ -60,10 +60,12 @@ Phase 25's criterion 1).
 - **Allow folding, and adapt.** Editing in a 36px rail needs a different
   affordance — possibly the toolbar becomes the whole editing surface. Much
   larger, but it is the honest answer if people actually want to edit folded.
-- **Auto-restore on exit.** Whatever is chosen, check whether the user's folded
-  preference survives leaving edit mode. `forceUnfold()` strips the class; core
-  stores the preference in user meta, so it likely returns on reload — but that
-  is worth verifying rather than assuming.
+- **Auto-restore on exit — VERIFIED 2026-08-10, no action needed.** The folded
+  preference DOES return. `forceUnfold()` only ever runs from `init()`, which is
+  reached solely in edit mode, and it strips the class client-side. Leaving edit
+  mode is a page navigation, so core re-renders `body.folded` from user meta on
+  the next load and the `MutationObserver` dies with the page. Nothing to undo
+  and nothing leaks — this option is closed, not open.
 
 ## Not urgent
 
@@ -71,3 +73,42 @@ Nothing is broken in the sense of losing data, and the toolbar works. But the
 silently-dead control is a small, real papercut on a plugin whose whole pitch is
 that editing happens in place with zero ceremony — and the fold decision gates a
 feature already in the backlog.
+
+
+## Verified findings (2026-08-10)
+
+Recorded so the next person does not re-derive them:
+
+1. **The control is inert, not merely overridden.** `forceUnfold()`
+   (`assets/maestro.js` ~L197-215) removes `folded`/`auto-fold`, installs a
+   `MutationObserver` to re-remove them if `common.js` writes them back, and
+   registers a **capture-phase** listener on `#collapse-menu` calling
+   `preventDefault()` + `stopImmediatePropagation()`. Nothing downstream ever
+   sees the click.
+2. **There is a CSS backstop too.** `maestro.css` ~L11-29 forces
+   `width: 160px !important` on `#adminmenu`/`#adminmenuwrap`/`#adminmenuback`
+   and a matching `margin-left` on `#wpcontent`/`#wpfooter`, for
+   `body.maestro-editing.folded` and `.auto-fold`. So even if the class survives
+   a frame, the layout holds. Any fold decision has to change BOTH layers.
+3. **The user's preference is safe** — see the verified note above.
+4. **It is undocumented outside the code.** The behaviour is explained in
+   `maestro.js`'s file header (~L13-16) and at the function, but appears nowhere
+   in `README.md`, `readme.txt`, or `docs/` — the only other mentions are in
+   `docs/archive/FIXES.md`, which is an archived record of a *historical* folded-mode
+   bug and actively misleading if found while searching for this one.
+
+   **Open question for whoever takes this:** should a `readme.txt` FAQ entry be
+   added NOW, or only once the fold behaviour is settled? Documenting
+   "collapse does nothing while editing" as intended, and then changing it,
+   costs a second doc edit and a changelog line. Deliberately not added here.
+
+## Why the conflict matters, restated concretely
+
+`configurable-admin-menu-width` stores a global width and applies it on **every**
+admin page. Edit mode forces 160px via `!important`. So with both shipped, a
+site with `menu_width: 240` would render 240px while browsing and snap to 160px
+the moment edit mode opens — the editor showing a different width than the thing
+it is editing. That is not a minor inconsistency; it is the editor lying about
+its own subject.
+
+Deciding the fold story first is what prevents that.

From 6b6c20469597eee9146a258b2a559635c12368ee Mon Sep 17 00:00:00 2001
From: Dan Knauss <273554+dknauss@users.noreply.github.com>
Date: Mon, 10 Aug 2026 00:56:35 -0600
Subject: [PATCH 18/27] docs(planning): decide the fold story and plan Phase 28
 (menu width) (#142)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

DECISION: keep forcing unfold, stop lying about it, de-hardcode the width.

Forced unfold is KEPT and the reasoning is recorded rather than assumed. A folded
menu is a 36px icon rail with hover flyouts; Maestro's model is click-a-row and
edit its label, so you cannot rename what you cannot read, and submenu editing
would happen inside a flyout that vanishes when the pointer leaves.
docs/archive/FIXES.md #4 records that the editing UI BROKE in folded mode
historically — forcing unfold was the fix, not an oversight. The rejected
alternative (adapt the editor to a 36px rail) is recorded too: much larger work
whose payoff is editing in a mode where the labels being edited are invisible.

What changes is the honesty. #collapse-menu currently renders, takes focus and
does nothing, via a capture-phase preventDefault + stopImmediatePropagation. It
becomes visibly and programmatically disabled with a reason, matching the
treatment Phase 25 gave the derived-locked checkbox: a dead control that LOOKS
dead is not a bug, a live-looking one is.

I ALSO MIS-FRAMED THE CONFLICT ON 2026-08-09 AND HAVE WITHDRAWN IT. There is no
fold-versus-width design conflict. `160px` is hardcoded in three places
(maestro.css :22 width, :28 margin-left, :523 the toolbar's left edge), one of
which is the exact constant the width feature makes configurable. That is a
constant needing to become a variable. Outside edit mode width applies to the
expanded menu and folding works normally; inside edit mode folding is off, so
width simply applies. The decision UNBLOCKS the width work rather than
constraining it, and both todos now say so in both directions.

Phase 28 folds the two together, in dependency order:

28-01 is independently shippable and fixes today's defect: one source of truth
for the width, and an honest collapse control. It deliberately changes no
rendering at the default, because a refactor that also shifts layout by a pixel
is two changes wearing one commit.

28-02 crosses the line this feature actually turns on — applying width while
merely BROWSING wp-admin. Every asset today is edit-mode-gated except the
admin-bar CSS, so "costs nothing unless you are editing" is true now and stops
being, for every admin user on every page load. Task 1 is a checkpoint on
delivery mechanism and, more importantly, on the OPTION READ — the cost is the
non-autoloaded get_option, not the CSS. Measured numbers required, not adjectives.

28-03 adds the control. Flagged there: this is the first GLOBAL setting in a
plugin built entirely from per-item overrides, so it must not read as a property
of the selected row, and Reset Item versus Reset All semantics need deciding
with it rather than discovering later.

Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
---
 .planning/ROADMAP.md                          |  30 ++++
 .../28-01-PLAN.md                             | 134 ++++++++++++++
 .../28-02-PLAN.md                             | 153 ++++++++++++++++
 .../28-03-PLAN.md                             | 170 ++++++++++++++++++
 ...026-08-09-configurable-admin-menu-width.md |  10 +-
 ...toolbar-height-and-collapse-menu-parity.md |  38 +++-
 6 files changed, 531 insertions(+), 4 deletions(-)
 create mode 100644 .planning/phases/28-configurable-admin-menu-width/28-01-PLAN.md
 create mode 100644 .planning/phases/28-configurable-admin-menu-width/28-02-PLAN.md
 create mode 100644 .planning/phases/28-configurable-admin-menu-width/28-03-PLAN.md

diff --git a/.planning/ROADMAP.md b/.planning/ROADMAP.md
index 8c13940..d6b0a9a 100644
--- a/.planning/ROADMAP.md
+++ b/.planning/ROADMAP.md
@@ -151,6 +151,7 @@ Full phase details, success criteria, and outcomes are archived in
 - [x] **Phase 24: Release v1.4.0** — cut and shipped to WordPress.org 2026-08-04 (tag `v1.4.0` on `482510c`, PR #113); editor + directory screenshots recaptured. Patch **v1.4.1** followed 2026-08-05 (tag on `c6cdcbe`, PR #116) for the shared-slug propagation defect. Shipped WITHOUT Phases 21 and 22 — see the outcome note below
 - [x] **Phase 25: Edit-Mode Toolbar Dark-Surface Polish** — ✅ COMPLETE 2026-08-09 (2/2 plans; human-verified). Audit struck 1 of 5 criteria as already satisfied, downgraded 1 from fix to choice, absorbed 1. Shipped: reserved status slot, focus ring 3.07:1 → 6.74:1, a11y M2/M3. Original text follows — dark-toolbar icon/focus contrast (WCAG 1.4.11), save-indicator layout shift, rename commit feedback (added 2026-08-02; pre-existing v1.3.1 surfaces, non-blocking for v1.4.0)
 - [ ] **Phase 27: Cloned-Role Hiding Profiles** — completes ROLE-02's deferred half: a named, Maestro-internal hiding profile that compiles onto an inline `hidden_profiles` axis and resolves through the seam slot Phase 21 reserved at `class-replay.php:510` (planned 2026-08-10)
+- [ ] **Phase 28: Configurable Admin Menu Width** — a global `menu_width` so a renamed item no longer wraps at 160px, plus the fold decision it depends on: edit mode keeps forcing unfold but the collapse control stops pretending to work (planned 2026-08-10)
 
 ### Phase 19: Cosmetic Hiding Feasibility
 **Goal**: It is known, before any implementation, whether per-user and/or cloned-role menu hiding can be delivered without touching capabilities — and if so, how it should be stored and resolved
@@ -319,6 +320,35 @@ M2/M3 items from `todos/pending/2026-08-02-a11y-locked-checkbox-refinements.md`.
 > things, and its assumption that term 3 is a list-intersect may not survive
 > contact, since membership is a property of the USER rather than the item.
 
+### Phase 28: Configurable Admin Menu Width
+**Goal**: A renamed menu item that used to wrap at WordPress's hardcoded 160px no longer has to — a global width, applied while browsing, with folding still working everywhere it should
+**Depends on**: nothing (28-01 is independently shippable)
+**Requirements**: (none formal — V2-09, extracted from SPEC.md item 9 during the 2026-08-09 backlog reconciliation)
+**Success Criteria** (what must be TRUE):
+  1. `#collapse-menu` is VISIBLY disabled during edit mode with a programmatic reason, not silently swallowed by a capture-phase handler
+  2. The menu column width resolves from ONE source, not three hardcoded `160px` literals (`maestro.css` :22, :28, :523)
+  3. `menu_width` is stored bounded and sparse — the default is never written, and reset means absent
+  4. The width applies on ORDINARY admin pages, not only in edit mode — and a site that never set one loads nothing new and pays no new page cost
+  5. `body.folded` still folds to core's 36px outside edit mode, and the `<782px` overlay is unaffected
+  6. Zero regression across both integration lanes, JS, e2e, WPCS, PHPStan, Plugin Check
+**Plans**: 28-01 fold honesty + de-hardcode · 28-02 storage + the always-loaded seam · 28-03 control, docs, close
+
+> **The fold story was DECIDED 2026-08-10 and folded into this phase.** Edit mode
+> keeps forcing unfold — a 36px icon rail cannot show the labels being edited, and
+> `docs/archive/FIXES.md` #4 records that the editor *broke* in folded mode
+> historically. What changes is the honesty: the collapse control currently
+> renders, takes focus and does nothing, which is the actual defect.
+>
+> The "fold versus width conflict" flagged on 2026-08-09 was **mis-framed and is
+> withdrawn**. It is not a design conflict — `160px` is simply hardcoded in three
+> places, one of which is the constant this phase makes configurable. Outside edit
+> mode width applies to the expanded menu and folding works normally; inside edit
+> mode folding is off, so width just applies.
+>
+> **This phase turns Maestro into something that loads outside edit mode** for the
+> first time (28-02). "Costs nothing unless you are editing" is true today and
+> stops being — hence the measured-footprint checkpoint rather than an assumption.
+
 ## Phase Details (v1.5 — Per-User Visibility)
 
 **Milestone goal:** ship ROLE-02's per-user cosmetic hiding to WordPress.org. The
diff --git a/.planning/phases/28-configurable-admin-menu-width/28-01-PLAN.md b/.planning/phases/28-configurable-admin-menu-width/28-01-PLAN.md
new file mode 100644
index 0000000..b818ad8
--- /dev/null
+++ b/.planning/phases/28-configurable-admin-menu-width/28-01-PLAN.md
@@ -0,0 +1,134 @@
+---
+phase: 28-configurable-admin-menu-width
+plan: 01
+type: tdd
+wave: 1
+depends_on: []
+files_modified:
+  - assets/maestro.css
+  - assets/maestro.js
+  - tests/e2e/specs/fold-honesty.spec.ts
+  - TESTING.md
+autonomous: true
+requirements: []
+must_haves:
+  truths:
+    - "The menu column width exists in ONE place, not three hardcoded 160px literals."
+    - "#collapse-menu is VISIBLY disabled during edit mode, with a reason — never silently swallowed."
+    - "Forced unfold still works: the menu is expanded and legible while editing."
+    - "The user's folded preference still returns on exit."
+---
+
+<objective>
+Land the decided fold behaviour and de-hardcode the width — independently of any
+storage or settings work.
+
+Purpose: this is shippable on its own and makes the width feature a
+substitution rather than a refactor. It also fixes the actual defect in today's
+behaviour: `#collapse-menu` renders, takes focus, and does nothing.
+
+Decision recorded at
+`todos/pending/2026-08-10-toolbar-height-and-collapse-menu-parity.md` —
+**keep forcing unfold, stop lying about it, de-hardcode the width.** Do not
+re-litigate it here.
+</objective>
+
+<context>
+@.planning/todos/pending/2026-08-10-toolbar-height-and-collapse-menu-parity.md
+@assets/maestro.css
+@assets/maestro.js
+
+<interfaces>
+<!-- Contracts the executor builds on. Use directly — no exploration needed. -->
+
+**The three hardcoded values** (verified 2026-08-10 against `main`):
+
+| Location | Rule | Role |
+|---|---|---|
+| `maestro.css:22` | `width: 160px !important` | unfold backstop on `#adminmenu`/`#adminmenuwrap`/`#adminmenuback` |
+| `maestro.css:28` | `margin-left: 160px !important` | matching offset on `#wpcontent`/`#wpfooter` |
+| `maestro.css:523` | `left: 160px` | the toolbar's left edge — "clears the admin menu column" |
+
+`maestro.css:485`'s `max-height: 160px` is an unrelated results-list bound. Do
+NOT touch it — it is the same number by coincidence, which is exactly the trap.
+
+**Both layers enforce the unfold**, and both must stay in step: `forceUnfold()`
+in `maestro.js` (~L197) strips the classes and re-strips via `MutationObserver`,
+and the CSS above is the defensive backstop for a frame where the class survives.
+
+**The collapse control today:** a capture-phase listener calling
+`preventDefault()` + `stopImmediatePropagation()`. Phase 25's derived-locked
+checkbox is the model for the replacement — `aria-disabled` plus a programmatic
+reason, not native `disabled`, so the control stays reachable and can explain
+itself to assistive tech instead of vanishing from the tab order.
+</interfaces>
+</context>
+
+<tasks>
+
+<task type="auto" tdd="true">
+  <name>Task 1: One source of truth for the menu column width</name>
+  <files>assets/maestro.css</files>
+  <behavior>
+    - The three width-related literals resolve from a single custom property
+      (e.g. `--maestro-menu-width`), defaulting to 160px.
+    - Rendering is byte-identical to today at the default — this task changes
+      no behaviour, only where the number lives.
+    - The unrelated `max-height: 160px` is untouched.
+  </behavior>
+  <action>
+    A CSS custom property on `:root` (or `body.maestro-editing`) is enough; the
+    later plans set it from stored config. Keep `!important` where it already is
+    — it is there to beat core's folded rules, and that fight has not changed.
+
+    Confirm the default renders identically before moving on. A refactor that
+    also shifts layout by a pixel is two changes wearing one commit.
+  </action>
+  <verify><automated>composer lint &amp;&amp; npm run test:e2e -- tests/e2e/specs/toolbar-dark-surface.spec.ts</automated></verify>
+  <done>Width lives in one place; default rendering unchanged.</done>
+</task>
+
+<task type="auto" tdd="true">
+  <name>Task 2: Make the collapse control honestly disabled</name>
+  <files>assets/maestro.js, assets/maestro.css, tests/e2e/specs/fold-honesty.spec.ts, TESTING.md</files>
+  <behavior>
+    - During edit mode `#collapse-menu` is marked `aria-disabled="true"` and
+      carries a reason a screen reader can read.
+    - It is visually muted so a sighted user can see it is unavailable.
+    - Clicking it still does not fold — but the click is refused by an explicit
+      guard, not swallowed by a capture-phase listener that hides the intent.
+    - It remains focusable (same reasoning as Phase 25's locked checkbox: a
+      control removed from the tab order can never explain itself).
+    - Leaving edit mode restores it fully.
+  </behavior>
+  <action>
+    Keep the `MutationObserver` and the CSS backstop — the goal is to stop the
+    control lying, not to weaken the unfold.
+
+    Write the reason as user-facing copy, i18n'd: the menu stays expanded while
+    editing so labels are readable. That sentence is the whole justification and
+    the user deserves it at the point of confusion.
+
+    The e2e spec should assert the state, the reason, and that folding genuinely
+    does not happen — plus that the control is normal again outside edit mode.
+  </action>
+  <verify><automated>npm run test:e2e -- tests/e2e/specs/fold-honesty.spec.ts</automated></verify>
+  <done>Collapse control visibly and programmatically disabled with a reason; unfold still enforced; restored on exit.</done>
+</task>
+
+</tasks>
+
+<verification>
+- Full gate green (both integration lanes, JS, e2e, WPCS, PHPStan).
+- Default-width rendering identical to before.
+- No user-visible string left un-i18n'd.
+</verification>
+
+<success_criteria>
+- The width is a variable, so later plans substitute rather than refactor.
+- The collapse control no longer pretends to work.
+</success_criteria>
+
+<output>
+Create `.planning/phases/28-configurable-admin-menu-width/28-01-SUMMARY.md`.
+</output>
diff --git a/.planning/phases/28-configurable-admin-menu-width/28-02-PLAN.md b/.planning/phases/28-configurable-admin-menu-width/28-02-PLAN.md
new file mode 100644
index 0000000..b9f41bd
--- /dev/null
+++ b/.planning/phases/28-configurable-admin-menu-width/28-02-PLAN.md
@@ -0,0 +1,153 @@
+---
+phase: 28-configurable-admin-menu-width
+plan: 02
+type: tdd
+wave: 2
+depends_on: [28-01]
+files_modified:
+  - includes/class-config.php
+  - includes/class-assets.php
+  - tests/unit/ConfigSanitizeTest.php
+  - tests/integration/MenuWidthAssetTest.php
+  - TESTING.md
+autonomous: false
+requirements: []
+must_haves:
+  truths:
+    - "`menu_width` is a bounded global in the stored config, sanitized like every other value."
+    - "A site that has never set a width loads NOTHING new — the zero-config cost stays zero."
+    - "The always-loaded surface is as small as it can be, and its cost is measured, not assumed."
+---
+
+<objective>
+Store the width, and cross the line this feature actually turns on: applying it
+while merely *browsing* wp-admin.
+
+Purpose: every Maestro asset today is edit-mode-gated except
+`maestro-admin-bar.css`. "Costs nothing unless you are editing" is currently true
+and this plan is where it stops being — for every admin user, on every page load.
+That is worth being deliberate and measured about rather than discovering in a
+support thread.
+
+**`autonomous: false`** — Task 1 carries a footprint decision that is the
+user's to make.
+</objective>
+
+<context>
+@.planning/todos/pending/2026-08-09-configurable-admin-menu-width.md
+@includes/class-config.php
+@includes/class-assets.php
+@docs/performance/config-size-and-page-load.md
+
+<interfaces>
+<!-- Contracts the executor builds on. Use directly — no exploration needed. -->
+
+`Config::sanitize()`'s established shape for a scalar: coerce → bound → drop when
+it equals the default (sparse contract — a config that stores the default is
+indistinguishable from one that never set it, and reset means "absent").
+
+`Assets::enqueue()` currently returns early when `! is_edit_mode()`, after
+enqueueing only `maestro-admin-bar.css`. The width rule has to be emitted BEFORE
+that early return.
+
+**Cheapest viable delivery, in order of footprint:**
+1. An inline `<style>` on `admin_head` — no HTTP request, a few dozen bytes,
+   emitted only when a non-default width is stored. Almost certainly right.
+2. A tiny enqueued stylesheet — an extra request per page load, for one rule.
+3. Extending an existing always-loaded file — couples unrelated concerns.
+
+**The `docs/performance/config-size-and-page-load.md` baseline applies**: a
+realistic config costs ~0.1 ms/page today, and `Config::get()` is a
+non-autoloaded option, so reading it on every admin page is a new cost that
+needs measuring — not the CSS, the OPTION READ.
+</interfaces>
+</context>
+
+<tasks>
+
+<task type="checkpoint">
+  <name>Task 1: DECIDE the always-loaded footprint</name>
+  <action>
+    Two questions, both the user's:
+
+    1. **Delivery.** Inline `<style>` (recommended — no request, tiny, trivially
+       conditional) versus an enqueued file. Inline CSS is sometimes disliked on
+       principle; here it is a single rule whose value comes from user config, and
+       an extra HTTP request per admin page load to carry it is the worse trade.
+    2. **The option read.** Applying width outside edit mode means reading
+       `maestro_config` on every admin page for every admin user. It is a single
+       non-autoloaded option and object-cache-backed, so the marginal cost should
+       be near zero on a site with a persistent cache and one query without —
+       but *should be* is not *is*. Measure before shipping, and decide whether a
+       tiny autoloaded `maestro_menu_width` option is worth avoiding the read of
+       the larger one.
+
+    State the measured numbers at the checkpoint, not adjectives.
+  </action>
+  <verify><manual>Footprint decision recorded with measurements.</manual></verify>
+  <done>Delivery mechanism and option strategy decided, with numbers.</done>
+</task>
+
+<task type="auto" tdd="true">
+  <name>Task 2: Store and bound `menu_width`</name>
+  <files>includes/class-config.php, tests/unit/ConfigSanitizeTest.php, TESTING.md</files>
+  <behavior>
+    - `menu_width` sanitizes to an integer within sane bounds; out-of-range clamps
+      rather than rejecting the whole save.
+    - The default (160) is NOT stored — sparse contract, reset = absent.
+    - Non-numeric, negative and absurd values cannot reach storage.
+    - Every existing config shape sanitizes byte-identically (zero regression).
+  </behavior>
+  <action>
+    Pick the bounds deliberately and say why in the constant's docblock. A lower
+    bound below roughly the folded width makes the menu unusable; an upper bound
+    much past a third of a typical viewport starts eating the content column. The
+    numbers matter less than the reasoning being recorded — the next person will
+    otherwise assume they were arbitrary and change them.
+  </action>
+  <verify><automated>composer test:unit -- --filter ConfigSanitizeTest</automated></verify>
+  <done>Bounded, sparse, zero-regression; bounds justified in the docblock.</done>
+</task>
+
+<task type="auto" tdd="true">
+  <name>Task 3: Apply it outside edit mode</name>
+  <files>includes/class-assets.php, tests/integration/MenuWidthAssetTest.php, TESTING.md</files>
+  <behavior>
+    - With a non-default width stored, the rule is emitted on ordinary admin pages.
+    - With no width stored, NOTHING is emitted and no new work happens — the
+      zero-config path stays exactly as it is today.
+    - The rule sets `#adminmenu`/`#adminmenuwrap`/`#adminmenuback` width AND the
+      matching `#wpcontent`/`#wpfooter` offset. Setting one without the other
+      overlaps or gaps the content column.
+    - `body.folded` still folds to core's 36px outside edit mode — width applies
+      to the EXPANDED state only.
+    - Below the `<782px` breakpoint the menu is an overlay; the width must not
+      fight core's responsive rules.
+  </behavior>
+  <action>
+    The folded and responsive cases are where this breaks in the wild, and both
+    are cheap to assert. A width override that survives into folded mode disables
+    the collapse control for every admin page — which is the bug this phase's
+    own decision exists to avoid re-creating outside edit mode.
+  </action>
+  <verify><automated>npm run test:php -- --filter MenuWidthAssetTest</automated></verify>
+  <done>Width applies while browsing; zero-config emits nothing; folded and responsive both still correct.</done>
+</task>
+
+</tasks>
+
+<verification>
+- Unit + both integration lanes green; WPCS and PHPStan clean.
+- A config with no `menu_width` produces byte-identical output and no new page cost.
+- Folded (36px) and `<782px` behaviour asserted, not assumed.
+</verification>
+
+<success_criteria>
+- Width is stored, bounded, and applied while browsing.
+- Sites that never set one pay nothing.
+- Folding still works everywhere it should.
+</success_criteria>
+
+<output>
+Create `.planning/phases/28-configurable-admin-menu-width/28-02-SUMMARY.md`.
+</output>
diff --git a/.planning/phases/28-configurable-admin-menu-width/28-03-PLAN.md b/.planning/phases/28-configurable-admin-menu-width/28-03-PLAN.md
new file mode 100644
index 0000000..5a8694d
--- /dev/null
+++ b/.planning/phases/28-configurable-admin-menu-width/28-03-PLAN.md
@@ -0,0 +1,170 @@
+---
+phase: 28-configurable-admin-menu-width
+plan: 03
+type: tdd
+wave: 3
+depends_on: [28-02]
+files_modified:
+  - assets/maestro.js
+  - assets/maestro.css
+  - includes/class-assets.php
+  - tests/e2e/specs/menu-width.spec.ts
+  - README.md
+  - readme.txt
+  - TESTING.md
+autonomous: false
+requirements: []
+must_haves:
+  truths:
+    - "The width is adjusted from within edit mode — no settings screen."
+    - "The change previews live, because the thing being adjusted is on screen."
+    - "The control is keyboard-operable and labelled at the point it is written."
+    - "Docs state that the width applies while browsing, not only while editing."
+---
+
+<objective>
+Give the width a control, and close the phase.
+
+Purpose: 28-02 makes width real but unreachable. This is also the phase's second
+authoring-surface question — Maestro has no settings screen by design, and this
+is a *global* setting rather than a per-item override, which is a genuinely new
+shape for this plugin.
+
+**`autonomous: false`** — where a global setting lives is a product decision, and
+the phase ends at a human checkpoint.
+</objective>
+
+<context>
+@.planning/phases/28-configurable-admin-menu-width/28-02-SUMMARY.md
+@assets/maestro.js
+@assets/maestro.css
+
+<interfaces>
+<!-- Contracts the executor builds on. Use directly — no exploration needed. -->
+
+**This is the first GLOBAL setting in a plugin built entirely from per-item
+overrides.** Everything in the toolbar today acts on the selected item; width
+acts on the whole menu and persists for every admin user. The control needs to
+read as global rather than as another property of whatever row is selected, or
+people will expect it to reset with Reset Item.
+
+**Reset semantics need deciding with it:** Reset Item is per-item and must NOT
+clear the width. Reset All plausibly should — it means "back to WordPress
+defaults", and a 240px menu is not a WordPress default. Whichever is chosen,
+assert it; this is exactly the kind of interaction that gets discovered by a user.
+
+**Live preview is nearly free and worth a lot.** The width is a CSS custom
+property after 28-01, so the control can set it on input and the menu resizes
+under the cursor. A width picker that requires a save to see the result is a
+worse product for no saved effort.
+
+**Toolbar geometry follows.** `.maestro-toolbar` is `left: <width>` after 28-01 —
+it must track a live change too, or the toolbar detaches from the menu column
+mid-drag.
+</interfaces>
+</context>
+
+<tasks>
+
+<task type="checkpoint">
+  <name>Task 1: DECIDE where the control lives</name>
+  <action>
+    The toolbar's right-hand zone (beside Reset All) is the obvious home — always
+    visible in edit mode, already the place for menu-wide actions rather than
+    item actions. The alternative is a small popover like the icon/visibility
+    ones, which buys room for a labelled slider plus numeric input at the cost of
+    another surface.
+
+    Decide also:
+    - slider, numeric input, or both (a slider alone is imprecise; a number alone
+      loses the live-drag feel that makes this pleasant)
+    - whether Reset All clears the width
+    - what the control shows when no width is stored — "160" or "Default"; the
+      distinction matters because the sparse contract means "unset" and "160" are
+      genuinely different stored states
+  </action>
+  <verify><manual>Decision recorded with reasoning.</manual></verify>
+  <done>Control placement, form, and reset semantics decided.</done>
+</task>
+
+<task type="auto" tdd="true">
+  <name>Task 2: Build the control with live preview</name>
+  <files>assets/maestro.js, assets/maestro.css, includes/class-assets.php, TESTING.md</files>
+  <behavior>
+    - Adjusting the control resizes the menu immediately, before any save.
+    - The toolbar's left edge tracks the change so it stays flush with the column.
+    - The value persists through the normal autosave and survives reload.
+    - Reset Item does NOT touch it; Reset All behaves as 28-03 Task 1 decided.
+    - The control is labelled, keyboard-operable, and announces its value.
+  </behavior>
+  <action>
+    Set the custom property live on input, and let the existing autosave carry the
+    value — do not add a second save path. Debounce the persistence, not the
+    preview: the preview should feel immediate, the writes should not be one per
+    pixel.
+
+    a11y at the point of writing: a range input needs a real label and an
+    accessible current value; if a numeric input pairs with it, keep them in sync
+    both ways. Phase 20 and the person picker both had to retrofit this.
+  </action>
+  <verify><automated>npm run test:js</automated></verify>
+  <done>Control adjusts width live, persists via autosave, respects reset semantics, and is accessible.</done>
+</task>
+
+<task type="auto">
+  <name>Task 3: e2e, docs, and the full gate</name>
+  <files>tests/e2e/specs/menu-width.spec.ts, README.md, readme.txt, TESTING.md</files>
+  <behavior>
+    - e2e: set a width, save, reload, confirm it applies BOTH in edit mode and on
+      an ordinary admin page.
+    - e2e: confirm folding still works outside edit mode at a custom width.
+    - Docs explain that the width is global, applies while browsing, and pairs
+      with renaming — which is the reason it exists.
+    - Full gate green: unit, both integration lanes, JS, e2e, WPCS, PHPStan,
+      doc-links, Plugin Check on the ZIP.
+  </behavior>
+  <action>
+    The ordinary-admin-page assertion is the one that matters — it is the whole
+    difference between this feature and a CSS tweak inside edit mode, and it is
+    the first time Maestro affects a page it is not editing.
+
+    Docs should say plainly that this is the fix for the problem renaming creates:
+    longer labels wrap at 160px. That framing is why this belongs in Maestro
+    rather than in a separate width plugin.
+  </action>
+  <verify><automated>npm run test:e2e -- tests/e2e/specs/menu-width.spec.ts</automated></verify>
+  <done>Width proven on a non-edit-mode page; folding intact; docs honest; gate green.</done>
+</task>
+
+<task type="checkpoint">
+  <name>Task 4: Phase verification</name>
+  <action>
+    Present the measured always-loaded cost from 28-02, what the control looks
+    like, and the reset semantics chosen.
+
+    State plainly whether a human checked the width at several values across the
+    three admin colour schemes and below the 782px breakpoint — that last one is
+    where a width feature most plausibly breaks, and no automated assertion
+    substitutes for looking at it.
+  </action>
+  <verify><manual>Human verifies in wp-env; phase approved.</manual></verify>
+  <done>Phase verified and closed; VERIFICATION.md written; todos moved to completed.</done>
+</task>
+
+</tasks>
+
+<verification>
+- Width applies on ordinary admin pages, not just in edit mode.
+- Folding and the responsive breakpoint both still correct at a custom width.
+- Full gate green; measured footprint recorded.
+</verification>
+
+<success_criteria>
+- A renamed menu item that used to wrap at 160px no longer has to.
+- Sites that never set a width pay nothing.
+- The collapse control tells the truth (28-01) and folding still works everywhere it should.
+</success_criteria>
+
+<output>
+Create `28-03-SUMMARY.md` and `28-VERIFICATION.md`.
+</output>
diff --git a/.planning/todos/pending/2026-08-09-configurable-admin-menu-width.md b/.planning/todos/pending/2026-08-09-configurable-admin-menu-width.md
index 52b534a..a6c8239 100644
--- a/.planning/todos/pending/2026-08-09-configurable-admin-menu-width.md
+++ b/.planning/todos/pending/2026-08-09-configurable-admin-menu-width.md
@@ -34,14 +34,18 @@ every page load for every admin user — worth being deliberate about, since
 Three interactions to get right, none optional:
 - **Folded mode** (`.folded`, 36px) must still fold — a fixed width that ignores
   it breaks the collapse control entirely.
-  **⚠️ BLOCKED ON A DECISION, added 2026-08-10.** Edit mode currently REFUSES to
+  **✅ UNBLOCKED 2026-08-10 — decision made; both this todo and the fold work are now Phase 28.** Formerly blocked: Edit mode currently REFUSES to
   fold: `forceUnfold()` strips the classes, re-strips them via MutationObserver,
   neuters `#collapse-menu` with a capture-phase handler, and `maestro.css` forces
   `width: 160px !important` as a backstop. Ship both features as-is and a site
   with `menu_width: 240` renders 240px while browsing and snaps to 160px the
   instant edit mode opens — the editor showing a different width than the thing
-  it is editing. **Settle the fold story first:**
-  `todos/pending/2026-08-10-toolbar-height-and-collapse-menu-parity.md`
+  it is editing. **Settled:** edit mode keeps forcing unfold (a 36px rail cannot show the labels
+  being edited), the collapse control becomes visibly disabled instead of
+  silently dead, and the three hardcoded `160px` values become the configured
+  width. Not a fold-versus-width conflict after all — a hardcoded constant that
+  needs to become a variable. Decision recorded in
+  `todos/pending/2026-08-10-toolbar-height-and-collapse-menu-parity.md`.
 - **The `<782px` responsive breakpoint**, where the menu becomes an overlay
 - **`#wpcontent`'s matching offset** — set one without the other and the content
   column overlaps or leaves a gap
diff --git a/.planning/todos/pending/2026-08-10-toolbar-height-and-collapse-menu-parity.md b/.planning/todos/pending/2026-08-10-toolbar-height-and-collapse-menu-parity.md
index b741a78..a30324a 100644
--- a/.planning/todos/pending/2026-08-10-toolbar-height-and-collapse-menu-parity.md
+++ b/.planning/todos/pending/2026-08-10-toolbar-height-and-collapse-menu-parity.md
@@ -51,7 +51,40 @@ width work inherits an unstated conflict and discovers it late, which is the
 pattern this project has already paid for twice (Phase 21's release target,
 Phase 25's criterion 1).
 
-## Options for the fold question
+## ✅ DECIDED 2026-08-10 — folded into Phase 28
+
+**Keep forcing unfold. Stop lying about it. De-hardcode the width.**
+
+Implementation moves to **Phase 28 (Configurable Admin Menu Width)**; this todo
+stays as the decision record and the seed.
+
+**1. Forced unfold is KEPT — it is justified, not incidental.**
+A folded menu is a 36px icon rail with hover flyouts. Maestro's model is *click a
+row, edit its label*: you cannot rename what you cannot read, and submenu editing
+would happen inside a flyout that vanishes when the pointer leaves — hostile for
+drag-reorder and text entry. The core value is that editing happens directly on
+the menu, which requires the menu to be legible. `docs/archive/FIXES.md` #4
+records that the editing UI *broke* in folded mode historically; forcing unfold
+was the fix, not an oversight.
+
+**2. The silent swallow is the actual defect, and it goes.**
+`#collapse-menu` currently renders, takes focus, and does nothing — a
+capture-phase `preventDefault()` + `stopImmediatePropagation()`. Replace with a
+VISIBLY disabled control carrying a reason, matching the treatment the
+derived-locked checkbox got in Phase 25. A dead control that looks dead is not a
+bug; a live-looking one is.
+
+**3. The "conflict" with the width feature was mis-framed — corrected.**
+It is not fold-versus-width. `160px` is simply HARDCODED IN THREE PLACES
+(`maestro.css:22` width, `:28` margin-left, `:523` the toolbar's `left`), one of
+which is the exact constant the width feature makes configurable. That is a
+constant needing to become a variable, not a design conflict. Outside edit mode
+width applies to the expanded menu and folding works normally; inside edit mode
+folding is off, so width simply applies.
+
+**Net effect: this decision UNBLOCKS the width work rather than constraining it.**
+
+## Options considered (rejected)
 
 - **Keep forcing unfold, but say so.** Cheapest. Disable the control visibly
   (`aria-disabled` + a title explaining why, matching the treatment the
@@ -60,6 +93,9 @@ Phase 25's criterion 1).
 - **Allow folding, and adapt.** Editing in a 36px rail needs a different
   affordance — possibly the toolbar becomes the whole editing surface. Much
   larger, but it is the honest answer if people actually want to edit folded.
+- **Allow folding and adapt the editor to a 36px rail** — rejected. It is a much
+  larger piece of work whose payoff is editing in a mode where the labels being
+  edited are invisible. Revisit only if users actually ask for it.
 - **Auto-restore on exit — VERIFIED 2026-08-10, no action needed.** The folded
   preference DOES return. `forceUnfold()` only ever runs from `init()`, which is
   reached solely in edit mode, and it strips the class client-side. Leaving edit

From a69c4a5cc2d479236d985afc4c0d8d11bcdafc35 Mon Sep 17 00:00:00 2001
From: Dan Knauss <273554+dknauss@users.noreply.github.com>
Date: Mon, 10 Aug 2026 01:20:25 -0600
Subject: [PATCH 19/27] docs(planning): decide where menu-wide features live
 (#143)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Phases 27 and 28 both stalled on the same question from different directions:
Maestro has deliberately never had a settings screen, and both features need
somewhere to live. Answering it per-phase risked two inconsistent surfaces, then
four — precisely the drift the 2026-08-09 backlog reconciliation cleaned up.

DECIDED: two icon buttons in the edit-mode toolbar's right zone, each opening a
modal — Profiles (create/rename/delete/membership) and Settings (menu_width now;
declutter switch and config presets later). Per-item features stay in the
per-item panel. No wp-admin settings page, ever.

This is consistent rather than novel, on two counts the code already establishes:
the toolbar's right zone ALREADY hosts the only menu-wide action (Reset All at
maestro.js ~L646-660 — the one control that does not act on the selected item),
and the modal idiom ALREADY exists as role=dialog + aria-modal + focus trap in
the icon picker, visibility popover and coachmark (:758, :1009, :1942). Both
modals reuse that machinery instead of introducing a second dialog pattern.

What it protects: a settings page would add an entry to the admin menu, which is
self-parodying for a plugin whose purpose is decluttering the admin menu, and it
would break the core value's "operates on the menu itself" — the point of which
is not having to go elsewhere to configure the menu.

GUARDRAIL: two icons is the budget. A fifth menu-wide feature goes INSIDE the
Settings modal, not as a third icon. Without that rule the toolbar accretes one
icon per feature and becomes the settings screen we just declined to build,
arrived at by increments rather than by decision.

One deliberate exception recorded for width: it should ALSO be directly
draggable at the menu edge, not only a field. 28-01 makes the width a CSS custom
property so live preview is nearly free, and dragging the thing you are resizing
is more in-place than any field. The field is the precise/accessible path, the
drag is the discoverable one — drag-only would be inaccessible, field-only is a
settings screen in a costume.

Recorded in PROJECT.md's Key Decisions table, written up in full in
.planning/DECISION-settings-surface.md, and propagated into 27-01 and 28-03 so
neither checkpoint re-opens it. The sub-questions each phase still owns are
narrowed rather than deleted.
---
 .planning/DECISION-settings-surface.md        | 87 +++++++++++++++++++
 .planning/PROJECT.md                          |  1 +
 .../27-01-PLAN.md                             | 19 ++--
 .../28-03-PLAN.md                             | 21 +++--
 4 files changed, 117 insertions(+), 11 deletions(-)
 create mode 100644 .planning/DECISION-settings-surface.md

diff --git a/.planning/DECISION-settings-surface.md b/.planning/DECISION-settings-surface.md
new file mode 100644
index 0000000..a5017f8
--- /dev/null
+++ b/.planning/DECISION-settings-surface.md
@@ -0,0 +1,87 @@
+# Decision: where menu-wide features live
+
+**Decided 2026-08-10.** Unblocks Phase 27 (profiles) and Phase 28 (width), which
+both stalled on the same question from different directions.
+
+## The decision
+
+**Two new icon buttons in the edit-mode toolbar's right zone, each opening a
+modal dialog:**
+
+| Icon | Modal | Owns |
+|---|---|---|
+| Profiles | Manage hiding profiles | create / rename / delete a profile, edit its membership (Phase 27) |
+| Settings | Menu-wide configuration | `menu_width` (Phase 28); later the declutter switch and config presets |
+
+**Per-item features stay exactly where they are** — the shared panel and its
+icon/visibility popovers, acting on the selected row.
+
+**No wp-admin settings page. Not now, not later.**
+
+## Why this is consistent rather than a new invention
+
+Two things already exist that make this the path of least surprise:
+
+1. **The toolbar's right zone is already the home of menu-wide actions.**
+   `Reset All` lives there (`maestro.js` ~L646-660) and is global — it is the one
+   existing control that does not act on the selected item. Two more global
+   controls beside it is the established meaning of that zone, not a new one.
+2. **The modal idiom already exists.** The icon picker, the visibility popover
+   and the coachmark are all `role="dialog"` + `aria-modal="true"` with focus
+   traps (`maestro.js` :758, :1009, :1942). These modals reuse that machinery
+   rather than introducing a second dialog pattern.
+
+And the thing it protects: a settings page would add an entry to the admin menu.
+For a plugin whose purpose is decluttering the admin menu, that is
+self-parodying — and it would break the core value's "operates on the menu
+itself", which is about not having to go elsewhere to configure the menu.
+
+## Why a shared surface was worth deciding once
+
+Four queued features are menu-wide, not per-item, and none had a home:
+
+- `cloned-role-hiding-profiles` (Phase 27)
+- `configurable-admin-menu-width` (Phase 28)
+- `config-presets-export-import` (V2-06)
+- `declutter-switch-non-core-menu-items`
+
+Answering this per-phase risked two inconsistent surfaces and then four —
+precisely the drift the 2026-08-09 backlog reconciliation existed to clean up.
+
+## Guardrail: two icons is the budget
+
+A fifth menu-wide feature goes **inside the Settings modal**, not as a third
+toolbar icon. Presets and the declutter switch are already earmarked for it.
+
+Without this rule the toolbar accretes one icon per feature and becomes the
+settings screen we just said we would not build — arrived at by increments
+instead of by decision.
+
+## Consequences for the two phases
+
+**Phase 27** — 27-01's authoring-UX question is answered: profiles are created
+and managed in the Profiles modal; assigning one to an item stays in the existing
+visibility popover as a fifth group. That split matters — assignment is per-item
+and belongs with the other per-item axes; management is global and does not.
+
+**Phase 28** — 28-03's placement question is answered for the *control*, but with
+a deliberate exception:
+
+> **Width should ALSO be directly draggable**, not only a field in the Settings
+> modal. Dragging the menu edge and watching it resize is more in-place than any
+> field, and 28-01 makes the width a CSS custom property, so live preview is
+> nearly free. The Settings field is the precise/accessible path; the drag is the
+> discoverable one. Neither alone is sufficient — a drag-only control is
+> inaccessible, a field-only control is a settings screen in a costume.
+
+**Sequencing:** whichever phase runs first builds the modal shell; the second
+reuses it. Phase 28 is the lighter lift and would prove the surface with a single
+scalar before Phase 27 puts CRUD in one.
+
+## Still open, deliberately
+
+- Which dashicons. Cosmetic; pick at build time.
+- Whether the Settings modal shows anything at all before Phase 28 lands (if 27
+  goes first, it may ship with only the Profiles icon).
+- Whether Reset All clears menu-wide settings — flagged in 28-03 and unchanged by
+  this decision.
diff --git a/.planning/PROJECT.md b/.planning/PROJECT.md
index 233ee0b..befffab 100644
--- a/.planning/PROJECT.md
+++ b/.planning/PROJECT.md
@@ -184,6 +184,7 @@ and `.planning/milestones/` for records.
 | Sparse delta, not a stored full menu | Trivial reset, resilience to plugin churn, upstream label changes show through | ✓ Good |
 | Debounced autosave, no Save button | In-place ethos; Save was implicated in early "doesn't persist" reports | ✓ Good |
 | Click-to-select, whole-row drag, no handles | Per-item clusters/handles were heavy and broke folded mode + hard to grab | ✓ Good |
+| **Menu-wide features get a toolbar icon opening a modal; per-item features stay in the per-item panel. No wp-admin settings page, ever.** | The toolbar's right zone ALREADY hosts the only global action (Reset All), so placement itself distinguishes global from per-item — and the modal idiom already exists (`role=dialog` + `aria-modal` + focus trap) in the icon and visibility popovers. A settings page would add an admin menu item, which is self-parodying for a menu-decluttering plugin, and would break "operates on the menu itself". Decided 2026-08-10 for Phases 27/28, which both stalled on it. | Pending (Phases 27, 28) |
 | Unique slug, no `Update URI` header | Slug uniqueness is the .org collision protection; the header is disallowed by Plugin Check | ✓ Good |
 | Strip `menu-icon-*` for custom image icons | Core's `background-image:none !important` on its own items hid data-URI/URL icons | ✓ Good |
 | Visibility is cosmetic only | Authorization is a separate, mature concern; half-enforcement is the worst failure mode | ✓ Good |
diff --git a/.planning/phases/27-cloned-role-hiding-profiles/27-01-PLAN.md b/.planning/phases/27-cloned-role-hiding-profiles/27-01-PLAN.md
index 761f273..a5b65f9 100644
--- a/.planning/phases/27-cloned-role-hiding-profiles/27-01-PLAN.md
+++ b/.planning/phases/27-cloned-role-hiding-profiles/27-01-PLAN.md
@@ -77,6 +77,16 @@ assigns and deletes a profile.
 <task type="checkpoint">
   <name>Task 1: Decide the authoring UX</name>
   <action>
+    **PARTLY ANSWERED 2026-08-10 — see `.planning/DECISION-settings-surface.md`.**
+    Profiles are created, renamed, deleted and have their membership edited in a
+    **Profiles modal**, opened from a new icon in the toolbar's right zone (the
+    zone that already hosts Reset All, the one existing menu-wide action).
+    ASSIGNING a profile to an item stays in the visibility popover as a fifth
+    group, because assignment is per-item and belongs beside the other axes.
+    There is no wp-admin settings page.
+
+    What remains for this task is the detail INSIDE that frame:
+
     The visibility popover is already at FOUR groups after Phase 21. A fifth
     ("Hide for profile") is cheap to add, but profiles also need somewhere to be
     *created and managed*, and that has no home today — Maestro has deliberately
@@ -85,11 +95,10 @@ assigns and deletes a profile.
 
     Questions that need answers, each with a real trade-off:
 
-    1. **Where do profiles get authored?** Inline in the popover (create-on-the-fly
-       from a name field), or a dedicated management surface? The former keeps the
-       no-settings-screen promise; the latter is where "rename this profile" and
-       "who is in it" actually belong. A hybrid — assign inline, manage elsewhere —
-       is possible but means two surfaces to keep consistent.
+    1. ~~Where do profiles get authored?~~ **Decided** — see above. Remaining
+       sub-question: can a profile be created *inline* from the assignment group
+       as a shortcut, or must every creation go through the modal? A shortcut is
+       convenient and is a second creation path to keep consistent.
     2. **What is a profile's assignment?** The note's §5c shape allows both users
        AND roles under one profile. Roles-in-profiles overlaps confusingly with
        the existing `hidden_roles` axis — worth asking whether v1 profiles should
diff --git a/.planning/phases/28-configurable-admin-menu-width/28-03-PLAN.md b/.planning/phases/28-configurable-admin-menu-width/28-03-PLAN.md
index 5a8694d..850d4f9 100644
--- a/.planning/phases/28-configurable-admin-menu-width/28-03-PLAN.md
+++ b/.planning/phases/28-configurable-admin-menu-width/28-03-PLAN.md
@@ -67,13 +67,22 @@ mid-drag.
 <tasks>
 
 <task type="checkpoint">
-  <name>Task 1: DECIDE where the control lives</name>
+  <name>Task 1: DECIDE the control's form (placement is settled)</name>
   <action>
-    The toolbar's right-hand zone (beside Reset All) is the obvious home — always
-    visible in edit mode, already the place for menu-wide actions rather than
-    item actions. The alternative is a small popover like the icon/visibility
-    ones, which buys room for a labelled slider plus numeric input at the cost of
-    another surface.
+    **PLACEMENT ANSWERED 2026-08-10 — see `.planning/DECISION-settings-surface.md`.**
+    The width field lives in a **Settings modal**, opened from a new icon in the
+    toolbar's right zone. This phase builds that modal shell if Phase 27 has not
+    already; the shell is shared.
+
+    **With a deliberate exception this task must honour:** width should ALSO be
+    directly draggable at the menu edge. 28-01 makes the width a CSS custom
+    property, so live preview is nearly free, and dragging the thing you are
+    resizing is more in-place than any field. The modal field is the precise and
+    accessible path; the drag is the discoverable one. **Neither alone is
+    sufficient** — drag-only is inaccessible, field-only is a settings screen in
+    a costume.
+
+    Remaining for this task:
 
     Decide also:
     - slider, numeric input, or both (a slider alone is imprecise; a number alone

From baab892d74e667ae39dd954afffc02a8ca38a669 Mon Sep 17 00:00:00 2001
From: Dan Knauss <273554+dknauss@users.noreply.github.com>
Date: Mon, 10 Aug 2026 01:31:35 -0600
Subject: [PATCH 20/27] docs(planning): write an accurate session handoff into
 STATE.md (#144)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Session Continuity was badly stale — it still read "Last session 2026-08-02,
stopped at Phase 21 context gathered, resume from 21-CONTEXT.md", which predates
Phase 21 executing, v1.5.0 shipping, Phase 25, the correctness fixes, and the
planning of Phases 27 and 28. Clearing context against that would have lost real
continuity, which is the whole thing this section exists to prevent.

Rewritten as a START HERE paragraph a fresh session can act on without
reconstructing the history:

- v1.5.0 is live, but main carries UNRELEASED work (Phase 25 + the three Phase 20
  correctness fixes). A v1.5.1 patch is the obvious next release and clears the
  decks before new phases land on top — this is the single most important fact
  and was not recorded anywhere a resuming session would look.
- Phases 27 and 28 are planned and unblocked, with a recommended order and the
  reasoning for it (28 is lighter, 28-01 ships alone, and it proves the shared
  modal shell with a scalar before 27 puts CRUD in one).
- Both 2026-08-10 decisions are named with their files, flagged as read-before-
  reopening: the settings surface, and the fold story — including that the
  fold-versus-width "conflict" was mis-framed and is withdrawn, so nobody
  re-derives a constraint that does not exist.
- The three carried caveats are restated rather than left only in the milestone
  entry: #128 shipped unreviewed, no human screen-reader pass, and 21-05's
  checkpoint accepted on automated evidence.
- The wp-env port gotcha is written down, including that Playwright reads
  WP_ENV_TESTS_PORT independently, and that the other project's containers are
  not ours to stop.

Also updates stopped_at and last_updated, both of which still described the state
immediately after the v1.5.0 release.
---
 .planning/STATE.md | 47 +++++++++++++++++++++++++++++++++++++++++-----
 1 file changed, 42 insertions(+), 5 deletions(-)

diff --git a/.planning/STATE.md b/.planning/STATE.md
index 67d9f58..df7f81b 100644
--- a/.planning/STATE.md
+++ b/.planning/STATE.md
@@ -3,8 +3,8 @@ gsd_state_version: 1.0
 milestone: v1.5
 milestone_name: Per-User Visibility
 status: shipped
-stopped_at: "v1.5.0 SHIPPED to WordPress.org (tag v1.5.0 on 694b1bf, SVN verified). Milestone recorded; next milestone not yet opened."
-last_updated: "2026-08-09T00:00:00.000Z"
+stopped_at: "v1.5.0 shipped. UNRELEASED work now on main (Phase 25 + 3 Phase-20 correctness fixes) awaiting a v1.5.1 patch. Phases 27 and 28 planned and unblocked; no milestone open."
+last_updated: "2026-08-10T00:00:00.000Z"
 last_activity: "2026-08-08 — **Phase 21 (ROLE-02 per-user hiding) executed, 5/5 plans, awaiting the human-verify checkpoint.** Branch `phase/21-cosmetic-per-user-hiding`, PR #120, nothing merged. Delivered: `hidden_users` / `child_hidden_users` storage; the `is_hidden_for_current_user()` seam widened to independent OR'd terms (3rd term reserved for the deferred `hidden_profiles`); `resolved_hidden_roles()` GENERALIZED to a field-parameterized resolver rather than duplicated, so the user axis inherits the qualified-key, schema-v2 (#115) and Axis-1 guards from one implementation; a shared `Cascade` union; the §6 cosmetic-invariant guardrail made enforcing; editor model exposure as id+name pairs via one batched query; four-group visibility popover with an async person picker on core's `wp/v2/users`. Gate: unit 165/165 (218), integration 109/109 (257), JS 83/83, e2e 39 passed/28 capture-skipped/0 failed, WPCS clean, PHPStan 0, Plugin Check 0 errors on the ZIP (1 pre-existing readme warning). THREE bugs found by verification that no unit test would have caught: (1) the guardrail initially could NOT detect a broken seam — `current_user_can()` answers from a cached allcaps array, so `snapshot_caps()` now drops `$GLOBALS['current_user']` to force re-derivation; (2) the picker URL appended `?` unconditionally, 404ing on every PLAIN-PERMALINK site since `rest_url()` already carries a query string; (3) clicking a search result or chip closed the whole popover, because re-rendering detached the node before `placePopover()`'s outside-click handler ran. Ruling recorded 2026-08-08: the super-admin exemption covers the NEW user axis only, multisite-scoped (unscoped would make administrators un-hideable on single-site and contradict the locked self-target decision). Prior: 2026-08-05 — **v1.4.1 SHIPPED** (PR #116, tag on c6cdcbe; wp.org API confirms 1.4.1). Patch for the shared-slug propagation defect (#115): a bare top-level key no longer applies to a submenu row whose slug names a rendered top-level item. Two Codex P2 rounds on #115 — the first cut of the gate tested `$nk === $norm_parent` and missed submenus parked under an unrelated parent; widened to `isset( $top_rendered_matches[ $nk ] )`. Prior: 2026-08-04 — **v1.4.0 SHIPPED** (PR #113, tag on 482510c, GitHub Release + wp.org SVN trunk/tags/1.4.0/assets confirmed). Phase 24 release gates 8–11 run consolidated over the full v1.3.1..main diff; one defect found and fixed (multibyte truncation blanked labels) and one changelog overclaim corrected (shared-slug isolation is submenu-direction only). ROLE-02 (Phase 21) deferred to v1.5."
 progress:
   total_phases: 6
@@ -400,6 +400,43 @@ Recent decisions affecting current work:
 
 ## Session Continuity
 
-Last session: 2026-08-02T15:43:40.067Z
-Stopped at: Phase 21 context gathered
-Resume file: .planning/phases/21-cosmetic-per-user-cloned-role-hiding/21-CONTEXT.md
+Last session: 2026-08-10
+Stopped at: planning complete for Phases 27 + 28; nothing in flight
+
+**START HERE — the state in one paragraph.** v1.5.0 is live on WordPress.org.
+`main` carries work that is NOT yet released: Phase 25 (toolbar polish, human-
+verified) and the three Phase 20 correctness fixes. A **v1.5.1 patch is the
+obvious next release** and clears the decks before new phases land on top. Two
+phases are fully planned and unblocked — **Phase 28 (menu width + fold honesty)**
+and **Phase 27 (cloned-role profiles, completes ROLE-02)**. Phase 22 (Playground
+demo) is scoped but never planned. 10 todos pending, 2 of them explicitly
+ignorable.
+
+**Recommended order:** v1.5.1 patch → Phase 28 → Phase 27. Phase 28 is the
+lighter lift, its 28-01 ships value alone by fixing a live defect, and it proves
+the shared modal shell with a single scalar before Phase 27 puts CRUD in one.
+
+**Two decisions were made 2026-08-10 that unblock both phases — read them before
+re-opening either question:**
+- `.planning/DECISION-settings-surface.md` — menu-wide features get a toolbar
+  icon opening a modal (Profiles, Settings); per-item stays in the per-item
+  panel; **no wp-admin settings page, ever**; two icons is the budget.
+- The fold story, recorded in
+  `todos/pending/2026-08-10-toolbar-height-and-collapse-menu-parity.md` — edit
+  mode keeps forcing unfold, but `#collapse-menu` stops pretending to work. The
+  "fold versus width conflict" flagged on 2026-08-09 was mis-framed and is
+  **withdrawn**: `160px` is just hardcoded in three places.
+
+**Three things carried, not resolved** (also in the v1.5.0 milestone entry):
+1. The #128 fixes shipped **unreviewed** — the ultrareview ran against the prior commit.
+2. **No human screen-reader pass** on the person picker; axe is clean, which is not the same claim.
+3. 21-05 Task 5 (human browser verification) was never performed; the phase was accepted on automated evidence.
+
+**Environment gotcha:** another project's wp-env on this machine has claimed
+8888/8889 and at times 8899. Check which ports are free before `wp-env start`,
+use `WP_ENV_PORT` / `WP_ENV_TESTS_PORT` to move, and remember Playwright needs
+`WP_ENV_TESTS_PORT` passed separately — it reads it independently of wp-env.
+**Do not stop the other project's containers.**
+
+Resume file: `.planning/ROADMAP.md` (Phase 28 details), then
+`.planning/phases/28-configurable-admin-menu-width/28-01-PLAN.md`

From 2e6e1740e67a3c19c25316aac28859235d06fea4 Mon Sep 17 00:00:00 2001
From: Dan Knauss <273554+dknauss@users.noreply.github.com>
Date: Mon, 10 Aug 2026 07:41:06 -0600
Subject: [PATCH 21/27] docs(planning): log the AME feature-surface research
 todo (#145)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The 2026-08-01 prior-art spike read Admin Menu Editor architecturally, scoped to
Phase 20's questions — identity, apply model, submenu targeting, hook order,
storage. Those findings shipped as COMPAT-04/07/14.

It never examined AME as a product. Its whole feature-facing output is one
"market signals" section, and all four gaps it named are now spent: import/export
is queued, reparenting is out of scope, per-role deny shipped, and inline editing
UX is the premise rather than a gap. The one artifact meant to say what to build
next has nothing unclaimed left in it — and after Phases 27/28 there is no
milestone.

The todo scopes a second pass over AME free/Pro/add-ons as a product, sorting
each feature into have-it / deliberately-not / already-queued / unclaimed /
anti-feature. Deliverable is a NOTE on the 19-FEASIBILITY-NOTE model, and
"nothing worth adopting" is written in as a legitimate verdict so the pass is not
padded to justify itself.

Constraints are pre-loaded so a finding gets rejected in the note rather than by
a later phase: cosmetic-only, the two-icon budget from DECISION-settings-surface,
borrow-patterns-not-code, and editing-happens-on-the-menu. New candidates rank
against the existing queue — losing to something already queued is a finding too.

Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
---
 .planning/STATE.md                            |   8 ++
 ...2026-08-10-ame-feature-surface-research.md | 113 ++++++++++++++++++
 2 files changed, 121 insertions(+)
 create mode 100644 .planning/todos/pending/2026-08-10-ame-feature-surface-research.md

diff --git a/.planning/STATE.md b/.planning/STATE.md
index df7f81b..e6f3f99 100644
--- a/.planning/STATE.md
+++ b/.planning/STATE.md
@@ -376,6 +376,14 @@ Recent decisions affecting current work:
   and arbitrary SVG upload, which is a security feature wearing a UI feature's
   clothes and wants its own pass. `todos/pending/2026-08-09-icon-picker-remaining-scope.md`
 
+- **AME feature-surface research** — the 2026-08-01 prior-art spike was
+  *architectural*, scoped to Phase 20; its four-bullet market-gap list is now spent
+  (import/export queued, reparenting out of scope, per-role deny shipped, inline UX
+  is the premise). A second pass would inventory AME free/Pro/add-ons as a **product**
+  and sort each feature into have-it / deliberately-not / already-queued /
+  unclaimed / anti-feature. Deliverable is a NOTE, and "nothing worth adopting" is a
+  legitimate verdict. Worth doing because after Phases 27/28 there is no milestone.
+  `todos/pending/2026-08-10-ame-feature-surface-research.md`
 - **Named config presets + JSON export/import** — v1.5 candidate; supersedes/extends V2-06 (SPEC.md Roadmap item 6). Research captured in `todos/pending/2026-07-03-config-presets-export-import.md`
 - **Declutter switch (non-core menu items → bottom section)** — v1.5 candidate; needs discuss/feasibility pass (top_order precedence, CPT handling). Research captured in `todos/pending/2026-07-03-declutter-switch-non-core-menu-items.md`
 - ~~**Research Admin Menu Editor (Jānis Elsts) prior art**~~ — ✅ DONE 2026-08-01 (pulled forward from v1.5 to feed Phase 20). Findings note: `compat/PRIOR-ART-admin-menu-editor.md` (adopt/avoid/differentiate; AME 1.15.1 source read). Key inputs to Phase 20: COMPAT-04 → adopt AME's parent-scoped `parent>child` submenu identity; COMPAT-07 → split editable label from preserved title markup; COMPAT-10 → no prior art, Maestro-original. Cosmetic-only stays Maestro's differentiator (AME conflates hide with access). Todo moved to `todos/completed/`.
diff --git a/.planning/todos/pending/2026-08-10-ame-feature-surface-research.md b/.planning/todos/pending/2026-08-10-ame-feature-surface-research.md
new file mode 100644
index 0000000..f70f56a
--- /dev/null
+++ b/.planning/todos/pending/2026-08-10-ame-feature-surface-research.md
@@ -0,0 +1,113 @@
+---
+created: 2026-08-10T00:00:00.000Z
+title: Admin Menu Editor — feature-surface scoping research (what to build next, not how)
+area: research
+files:
+  - .planning/compat/PRIOR-ART-admin-menu-editor.md (the 2026-08-01 spike — its ARCHITECTURE half is done; do not redo it)
+  - .planning/DECISION-settings-surface.md (the two-icon / no-settings-page budget any adopted feature must fit)
+  - .planning/phases/19-cosmetic-hiding-feasibility/19-FEASIBILITY-NOTE.md (the deliverable shape to copy)
+  - SPEC.md (Roadmap items 1-10 + Out of Scope — the existing claims on this territory)
+---
+
+## Problem
+
+AME has been read once, and only architecturally.
+[`compat/PRIOR-ART-admin-menu-editor.md`](../../compat/PRIOR-ART-admin-menu-editor.md)
+(2026-08-01, AME free 1.15.1, source read) was pulled forward to feed Phase 20 and
+answered Phase 20's questions — identity, apply model, submenu targeting, hook
+order, storage. Those findings shipped as COMPAT-04/07/14.
+
+It never examined AME as a *product*. Its whole feature-facing output is one
+"market signals" section whose gap list is now spent:
+
+| Named gap (2026-08-01) | Status 2026-08-10 |
+|---|---|
+| Import/export | Queued as [[2026-07-03-config-presets-export-import]] — unplanned |
+| Reparenting / drag between levels | Out of scope in `SPEC.md` v1, gated on highlighting |
+| Per-role *deny* | **Shipped** — this is Maestro's cosmetic hiding |
+| True inline editing UX | Not a gap; it is the product's premise |
+
+The one artifact meant to say what to build next has nothing unclaimed left in it,
+and after Phases 27/28 there is no milestone. That makes this worth doing now — and
+easy to get wrong by inventing features instead of finding them.
+
+## The deliverable is a NOTE, not a feature
+
+Same contract as [[2026-08-09-admin-toolbar-editing-research]]: a scoping note, no
+commitment to build. `19-FEASIBILITY-NOTE.md` is the shape — explicit verdict,
+reasons, named constraints, written so a phase can be planned from it.
+
+**A legitimate verdict is "nothing worth adopting."** If the remaining gaps are all
+already queued, say so in a paragraph and stop. Do not pad a feature list to justify
+the pass.
+
+## Scope
+
+**In:** the user-facing feature inventory of AME free, Pro, and its add-ons
+(Branding, Toolbar) — including the free build's `modules/` directory, which the
+prior read skipped and which is where discrete features live. Map each to one
+verdict:
+
+1. **Have it** — name Maestro's equivalent, so the note doubles as a position statement
+2. **Deliberately not** — excluded by Out of Scope or cosmetic-only; record *why*, because this gets asked again
+3. **Already queued** — link the todo/phase, don't re-derive
+4. **Genuinely unclaimed** — the only category that produces new work
+5. **Anti-feature** — they ship it; we should be able to say why we won't
+
+**Out:** architecture, apply model, hook ordering, storage, identity, submenu
+targeting — all answered 2026-08-01. If a feature finding needs an architectural
+answer, note the dependency and stop. Also out: other prior art — "Wider Admin Menu"
+and "Hide Admin Menu" belong to `SPEC.md` items 9 and 10. AME-only is what keeps
+this bounded.
+
+## Constraints an "unclaimed" finding must already clear
+
+Reject in place rather than surfacing for a later phase to reject again:
+
+- **Cosmetic-only is not negotiable.** AME conflates hiding with access control
+  (`do_not_allow`, `wp_die()`), its largest user-confusion category per the
+  2026-08-01 forum mining. `SPEC.md` item 7 (enforcement bridge) is already flagged
+  IN TENSION — don't let a feature finding smuggle that decision in.
+- **The settings surface is decided; the budget is two icons.**
+  `DECISION-settings-surface.md` allots Profiles and Settings modals and rules out a
+  wp-admin settings page permanently. A feature needing a third icon has a placement
+  problem to solve *in the note*.
+- **Borrow patterns, not code** (`SPEC.md` principle 4). A feature that only works
+  under AME's full-rebuild model is a no.
+- **Editing happens on the menu.** Anything requiring you to leave the menu to
+  configure the menu contradicts the core value.
+
+## Questions the note must answer
+
+- **What does AME free actually let a user do, enumerated?** Start with `modules/`.
+- **What is Pro-gated, and which are Maestro's cheapest credible free wins?** The
+  headline split is recorded (granting, hide-from-all-except-one, import/export,
+  drag between levels, iframe items, colors, 600+ icons, Branding, Toolbar;
+  $49–$179/yr). Missing is the per-feature judgement: cost, fit with cosmetic-only,
+  and whether "AME charges for this" is demand evidence or just their packaging.
+- **Do the recurring-pain categories point at features, not just fixes?** The five
+  named on 2026-08-01 were mined for bugs to pre-empt. "Menu reset to default"
+  confusion in particular smells like a missing feature — a durable answer to *what
+  changed and how do I get back* — which per-item reset plus
+  [[2026-07-03-config-presets-export-import]] may or may not already be.
+- **Has AME shipped since 1.15.1?** Re-check version and changelog delta first;
+  record the version studied, as the prior note did.
+- **Does anything justify a milestone?** Rank candidates against the
+  queued-but-unplanned set ([[2026-07-03-config-presets-export-import]],
+  [[2026-07-03-declutter-switch-non-core-menu-items]],
+  [[2026-08-09-icon-picker-remaining-scope]], Phase 22) — a new idea that loses to
+  something already queued is a finding too.
+
+## Method
+
+Free AME is GPL and readable from the official zip. **Pro is not** — its feature set
+comes from marketing, upsell strings, and the forum, all claims rather than verified
+behaviour. Label those unverified, as the prior note did. Do not cite the
+unconfirmed GitHub mirror.
+
+**Placement:** `.planning/compat/PRIOR-ART-admin-menu-editor-features.md`, beside the
+architecture note rather than inside it — that one is a shipped input to Phase 20 and
+should stay readable as the record of what fed those fixes.
+
+Source: Dan's request 2026-08-10, after confirming no AME research phase was ever
+planned.

From 9caa65de626f4b3d5c54d599be3f700a2c943fec Mon Sep 17 00:00:00 2001
From: Dan Knauss <273554+dknauss@users.noreply.github.com>
Date: Mon, 10 Aug 2026 08:07:36 -0600
Subject: [PATCH 22/27] release: prep v1.5.1 (#146)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Version strings bumped via bin/prep-release.sh (plugin header, MAESTRO_VERSION,
Stable tag, package.json + lock).

The changelog is derived from the `v1.5.0..main` DIFF, not the phase list —
v1.4.0's gate 8 caught an overclaim by doing exactly that, so it is done first
here rather than last. The shippable diff is four files: assets/maestro.css,
assets/maestro.js, includes/class-config.php, includes/class-replay.php.

Six entries, covering both unreleased code commits:

f04dd13 (Phase 25) — the reserved toolbar status slot (measured: the status grew
4px -> 24px and displaced the rename field 20px on every save), the a11y M2
locked-checkbox change (aria-disabled instead of native disabled, so the row
stays reachable and its reason is finally announced rather than merely written),
the M3 focus return on click-away dismissal, and the lightened focus ring.

The focus ring is described as a clarity improvement, NOT a compliance fix. The
old #2271b1 ring PASSED WCAG 1.4.11 at 3.07:1; it passed by 0.07, and the change
is a deliberate robustness margin. Claiming a fix would be the same species of
overclaim gate 8 caught.

4359994 (Phase 20 follow-ups) — the Axis-2 drift fix, written user-facing because
its effect was: the popover could show roles checked while replay applied
nothing, and autosave's full-replace could then store the lie. Plus the entity
collision, kept to one internal line.

NOT claimed: the child-role-lock predicate parity change. It routes the popover
through the already-tested exported predicate instead of a re-inlined copy —
real value, zero behavior change, so it does not belong in a user changelog.

Upgrade Notice is 287 chars (Plugin Check limit 300).

Gate (local, Docker-free lanes): unit 167/167 (223 assertions), JS 83/83,
doc-links clean, composer lint clean (11 files), PHPStan 0 errors. Integration
and e2e run in CI.

Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
---
 maestro-menu-editor.php |  4 ++--
 package-lock.json       |  4 ++--
 package.json            |  2 +-
 readme.txt              | 13 ++++++++++++-
 4 files changed, 17 insertions(+), 6 deletions(-)

diff --git a/maestro-menu-editor.php b/maestro-menu-editor.php
index 7f60271..7164d04 100644
--- a/maestro-menu-editor.php
+++ b/maestro-menu-editor.php
@@ -3,7 +3,7 @@
  * Plugin Name:       Maestro: The Inline Admin Menu Editor
  * Plugin URI:        https://github.com/dknauss/Maestro/
  * Description:        In-place editing of the WordPress admin menu — rename items, reorder them, swap top-level icons, and hide items per role. Cosmetic only: hiding declutters, it does not lock access.
- * Version:           1.5.0
+ * Version:           1.5.1
  * Requires at least: 6.4
  * Requires PHP:      7.4
  * Author:            Dan Knauss
@@ -20,7 +20,7 @@
 
 defined( 'ABSPATH' ) || exit;
 
-define( 'MAESTRO_VERSION', '1.5.0' );
+define( 'MAESTRO_VERSION', '1.5.1' );
 define( 'MAESTRO_FILE', __FILE__ );
 define( 'MAESTRO_DIR', plugin_dir_path( __FILE__ ) );
 define( 'MAESTRO_URL', plugin_dir_url( __FILE__ ) );
diff --git a/package-lock.json b/package-lock.json
index 7377198..d20ac2e 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -1,12 +1,12 @@
 {
 	"name": "maestro",
-	"version": "1.5.0",
+	"version": "1.5.1",
 	"lockfileVersion": 3,
 	"requires": true,
 	"packages": {
 		"": {
 			"name": "maestro",
-			"version": "1.5.0",
+			"version": "1.5.1",
 			"devDependencies": {
 				"@axe-core/playwright": "^4.12.1",
 				"@playwright/test": "^1.62.1",
diff --git a/package.json b/package.json
index ecd1f69..74742fb 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
 {
 	"name": "maestro",
-	"version": "1.5.0",
+	"version": "1.5.1",
 	"private": true,
 	"description": "Tooling for Maestro: The Inline Admin Menu Editor: wp-env, PHP integration tests, Playwright E2E.",
 	"scripts": {
diff --git a/readme.txt b/readme.txt
index 7925a95..ba93285 100644
--- a/readme.txt
+++ b/readme.txt
@@ -4,7 +4,7 @@ Donate link: https://github.com/sponsors/dknauss
 Tags: admin menu, admin menu editor, menu editor, hide menu items, menu icons
 Requires at least: 6.4
 Tested up to: 7.0
-Stable tag: 1.5.0
+Stable tag: 1.5.1
 Requires PHP: 7.4
 License: GPLv2 or later
 License URI: https://www.gnu.org/licenses/gpl-2.0.html
@@ -156,6 +156,14 @@ If Maestro saves you time or brings you or your clients the joy of a tidy admin
 
 == Changelog ==
 
+= 1.5.1 =
+* **Fixed: the edit-mode toolbar no longer shifts while a change saves.** The save status now sits in a reserved slot, so the rename field stays where it is instead of sliding sideways every time a save cycles through "Saving…" and "Saved".
+* **Accessibility: a locked sub-item role is now reachable, and says why it is locked.** When a role is already hidden at the parent level, that role's checkbox under "Hide its sub-items from:" is shown as locked. It was previously skipped by keyboard and screen-reader navigation entirely — so the explanation was written for assistive technology but could never actually be heard. It is now reachable and announces its reason. The value still cannot be changed.
+* **Accessibility: dismissing the visibility popover by clicking outside it now returns focus** to the button that opened it, matching what pressing Escape already did. Previously focus fell to the top of the page and a keyboard user had to tab back.
+* The focus outline on edit-mode toolbar buttons is lighter, giving a clearer ring against dark admin colour schemes.
+* **Fixed: an override could look applied in the editor when it was not being applied.** On a site where two menu rows resolve to the same address — the same screen registered twice with different version or tracking parameters — the visibility popover could show roles as checked while the menu itself ignored the rule, and saving from that state could store what the popover showed. The editor now applies nothing for an ambiguous row, exactly as rendering the menu already did.
+* Internal: a stored override key carrying an HTML-encoded `>` is now classified consistently as a top-level or a sub-item key.
+
 = 1.5.0 =
 * **New: hide menu items from specific people, not just roles.** The visibility popover now has a search box for people alongside the role lists. Type a name, pick them, and the item disappears from that person's admin menu only — everyone else with the same role still sees it. You can target several people, and on an item with sub-items you can hide the sub-items per person while the parent stays visible. Use it when a role is the wrong unit: one editor on a team of editors who doesn't need a particular tool.
 * **Still cosmetic, exactly like hiding by role.** This changes what someone sees, never what they can do. A hidden page still opens normally for anyone who types its URL and holds the capability it requires, and no capability is added or removed by any rule. If you need to actually restrict access, pair Maestro with a capability manager — hiding a menu item is not a security measure.
@@ -221,6 +229,9 @@ If Maestro saves you time or brings you or your clients the joy of a tidy admin
 
 == Upgrade Notice ==
 
+= 1.5.1 =
+Fixes a toolbar that shifted sideways while saving, and three editor accessibility gaps. Also fixes a rare case where the visibility popover could show a rule as active while the menu ignored it, and saving could then store it. No configuration changes; existing overrides are untouched.
+
 = 1.5.0 =
 Adds hiding menu items from specific people, alongside hiding by role — on items and their sub-items. Still cosmetic only: a hidden page still opens by URL for anyone allowed to see it, and no capability changes. Existing role rules are untouched.
 

From 343c0f9eed2a5dd2d294327d462c10086fcafa16 Mon Sep 17 00:00:00 2001
From: Dan Knauss <273554+dknauss@users.noreply.github.com>
Date: Mon, 10 Aug 2026 08:20:41 -0600
Subject: [PATCH 23/27] docs(planning): record v1.5.1 shipped, and diagnose the
 deploy trigger (#147)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

v1.5.1 verified FROM SVN rather than the wp.org API: trunk Stable tag 1.5.1,
tags/1.5.1/ present and carrying the actual 1.5.1 CODE (reserved-slot min-width,
the #72aee6 ring, aria-describedby, isChildRoleLockedByParent, the norm_skip
fold) rather than merely the right version string, assets/ intact.

The more useful finding is the second one.

STATE.md has carried "the SVN deploy is not automatic — plan the step in" as a
standing lesson for FOUR consecutive releases, framed as something to remember.
It is not a discipline problem. wp-deploy.yml declares `release: types:
[published]`, and that path has fired zero times in six releases — every deploy
in the repo's history is workflow_dispatch.

Cause confirmed in source, not inferred: release.yml:36 publishes the Release
with softprops/action-gh-release@v3 and no `token:` input, so it authenticates as
GITHUB_TOKEN — and GitHub does not create workflow runs from GITHUB_TOKEN-
generated events. The trigger cannot fire. The lesson was scar tissue over a
workflow that declares automation it is structurally unable to perform.

Worth fixing rather than remembering because the failure is quiet in the worst
way: tag lands, Release publishes with its ZIP, CI is green, and every visible
signal says shipped while users still have the previous version.

Todo recommends having release.yml invoke the deploy directly over adding a PAT —
the PAT defeats a loop-guard that exists for good reasons, which is a real
security tradeoff for a convenience win. It also says not to delete the manual
step in the same change that adds the automation, since only a real release can
prove the fix.

Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
---
 .planning/STATE.md                            | 40 ++++++++-
 ...08-10-wp-deploy-release-trigger-is-dead.md | 90 +++++++++++++++++++
 2 files changed, 129 insertions(+), 1 deletion(-)
 create mode 100644 .planning/todos/pending/2026-08-10-wp-deploy-release-trigger-is-dead.md

diff --git a/.planning/STATE.md b/.planning/STATE.md
index e6f3f99..d4379c0 100644
--- a/.planning/STATE.md
+++ b/.planning/STATE.md
@@ -3,7 +3,7 @@ gsd_state_version: 1.0
 milestone: v1.5
 milestone_name: Per-User Visibility
 status: shipped
-stopped_at: "v1.5.0 shipped. UNRELEASED work now on main (Phase 25 + 3 Phase-20 correctness fixes) awaiting a v1.5.1 patch. Phases 27 and 28 planned and unblocked; no milestone open."
+stopped_at: "v1.5.1 SHIPPED and verified from SVN — main carries no unreleased code. Phases 27 and 28 planned and unblocked; no milestone open. New CI todo: the release→deploy trigger is dead by construction (GITHUB_TOKEN), which is what the four-release 'remember the manual step' lesson was actually describing."
 last_updated: "2026-08-10T00:00:00.000Z"
 last_activity: "2026-08-08 — **Phase 21 (ROLE-02 per-user hiding) executed, 5/5 plans, awaiting the human-verify checkpoint.** Branch `phase/21-cosmetic-per-user-hiding`, PR #120, nothing merged. Delivered: `hidden_users` / `child_hidden_users` storage; the `is_hidden_for_current_user()` seam widened to independent OR'd terms (3rd term reserved for the deferred `hidden_profiles`); `resolved_hidden_roles()` GENERALIZED to a field-parameterized resolver rather than duplicated, so the user axis inherits the qualified-key, schema-v2 (#115) and Axis-1 guards from one implementation; a shared `Cascade` union; the §6 cosmetic-invariant guardrail made enforcing; editor model exposure as id+name pairs via one batched query; four-group visibility popover with an async person picker on core's `wp/v2/users`. Gate: unit 165/165 (218), integration 109/109 (257), JS 83/83, e2e 39 passed/28 capture-skipped/0 failed, WPCS clean, PHPStan 0, Plugin Check 0 errors on the ZIP (1 pre-existing readme warning). THREE bugs found by verification that no unit test would have caught: (1) the guardrail initially could NOT detect a broken seam — `current_user_can()` answers from a cached allcaps array, so `snapshot_caps()` now drops `$GLOBALS['current_user']` to force re-derivation; (2) the picker URL appended `?` unconditionally, 404ing on every PLAIN-PERMALINK site since `rest_url()` already carries a query string; (3) clicking a search result or chip closed the whole popover, because re-rendering detached the node before `placePopover()`'s outside-click handler ran. Ruling recorded 2026-08-08: the super-admin exemption covers the NEW user axis only, multisite-scoped (unscoped would make administrators un-hideable on single-site and contradict the locked self-target decision). Prior: 2026-08-05 — **v1.4.1 SHIPPED** (PR #116, tag on c6cdcbe; wp.org API confirms 1.4.1). Patch for the shared-slug propagation defect (#115): a bare top-level key no longer applies to a submenu row whose slug names a rendered top-level item. Two Codex P2 rounds on #115 — the first cut of the gate tested `$nk === $norm_parent` and missed submenus parked under an unrelated parent; widened to `isset( $top_rendered_matches[ $nk ] )`. Prior: 2026-08-04 — **v1.4.0 SHIPPED** (PR #113, tag on 482510c, GitHub Release + wp.org SVN trunk/tags/1.4.0/assets confirmed). Phase 24 release gates 8–11 run consolidated over the full v1.3.1..main diff; one defect found and fixed (multibyte truncation blanked labels) and one changelog overclaim corrected (shared-slug isolation is submenu-direction only). ROLE-02 (Phase 21) deferred to v1.5."
 progress:
@@ -121,6 +121,34 @@ Progress: [██████████] v1.5 SHIPPED 2026-08-09 (Phases 21 +
 
 ## Release Binding
 
+### v1.5.1 — ✅ SHIPPED 2026-08-10
+
+**Tag `v1.5.1` on `9caa65d`** (PR #146 squash-merged). Patch for work that had sat
+on `main` across two releases: Phase 25's toolbar polish and the three Phase 20
+correctness follow-ups. Four files changed — `assets/maestro.{css,js}`,
+`includes/class-{config,replay}.php`.
+
+**Verified FROM SVN, not the API:** `trunk` Stable tag reads 1.5.1, `tags/1.5.1/`
+exists and carries the actual 1.5.1 CODE (the reserved-slot `min-width: 24px`, the
+`#72aee6` ring, `aria-describedby`, `isChildRoleLockedByParent`, the `norm_skip`
+fold) rather than merely the right version string, and `assets/` is intact — 2
+banners, 2 icons, 6 screenshots.
+
+**The changelog was derived from the `v1.5.0..main` diff**, per the gate-8 lesson.
+Two things were deliberately NOT claimed: the focus-ring change is described as
+clarity rather than a compliance fix (the old `#2271b1` passed WCAG 1.4.11 at
+3.07:1 — by 0.07), and the predicate-parity refactor is absent entirely (real
+value, zero behavior change). Upgrade Notice 287/300 chars.
+
+**The pipeline lesson is now DIAGNOSED, and it was never a discipline problem.**
+`wp-deploy.yml` declares `release: types: [published]`, but that path has fired
+zero times in six releases — all six were `workflow_dispatch`. Cause confirmed in
+source: `release.yml:36` publishes via `softprops/action-gh-release@v3` with the
+default `GITHUB_TOKEN`, and GitHub does not create workflow runs from
+`GITHUB_TOKEN`-generated events. The trigger cannot fire. Captured in
+`todos/pending/2026-08-10-wp-deploy-release-trigger-is-dead.md` — keep the manual
+step in the checklist until a real release proves a fix.
+
 ### v1.5 Per-User Visibility — ✅ SHIPPED 2026-08-09
 
 **Tag `v1.5.0` on `694b1bf`.** GitHub Release published with the ZIP; SVN deploy
@@ -376,6 +404,16 @@ Recent decisions affecting current work:
   and arbitrary SVG upload, which is a security feature wearing a UI feature's
   clothes and wants its own pass. `todos/pending/2026-08-09-icon-picker-remaining-scope.md`
 
+- **The release→deploy trigger is dead by construction** — `wp-deploy.yml`
+  declares `release: types: [published]`, a path that has fired **zero times in
+  six releases**; all six deploys were manual `workflow_dispatch`. Cause confirmed
+  in source, not inferred: `release.yml:36` publishes with the default
+  `GITHUB_TOKEN`, and GitHub does not create workflow runs from `GITHUB_TOKEN`
+  events. The four-release "remember the manual step" lesson was scar tissue over
+  this. Failure mode is quiet — tag, Release, green CI all say shipped while users
+  stay on the old version. Recommended fix is to have `release.yml` call the deploy
+  directly rather than to add a PAT.
+  `todos/pending/2026-08-10-wp-deploy-release-trigger-is-dead.md`
 - **AME feature-surface research** — the 2026-08-01 prior-art spike was
   *architectural*, scoped to Phase 20; its four-bullet market-gap list is now spent
   (import/export queued, reparenting out of scope, per-role deny shipped, inline UX
diff --git a/.planning/todos/pending/2026-08-10-wp-deploy-release-trigger-is-dead.md b/.planning/todos/pending/2026-08-10-wp-deploy-release-trigger-is-dead.md
new file mode 100644
index 0000000..03f2be7
--- /dev/null
+++ b/.planning/todos/pending/2026-08-10-wp-deploy-release-trigger-is-dead.md
@@ -0,0 +1,90 @@
+---
+created: 2026-08-10T00:00:00.000Z
+title: The release→deploy trigger is dead, and the "remember the manual step" lesson is a workaround for it
+area: ci
+files:
+  - .github/workflows/wp-deploy.yml (declares `release: types: [published]` — a path that has never fired)
+  - .github/workflows/release.yml (:36 — publishes the Release via softprops/action-gh-release@v3 with the default GITHUB_TOKEN)
+  - .planning/STATE.md (the "standing lesson" this replaces)
+---
+
+## Problem
+
+`wp-deploy.yml` declares two triggers:
+
+```yaml
+on:
+  workflow_dispatch:
+    inputs: { tag: ... }
+  release:
+    types: [published]
+```
+
+**The `release` path has never fired.** Every deploy in the repo's history is
+`workflow_dispatch`, six for six:
+
+| Run | Event | Date |
+|---|---|---|
+| 31396731982 | workflow_dispatch | 2026-08-10 (v1.5.1) |
+| 31348382131 | workflow_dispatch | 2026-08-10 (v1.5.0) |
+| 30975261722 | workflow_dispatch | 2026-08-05 (v1.4.1) |
+| 30966385425 | workflow_dispatch | 2026-08-05 (v1.4.0) |
+| 28751365681 | workflow_dispatch | 2026-07-05 |
+| 28432154051 | workflow_dispatch | 2026-06-30 |
+
+## Cause (confirmed, not inferred)
+
+`release.yml:36` creates the GitHub Release with
+`softprops/action-gh-release@v3` and **no `token:` input**, so it authenticates
+as the default `GITHUB_TOKEN`. GitHub does not create new workflow runs from
+events generated by `GITHUB_TOKEN` — a deliberate loop-prevention rule. The
+`release: [published]` event therefore never reaches `wp-deploy.yml`.
+
+Both halves are verified: the run history above, and the missing `token:` in the
+workflow source. This is not a flaky trigger or a forgotten click.
+
+## Why this is worth fixing rather than remembering
+
+STATE.md carries this as a **standing lesson repeated for four consecutive
+releases** — "the SVN deploy is not automatic and required a manual
+`workflow_dispatch`; plan the step in." That framing makes it a discipline
+problem. It isn't. It is a workflow that declares automation it cannot perform,
+and the lesson is the scar tissue.
+
+The failure mode is quiet and specifically bad: the tag lands, the GitHub Release
+publishes with its ZIP, CI is green, and **every visible signal says shipped**
+while users still have the previous version. Nothing surfaces the gap. v1.5.1 is
+only live because the step was performed by hand, again.
+
+## Options
+
+1. **Have `release.yml` invoke the deploy directly** — extract the deploy job to
+   `workflow_call` and `needs:` it, or call it as a reusable workflow. Removes the
+   event dependency entirely rather than repairing it. No new credential.
+   **Recommended.**
+2. **Publish the Release with a PAT** so the event fires. Works, but adds a
+   long-lived credential with `contents: write` to the release path purely to
+   defeat a loop-guard that exists for good reasons. A real security tradeoff for
+   a convenience win — weigh it, don't default to it.
+3. **Delete the dead `release:` trigger** and make the manual dispatch explicit —
+   documented in the release checklist as a required step, ideally with a check
+   that fails or warns when a tag exists with no corresponding deploy run.
+
+Option 3 is honest but keeps the manual step. Option 1 gets the automation the
+workflow already claims. The one outcome to avoid is leaving a trigger in place
+that reads as automation and isn't — that is what produced four repetitions.
+
+## Verification bar
+
+Whatever lands cannot be proven by inspection; it needs an actual release to fire
+it. And the check is **SVN, not the wp.org API** — `trunk`'s Stable tag, the
+existence of `tags/<version>/`, and that the tag contains the version's real
+CODE rather than merely the right version string (the v1.4.0 lesson), plus
+`assets/` intact.
+
+Until it is proven by a real release, the release checklist should keep the
+manual dispatch step. Do not delete the step in the same change that adds the
+automation.
+
+Source: found 2026-08-10 while deploying v1.5.1 — checked for an auto-fired run
+before dispatching, and there wasn't one, in six releases.

From 80df8ccab8b8979dc7f9fea07c67a381046ddf65 Mon Sep 17 00:00:00 2001
From: Dan Knauss <273554+dknauss@users.noreply.github.com>
Date: Mon, 10 Aug 2026 08:43:22 -0600
Subject: [PATCH 24/27] =?UTF-8?q?docs(planning):=20consolidate=20the=20car?=
 =?UTF-8?q?ried=20v1.5.0=20gaps=20=E2=80=94=20three=20become=20two=20(#148?=
 =?UTF-8?q?)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Reviewed the three items carried out of v1.5.0 rather than restating them, and
two of the three moved.

21-05 TASK 5 — STRUCK AS SUPERSEDED. Phase 25 performed a genuine human pass in
a live editor (25-VERIFICATION.md, 2026-08-09), and recorded itself as such
precisely because this project had one checkpoint recorded the other way. It
covered the toolbar and the locked-checkbox row. It did not cover the person
picker or the four-group popover — so the residue is real, but it is the SAME
residue as the screen-reader item, not a separate one.

THE SCREEN-READER ITEM slightly WIDENED and now owns that residue. Phase 25's M2
change altered the same popover AFTER the v1.5.0 axe scan: the derived-locked
checkbox went from natively disabled to aria-disabled, so a control that focus
mode used to skip is now reachable and refuses its own toggle. That was the right
fix — the lock reason was written for assistive technology and could never be
heard while the row was skipped — but it changes tab order and announcement
sequence in exactly the component that has never had a human pass, and axe passes
over it either way.

Both now live as one todo, with a concrete six-point script. Neither was ever a
todo before; they were prose in STATE.md, which is how they survived two releases
without moving.

THE #128 GAP IS UNCHANGED AND VERIFIED STILL LIVE. 707d9b6 changed 192 lines of
class-config.php plus the logic modules, and that mechanism is intact in main,
touched since only by #138's 20-line entity-collision fix. It is the same
sanitize path in which the ultrareview found four consecutive holes, and the one
round no adversarial pass has seen. Closing it needs /code-review ultra over
1a32f08..707d9b6, which is user-triggered.

Also struck one stale entry found while editing: the v1.5.0 milestone's "open,
carried deliberately" list still said Phase 25 remains open. It shipped in
v1.5.1. Struck in the same change, per the rule the 2026-08-09 reconciliation
established.

Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
---
 .planning/STATE.md                            | 77 +++++++++++++---
 ...-08-10-person-picker-screen-reader-pass.md | 87 +++++++++++++++++++
 2 files changed, 154 insertions(+), 10 deletions(-)
 create mode 100644 .planning/todos/pending/2026-08-10-person-picker-screen-reader-pass.md

diff --git a/.planning/STATE.md b/.planning/STATE.md
index d4379c0..702b7e3 100644
--- a/.planning/STATE.md
+++ b/.planning/STATE.md
@@ -66,8 +66,11 @@ settled. The gate earned its place; the hold was correct.
   `1a32f08`. Accepted deliberately: the collapse removed a class of seam rather
   than adding another guard.
 - No human screen-reader pass on the person picker. axe is clean across empty and
-  populated states, which is not the same thing.
-- 21-05 Task 5 (human browser verification) was never performed.
+  populated states, which is not the same thing. **Consolidated 2026-08-10 into
+  `todos/pending/2026-08-10-person-picker-screen-reader-pass.md`** — see the
+  reassessment below.
+- ~~21-05 Task 5 (human browser verification) was never performed.~~ **STRUCK
+  2026-08-10 as superseded** — see below.
 
 ### The two carried gaps — one closed, one only narrowed (2026-08-09)
 
@@ -94,6 +97,34 @@ whether the live-region timing is usable, or whether the four similarly-named
 groups are actually distinguishable in practice. A human with NVDA or VoiceOver
 remains worthwhile, and no automated result should be read as having replaced it.
 
+### Reassessed 2026-08-10 — the two remaining items are ONE task
+
+Both were carried as prose here rather than as a todo, which is how they survived
+two releases without moving. Reviewing them together:
+
+**21-05 Task 5 — STRUCK as superseded.** Phase 25 performed a genuine human pass
+in a live editor (`25-VERIFICATION.md`, 2026-08-09), and recorded itself as such
+precisely because this project had one checkpoint recorded the other way. It
+covered the toolbar and the locked-checkbox row. It did NOT cover the person
+picker or the four-group popover — so the residue is real, but it is the same
+residue as the screen-reader item, not a separate one.
+
+**The screen-reader item slightly WIDENED, and now owns the residue.** Phase 25's
+M2 change altered this same popover AFTER the v1.5.0 axe scan: the derived-locked
+checkbox went from natively `disabled` to `aria-disabled`, so a control that
+focus mode used to skip is now reachable and refuses its own toggle. That was the
+right fix — the lock reason was written for assistive technology and could never
+be heard while the row was skipped — but it changes tab order and announcement
+sequence in exactly the component that has never had a human pass, and a
+focusable-but-refusing control is not something automated tooling can evaluate
+for comprehensibility. axe passes over it either way.
+
+Both now live in `todos/pending/2026-08-10-person-picker-screen-reader-pass.md`
+as one task: one person, one sitting, VoiceOver or NVDA actually running.
+
+The original record of 21-05 Task 5 follows, kept because the distinction it
+draws is the reason both were written down.
+
 **21-05 Task 5 (human verification) — NOT PERFORMED AS SPECIFIED.** The plan
 marked it `autonomous: false` and called for a person driving the real editor in
 a browser before the phase closed. That did not happen. The phase was accepted
@@ -166,10 +197,17 @@ not automatic and required a manual `workflow_dispatch`. Plan the step in.
 **Open, carried deliberately:**
 - ROLE-02's cloned-role "profiles" half is still deferred
   (`todos/pending/2026-08-02-cloned-role-hiding-profiles.md`)
-- Phase 22 (Playground demo) and Phase 25 (toolbar polish) remain open
-- The #128 fixes shipped unreviewed (the ultrareview ran against the prior commit)
-- No human screen-reader pass on the person picker
-- 21-05 Task 5 (human browser verification) was never performed
+- Phase 22 (Playground demo) remains open. ~~Phase 25 (toolbar polish)~~ —
+  ✅ COMPLETE 2026-08-09, SHIPPED in v1.5.1
+- The #128 fixes shipped unreviewed (the ultrareview ran against the prior commit).
+  **Still true as of v1.5.1** — the mechanism is intact in `main`, touched since
+  only by #138's 20-line entity-collision fix. Closing it needs `/code-review ultra`
+  over `1a32f08..707d9b6`, which is user-triggered.
+- No human screen-reader pass on the person picker → consolidated into
+  `todos/pending/2026-08-10-person-picker-screen-reader-pass.md`
+- ~~21-05 Task 5 (human browser verification) was never performed~~ — **STRUCK
+  2026-08-10 as superseded** by Phase 25's human pass; the residue merged into the
+  todo above
 
 ### Release Checklist (v1.4.0)
 
@@ -404,6 +442,14 @@ Recent decisions affecting current work:
   and arbitrary SVG upload, which is a security feature wearing a UI feature's
   clothes and wants its own pass. `todos/pending/2026-08-09-icon-picker-remaining-scope.md`
 
+- **Human screen-reader pass on the person picker** — consolidates the two
+  surviving v1.5.0 caveats into one task (21-05 Task 5 is struck as superseded by
+  Phase 25's human pass). axe is clean and still passing, which is not the same
+  claim: it cannot judge announcement sequence, live-region timing, or whether four
+  similarly-named groups are distinguishable by ear. Phase 25's M2 change made a
+  previously-skipped control focusable in that popover *after* the axe scan, so the
+  gap widened slightly. One person, one sitting, VoiceOver or NVDA actually running.
+  `todos/pending/2026-08-10-person-picker-screen-reader-pass.md`
 - **The release→deploy trigger is dead by construction** — `wp-deploy.yml`
   declares `release: types: [published]`, a path that has fired **zero times in
   six releases**; all six deploys were manual `workflow_dispatch`. Cause confirmed
@@ -473,10 +519,21 @@ re-opening either question:**
   "fold versus width conflict" flagged on 2026-08-09 was mis-framed and is
   **withdrawn**: `160px` is just hardcoded in three places.
 
-**Three things carried, not resolved** (also in the v1.5.0 milestone entry):
-1. The #128 fixes shipped **unreviewed** — the ultrareview ran against the prior commit.
-2. **No human screen-reader pass** on the person picker; axe is clean, which is not the same claim.
-3. 21-05 Task 5 (human browser verification) was never performed; the phase was accepted on automated evidence.
+**Reviewed 2026-08-10 — three carried items are now TWO, and both are actionable:**
+1. **The #128 fixes shipped unreviewed.** Verified still live: `707d9b6` changed
+   192 lines of `class-config.php` plus the logic modules, and that mechanism is
+   intact in `main` (touched since only by #138's 20 lines). It is the same
+   sanitize path in which the ultrareview found four consecutive holes, and it is
+   the one round no adversarial pass has ever seen. **Close with `/code-review
+   ultra` over `1a32f08..707d9b6`** — user-triggered and billed, so it needs Dan.
+   Highest value of the three, and the cheapest.
+2. **The screen-reader pass**, now a real todo rather than prose:
+   `todos/pending/2026-08-10-person-picker-screen-reader-pass.md`. It absorbed
+   item 3 and slightly widened — Phase 25's M2 change made a previously-skipped
+   control focusable in that same popover *after* the v1.5.0 axe scan.
+3. ~~21-05 Task 5 (human browser verification)~~ — **STRUCK as superseded.** Phase
+   25 did a genuine human pass (`25-VERIFICATION.md`); it covered the toolbar and
+   the locked-checkbox row, not the person picker. That residue is item 2.
 
 **Environment gotcha:** another project's wp-env on this machine has claimed
 8888/8889 and at times 8899. Check which ports are free before `wp-env start`,
diff --git a/.planning/todos/pending/2026-08-10-person-picker-screen-reader-pass.md b/.planning/todos/pending/2026-08-10-person-picker-screen-reader-pass.md
new file mode 100644
index 0000000..7d69f12
--- /dev/null
+++ b/.planning/todos/pending/2026-08-10-person-picker-screen-reader-pass.md
@@ -0,0 +1,87 @@
+---
+created: 2026-08-10T00:00:00.000Z
+title: Human screen-reader pass on the visibility popover and person picker
+area: a11y
+files:
+  - assets/maestro.js (buildRoleGroup + the person picker — four similarly-named groups in one dialog)
+  - tests/e2e/specs/person-picker-a11y.spec.ts (the axe coverage this does NOT replace)
+  - .planning/phases/25-edit-mode-toolbar-dark-surface-polish/25-VERIFICATION.md (the human pass that closed the other half)
+---
+
+## Problem
+
+**Nobody has driven the person picker in a browser with a screen reader on.**
+
+This merges two items that were tracked separately across v1.5.0 and v1.5.1 and
+have turned out to be one task. Both were carried as prose in STATE.md rather
+than as a todo, which is how they survived two releases without moving.
+
+## What is actually covered, and what is not
+
+**Covered — axe-core.** `person-picker-a11y.spec.ts` scans the popover in BOTH
+empty and populated states (the chips, results list and live-region messages only
+exist after interaction, so an empty-state scan would miss most of what the
+feature renders). Zero violations against wcag2a/2aa/21a/21aa, scoped to the
+popover so wp-admin's own pre-existing findings don't train people to ignore the
+suite. This still passes.
+
+**Covered — a human in a live editor, for the OTHER half.** Phase 25 was a real
+human pass (`25-VERIFICATION.md`, 2026-08-09) and it deliberately records itself
+as such because this project has one checkpoint recorded the other way. It
+covered the toolbar and the locked-checkbox row. **It did not cover the person
+picker or the four-group popover**, and it names no assistive technology.
+
+**Not covered — anything about sequence or sense.** axe catches
+machine-detectable violations. It cannot tell you whether the announcements make
+sense in order, whether the live-region timing is usable, or whether four
+similarly-named groups ("Hide this item from:", "Hide its sub-items from:", and
+their two person equivalents) are actually distinguishable by ear. No automated
+result should be read as having replaced that.
+
+## Why this got slightly WORSE, not just older
+
+Phase 25's M2 change altered this same popover **after** the v1.5.0 axe scan: the
+derived-locked checkbox moved from natively `disabled` to `aria-disabled`, so a
+control that screen-reader focus mode used to skip entirely is now reachable and
+refuses its own toggle.
+
+That was the right fix — the lock reason was written for assistive technology and
+could never be heard while the row was skipped. But it changes tab order and
+announcement sequence in exactly the component that has never had a human pass,
+and "focusable control that declines to change" is a pattern automated tooling
+cannot evaluate for comprehensibility. The axe suite passes over it either way.
+
+## The task
+
+One person, one sitting, roughly twenty minutes, with VoiceOver or NVDA actually
+running:
+
+- Open the visibility popover on an item WITH sub-items, so all four groups are
+  present. Can you tell the four groups apart by ear alone?
+- Tab to a derived-locked checkbox. Is the lock reason announced, and does it
+  arrive as a description after the name rather than tangled into it?
+- Try to toggle it. Is the refusal comprehensible, or does it read as broken?
+- Use the person search: type, wait for results, pick someone. Is the live-region
+  announcement timed usefully, or does it fire before or long after the results?
+- Add and remove a chip. Is what happened announced?
+- Dismiss by clicking outside. Does focus land somewhere sensible (Phase 25's M3
+  fix should return it to the anchor)?
+
+## Not automatable, and not a code change
+
+The deliverable is a short findings note plus any defects it turns up — not a
+patch. If it finds nothing, that is worth recording too: the claim "a human
+listened to this" is one this project cannot currently make about its most
+complex surface, and making it once is the point.
+
+## Supersedes
+
+- **21-05 Task 5** (human browser verification) — struck as superseded 2026-08-10.
+  The plan marked it `autonomous: false` and it was never performed; Phase 21 was
+  accepted on automated evidence, two Codex rounds, and Claude's own browser-driven
+  round-trip during 21-04. Phase 25 has since done a genuine human pass over part
+  of the editor. The residue that actually remains is this todo.
+- The "screen-reader pass — narrowed, not closed" caveat carried in STATE.md
+  since 2026-08-09.
+
+Source: consolidated 2026-08-10 while reviewing the three carried v1.5.0 gaps.

From 7931bbf4e24c48076aa370667bcecb41ae75d322 Mon Sep 17 00:00:00 2001
From: Dan Knauss <273554+dknauss@users.noreply.github.com>
Date: Mon, 10 Aug 2026 09:03:49 -0600
Subject: [PATCH 25/27] docs(planning): rescope the AME research to a
 comprehensive sweep with a matrix (#150)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The earlier framing was a scoping note that "might legitimately return nothing
worth adopting". That under-specified the work. Whether any single feature is
worth adopting is a judgement per row — not a reason to skip the survey. The gap
actually being closed is that AME's feature surface has NEVER been enumerated;
only its architecture has.

The deliverable is now a row-per-feature AME<->Maestro MATRIX, built on the R1
conventions in compat/SCHEMA.md rather than invented: fixed cell vocabulary
(have / partial / deliberately-not / queued / unclaimed / anti-feature), evidence
inline, and a completion check so "comprehensive" is verifiable instead of
asserted. Recommendations are a column that falls out of it, not the point.

Evidence is its own COLUMN because the rows differ epistemically: free AME is GPL
and source-readable, while Pro and both add-ons are only marketing claims, upsell
strings and forum reports. Flattening those into one table without marking which
is which would launder claims into findings.

Coverage is now explicit and checkable — the free build's modules/ directory
(skipped entirely by the 2026-08-01 read, and where the discrete features live),
Pro, and BOTH add-ons. Branding and Toolbar have never been looked at at all.

The four constraints (cosmetic-only, the two-icon settings budget, borrow-
patterns-not-code, editing-happens-on-the-menu) moved from gate to filter: they
decide whether an `unclaimed` row is a real candidate. A row failing one is
marked deliberately-not WITH THE REASON, not dropped — "AME does X and we don't"
gets asked repeatedly and should be answered once, in writing.

Two sibling todos cross-linked so the matrix feeds them instead of being
duplicated:

- config-presets-export-import rests on one load-bearing market claim (AME has no
  named presets even in Pro) checked on 2026-07-03, BEFORE the source read. Flagged
  for re-verification from the matrix.
- admin-toolbar-editing-research gets a sequencing note: AME ships a Toolbar
  add-on nobody has examined, and its treatment of safely-hideable nodes is direct
  prior art for that note's hardest question. Soft dependency, not a blocker.

Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
---
 .planning/STATE.md                            |  19 +-
 ...2026-07-03-config-presets-export-import.md |   7 +
 ...26-08-09-admin-toolbar-editing-research.md |  13 ++
 ...2026-08-10-ame-feature-surface-research.md | 193 +++++++++++-------
 4 files changed, 148 insertions(+), 84 deletions(-)

diff --git a/.planning/STATE.md b/.planning/STATE.md
index 702b7e3..96c5e9c 100644
--- a/.planning/STATE.md
+++ b/.planning/STATE.md
@@ -460,13 +460,18 @@ Recent decisions affecting current work:
   stay on the old version. Recommended fix is to have `release.yml` call the deploy
   directly rather than to add a PAT.
   `todos/pending/2026-08-10-wp-deploy-release-trigger-is-dead.md`
-- **AME feature-surface research** — the 2026-08-01 prior-art spike was
-  *architectural*, scoped to Phase 20; its four-bullet market-gap list is now spent
-  (import/export queued, reparenting out of scope, per-role deny shipped, inline UX
-  is the premise). A second pass would inventory AME free/Pro/add-ons as a **product**
-  and sort each feature into have-it / deliberately-not / already-queued /
-  unclaimed / anti-feature. Deliverable is a NOTE, and "nothing worth adopting" is a
-  legitimate verdict. Worth doing because after Phases 27/28 there is no milestone.
+- **AME comprehensive feature sweep → an AME↔Maestro MATRIX** — the 2026-08-01
+  prior-art spike was *architectural*, scoped to Phase 20; AME's feature surface has
+  never been enumerated at all, and the four-bullet market-gap list it did produce
+  is now spent (import/export queued, reparenting out of scope, per-role deny
+  shipped, inline UX is the premise). Deliverable is a **row-per-feature matrix**
+  on the R1 `compat/SCHEMA.md` conventions — fixed cell vocabulary (have / partial /
+  deliberately-not / queued / unclaimed / anti-feature), evidence as its own column
+  (free is source-readable, Pro and the add-ons are only claims), and a completion
+  check so "comprehensive" is verifiable. Coverage must include the free build's
+  `modules/` dir (skipped in 2026-08-01), Pro, and BOTH add-ons — the Toolbar
+  add-on overlaps the toolbar-editing research directly. Recommendations are a
+  column that falls out, not the point. Scope clarified 2026-08-10.
   `todos/pending/2026-08-10-ame-feature-surface-research.md`
 - **Named config presets + JSON export/import** — v1.5 candidate; supersedes/extends V2-06 (SPEC.md Roadmap item 6). Research captured in `todos/pending/2026-07-03-config-presets-export-import.md`
 - **Declutter switch (non-core menu items → bottom section)** — v1.5 candidate; needs discuss/feasibility pass (top_order precedence, CPT handling). Research captured in `todos/pending/2026-07-03-declutter-switch-non-core-menu-items.md`
diff --git a/.planning/todos/pending/2026-07-03-config-presets-export-import.md b/.planning/todos/pending/2026-07-03-config-presets-export-import.md
index 31ec140..288c699 100644
--- a/.planning/todos/pending/2026-07-03-config-presets-export-import.md
+++ b/.planning/todos/pending/2026-07-03-config-presets-export-import.md
@@ -18,6 +18,13 @@ Admin Menu Editor (300k+ installs) gates JSON import/export behind Pro
 ($49–179) and has **no** named/switchable preset system even in Pro (confirmed
 2026-07-03 against their Permissions/CLI/changelog docs).
 
+> **Re-verify that claim before scoping.** It was checked against AME's docs on
+> 2026-07-03, before the 2026-08-01 source read, and it is the single load-bearing
+> market fact in this todo. [[2026-08-10-ame-feature-surface-research]] will
+> enumerate AME free/Pro/add-ons row by row — take the preset and import/export
+> rows from that matrix rather than re-deriving them here, and correct this
+> paragraph if the matrix disagrees.
+
 ## Solution (research done 2026-07-03, not yet scoped)
 
 The config is already preset-shaped: a sparse delta `{items, top_order,
diff --git a/.planning/todos/pending/2026-08-09-admin-toolbar-editing-research.md b/.planning/todos/pending/2026-08-09-admin-toolbar-editing-research.md
index cc8d379..8f0d7a0 100644
--- a/.planning/todos/pending/2026-08-09-admin-toolbar-editing-research.md
+++ b/.planning/todos/pending/2026-08-09-admin-toolbar-editing-research.md
@@ -24,6 +24,19 @@ go/no-go question with an explicit verdict, a storage recommendation, a named
 resolution seam, and invariants that must hold. That note is why Phase 21 could
 be planned confidently, and why its cosmetic-only claim was provable.
 
+## Sequencing note (added 2026-08-10)
+
+**AME ships a Toolbar add-on**, and it has never been looked at.
+[[2026-08-10-ame-feature-surface-research]] covers both add-ons as part of its
+sweep, so its matrix will say what AME's toolbar product actually does — which is
+directly relevant prior art for the questions below, particularly which nodes it
+treats as safely hideable and whether it makes any cosmetic-vs-access distinction
+at all.
+
+Doing the sweep first is cheaper than answering these blind. Not a hard
+dependency — this note can proceed without it — but if both are queued, take the
+AME matrix first.
+
 ## Questions the note must answer
 
 - **`WP_Admin_Bar` node registration** — how nodes are added, when, and whether
diff --git a/.planning/todos/pending/2026-08-10-ame-feature-surface-research.md b/.planning/todos/pending/2026-08-10-ame-feature-surface-research.md
index f70f56a..76d76e7 100644
--- a/.planning/todos/pending/2026-08-10-ame-feature-surface-research.md
+++ b/.planning/todos/pending/2026-08-10-ame-feature-surface-research.md
@@ -1,24 +1,34 @@
 ---
 created: 2026-08-10T00:00:00.000Z
-title: Admin Menu Editor — feature-surface scoping research (what to build next, not how)
+title: Admin Menu Editor — comprehensive feature sweep, delivered as an AME↔Maestro matrix
 area: research
 files:
   - .planning/compat/PRIOR-ART-admin-menu-editor.md (the 2026-08-01 spike — its ARCHITECTURE half is done; do not redo it)
-  - .planning/DECISION-settings-surface.md (the two-icon / no-settings-page budget any adopted feature must fit)
-  - .planning/phases/19-cosmetic-hiding-feasibility/19-FEASIBILITY-NOTE.md (the deliverable shape to copy)
+  - .planning/compat/SCHEMA.md (the R1 matrix conventions this deliverable should copy)
+  - .planning/DECISION-settings-surface.md (the two-icon / no-settings-page budget a candidate must fit)
   - SPEC.md (Roadmap items 1-10 + Out of Scope — the existing claims on this territory)
 ---
 
-## Problem
+## The deliverable is a MATRIX, not a verdict
+
+**A comprehensive, row-per-feature sweep of Admin Menu Editor, mapped cell by cell
+against what Maestro does.** The matrix IS the artifact. Recommendations fall out
+of it as a column; they are not the point of the exercise, and the sweep is worth
+doing even if every row lands in an already-known bucket.
+
+This supersedes an earlier framing of this todo as a scoping note that might
+return "nothing worth adopting". That under-specified the work: whether any single
+feature is worth adopting is a judgement per row, not a reason to skip the survey.
+The gap being closed is that **AME's feature surface has never been enumerated at
+all** — only its architecture.
+
+## Why it doesn't exist yet
 
-AME has been read once, and only architecturally.
 [`compat/PRIOR-ART-admin-menu-editor.md`](../../compat/PRIOR-ART-admin-menu-editor.md)
 (2026-08-01, AME free 1.15.1, source read) was pulled forward to feed Phase 20 and
 answered Phase 20's questions — identity, apply model, submenu targeting, hook
-order, storage. Those findings shipped as COMPAT-04/07/14.
-
-It never examined AME as a *product*. Its whole feature-facing output is one
-"market signals" section whose gap list is now spent:
+order, storage. Those findings shipped as COMPAT-04/07/14. Its only feature-facing
+output is a four-bullet "market signals" list, and every bullet is now spent:
 
 | Named gap (2026-08-01) | Status 2026-08-10 |
 |---|---|
@@ -27,87 +37,116 @@ It never examined AME as a *product*. Its whole feature-facing output is one
 | Per-role *deny* | **Shipped** — this is Maestro's cosmetic hiding |
 | True inline editing UX | Not a gap; it is the product's premise |
 
-The one artifact meant to say what to build next has nothing unclaimed left in it,
-and after Phases 27/28 there is no milestone. That makes this worth doing now — and
-easy to get wrong by inventing features instead of finding them.
-
-## The deliverable is a NOTE, not a feature
-
-Same contract as [[2026-08-09-admin-toolbar-editing-research]]: a scoping note, no
-commitment to build. `19-FEASIBILITY-NOTE.md` is the shape — explicit verdict,
-reasons, named constraints, written so a phase can be planned from it.
-
-**A legitimate verdict is "nothing worth adopting."** If the remaining gaps are all
-already queued, say so in a paragraph and stop. Do not pad a feature list to justify
-the pass.
-
-## Scope
+Four bullets is not a survey of a ten-year, ~89-class plugin. Nobody has ever
+listed what AME actually does.
 
-**In:** the user-facing feature inventory of AME free, Pro, and its add-ons
-(Branding, Toolbar) — including the free build's `modules/` directory, which the
-prior read skipped and which is where discrete features live. Map each to one
-verdict:
+## Matrix schema
 
-1. **Have it** — name Maestro's equivalent, so the note doubles as a position statement
-2. **Deliberately not** — excluded by Out of Scope or cosmetic-only; record *why*, because this gets asked again
-3. **Already queued** — link the todo/phase, don't re-derive
-4. **Genuinely unclaimed** — the only category that produces new work
-5. **Anti-feature** — they ship it; we should be able to say why we won't
+Copy the R1 conventions from [`compat/SCHEMA.md`](../../compat/SCHEMA.md) — fixed
+vocabulary per cell, evidence inline, and a completion check so "comprehensive" is
+verifiable rather than asserted. One row per AME feature:
 
-**Out:** architecture, apply model, hook ordering, storage, identity, submenu
-targeting — all answered 2026-08-01. If a feature finding needs an architectural
-answer, note the dependency and stop. Also out: other prior art — "Wider Admin Menu"
-and "Hide Admin Menu" belong to `SPEC.md` items 9 and 10. AME-only is what keeps
-this bounded.
-
-## Constraints an "unclaimed" finding must already clear
-
-Reject in place rather than surfacing for a later phase to reject again:
+| Column | Values / content |
+|---|---|
+| **AME feature** | The discrete user-facing capability, named as AME names it |
+| **Tier** | `free` · `Pro` · `add-on (Branding)` · `add-on (Toolbar)` |
+| **Evidence** | `source-read` (free zip) · `marketing claim` · `forum/changelog` · `upsell string` — see Method |
+| **What it does** | One line, behavioural — what a user gets, not how it is built |
+| **Maestro status** | `have` · `partial` · `deliberately-not` · `queued` · `unclaimed` · `anti-feature` |
+| **Maestro equivalent / blocker** | The shipped feature that covers it, the todo/phase that queues it, or the constraint that rules it out |
+| **Note** | Only where the row needs one |
+
+Status vocabulary, defined so cells stay comparable:
+
+- **have** — Maestro ships an equivalent. Name it. These rows make the matrix
+  double as a competitive position statement, which is worth as much as the gaps.
+- **partial** — an equivalent exists but is narrower. Say how.
+- **deliberately-not** — excluded by `REQUIREMENTS.md` Out of Scope or the
+  cosmetic-only invariant. **Record why**, because "AME does X and we don't" gets
+  asked repeatedly and the answer should be written once.
+- **queued** — maps to an existing todo or planned phase. Link it; don't re-derive.
+- **unclaimed** — no equivalent, not excluded, not queued. The candidate column.
+- **anti-feature** — AME ships it and Maestro should be able to say why it won't.
+
+## Coverage — what "comprehensive" means here
+
+The sweep is not done until each of these is enumerated and every item lands in a row:
+
+1. **AME free**, from the zip — including the `modules/` directory, which the
+   2026-08-01 read skipped entirely and which is where the discrete features live.
+   The central `WPMenuEditor` class was read; the modules were not.
+2. **AME Pro**, from published material. The headline split is already recorded
+   (per-role/user granting, hide-from-all-except-one-user, import/export, drag
+   between menu levels, new-window/iframe items, shortcodes in fields, colors,
+   600+ icons; $49–$179/yr) — but as a list of names, not as evaluated rows.
+3. **The add-ons** — Branding and Toolbar — which are their own products and have
+   never been looked at at all. The Toolbar add-on overlaps
+   [[2026-08-09-admin-toolbar-editing-research]] directly and may inform its
+   feasibility question.
+4. **The settings/UI surface** — what AME exposes where. Relevant because
+   `DECISION-settings-surface.md` locked Maestro's answer and AME is the
+   counter-example (a dedicated editor screen).
+
+**Completion check** (mirroring SCHEMA.md's): every file in AME's `modules/`
+accounted for in at least one row; every bullet on the Pro pricing page accounted
+for; both add-ons covered; zero rows with an empty status cell.
+
+## Constraints — a filter on the `unclaimed` column, not on the sweep
+
+Every row still gets surveyed and classified. These decide only whether an
+`unclaimed` row is a real candidate, and a row that fails one should be marked
+`deliberately-not` **with the reason recorded**, rather than dropped:
 
 - **Cosmetic-only is not negotiable.** AME conflates hiding with access control
-  (`do_not_allow`, `wp_die()`), its largest user-confusion category per the
-  2026-08-01 forum mining. `SPEC.md` item 7 (enforcement bridge) is already flagged
-  IN TENSION — don't let a feature finding smuggle that decision in.
+  (`do_not_allow` rewrites, `wp_die()` on page access) — its largest
+  user-confusion category per the 2026-08-01 forum mining, and Maestro's cleanest
+  differentiator. `SPEC.md` item 7 (the enforcement bridge) is already flagged IN
+  TENSION; do not let a matrix row smuggle that decision in.
 - **The settings surface is decided; the budget is two icons.**
-  `DECISION-settings-surface.md` allots Profiles and Settings modals and rules out a
-  wp-admin settings page permanently. A feature needing a third icon has a placement
-  problem to solve *in the note*.
+  `DECISION-settings-surface.md` allots Profiles and Settings modals and rules out
+  a wp-admin settings page permanently. A menu-wide candidate needing a third icon
+  has a placement problem to name in the matrix.
 - **Borrow patterns, not code** (`SPEC.md` principle 4). A feature that only works
-  under AME's full-rebuild model is a no.
+  under AME's full-rebuild model is `deliberately-not`.
 - **Editing happens on the menu.** Anything requiring you to leave the menu to
   configure the menu contradicts the core value.
 
-## Questions the note must answer
-
-- **What does AME free actually let a user do, enumerated?** Start with `modules/`.
-- **What is Pro-gated, and which are Maestro's cheapest credible free wins?** The
-  headline split is recorded (granting, hide-from-all-except-one, import/export,
-  drag between levels, iframe items, colors, 600+ icons, Branding, Toolbar;
-  $49–$179/yr). Missing is the per-feature judgement: cost, fit with cosmetic-only,
-  and whether "AME charges for this" is demand evidence or just their packaging.
-- **Do the recurring-pain categories point at features, not just fixes?** The five
-  named on 2026-08-01 were mined for bugs to pre-empt. "Menu reset to default"
-  confusion in particular smells like a missing feature — a durable answer to *what
-  changed and how do I get back* — which per-item reset plus
-  [[2026-07-03-config-presets-export-import]] may or may not already be.
-- **Has AME shipped since 1.15.1?** Re-check version and changelog delta first;
-  record the version studied, as the prior note did.
-- **Does anything justify a milestone?** Rank candidates against the
-  queued-but-unplanned set ([[2026-07-03-config-presets-export-import]],
-  [[2026-07-03-declutter-switch-non-core-menu-items]],
-  [[2026-08-09-icon-picker-remaining-scope]], Phase 22) — a new idea that loses to
-  something already queued is a finding too.
+## Out of scope
+
+The architecture comparison — apply model, hook ordering, storage format, menu
+identity, submenu targeting — all answered 2026-08-01. If a feature row needs an
+architectural answer, note the dependency in its Note cell and move on.
+
+Other prior art is also out: "Wider Admin Menu" and "Hide Admin Menu" belong to
+`SPEC.md` items 9 and 10. AME-only keeps this bounded.
 
 ## Method
 
-Free AME is GPL and readable from the official zip. **Pro is not** — its feature set
-comes from marketing, upsell strings, and the forum, all claims rather than verified
-behaviour. Label those unverified, as the prior note did. Do not cite the
-unconfirmed GitHub mirror.
+Free AME is GPL and readable from the official zip — same as the 2026-08-01 read.
+**Pro is not**, and neither are the add-ons: their feature sets come from
+marketing pages, the free build's upsell strings, and the support forum. That is a
+real epistemic difference between rows, which is why **Evidence is a column**
+rather than a footnote. Label Pro rows as claims. Do not cite the unconfirmed
+`Priyank57/admin-menu-editor-pro` GitHub mirror; it was never confirmed as
+Elsts-authored.
+
+**Re-check the version first.** AME was pinned at free 1.15.1 on 2026-08-01;
+record the version studied and skim the changelog delta before drawing
+conclusions.
+
+## After the matrix
+
+Rank the `unclaimed` rows against the queued-but-unplanned set —
+[[2026-07-03-config-presets-export-import]],
+[[2026-07-03-declutter-switch-non-core-menu-items]],
+[[2026-08-09-icon-picker-remaining-scope]], Phase 22 — rather than in isolation. A
+new candidate that loses to something already queued is a finding worth writing
+down.
 
-**Placement:** `.planning/compat/PRIOR-ART-admin-menu-editor-features.md`, beside the
-architecture note rather than inside it — that one is a shipped input to Phase 20 and
-should stay readable as the record of what fed those fixes.
+**Placement:** `.planning/compat/PRIOR-ART-admin-menu-editor-features.md`, beside
+the architecture note rather than inside it — that one is a shipped input to Phase
+20 and should stay readable as the record of what fed those fixes.
 
 Source: Dan's request 2026-08-10, after confirming no AME research phase was ever
-planned.
+planned; scope clarified the same day to a comprehensive sweep with a matrix
+deliverable.

From 92ee2b4e9ccd58884cf4729452e2309a36f29cf1 Mon Sep 17 00:00:00 2001
From: Dan Knauss <273554+dknauss@users.noreply.github.com>
Date: Mon, 10 Aug 2026 09:31:11 -0600
Subject: [PATCH 26/27] fix(ci): call the deploy workflow directly instead of
 relying on a dead trigger (#151)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* fix(ci): call the deploy workflow directly instead of relying on a dead trigger

wp-deploy.yml declared `release: types: [published]`. That trigger never fired,
in six consecutive releases — every deploy in this repo's history was a manual
workflow_dispatch, and STATE.md carried "remember the manual step" as a standing
lesson across four of them.

It is not a discipline problem. release.yml publishes the Release with
softprops/action-gh-release@v3 and no `token:` input, so it authenticates as the
default GITHUB_TOKEN — and GitHub deliberately does not start workflow runs from
GITHUB_TOKEN-generated events. The trigger could not work.

Option 1 from the todo, chosen over adding a PAT: a PAT would defeat a loop-guard
that exists for good reasons, and buys a convenience win with a long-lived
credential holding contents: write on the release path.

- wp-deploy.yml gains `workflow_call` with a declared `tag` input and the two SVN
  secrets; the dead `release:` trigger is REMOVED rather than left in place, since
  a trigger that reads as automation and isn't is what produced four repetitions
- release.yml gains a `deploy` job: uses the local workflow, needs: release,
  secrets: inherit
- workflow_dispatch is deliberately KEPT — it is how you re-deploy a tag whose
  commit predates these workflows, and how you recover from a half-failed deploy

Two details that would bite later:

`inputs.tag`, not `github.event.inputs.tag`. The latter is null on a
workflow_call and would fall through to github.ref_name — correct today only
because the caller is a tag push, and wrong the moment anything else calls this.
The concurrency group had the same bug and would have collapsed every release
into one group.

`needs: release` is the safety property, not just ordering: a failed build,
failed tag/version match, or failed Release publish all stop the deploy, so
wp.org is never reached by a tag that did not pass the gate.

BEHAVIOUR CHANGE: pushing a v* tag now deploys to WordPress.org with no human
step in between. That is the fix, but it removes a checkpoint that existed by
accident for six releases.

The todo stays PENDING and annotated rather than closed — only a real release can
prove this, and its verification bar says not to delete the manual step in the
same change that adds the automation.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

* fix(ci): gate the wp.org deploy behind an environment approval

Adds `environment: wordpress-org` to the deploy job. The environment was created
2026-08-10 with `dknauss` as a required reviewer.

This corrects the trade the previous commit made. Wiring the deploy directly fixes
a step that was silently forgotten six times — but on its own it meant a pushed
tag publishes to users with nobody in the loop. The ask was automation WITH a
final confirm, not without one.

Now: tag push -> build -> version check -> Release publish -> the deploy job
PAUSES for approval -> SVN. Nothing is forgettable, because the run is sitting
there and GitHub notifies rather than never starting. Nothing ships unattended,
because it will not proceed unapproved. workflow_dispatch hits the same gate.

Required reviewers on environments are free here because the repo is PUBLIC; on a
private repo this would need Pro/Team/Enterprise. Worth knowing before anyone
reuses the pattern.

The sharp edge, commented in place at the `environment:` line and in the todo: the
gate is only real while the environment EXISTS with a required reviewer. GitHub
auto-creates a missing environment with NO protection rules and the job sails
straight through — no error, it simply stops asking. Deleting or recreating
wordpress-org without reviewers silently turns this line into a no-op.

Not done, logged as optional hardening: WP_ORG_SVN_USERNAME / WP_ORG_SVN_PASSWORD
are still repo-level secrets readable by any workflow in the repo. Moving them
into the environment would scope them to approved deploy runs only, and needs the
values re-entered by hand.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
---
 .github/workflows/release.yml                 | 17 +++++
 .github/workflows/wp-deploy.yml               | 66 ++++++++++++++++---
 ...08-10-wp-deploy-release-trigger-is-dead.md | 37 +++++++++++
 3 files changed, 111 insertions(+), 9 deletions(-)

diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index 85d628d..0b51827 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -38,3 +38,20 @@ jobs:
           files: build/maestro-menu-editor.zip
           generate_release_notes: true
           fail_on_unmatched_files: true
+
+  # Deploy to WordPress.org by CALLING the deploy workflow, not by publishing a
+  # Release and hoping the `release: published` event starts it. It does not: the
+  # step above authenticates as the default GITHUB_TOKEN, and GitHub does not start
+  # workflow runs from GITHUB_TOKEN-generated events. That dead trigger is why every
+  # deploy in this repo's history was manual. See wp-deploy.yml's trigger comment.
+  #
+  # `needs: release` means a failed build, a failed tag/version check, or a failed
+  # Release publish all stop the deploy — wp.org is never reached by a tag that did
+  # not pass the gate above.
+  deploy:
+    name: Deploy to WordPress.org
+    needs: release
+    uses: ./.github/workflows/wp-deploy.yml
+    with:
+      tag: ${{ github.ref_name }}
+    secrets: inherit
diff --git a/.github/workflows/wp-deploy.yml b/.github/workflows/wp-deploy.yml
index 2f08722..361162f 100644
--- a/.github/workflows/wp-deploy.yml
+++ b/.github/workflows/wp-deploy.yml
@@ -1,20 +1,44 @@
 name: Deploy to WordPress.org
 
+# TRIGGERS — read this before adding a third one.
+#
+# This workflow used to declare `release: types: [published]`. That trigger NEVER
+# FIRED, in six consecutive releases: `release.yml` publishes the Release with the
+# default GITHUB_TOKEN, and GitHub deliberately does not start workflow runs from
+# GITHUB_TOKEN-generated events. Every deploy in this repo's history was a manual
+# workflow_dispatch, and STATE.md carried "remember the manual step" as a standing
+# lesson for four releases — scar tissue over a trigger that could not work.
+#
+# It is replaced by `workflow_call`: release.yml now invokes this workflow
+# DIRECTLY as a dependent job, so there is no event in the middle to be swallowed.
+# workflow_dispatch stays, deliberately — it is how you re-deploy a tag whose
+# commit predates these workflows, and how you recover if a deploy half-fails.
 on:
   workflow_dispatch:
     inputs:
       tag:
-        description: "Git tag to deploy (e.g. v1.1.1). Leave blank when triggered by a release."
+        description: "Git tag to deploy (e.g. v1.1.1). Leave blank to use the ref this was dispatched from."
         required: false
         default: ""
-  release:
-    types: [published]
+  workflow_call:
+    inputs:
+      tag:
+        description: "Git tag to deploy (e.g. v1.1.1), passed by release.yml."
+        required: true
+        type: string
+    secrets:
+      WP_ORG_SVN_USERNAME:
+        required: true
+      WP_ORG_SVN_PASSWORD:
+        required: true
 
 permissions:
   contents: read
 
 concurrency:
-  group: wporg-deploy-${{ github.event.inputs.tag || github.ref_name }}
+  # `inputs` covers BOTH workflow_dispatch and workflow_call; `github.event.inputs`
+  # would be null on a call and silently collapse every release into one group.
+  group: wporg-deploy-${{ inputs.tag || github.ref_name }}
   cancel-in-progress: false
 
 jobs:
@@ -22,11 +46,30 @@ jobs:
     name: Deploy to WordPress.org SVN
     runs-on: ubuntu-latest
 
+    # THE HUMAN GATE. Everything above this line is automatic — tag push, build,
+    # version check, Release publish — and then this job STOPS and waits for an
+    # approval on the `wordpress-org` environment before anything reaches wp.org.
+    #
+    # This is the deliberate answer to a real tension. Wiring the deploy directly
+    # (see the trigger comment above) fixes a step that was silently forgotten six
+    # times; but it would also mean a pushed tag publishes to users with no human
+    # in the loop. The environment gate keeps the automation — the run is sitting
+    # there, notified, impossible to forget — while keeping the final confirm.
+    #
+    # ⚠️ The gate is only real because the environment EXISTS with a required
+    # reviewer (created 2026-08-10, reviewer: dknauss). If a workflow names an
+    # environment that does not exist, GitHub AUTO-CREATES IT WITH NO PROTECTION
+    # RULES and the job sails straight through. Deleting or recreating this
+    # environment without reviewers silently converts this line into a no-op —
+    # there is no error, and the deploy simply stops asking.
+    environment: wordpress-org
+
     steps:
-      # Resolve which ref/version to ship. On a release event the tag comes from
-      # github.ref_name; on manual dispatch it comes from the `tag` input. This
-      # lets us deploy a tag whose commit predates these workflows (e.g. v1.0.0),
-      # since the workflow file itself is read from the dispatched ref (main).
+      # Resolve which ref/version to ship. The `tag` input carries it on both a
+      # workflow_call (release.yml passes github.ref_name) and a manual dispatch;
+      # github.ref_name is the fallback when a dispatch leaves it blank. This lets
+      # us deploy a tag whose commit predates these workflows (e.g. v1.0.0), since
+      # the workflow file itself is read from the dispatched ref (main).
       - name: Resolve ref + version
         id: meta
         env:
@@ -34,7 +77,12 @@ jobs:
           # of interpolating ${{ }} straight into the script body — GitHub sets
           # these as env values, so no dispatch input can break out of the string
           # and inject shell.
-          INPUT_TAG: ${{ github.event.inputs.tag }}
+          #
+          # `inputs.tag`, NOT `github.event.inputs.tag`: the latter is null on a
+          # workflow_call, which would silently fall through to github.ref_name.
+          # That happens to be correct today (the caller is a tag push) but only by
+          # accident, and it would break the moment anything else calls this.
+          INPUT_TAG: ${{ inputs.tag }}
           REF_NAME: ${{ github.ref_name }}
         run: |
           REF="$INPUT_TAG"
diff --git a/.planning/todos/pending/2026-08-10-wp-deploy-release-trigger-is-dead.md b/.planning/todos/pending/2026-08-10-wp-deploy-release-trigger-is-dead.md
index 03f2be7..c84fd60 100644
--- a/.planning/todos/pending/2026-08-10-wp-deploy-release-trigger-is-dead.md
+++ b/.planning/todos/pending/2026-08-10-wp-deploy-release-trigger-is-dead.md
@@ -8,6 +8,43 @@ files:
   - .planning/STATE.md (the "standing lesson" this replaces)
 ---
 
+## ⚙️ FIX IMPLEMENTED 2026-08-10 — NOT YET PROVEN
+
+**Option 1 was taken.** `wp-deploy.yml` gained a `workflow_call` trigger (with
+declared `tag` input and the two SVN secrets), the dead `release: [published]`
+trigger was **removed**, and `release.yml` gained a `deploy` job that calls it
+with `needs: release` + `secrets: inherit`. No new credential.
+
+**This todo stays PENDING until a real release fires it**, per the verification
+bar below. Until then, keep treating the manual dispatch as the live path.
+
+**The human gate is preserved, deliberately.** An earlier cut of this fix let a
+tag push publish straight to wp.org. That traded a forgotten step for an
+unattended one, which was the wrong trade: the ask was automation *with* a final
+confirm, not without one.
+
+The deploy job now runs in the **`wordpress-org` environment** (created
+2026-08-10, required reviewer `dknauss`). Tag push → build → version check →
+Release publish → the deploy job **pauses for approval** → SVN. Nothing is
+forgettable, because the run is sitting there and GitHub notifies; nothing ships
+unattended, because it will not proceed unapproved.
+
+`needs: release` is the other guard — a failed build, a failed tag/version match,
+or a failed Release publish all stop the deploy before wp.org is touched.
+`workflow_dispatch` is retained for re-deploys and recovery, and it hits the same
+gate.
+
+**⚠️ The gate is only real while the environment exists WITH a required reviewer.**
+GitHub auto-creates a missing environment with **no protection rules** and the job
+sails through — no error, it just stops asking. Deleting or recreating
+`wordpress-org` without reviewers silently converts `environment:` into a no-op.
+Worth re-checking if deploys ever stop prompting.
+
+**Optional hardening, not done:** `WP_ORG_SVN_USERNAME` / `WP_ORG_SVN_PASSWORD`
+are still repo-level secrets, readable by any workflow in the repo. Moving them
+into the `wordpress-org` environment would scope them to approved deploy runs
+only. Requires re-entering the values by hand in Settings → Environments.
+
 ## Problem
 
 `wp-deploy.yml` declares two triggers:

From a8f810631cdb6574d3c716e02a1d838181a511c5 Mon Sep 17 00:00:00 2001
From: Dan Knauss <273554+dknauss@users.noreply.github.com>
Date: Tue, 11 Aug 2026 19:37:35 -0600
Subject: [PATCH 27/27] docs(compat): record the non-autoloaded option as
 differentiator D4 (#152)

* docs(compat): record the non-autoloaded option as differentiator D4

Dan observed on live sites that Admin Menu Editor's option row can dominate
wp_options and slow admin loads. It is a known, acknowledged issue upstream,
and Maestro's storage model is the direct counter-position -- but that was
recorded nowhere except one cell of the 2026-08-01 architecture table.

- PRIOR-ART: add D4 to Differentiate. AME's `ws_menu_editor` is autoloaded, so
  every request -- front end included, where the data is unused -- pays to fetch
  and unserialize it, and it grows with the whole admin menu rather than with
  what the user edited. Evidence is upstream, not inferred: Elsts confirms the
  autoload behavior in a wordpress.org thread and declines to flip it (an extra
  admin query), plus three size mitigations across 2.5 / 2.11 / 2.27 -- which is
  what makes it structural. Maestro's side is stated with the measured numbers
  and with the trade named honestly (1 extra admin-page query, exactly Elsts'
  objection; zero front-end cost, which is the bulk of real traffic).
  Framed as the storage-row consequence of the existing V2 finding, not a new
  claim. Notes the evidence caveat: the autoload flag comes from the reply and
  the changelog, not from the 1.15.1 source read.

- Feature-sweep todo: the sweep had storage entirely out of scope and would have
  missed this. Carve out the footprint consequences -- format stays out, but
  AME's two Settings-tab toggles ("Compress menu configuration data",
  "Optimize menu configuration size") are user-facing features and earn rows,
  landing `deliberately-not`. Folds in the open evidence question so the zip
  read confirms the `update_option` call and upgrades D4 to `source-read`.

- class-config.php: the MAX_CONFIG_BYTES docblock said the cap protects "every
  autoloaded read of it", contradicting the design two methods below it. Say
  admin-request read, and state that the option is never in `alloptions`.

Comment-only code change: php -l and phpcs both clean.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

* docs(readme): sharpen the footprint copy, and pin down where the autoload cost lands

Lead the Performance section with the alloptions point instead of burying it
fourth, since it is the claim that distinguishes Maestro and the one a user can
verify themselves -- `wp option list --autoload=on` does not list maestro_config.
Adds the sparse-delta framing (storage tracks edits, not installed-plugin count)
and the measured 0.1 ms / 1 ms figures with a link to the method. No competitor
is named, and no comparative claim is made about any other plugin -- the copy
describes the WordPress mechanism and what Maestro does with it.

Also tightens D4 in the prior-art note. "Every request pays to fetch and
unserialize it" was loose: wp_load_alloptions() pulls every autoloaded row in
one query and holds it in memory, but the option's own maybe_unserialize() runs
only when get_option() asks for it. The front-end tax is the bundle -- transfer,
memory, and with a persistent object cache a per-request fetch and unserialize
of the whole alloptions object, which is where a fat row hurts most. Notes that
full-page caching spares requests that never boot WP.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

* docs(readme): lead the footprint section with the competitive claim, and retag

Per Dan: state the performance advantage head-on rather than leaving the reader
to infer it from the mechanism. Wording is his. The "nothing to compress,
optimize, or tune" clause moves up into it, so it is dropped from the
sparse-delta bullet to avoid saying it twice.

Tags: drop "admin menu editor" -- guideline 12 treats a competitor's plugin name
as spam, and the phrase is already in our plugin TITLE, which the directory
weights far above tags, so the SEO cost is close to nil. (Evidence that tags are
weak: Admin Menu Editor ranks #1 for "hide admin menu", "menu editor", "admin
menu icons" and "hide menu items" while tagging none of them -- it tags only
admin/dashboard/menu/security/wpmu.)

Filled the slot with "rename menu items" rather than the requested "hide admin
menu": Hide Admin Menu is itself a plugin (20k installs), so that swap would
have reproduced the exact problem being fixed. "rename menu items" collides with
no plugin name, pairs with the existing "hide menu items", and covers the one
core capability the tag set had no term for.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

* docs(readme): work the searched phrases into the description prose

The directory indexes the whole readme and weights the title and body far above
tags -- AME ranks #1 for "hide admin menu", "menu editor", "admin menu icons"
and "hide menu items" while tagging none of them. So the description, not the
tag line, is where discoverability is won, and ours led with "orchestrate the
appearance of the WordPress admin menu": true to the product, but containing
almost none of the literal phrases people type.

- Short description now leads with "Hide admin menu items per user role", the
  highest-intent phrase we can claim. 146 chars, same as before, still under the
  150 limit.
- Opening bold line names the four capabilities in searchable form (rename /
  reorder / change icons / hide admin menu items) instead of only "orchestrate".
- New second paragraph frames the jobs -- declutter a client site, rename
  cryptic plugin labels, reorder, hide per role -- so the phrases appear in
  prose a human wants to read rather than as a keyword list. Guideline 12 bars
  keyword stuffing; this stays on the right side of that line by describing real
  use cases.
- Adds a one-line performance tease pointing at the footprint section, so the
  differentiator is visible above the fold rather than only near the bottom.

The inline-editing paragraph is unchanged apart from a closing line, since that
premise is still the lead story.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
---
 .../compat/PRIOR-ART-admin-menu-editor.md     | 38 +++++++++++++++++++
 ...2026-08-10-ame-feature-surface-research.md | 20 ++++++++++
 includes/class-config.php                     |  7 +++-
 readme.txt                                    | 26 ++++++++-----
 4 files changed, 80 insertions(+), 11 deletions(-)

diff --git a/.planning/compat/PRIOR-ART-admin-menu-editor.md b/.planning/compat/PRIOR-ART-admin-menu-editor.md
index 521a26e..2885c44 100644
--- a/.planning/compat/PRIOR-ART-admin-menu-editor.md
+++ b/.planning/compat/PRIOR-ART-admin-menu-editor.md
@@ -99,6 +99,44 @@ solved — or paid for the sharp corners of — most of Maestro's hard problems.
   drag-between-levels (reparenting), and per-role deny are all either Pro-gated or fragile in AME.
   Maestro's own backlog (`config-presets-export-import`, reparenting v2) lines up to undercut these
   for free.
+- **D4 — Zero front-end footprint: one sparse, NON-AUTOLOADED row (added 2026-08-11).** The
+  storage-row consequence of V2, and a **key differentiator / USP** — the one Maestro claim that is
+  measurable by a third party (`wp option list --autoload=on`) without installing either plugin.
+  - **AME's row is autoloaded**, so its bytes ride in the `alloptions` bundle on every request that
+    boots WP — front end and logged-out included, where the data is never read. Its size grows with
+    the *whole* admin menu (every plugin installed adds to the stored full tree) and with every
+    role/user rule, not with what the user edited.
+  - **Where that cost actually lands** (state it precisely; the loose version invites a correction):
+    `wp_load_alloptions()` fetches every autoloaded row in one query and holds them in memory for
+    the request. The option's own `maybe_unserialize()` runs only when something calls
+    `get_option()` for it — so the front-end tax is the **bundle**, not that call: DB→PHP transfer,
+    memory, and — with a persistent object cache, where `alloptions` is a single cache object — a
+    per-request fetch and unserialize of the *whole* bundle, which is precisely where a fat row
+    hurts most. A full-page cache spares requests that never boot WP; a logged-in or otherwise
+    uncacheable front-end request pays in full.
+  - **This is acknowledged upstream, not inferred.** A wordpress.org thread reports `ws_menu_editor`
+    as the site's largest autoloaded row; Elsts confirms the autoload behavior and declines to flip
+    it because non-autoloaded "would mean an additional SQL query on every admin page", pointing to
+    compression instead ([support thread](https://wordpress.org/support/topic/wp_option-table-ws_menu_editor-auotload-yes/)).
+    Three separate size mitigations over eight years ([Pro changelog](https://adminmenueditor.com/documentation/changelog/)):
+    **2.5** (2017) compress-menu-config, **2.11** (2020) + zlib ("greatly decreases the amount of
+    data stored… but increases decompression overhead"), **2.27** (2025) "Optimize menu
+    configuration size" for the `ws_menu_editor_pro` entry. Three rounds ⇒ structural, not a bug.
+  - **Maestro's position:** one `maestro_config` row written `update_option( …, false )`
+    (`includes/class-config.php`), never created until first save; sparse delta so size tracks
+    *edits*, not installed-plugin count; hard 1 MB aggregate cap; every hook admin-gated (`Replay`
+    on `admin_menu`, `Admin_Bar::node()` bails on `! is_admin()`) so a front-end request reads
+    nothing at all. Measured: **0 extra front-end queries**; ~0.1 ms added per admin page at a
+    realistic 5–15 KB config, ~1 ms at the 1 MB ceiling
+    (`docs/performance/config-size-and-page-load.md`).
+  - **The trade, stated honestly:** non-autoloaded costs **1 extra admin-page query** — exactly
+    Elsts' objection. Maestro takes it because that query is admin-only, memoized once per request
+    by `Config::get()`, and zero with a persistent object cache, while public traffic — the bulk of
+    a live site's requests — pays nothing. AME's arrangement inverts the tax.
+  - **Evidence caveat:** the autoload flag comes from the author's own reply and the changelog, not
+    from the 1.15.1 source read (that spike recorded the storage *format*, not the autoload
+    argument). Confirm the `update_option` call when the free zip is next opened — the feature
+    sweep todo now carries that as a check.
 
 ---
 
diff --git a/.planning/todos/pending/2026-08-10-ame-feature-surface-research.md b/.planning/todos/pending/2026-08-10-ame-feature-surface-research.md
index 76d76e7..3eba5e0 100644
--- a/.planning/todos/pending/2026-08-10-ame-feature-surface-research.md
+++ b/.planning/todos/pending/2026-08-10-ame-feature-surface-research.md
@@ -86,6 +86,20 @@ The sweep is not done until each of these is enumerated and every item lands in
 4. **The settings/UI surface** — what AME exposes where. Relevant because
    `DECISION-settings-surface.md` locked Maestro's answer and AME is the
    counter-example (a dedicated editor screen).
+5. **The database-footprint features** — AME's Settings tab ships "Compress menu
+   configuration data" (2.5, zlib in 2.11) and "Optimize menu configuration size"
+   (2.27). These are *user-facing toggles*, so they are feature rows despite the
+   storage carve-out in Out of scope below, and they are the rows where Maestro's
+   **D4 differentiator** (single sparse non-autoloaded row — see
+   [`PRIOR-ART-admin-menu-editor.md`](../../compat/PRIOR-ART-admin-menu-editor.md)
+   § Differentiate) states itself: status `deliberately-not`, because a config that
+   is sparse and out of `alloptions` never needs a compression toggle. Expected to
+   be among the strongest `have`/`deliberately-not` rows in the matrix for
+   competitive-positioning purposes.
+   **Also settle the open evidence question while the zip is open:** confirm
+   whether `ws_menu_editor` is written with an autoload argument at all. D4
+   currently rests on the author's forum reply plus the changelog, not on a source
+   read — grep the `update_option` call and record the answer as `source-read`.
 
 **Completion check** (mirroring SCHEMA.md's): every file in AME's `modules/`
 accounted for in at least one row; every bullet on the Pro pricing page accounted
@@ -117,6 +131,12 @@ The architecture comparison — apply model, hook ordering, storage format, menu
 identity, submenu targeting — all answered 2026-08-01. If a feature row needs an
 architectural answer, note the dependency in its Note cell and move on.
 
+**One carve-out: the options-table footprint is in scope** (Coverage item 5). The
+storage *format* is architecture and stays out, but its consequences — an
+autoloaded row that every front-end request pays for, and the two Settings-tab
+toggles AME ships to manage it — are user-visible and are Maestro's D4 selling
+point. They earn rows.
+
 Other prior art is also out: "Wider Admin Menu" and "Hide Admin Menu" belong to
 `SPEC.md` items 9 and 10. AME-only keeps this bounded.
 
diff --git a/includes/class-config.php b/includes/class-config.php
index f5dbfcb..212c8b6 100644
--- a/includes/class-config.php
+++ b/includes/class-config.php
@@ -133,8 +133,11 @@ class Config {
 	 * under this — five 128 KB icons plus titles/roles is ~0.65 MB. The ceiling
 	 * exists only to refuse the pathological multi-MB payload (e.g. 200 max
 	 * items each carrying a 128 KB icon ≈ 25 MB) that would bloat the option
-	 * and every autoloaded read of it. An over-ceiling save is rejected whole
-	 * rather than truncated — a partial config is worse than the prior one.
+	 * and every admin-request read of it. (The option is stored non-autoloaded —
+	 * see save() — so it is never part of the `alloptions` bundle; the cost the
+	 * ceiling bounds is the per-admin-request get_option + unserialize, not a
+	 * front-end tax.) An over-ceiling save is rejected whole rather than
+	 * truncated — a partial config is worse than the prior one.
 	 *
 	 * @var int
 	 */
diff --git a/readme.txt b/readme.txt
index ba93285..d65a532 100644
--- a/readme.txt
+++ b/readme.txt
@@ -1,7 +1,7 @@
 === Maestro: The Inline Admin Menu Editor ===
 Contributors: dpknauss
 Donate link: https://github.com/sponsors/dknauss
-Tags: admin menu, admin menu editor, menu editor, hide menu items, menu icons
+Tags: admin menu, menu editor, hide menu items, rename menu items, menu icons
 Requires at least: 6.4
 Tested up to: 7.0
 Stable tag: 1.5.1
@@ -9,13 +9,17 @@ Requires PHP: 7.4
 License: GPLv2 or later
 License URI: https://www.gnu.org/licenses/gpl-2.0.html
 
-Rename, reorder, change icons, and hide WordPress admin menu items per user role — an inline admin menu editor you drive right on the menu itself.
+Hide admin menu items per user role, rename them, reorder them, swap their icons — an inline admin menu editor you drive right on the menu itself.
 
 == Description ==
 
-**Maestro lets you orchestrate the appearance of the WordPress admin menu.** 
+**Maestro lets you orchestrate the appearance of the WordPress admin menu — rename admin menu items, reorder them, change their icons, and hide admin menu items from the roles and people who don't need them.**
 
-Instead of a separate settings screen, Maestro turns the admin menu into something you edit *in place* — right where it lives. Toggle **Edit Menu** from the admin bar, and the menu becomes editable. Click a menu item to rename it, hide it from selected user roles, or change its icon. Drag submenu items and whole menu groups to reorder them. 
+Every WordPress install accumulates menu clutter. A dozen plugins each claim a top-level slot, submenus sit in an order nobody chose, and clients meet a dashboard full of tools that aren't theirs. Maestro is how you customize the admin menu back into shape: **declutter** it for a client site, **rename** cryptic plugin labels into the words your team actually uses, **reorder** the admin menu so what you touch daily is at the top, and **hide admin menu items per user role** — or from one named person — so everyone sees only their own work.
+
+Instead of a separate settings screen, Maestro turns the admin menu into something you edit *in place* — right where it lives. Toggle **Edit Menu** from the admin bar, and the menu becomes editable. Click a menu item to rename it, hide it from selected user roles, or change its icon. Drag submenu items and whole menu groups to reorder them. Nothing to configure first, and nothing to learn: the menu you are editing *is* the menu you are looking at.
+
+And it stays out of the way. Maestro adds **no autoloaded options** and does no work at all on the front end, so a menu you tidied for the dashboard costs your visitors nothing (see **Performance & footprint** below).
 
 **Try Maestro right here.** Launch a demo in [WordPress Playground](https://playground.wordpress.net/?blueprint-url=https://raw.githubusercontent.com/dknauss/Maestro/main/playground/blueprint-hosted.json) — it boots a throwaway site with the plugin active in edit mode, plus User Switching and test users (editor, author, contributor, subscriber; password `password`) so you can try per-role visibility by switching to another user's account.
 
@@ -128,15 +132,19 @@ their current parent.
 
 == Performance & footprint ==
 
+**Unlike other admin menu editors, Maestro won't hurt your site's performance. It's small enough that there is nothing to compress, optimize, or tune.**
+
 Maestro is built to stay out of the way:
 
-* **Zero extra database queries on the front end.** Every hook is admin-only, so the plugin is completely inert for public page loads and logged-out visitors.
-* **One extra query on an admin page** — a single, *non-autoloaded* option (`maestro_config`), read once per request and cached. With a persistent object cache (Redis / Memcached) that drops to zero.
-* **Nothing added to `alloptions`.** Because the option is not autoloaded, it adds no weight to the bundle WordPress loads on every request.
+* **Nothing added to `alloptions` — the one that matters.** WordPress loads every *autoloaded* option into memory on every request that boots it, including front-end pages served to logged-out visitors. A menu configuration is admin-only data, so an autoloaded one is a tax on traffic that will never read it — and a bloated autoloaded bundle is a classic cause of a sluggish site. Maestro's option is explicitly non-autoloaded. **Check it on your own site:** `wp option list --autoload=on` will not list `maestro_config`.
+* **Zero extra database queries on the front end.** Not merely "light" — inert. Every hook is admin-gated, so a public page load reads nothing at all.
+* **One extra query on an admin page** — a single, *non-autoloaded* option (`maestro_config`), read once per request and cached, no matter how many parts of the plugin ask for it. With a persistent object cache (Redis / Memcached) that drops to zero. This is a deliberate trade: one query where the data is actually used, so that public traffic — the bulk of what a live site serves — pays nothing.
+* **Storage tracks your edits, not your plugin count.** Maestro stores a sparse delta: three renamed items are three renamed items, whether the site runs five plugins or fifty. A typical configuration is 5–15 KB, with a hard 1 MB ceiling.
 * **Minimal storage.** One `wp_options` row, created only when you first save a change — a fresh install stores nothing. No custom tables, no post or user meta, no transients, no cron jobs. Uninstalling deletes that single row.
-* **Small install** — roughly a 115 KB download. Menu changes are applied in memory during the `admin_menu` pass, not through extra queries.
+* **Measured, not asserted.** At a typical configuration size Maestro adds roughly **0.1 ms** to an admin page load; even a pathological config at the 1 MB ceiling adds about **1 ms**. Menu changes are applied in memory during the `admin_menu` pass, not through extra queries. Method and full numbers: [config size vs. page-load cost](https://github.com/dknauss/Maestro/blob/main/docs/performance/config-size-and-page-load.md).
+* **Small install** — roughly a 115 KB download.
 
-(Figures are a v1.4.1 snapshot.)
+(Size figures are a v1.4.1 snapshot; timings were measured 2026-08-03 on WordPress 7.0 / PHP 8.3.)
 
 == Known limits / deferred to v2 ==