Reviewed exact relative role ordering

Role-order audit and changes are independent of ordinary role reads, creation, configuration, assignment, scaffolds, and channel overwrites. Set capabilities.roleOrderingAudit: true and list each eligible guild in scopes.roleOrderingGuildIds to enable audit_role_order and discord://guilds/{guildId}/role-order. The guild allowlist must remain inside the configured read-guild boundary. Enabling changes additionally requires capabilities.roleOrderingChanges: true. Grant Manage Roles only in selected guilds, keep the connector's highest role above every possible target, anchor, and affected role, and do not grant Administrator.

The audit returns the complete canonical hierarchy from low to high, using raw position followed by descending snowflake ID when Discord reports tied positions. Each entry includes exact ID, transient untrusted name, canonical rank, raw position, managed-role provenance, connector ownership, mentionability, known permissions, unknown permission bits, unknown-field count, and aggregate holder count. The result also includes verified application, bot, guild, owner, complete connector permission, and highest-role evidence. Member identities are never fetched, and audit results are not cached, journaled, exported, or persisted.

The change surface accepts exactly one target role ID, one distinct anchor role ID, above or below, a Discord audit-log reason, and a unique one-shot operation key. It expresses only immediate relative placement. Arbitrary numeric positions, names as targets, bulk arrays, metadata changes, permission changes, membership changes, creation, deletion, retry, rollback, and reconciliation are unavailable.

1. Call plan_role_order with the exact guild, target role, anchor role, placement, audit reason, and one-shot operation key.
2. Review the verified application, bot, guild, target, anchor, current and desired ranks, complete affected segment, aggregate holder assignments, hierarchy-sensitive permission role IDs, connector authority, privacy boundary, risks, warnings, operation-key hash, and keyed digest.
3. If the status is already-current, no confirmation, coordination claim, receipt, activity entry, or write is needed.
4. Call execute_role_order with identical inputs plus the digest.
5. Approve the signed MCP confirmation only if every exact ID, relative placement, rank, affected role, holder impact, hierarchy-sensitive permission, authority fact, reason, risk, warning, operation-key hash, and digest remains intended.
6. Review the complete response match, full fresh hierarchy, aggregate holder-count match, activity ID, verification, and outcome before any follow-up.

Planning fetches the exact guild, connector member, complete role inventory, and complete role-holder-count map in one evidence pass. It rejects @everyone, an absent, managed, or connector-held target or anchor, missing MANAGE_ROLES, a target or anchor at or above the connector, any unsafe role crossed by the affected segment, and any unknown top-level role field anywhere in the inventory for a real change. Unknown permission bits are preserved and surfaced because ordering does not rewrite permissions. The plan highlights permissions whose authority depends on hierarchy and reports aggregate holder assignments with an explicit warning that one member may hold several affected roles. Ordinary permission aggregation and channel-overwrite order do not follow role position, but moderation authority and hoisted member-list presentation can change.

The process-keyed digest binds the normalized request without the raw operation key, its domain-separated hash, verified identities, exact guild and owner, connector membership and permission evidence, complete normalized hierarchy, complete holder-count map, target, anchor, current and desired order, impact, risks, and warnings. A connector restart invalidates the digest. The MCP adapter rebuilds the plan before confirmation, and the service rebuilds it immediately before reservation. Both require the exact same digest.

A real change reserves the one-shot key, appends a pending content-free activity record, and sends one non-retried PATCH containing only the target role ID and its reviewed destination rank plus the encoded audit reason. The connector validates Discord's complete returned role inventory, then fetches the complete hierarchy and holder counts again. Exact order and unchanged non-position metadata must match. Aggregate holder-count drift alone returns completed-with-drift; malformed, missing, reordered, metadata-drifted, or unreadable response or readback evidence is uncertain and may represent a completed write. A known pre-response Discord 4xx can settle as failed. The connector never retries, compensates, or rolls back.

Activity and operation records contain only the exact guild, target, and anchor role IDs, relative placement, plan digest, operation-key hash, timestamps, fixed verification and outcome values, activity ID, and sanitized error category. They never contain role names, permission evidence, ranks, holder counts or identities, audit reasons, raw operation keys, or raw Discord responses. Direct service instances serialize the whole guild role hierarchy and permanently quarantine that process-local guild after uncertainty. The production facade additionally acquires durable guild roles-collection, target-role, and anchor-role claims, so connector processes sharing the activity-state root exclude every overlapping role workflow and retain the claims after uncertainty. See Discord's modify guild role positions reference and role member-count reference.

Canonical source: docs/reference.md