Reviewed exact role retirement

Role retirement has no immediate-call path and is independent of role reads, creation, configuration, assignment, ordering, scaffolds, permission overwrites, integrations, invites, onboarding, AutoMod, and command administration. Set capabilities.roleDeletionAudit: true, list each eligible exact role in scopes.roleDeletionIds, include role-deletion in tools.toolsets when selecting toolsets, enable gateway.enabled, and include every possible target guild in readScope.guildIds. Add guild-blueprints only when using the optional prepare_guild_recovery prompt and satisfy the blueprint capture audit prerequisites documented below. Set capabilities.roleDeletions: true only when execution is intended.

Audit requires pinned application and bot identities plus complete guild-level MANAGE_ROLES and MANAGE_GUILD evidence. Only an exact standard unmanaged role with zero holders and a position strictly below the connector's highest role can become ready. @everyone, integration-managed roles, subscription roles, bot roles, roles held by any member, absent roles, targets at or above the connector, incomplete permission evidence, unknown role or permission semantics, and every discovered dependency are blockers. The audit gate permits audit_role_deletion and discord://guilds/{guildId}/roles/{roleId}/deletion-readiness; it does not grant execution.

One continuity-stable evidence pass combines a complete unobfuscated Gateway layout with exact guild, connector membership, full normalized role inventory, aggregate role-holder counts, channel role overwrites, invite role grants, guild-emoji role restrictions, onboarding role options when Community is enabled, AutoMod exempt roles when AutoMod is enabled, integration-owned roles, and permission overrides for this application's guild commands. Dependency identifiers stay inside the private evidence digest; readiness and plans expose only typed blocker kinds and aggregate counts. Discord names are transient untrusted review data and are never persisted.

Discord does not expose a complete bounded search for historical role mentions, so deletion can leave non-clickable historical mentions. Guild Template snapshots are not enumerable at role-reference granularity. The application-command permission endpoint covers this application, not command permissions owned by other applications. These are explicit operator review obligations rather than guessed-safe conditions. The connector never fetches messages or template snapshots to estimate them.

1. Optionally invoke prepare_guild_recovery with the exact guild and role IDs, then retain the complete returned blueprint and matching unexpired role attestation. This prompt performs no plan or write and never selects the no-artifact alternative.
2. Read the deletion-readiness resource or call audit_role_deletion with the exact guild and role IDs.
3. Call plan_role_deletion with the same IDs, literal acknowledgeIrreversibleRoleLoss: true, one bounded Discord audit-log reason, one unique operation key, and either the exact matching attestation plus caller-retention acknowledgement or the explicit no-artifact acknowledgement.
4. Review the exact target, aggregate holder count, hierarchy and permission evidence, dependency kinds and counts, layout completeness, credential-free recovery mode, capture fingerprint, target projection digest, timestamps, omissions and limitations, privacy boundary, risks, warnings, operation-key hash, and keyed digest. The plan never echoes the attestation.
5. If the plan is blocked, remove intentional dependencies through an appropriate separately reviewed workflow or Discord administration path and create a fresh plan; deletion performs no confirmation, reservation, activity write, cleanup, or Discord mutation for that result.
6. Call execute_role_deletion with identical input plus the digest, then approve the signed MCP confirmation only if the exact target, irreversible and recovery acknowledgements, credential-free recovery evidence and limitations, reason, dependency and permission evidence, blind spots, risks, warnings, operation-key hash, and digest remain intended.
7. Review the fresh target-absence result, complete surviving-role and dependency preservation verdict, any additive drift, activity ID, verification, and outcome before any follow-up.

The process-keyed plan digest binds the normalized request without the raw operation key or attestation, its domain-separated operation-key hash and attestation hash where present, verified credential-free recovery projection, verified application and bot identities, exact guild and owner, connector membership, complete role inventory and order, aggregate holder counts, target, permission and hierarchy evidence, complete normalized dependency inventory, coherent Gateway and HTTP layout evidence, audit reason, irreversible and recovery acknowledgements, privacy boundary, risks, and warnings. A connector restart invalidates both the digest and every recovery attestation. The MCP adapter rebuilds the plan before confirmation, the production facade rebuilds it before durable coordination, and the service rebuilds it before reservation. Every digest must match exactly.

A real retirement durably claims the exact role plus the guild role, channel, invite, emoji, onboarding, AutoMod, integration, and application-command collections, atomically reserves the one-shot key, and appends pending content-free activity before sending one non-retried exact-ID DELETE with the encoded audit reason. Fresh complete evidence must prove the target absent, every baseline role survivor semantically unchanged and in the same relative order, every survivor holder count unchanged, and every baseline dependency entry preserved. Newly added roles or dependency entries return completed-with-drift; a missing or changed survivor, remaining target, malformed response, or unreadable evidence never counts as success.

A known non-rate-limited Discord client refusal before acceptance can settle as failed. Rate limiting, transport ambiguity, server failure, target-presence readback, evidence contradiction, or any failure after the mutation may have begun is uncertain. Direct service instances quarantine later same-guild role deletion after uncertainty. The production facade's durable claims also exclude overlapping evidence-changing workflows across connector processes sharing the activity-state root and remain for operator review after ambiguity. There is no automatic retry, dependency cleanup, rollback, role recreation, or inference from a later 404.

Activity and operation records contain only exact guild and role IDs, aggregate baseline and observed role counts, target holder and blocker counts, plan and operation-key digests, timestamps, fixed verification and outcome values, activity ID, and sanitized error category. They never contain role or guild names, permissions, dependency identifiers, channel layout, recovery attestations or blueprint content, audit reasons, raw operation keys, or Discord payloads. See Discord's delete guild role contract, role member-count contract, and application-command permission contract.

Canonical source: docs/reference.md