Correct three clan comments that describe code that does not exist

ClanCapabilityProvider's CacheTtl doc justified its value with "the heal path
reconciles every server on a timer". WorkspaceHostedService heals at startup
and on ChannelDestroyed only; there is no timer. Say what actually bounds the
staleness: reconciles are event-driven and Invalidate, not expiry, is what
guarantees a transition is seen.

ClanMessageKeyParityTests claimed Features.Clans cannot see the internal
WorkspaceMessageKeys. It can — Features.Workspace grants it InternalsVisibleTo.
The constants are independent by choice, which is what makes the assertion
meaningful.

ClanMotdWriter claimed to re-check the permission because roles can change
between render and click. It reads the same cached snapshot the button was
rendered from, so a demotion the poller has not observed yet still gets
through. Describe what it does defend against: a forged component id and a
button clicked from scrollback.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: HandyS11

src/RustPlusBot.Features.Clans/State/ClanCapabilityProvider.cs

@@ -17,9 +17,11 @@ internal sealed class ClanCapabilityProvider(IServiceScopeFactory scopeFactory,
     : IWorkspaceCapabilityProvider
 {
     /// <summary>
-    /// How long an answer is reused. Two gated specs mean two probes per server per reconcile, and
-    /// the heal path reconciles every server on a timer; this is kept well under the reconcile
-    /// interval so a clan transition is still picked up promptly.
+    /// How long an answer is reused. Two gated specs mean two probes per server per reconcile, so a
+    /// short reuse window collapses them into one store read. It stays short because reconciles are
+    /// event-driven (startup, channel deletion, server registration, clan transition) rather than
+    /// timed: a cached answer must never outlive the transition that prompted the reconcile, and
+    /// <see cref="Invalidate"/> — not expiry — is what guarantees a transition is seen.
     /// </summary>
     private static readonly TimeSpan CacheTtl = TimeSpan.FromSeconds(5);
 

src/RustPlusBot.Features.Clans/Writing/ClanMotdWriter.cs

@@ -6,7 +6,10 @@ namespace RustPlusBot.Features.Clans.Writing;
 /// <summary>
 /// Applies a clan MOTD change, enforcing the acting player's clan permission before touching the
 /// socket. The permission check is duplicated here rather than trusted from the button's presence:
-/// component payloads can be forged, and roles can change between render and click.
+/// a component id can be forged, and a button rendered before a demotion can still be clicked from
+/// scrollback afterwards. It is not a fresh authority check — it reads the same cached clan
+/// snapshot the button was rendered from, so a demotion the poller has not yet observed still gets
+/// through; the game's own API is the last word there.
 /// </summary>
 /// <param name="store">Supplies the stored clan snapshot for the permission check.</param>
 /// <param name="query">Performs the write on the live socket.</param>

tests/RustPlusBot.Features.Workspace.Tests/Messages/ClanMessageKeyParityTests.cs

@@ -3,10 +3,12 @@
 namespace RustPlusBot.Features.Workspace.Tests.Messages;
 
 /// <summary>
-///     Pins that the clan renderers' key literals (declared in Features.Clans, which cannot see
-///     Features.Workspace's internal <see cref="WorkspaceMessageKeys" />) still match the keys the
-///     reconciler looks renderers up by. The reconciler compares with <c>StringComparer.Ordinal</c>,
-///     so a silent rename on either side would unhook a renderer without any other test catching it.
+///     Pins that the clan renderers' key literals still match the keys the reconciler looks renderers
+///     up by. Features.Clans can see Features.Workspace's internal <see cref="WorkspaceMessageKeys" />
+///     (it is granted <c>InternalsVisibleTo</c>) but deliberately declares its own public constants
+///     instead, so the two sides are independent literals. The reconciler compares them with
+///     <c>StringComparer.Ordinal</c>, so a silent rename on either side would unhook a renderer
+///     without any other test catching it.
 /// </summary>
 public sealed class ClanMessageKeyParityTests
 {