style(comments): strip obvious comments and label WHY/TODO/HACK across the rest of runtime

Second wave over 42 comment-dense runtime files (AgentMemory, World, Lua-CSharp mods, benchmarking,
composition, hub): remove restate-the-code comments and banners, tag genuine rationale with a
WHY:/TODO:/HACK: prefix (first line of each block); strip stray UTF-8 BOMs. Comment-only, code
verified unchanged, compiles clean. Bulk pass by gpt-5.3-spark agents, de-duplicated + reviewed.

Author: NeoXider

Assets/CoreAI/Runtime/Core/Features/AgentMemory/AgentBuilder.cs

@@ -1,4 +1,4 @@
-using System;
+using System;
 using System.Collections.Generic;
 using CoreAI.AgentMemory;
 using CoreAI.Logging;
@@ -44,7 +44,7 @@ public sealed class AgentBuilder
 
         private AgentMode _mode = AgentMode.ToolsAndChat;
 
-        // Default chat history keeps agent continuity; callers can opt out to save prompt tokens.
+        // WHY: Default chat history keeps agent continuity; callers can opt out to save prompt tokens.
         private bool _withChatHistory = true;
         private int? _contextWindowTokens;
         private bool _persistChatHistory;
@@ -62,7 +62,7 @@ public sealed class AgentBuilder
         /// <summary>Null = default true (LLM-assisted compaction when global setting allows).</summary>
         private bool? _useLlmContextCompaction;
 
-        // Skill authoring (manage_skills): when set, the agent can create/update/persist/reuse its own skills.
+        // WHY: Skill authoring (manage_skills): when set, the agent can create/update/persist/reuse its own skills.
         private ISkillStore _skillStore;
         private ILuaScriptVersionStore _skillVersionStore;
         private bool _skillAuthoring;
@@ -179,7 +179,7 @@ public AgentBuilder WithSkill(SkillSet skill)
                 throw new ArgumentNullException(nameof(skill));
             }
 
-            // Skill tools are routed through call_skill_tool to keep the prompt surface small.
+            // WHY: Skill tools are routed through call_skill_tool to keep the prompt surface small.
             _skills.Add(skill);
 
             return this;
@@ -483,7 +483,7 @@ public AgentConfig BuildDetached()
             int ctxTokens = _contextWindowTokens ??
                             _settings?.ContextWindowTokens ?? CoreAISettings.ContextWindowTokens;
 
-            // final composition time (three-layer architecture):
+            // WHY: final composition time (three-layer architecture):
             //   Layer 1: universalSystemPromptPrefix (project-wide rules)
             //   Layer 2: role base prompt from Manifest / Resources (.txt files)
             //   Layer 3: extra prompt from this builder (the one above)
@@ -600,7 +600,7 @@ private void CollectIssues(List<AgentBuilderIssue> issues)
 
             if (_mode == AgentMode.ToolsOnly && _tools.Count == 0)
             {
-                // Already reported by the rule above; no extra issue here.
+                // WHY: Already reported by the rule above; no extra issue here.
             }
 
             if (_useLlmContextCompaction == true)
@@ -734,7 +734,7 @@ public void ApplyToPolicy(AgentMemoryPolicy policy)
 
             policy.SetStreamingEnabled(RoleId, streamingOverride);
 
-            // Self-service skills: register catalog context provider + meta-tools.
+            // WHY: Self-service skills: register catalog context provider + meta-tools.
             // The catalog (name + description per skill) goes into the system prompt.
             // The model calls read_skill(name) to load instructions + tool schemas,
             // then call_skill_tool(tool_name, args_json) to execute them.
@@ -743,7 +743,7 @@ public void ApplyToPolicy(AgentMemoryPolicy policy)
             bool hasSkills = Skills != null && Skills.Count > 0;
             if (hasSkills || SkillAuthoringEnabled)
             {
-                // When the agent can author skills, the read_skill / call_skill_tool proxies read from a
+                // WHY: When the agent can author skills, the read_skill / call_skill_tool proxies read from a
                 // LIVE catalog so a skill created via manage_skills is immediately visible to the same
                 // agent. Without authoring, the static snapshot is used (cacheable, unchanged behavior).
                 IReadOnlyList<SkillSet> catalogSkills = Skills ?? (IReadOnlyList<SkillSet>)Array.Empty<SkillSet>();
@@ -755,7 +755,7 @@ public void ApplyToPolicy(AgentMemoryPolicy policy)
                     catalogSkills = liveCatalog;
                 }
 
-                // Inject the lightweight catalog into the stable system prefix. Skill catalog data is static
+                // WHY: Inject the lightweight catalog into the stable system prefix. Skill catalog data is static
                 // per agent build (host skills), unlike live world-state context, so it stays cacheable.
                 string catalog = SkillSet.BuildCatalog(Skills);
                 if (!string.IsNullOrWhiteSpace(catalog))
@@ -765,10 +765,10 @@ public void ApplyToPolicy(AgentMemoryPolicy policy)
                         : additionalPrompt.TrimEnd() + "\n\n" + catalog.Trim();
                 }
 
-                // Register read_skill meta-tool (loads instructions + tool schemas)
+                // WHY: Register read_skill meta-tool (loads instructions + tool schemas)
                 policy.AddToolForRole(RoleId, ReadSkillLlmTool.Create(catalogSkills));
 
-                // Register call_skill_tool proxy (routes to real skill tools)
+                // WHY: Register call_skill_tool proxy (routes to real skill tools)
                 policy.AddToolForRole(RoleId, CallSkillToolLlmTool.Create(catalogSkills));
             }
 
@@ -787,7 +787,7 @@ public void ApplyToPolicy(AgentMemoryPolicy policy)
         /// </summary>
         private void RehydrateAndRegisterAuthoring(AgentMemoryPolicy policy, MutableSkillCatalog liveCatalog)
         {
-            // Index every tool the role already has, by name, so an authored skill can reference it.
+            // WHY: Index every tool the role already has, by name, so an authored skill can reference it.
             Dictionary<string, ILlmTool> toolsByName = new(StringComparer.OrdinalIgnoreCase);
             foreach (ILlmTool tool in Tools)
             {
@@ -826,10 +826,10 @@ private void RehydrateAndRegisterAuthoring(AgentMemoryPolicy policy, MutableSkil
                 resolver,
                 RequireKnownSkillTools);
 
-            // Rehydrate persisted skills so prior-session skills reappear in this agent's read_skill catalog.
+            // WHY: Rehydrate persisted skills so prior-session skills reappear in this agent's read_skill catalog.
             coordinator.RehydrateFromStore();
 
-            // One extra visible tool (progressive disclosure: skill bodies still load on demand).
+            // WHY: One extra visible tool (progressive disclosure: skill bodies still load on demand).
             policy.AddToolForRole(RoleId, new ManageSkillsLlmTool(coordinator));
         }
 

Assets/CoreAI/Runtime/Core/Features/AgentMemory/AgentConfigExtensions.cs

@@ -1,4 +1,4 @@
-using System;
+using System;
 using System.Threading;
 using System.Threading.Tasks;
 using CoreAI.Logging;
@@ -40,7 +40,7 @@ public static Task<string> AskAsync(
             int priority = 0,
             CancellationToken cancellationToken = default)
         {
-            // Make sure the role is known to the global policy before we run. For the common newcomer
+            // WHY: Make sure the role is known to the global policy before we run. For the common newcomer
             // flow this AUTO-REGISTERS the built config, so `Build()` + `Ask*()` just works without an
             // explicit `ApplyToPolicy(CoreAIAgent.Policy)` call. Done before the orchestrator null-check
             // so a missing lifetime scope still surfaces its own clear message.
@@ -77,7 +77,7 @@ private static void EnsureRoleRegistered(AgentConfig config)
                     "(add CoreAILifetimeScope to the scene / run CoreAI setup) before asking an agent.");
             }
 
-            // Convenience: register the built config with the global policy on first use, so newcomers
+            // WHY: Convenience: register the built config with the global policy on first use, so newcomers
             // do not have to call ApplyToPolicy(CoreAIAgent.Policy) by hand. Re-applying is idempotent;
             // advanced users targeting a CUSTOM AgentMemoryPolicy still call ApplyToPolicy on that policy
             // themselves (and, once registered here, this no-ops).
@@ -108,7 +108,7 @@ public static void AskWithCallback(
             Action<string> onDone = null,
             int priority = 0)
         {
-            // Capture the caller's synchronization context (Unity main thread when called from it)
+            // WHY: Capture the caller's synchronization context (Unity main thread when called from it)
             // so onDone is safe to use with Unity APIs; without it the continuation after
             // ConfigureAwait(false) may land on a thread-pool thread.
             _ = RunAskFireAndForgetAsync(config, message, onDone, priority, SynchronizationContext.Current);

Assets/CoreAI/Runtime/Core/Features/AgentMemory/AgentMemoryPolicy.cs

@@ -1,4 +1,4 @@
-using System;
+using System;
 using System.Collections.Generic;
 using CoreAI.AgentMemory;
 
@@ -10,8 +10,6 @@ namespace CoreAI.Ai
     /// </summary>
     public sealed class AgentMemoryPolicy
     {
-        // ARCH-4 fix: lock protects all dictionary/set read-write operations
-        // against concurrent access from different coroutines/async continuations.
         private readonly object _lock = new();
         private readonly Dictionary<string, RoleMemoryConfig> _roleConfigs;
         private readonly Dictionary<string, List<ILlmTool>> _customTools = new();
@@ -279,7 +277,7 @@ public AgentMemoryPolicy()
                 bool isProgrammer = roleId == BuiltInAgentRoleIds.Programmer;
                 bool needsExactToolOutput = isProgrammer || roleId == BuiltInAgentRoleIds.CoreMechanic;
                 bool smartCompaction = !isProgrammer;
-                // Programmer keeps history off by default; chat-source runs enable it per-run
+                // WHY: Programmer keeps history off by default; chat-source runs enable it per-run
                 // without mutating global policy (see AiOrchestratorHistoryEditModeTests).
                 // Code/mechanics agents need exact tool output across turns for iterative correctness.
                 RoleMemoryConfig builtIn = new(
@@ -291,7 +289,7 @@ public AgentMemoryPolicy()
                         : ToolResultMemoryPolicy.CompactSummary,
                     useLlmContextCompaction: smartCompaction);
 
-                // The Programmer writes/iterates Lua and routinely needs many tool roundtrips in one turn
+                // WHY: The Programmer writes/iterates Lua and routinely needs many tool roundtrips in one turn
                 // (generate → run → read error → fix → re-run …), and the Creator orchestrates a whole
                 // build across many tool calls. Cap both at 0 = unlimited so they are never cut off
                 // mid-task. Other built-in roles inherit the global default (null = 20).
@@ -303,7 +301,7 @@ public AgentMemoryPolicy()
                 _roleConfigs[roleId] = builtIn;
             }
 
-            // Built-in chat roles:
+            // WHY: Built-in chat roles:
             // - PlainChat: no MemoryTool by default, persistent chat history only.
             // - SmartChat: MemoryTool + persistent chat history by default.
             _roleConfigs[BuiltInAgentRoleIds.PlainChat] = new RoleMemoryConfig(
@@ -652,10 +650,8 @@ private static bool ListContainsMemoryTool(List<ILlmTool> list)
 
         private readonly Dictionary<string, string> _additionalSystemPrompts = new();
 
-        // ===== Override Universal Prefix (per-role) =====
         private readonly HashSet<string> _overrideUniversalPrefix = new();
 
-        // ===== Streaming override (per-role) =====
         private readonly Dictionary<string, bool> _streamingOverrides = new();
 
         /// <summary>
@@ -741,8 +737,6 @@ public bool IsUniversalPrefixOverridden(string roleId)
             }
         }
 
-        // ===== Streaming (per-role override) =====
-
         /// <summary>
         /// Applies a per-role streaming override; <c>null</c> clears the override and uses
         /// <see cref="ICoreAISettings.EnableStreaming"/>.

Assets/CoreAI/Runtime/Core/Features/AgentMemory/Context/BpeEncoder.cs

@@ -19,7 +19,7 @@ namespace CoreAI.Ai
     /// </remarks>
     public sealed class BpeEncoder
     {
-        // tiktoken pre-tokenization regexes. cl100k_base and o200k_base use different patterns.
+        // WHY: tiktoken pre-tokenization regexes. cl100k_base and o200k_base use different patterns.
         // These are the canonical patterns; .NET regex supports the needed constructs.
         private const string Cl100kPattern =
             @"(?i:'s|'t|'re|'ve|'m|'ll|'d)|[^\r\n\p{L}\p{N}]?\p{L}+|\p{N}{1,3}| ?[^\s\p{L}\p{N}]+[\r\n]*|\s*[\r\n]+|\s+(?!\S)|\s+";
@@ -68,7 +68,7 @@ public static BpeEncoder TryLoad(
             }
             catch
             {
-                // Corrupt/partial data: signal fallback rather than producing wrong counts.
+                // WHY: Corrupt/partial data: signal fallback rather than producing wrong counts.
                 return null;
             }
 
@@ -84,7 +84,7 @@ public static BpeEncoder TryLoad(
             }
             catch
             {
-                // RegexOptions.Compiled is unsupported on some AOT/WebGL targets: retry interpreted.
+                // WHY: RegexOptions.Compiled is unsupported on some AOT/WebGL targets: retry interpreted.
                 try
                 {
                     pattern = new Regex(patternText, RegexOptions.CultureInvariant);
@@ -128,7 +128,7 @@ public int CountTokens(string text)
             int total = 0;
             int cursor = 0;
 
-            // Walk the string, peeling off special tokens as single tokens and BPE-encoding the gaps.
+            // WHY: Walk the string, peeling off special tokens as single tokens and BPE-encoding the gaps.
             while (cursor < text.Length)
             {
                 int nextSpecial = -1;
@@ -192,13 +192,13 @@ private int CountPiece(byte[] piece)
                 return 0;
             }
 
-            // A single byte is always a known token in byte-level BPE.
+            // WHY: A single byte is always a known token in byte-level BPE.
             if (n == 1)
             {
                 return 1;
             }
 
-            // Segment boundaries: parts[i] is the start index of segment i; there are (count) segments
+            // WHY: Segment boundaries: parts[i] is the start index of segment i; there are (count) segments
             // covering [parts[i], parts[i+1]). Initialize to one byte per segment.
             List<int> starts = new(n + 1);
             for (int i = 0; i <= n; i++)
@@ -226,11 +226,11 @@ private int CountPiece(byte[] piece)
                     break; // no further merges possible
                 }
 
-                // Merge segments bestIdx and bestIdx+1 by removing the boundary between them.
+                // WHY: Merge segments bestIdx and bestIdx+1 by removing the boundary between them.
                 starts.RemoveAt(bestIdx + 1);
             }
 
-            // Number of segments = starts.Count - 1.
+            // WHY: Number of segments = starts.Count - 1.
             return starts.Count - 1;
         }
 
@@ -352,7 +352,7 @@ public byte At(int i)
 
             public int ComputeHash()
             {
-                // FNV-1a over the slice contents.
+                // WHY: FNV-1a over the slice contents.
                 unchecked
                 {
                     const int prime = 16777619;

Assets/CoreAI/Runtime/Core/Features/AgentMemory/Context/CalibratingTokenEstimator.cs

@@ -77,15 +77,15 @@ public void RecordObservation(int estimatedPromptTokens, int realPromptTokens)
             double updatedScale;
             lock (_lock)
             {
-                // The observed estimate was produced as baseEstimate * _scale. Convert the
+                // WHY: The observed estimate was produced as baseEstimate * _scale. Convert the
                 // real/estimated ratio back into scale units so repeated observations converge
                 // toward real/baseEstimate, not sqrt(real/baseEstimate).
                 double targetScale = _scale * realPromptTokens / estimatedPromptTokens;
                 _scale = Clamp(_scale * (1d - Alpha) + targetScale * Alpha, MinScale, MaxScale);
                 updatedScale = _scale;
             }
 
-            // Persist outside the lock so a blocking disk write in the store does not stall concurrent
+            // WHY: Persist outside the lock so a blocking disk write in the store does not stall concurrent
             // EstimateText/CurrentScale calls (which also take _lock). The in-memory scale is already
             // updated; the store write does not need the estimator lock.
             _store.SaveScale(_modelKey, updatedScale);

Assets/CoreAI/Runtime/Core/Features/AgentMemory/ConversationHistoryPruner.cs

@@ -167,7 +167,7 @@ private static string StripThinkBlocks(string content)
                 int open = content.IndexOf(ThinkOpenTag, i, StringComparison.OrdinalIgnoreCase);
                 int close = content.IndexOf(ThinkCloseTag, i, StringComparison.OrdinalIgnoreCase);
 
-                // Orphan close before any open: treat the leading text as hidden reasoning and drop it.
+                // WHY: Orphan close before any open: treat the leading text as hidden reasoning and drop it.
                 if (close >= 0 && (open < 0 || close < open))
                 {
                     i = close + ThinkCloseTag.Length;
@@ -189,7 +189,7 @@ private static string StripThinkBlocks(string content)
                 int matchingClose = content.IndexOf(ThinkCloseTag, afterOpen, StringComparison.OrdinalIgnoreCase);
                 if (matchingClose < 0)
                 {
-                    // Unterminated reasoning block: drop everything to the end.
+                    // WHY: Unterminated reasoning block: drop everything to the end.
                     break;
                 }
 
@@ -295,7 +295,7 @@ private static List<string> ExtractToolNames(string content)
             {
                 string line = lines[i];
 
-                // Entry bullets are at column 0. Any leading whitespace means this is nested Detail content
+                // WHY: Entry bullets are at column 0. Any leading whitespace means this is nested Detail content
                 // (Full policy indents it by two spaces), never a tool-name entry — skip it.
                 if (line.Length < 2 || line[0] != '-' || line[1] != ' ')
                 {
@@ -309,7 +309,7 @@ private static List<string> ExtractToolNames(string content)
                     continue;
                 }
 
-                // The value after "name:" must begin with a status token; otherwise this "- x: y" line is
+                // WHY: The value after "name:" must begin with a status token; otherwise this "- x: y" line is
                 // arbitrary content that merely resembles an entry, not a real tool result.
                 if (!ValueStartsWithStatus(line, colon + 1))
                 {