Sprint Goal Assessment

Sprint 3 fully achieves its goal. Every doc that previously claimed "mailbox CRUD requires root" has been rewritten to match the shipped owner-gated model, the release notes call out the change explicitly with an upgrade-compatibility paragraph, and format_auth_error is now a single canonical renderer in src/auth.rs rather than three near-duplicates. The dogfood walkthrough exercised the canonical workflow end-to-end as a non-root user.

Acceptance Criteria Checklist

[S3-1] Rewrite book/security.md Trust Boundaries

• MailboxCrud row dropped — verified the previous per-Subject table is preserved and a new "Per-action authorization" table was added with the right rows.
• MailboxCreate / MailboxDelete rows added in the owner-gated column with per-action rules.
• Rationale paragraph references the single-trust-boundary model and the SO_PEERCRED defense.
• Cross-uid creates and the catchall aimx-catchall system user explicitly noted as remaining operator-only.

[S3-2] Rewrite book/mailboxes.md

• sudo framing dropped from create/delete. New "No sudo needed for the mailboxes you own" bullet is the headline.
• Owner-binding rule documented in plain English (the explicit three-bullet block).
• New "Agents can self-serve via MCP" section added.
• --owner documented as root-only-effective with the soft-warning behavior for non-root callers.

[S3-3] Rewrite affected paragraphs in remaining book chapters

• book/setup.md: "Provisioning your first mailbox" rewritten — non-root path is the common case, sudo only for cross-uid creates.
• book/troubleshooting.md: the "stance has been retired" line is GONE; it has been replaced by two correct entries — one for the non-root socket-missing failure mode, one for the EACCES owner-mismatch path. The flip is correct.
• book/mcp.md: "10 MCP tools" → "12 MCP tools"; the stale "Removed in this release" callout removed; mailbox_create and mailbox_delete documented with parameter schema, returns, and error cases.
• book/cli.md: aimx mailboxes create | delete rewritten to reflect owner-gated behavior + daemon-required for non-root + soft-warn on --owner.
• book/agent-integration.md: no stale guidance found; related agent reference (agents/common/references/troubleshooting.md) updated to point agents at MCP self-service.
• AC grep: independently re-ran grep -ri "requires root\|requires sudo\|run with sudo" book/ — every remaining match is a legitimate root-only command (setup, serve, uninstall, dkim-keygen, portcheck, --all), or part of the new error message text itself, or the FAQ entry on hand-editing mailbox.owner = "root" for hooks. AC met.

[S3-4] Release-notes entry

• New entry at top of unreleased section with title "Mailbox create/delete no longer requires root".
• Body covers all four required points: (1) what changed in CLI/UDS/MCP; (2) backwards compatibility; (3) privilege-escalation defense; (4) what stays root-only.
• Mentions mailbox_create and mailbox_delete MCP tools by name.
• "What stays root-only" list is complete and accurate (setup, serve, uninstall, dkim-keygen, portcheck, cross-uid creates, catchall, raw-shell hooks).

[S3-5] CLAUDE.md updates + format_auth_error consolidation

• mailbox_handler.rs line correctly describes the owner-bound model with Action::MailboxCreate { owner_uid } / Action::MailboxDelete { mailbox } and SO_PEERCRED-based owner synthesis.
• mailbox.rs line updated: both root and non-root prefer UDS; non-root cannot fall back when the daemon is down; root keeps the direct-write fallback.
• mcp.rs tool count: grep -c '#\[tool(name' src/mcp.rs returns 12, matching CLAUDE.md.
• AIMX_TEST_SKIP_ROOT_CHECK rewritten — confirmed it no longer claims to be read by src/mailbox.rs (none of the active mailbox.rs code reads it; only src/hooks.rs does, lines 162 and 297).
• format_auth_error consolidation: src/auth.rs defines a single canonical format_auth_error(err, ctx) renderer with an AuthErrorContext struct carrying optional surface / verb / resource / mailbox_name hints. The three previous duplicates all delegate to it correctly. Eight new unit tests cover every variant × context combination and all pass.

[S3-6] Final pass + soak

• cargo fmt clean (verified independently).
• cargo clippy --all-targets -D warnings clean (verified independently).
• cargo test for auth::tests::format_auth_error* — 8/8 pass.
• Implementer reports 1029 + 97 + 1 + 21 unit/integration green on root crate, 43 on verifier; sudo-lane 21/21 + 5/5; aimx doctor clean; dogfood pass.
• [~] grep -rn "MailboxCrud\|enforce_root.*MAILBOX" src/ services/: the strict reading of this AC fails. The grep matches ~70 occurrences across 6 files (MailboxCrudRequest, Request::MailboxCrud, MailboxCrudFallback). I evaluated whether these are in scope and concluded they're not — see "Alignment with PRD" below for the call.

Test Coverage

The new auth::tests::format_auth_error_* battery (8 tests) covers every arm of the four-arm match × every context shape any call site uses, and explicitly asserts the uid does not leak into OwnerMismatch rendering (NFR2). Test coverage for the consolidation work is solid.

The mailbox.rs::tests four tests now exercise the canonical renderer through a mailbox_ctx helper, so any wording drift from the canonical surface would surface as a test failure. This is the right pattern.

hooks.rs::tests tests still hit the local format_hook_auth_error shim — the assertions check contains("alice"), contains("sudo"), contains("no such mailbox") which all hold under the new rendering.

mcp.rs::tests was not extended for the consolidation, but the closure refactor preserves output exactly for every reachable arm (verified by reading the diff against the previous match), so this is acceptable — the integration tests for MCP authz already cover the user-visible behavior.

Potential Bugs

None identified. The consolidation refactor preserves existing wording at every reachable call site:

• mailbox.rs (test-only): mailbox_ctx passes surface = "aimx mailboxes", verb, and resource = "mailbox" — produces exactly the same strings as the deleted local renderer.
• hooks.rs: format_hook_auth_error shim passes surface = "aimx hooks", verb, and resource = "resource" — matches the previous output for NotRoot, NotOwner, NoSuchMailbox. The OwnerMismatch arm previously hardcoded "cannot create a resource owned by another user"; the new render reads "cannot {verb} a resource owned by another user". This is a wording shift only when the verb is not "create" (e.g. "delete"), but the variant is unreachable from hooks.rs per the Action::MailboxCreate-only origin in auth.rs. No user-visible regression.
• mcp.rs: the closure passes mailbox_name (when non-empty) and verb = "create" — preserves both the agent-friendly "mailbox '<name>' not found" rendering and the "cannot create a mailbox owned by another user" rendering for the only OwnerMismatch-producing action (MailboxCreate).

One subtle observation worth noting (non-blocker): the MCP renderer hardcodes verb: Some("create") for ALL action types, not just MailboxCreate. This is safe today because AuthError::OwnerMismatch is produced only by the MailboxCreate predicate per the auth.rs doc comment, so the verb is always correct in practice. If a future change adds OwnerMismatch to another predicate, the MCP rendering would say "cannot create a..." for a MailboxDelete action — which would be wrong. Worth a comment or a per-action verb derivation, but not a Sprint 3 blocker.

Security Issues

No new security concerns introduced. The rendering changes do not affect the predicate, the wire-format response shape, or NFR1/NFR2. The intentional NFR2 invariant — intended_owner_uid not interpolated into rendered strings — is preserved and explicitly tested (format_auth_error_owner_mismatch_uses_verb_and_resource asserts !msg.contains("0")).

The doc rewrites do not undermine the SO_PEERCRED-binding invariant — every relevant doc surface (book/security.md, book/mailboxes.md, book/setup.md, book/troubleshooting.md, book/cli.md, agents/common/references/troubleshooting.md) consistently states the daemon ignores client-supplied Owner: from non-root callers. No examples suggest passing --owner as a privilege-escalation path.

Code Quality

The AuthErrorContext design is sound — optional fields with sensible defaults keep the simplest call ergonomic (AuthErrorContext::default()) while letting each surface tune the rendering. The #[derive(Default)] and explicit doc comments on each field are good.

The hooks.rs::format_hook_auth_error thin wrapper is justified — keeping the call sites readable as format_hook_auth_error(&err, "create") rather than constructing a six-line AuthErrorContext literal each time is a real readability win and the wrapper is one-line dispatch with no logic to drift.

The mailbox.rs deletion of the local renderer (it was already #[cfg(test)]-only) is the cleanest illustration of the consolidation — there is now exactly one definition of the four-arm match.

Alignment with PRD

The PRD's R24–R28 documentation requirements are all met. The PRD does not require renaming the wire-protocol type names (MailboxCrudRequest, Request::MailboxCrud, MailboxCrudFallback).

On the S3-6 grep AC interpretation: the AC text reads literally grep -rn "MailboxCrud\|enforce_root.*MAILBOX" src/ services/ returns nothing. The strict reading fails (~70 matches). The lenient reading is that the AC is testing for the intent — no remaining Action::MailboxCrud variant, no remaining enforce_root calls against MAILBOX-* verbs.

I checked both:

• grep -n "MailboxCrud\b" src/auth.rs src/mailbox_handler.rs returns nothing — confirmed Action::MailboxCrud is gone.
• The wire types MailboxCrudRequest / MailboxCrudFallback / Request::MailboxCrud are pre-existing transport-level names that cover both CREATE and DELETE on the wire parser side. They were never the policy variant. Renaming them would be a sweeping mechanical refactor unrelated to the user-mailbox initiative.

I'm calling this a non-blocker with a recommendation: either rename the wire types in a follow-up cleanup PR (book the work in a future sprint) or amend the AC text in the sprint plan to match the spirit (grep -rn "Action::MailboxCrud\|enforce_root.*MAILBOX-" src/ services/). The implementer made the right call documenting the trade-off in "Deferred Items."

The uds_authz.rs::enforce_root_logs_reject test verb relabel from "MAILBOX-CREATE" to "DEMO-VERB" is a clean way to make the spot-check meaningful without removing the test — the test still verifies the same logging shape, and the relabel makes clear that enforce_root no longer has any production mailbox-lifecycle caller.

Summary and Recommended Actions

Overall verdict: Ready to merge

Sprint 3 is the docs + cleanup sprint and it landed cleanly. Every required doc rewrite is in place and accurate, the release-notes entry is complete and operator-actionable, the CLAUDE.md updates correctly reflect current code (verified line-by-line), and the format_auth_error consolidation is a real cleanup with eight new tests pinning every arm × context combination. Quality gates (fmt, clippy, the new auth tests) are green when re-run.

The one residual MailboxCrud grep noise is a reasonable Sprint-3 scope call — the matches are pre-existing wire type names, not authz-model leftovers.

Blockers: none.

Non-blockers:

• Wire-type names MailboxCrudRequest / Request::MailboxCrud / MailboxCrudFallback could be renamed in a follow-up cleanup PR to make the S3-6 spot-check pass strictly. Either rename or amend the AC text.
• MCP renderer hardcodes verb: Some("create") for all actions; safe today because OwnerMismatch only fires from MailboxCreate, but worth a comment or a per-action verb derivation if the predicate ever evolves.

Nice-to-haves:

• Future PR could standardize the wording across surfaces so the AuthErrorContext permutations collapse to fewer call-site variations.

[Sprint 3] User-mailbox docs + release: rewrite book/ to reflect owner-gated mailbox CRUD, add release-notes entry, consolidate format_auth_error into src/auth.rs

Rewrites every book/ chapter that claimed mailbox CRUD requires root (security.md, mailboxes.md, setup.md, troubleshooting.md, mcp.md, cli.md, hooks.md, agents/common/references/troubleshooting.md) to match the owner-gated model shipped in Sprints 1–2. Adds an "Unreleased — Mailbox create/delete no longer requires root" entry to release-notes.md covering CLI/UDS/MCP changes, the SO_PEERCRED privilege-escalation defense, what stays root-only, and upgrade compatibility. Updates CLAUDE.md (mailbox.rs / mailbox_handler.rs descriptions, mcp.rs tool count 9 -> 12, AIMX_TEST_SKIP_ROOT_CHECK note). Consolidates the three previous format_auth_error duplicates (mailbox.rs test-only, hooks.rs, mcp.rs) into a single canonical renderer in src/auth.rs with an AuthErrorContext struct + 8 new unit tests covering every variant × context combination.