# Cerebro

## [v0.10.21](https://github.com/Shezzannn/Cerebro/tree/v0.10.21) (2026-03-12)
[Full Changelog](https://github.com/Shezzannn/Cerebro/compare/v0.10.20...v0.10.21) 

- chore: Bump version to 0.10.21  
    Fix permanent sync divergence from ghost Pending records and eliminate thundering herd during raid sync (Options A/B/E).  
- Merge pull request #25 from Shezzannn/fix/sync-communication-overhaul  
    fix(sync): Communication overhaul (B+E+A) — eliminate thundering herd  
- Merge branch 'main' into fix/sync-communication-overhaul  
- Merge pull request #23 from Shezzannn/fix/sync-hash-participant-exclusion  
- fix(sync): PR2 — Communication overhaul (Options B+E+A) to fix thundering herd  
    Problem: 20+ raiders detecting a hash mismatch simultaneously sent STATE\_FETCH  
    at the same instant, causing the officer to queue 20 individual WHISPER  
    snapshots (~110 KB) through the shared 4 KB/s pipe, backing it up ~30s  
    and blocking bids, awards and receipts.  
    Option B — Staggered FETCH jitter:  
    Both SendFetch call sites in HandleHeartbeat's mismatch block (officer→officer  
    and non-officer→officer) now wrap the send in a 0-8s random ScheduleTimer  
    delay. SendFetch's own 30s per-peer cooldown still applies inside the closure.  
    Spreads a 20-raider storm over 8 seconds instead of firing simultaneously.  
    Option A — RAID broadcast replacing per-raider WHISPER push:  
    elseif Cerebro:IsOfficerSafe() officer→raider push path now uses a single  
    RAID/GUILD broadcast (channel = IsInRaid() and "RAID" or "GUILD") with an  
    independent scalar cooldown \_lastRaidBroadcastAt (30s).  
    \_lastSnapshotTo[sender] per-peer table used by officer↔officer WHISPER  
    exchange is completely untouched. HandleFetch response stays WHISPER with  
    per-requester diff preserved (Option A-i decision).  
    Net effect: 22 × 5 KB WHISPERs → 1 × 5 KB broadcast.  
    Option E — Sync Leader gate on HandleFetch:  
    Entry guard added after IsOfficerSafe() check: when IsInRaid() and  
    SyncScheduler:IsSyncLeader() returns false, return immediately. Outside  
    of a raid IsSyncLeader() always returns true → all officers respond normally.  
    Eliminates duplicate responses from multiple officers to the same FETCH.  
    Guards verified unchanged: IsOfficerSafe(), ShouldSync(), epoch check,  
    quarantine block, IsOfficer(sender) receive-side validation, append-only ledger.  
    Officer↔officer WHISPER path (\_lastSnapshotTo table) explicitly untouched.  
- fix(sync): PR1 — Hash participant exclusion to eliminate permanent roster divergence  
    Problem: Ghost Pending records (EP=0, GP=baseGP) created by ANN\_SELF on  
    whichever officer client received the announcement caused permanent hash  
    mismatches between clients. Two officers holding different ghost records  
    could never converge regardless of communication efficiency.  
    Changes:  
    - Utilities.lua: Add Cerebro:IsParticipant(pData, baseGP) helper. A player  
      is a participant if: status=Core OR ep>0 OR gp>baseGP. Non-participants  
      cannot cause hash divergence.  
    - CommunicationV2.lua ComputeRosterHash(): Apply participant filter before  
      building the sorted name list. Non-participants are excluded from the hash  
      but still travel in snapshot payloads for UI display. The #names return  
      value now reflects participant count (used by GetSyncStatus/synccheck).  
    - CommunicationV2.lua MergeRosterData() reconciliation: Add IsParticipant()  
      guard to both raider path and officer path deletion sweeps. Ghost stubs on  
      any client are left in place — they are hash-invisible and cause no harm.  
    Result: Ghost Pending accumulation from ANN\_SELF is no longer a source of  
    permanent 'always red' divergence. Only participants (real EPGP members)  
    drive hash computation and reconciliation deletions.  
    No DB schema changes. Backward compatible: mixed-version clients will show  
    a transient mismatch during rollout that resolves within one heartbeat cycle.  
- docs: add Owner Workflow section to collaborate.md  
    Clarifies when owner/AI agent should branch+PR vs direct push.  
    Addresses CI bypass gap from direct pushes this session.  
    AI agents reading this will branch for non-trivial changes going forward.  
- chore: archive unused GitHub Actions workflows  
    Archive 6 workflows that create noise or reference unimplemented systems:  
    Gemini workflows (gemini-dispatch, invoke, review, triage, scheduled-triage):  
    - Trigger on every PR/issue but fail without GEMINI\_API\_KEY secret configured  
    - 720 cron runs/month (scheduled-triage) for a low-volume repo  
    - Can be restored when external contributor volume warrants it  
    helper-release.yml:  
    - References backend/helper/ directory which does not exist  
    - Go helper app tied to Supabase integration (deferred per PROJECT\_STATE.md)  
    Active CI suite is now exactly 4 purposeful workflows:  
      lint.yml          - Luacheck (Lua correctness gate)  
      validate.yml      - Doc freshness + command parity gate  
      release.yml       - CurseForge distribution  
      pkgmeta-check.yml - Packaging guard (dev file leak prevention)  
- chore: skills/workflow overhaul for vibe coding best practices  
    New workflows:  
    - .agent/workflows/bug-triage.md: symptom→module lookup table + first  
      diagnostic commands; eliminates cold-start reading of 5+ files  
    - .agent/workflows/new-module.md: all 5 required steps for a new Lua  
      module (file, TOC, health check, doc tables, pkgmeta)  
    New CI:  
    - .github/workflows/validate.yml: runs validate\_docs.py + validate\_commands.py  
      on every push/PR — closes the gap where stale module tables could  
      land in main despite passing luacheck  
    Updated workflows:  
    - .agent/workflows/collaborate.md: add validate\_docs.py to pre-push  
      checklist and §6 branch protection table; add validate.yml note  
    - .agent/workflows/deploy-release.md: already updated in previous commit  
    Updated skills:  
    - .agent/skills/cerebro-deploy/SKILL.md: make bump\_version.py --release  
      the single canonical path; mark release.py/upload\_discord.py archived  
    - .agent/skills/cerebro-validation/SKILL.md: add lua interpreter install  
      note for Windows — prevents silent skip of unit tests  
    Updated docs:  
    - docs/AGENT\_CONTEXT.md: add 'Task-Type Entry Points' table mapping  
      intent (bug fix, new module, release, etc.) to starting workflow  
    Archived:  
    - tools/release.py → tools/archive/release.py (replaced by bump\_version --release)  
    - tools/upload\_discord.py → tools/archive/upload\_discord.py (Discord distribution dropped)  
- chore: add staleness prevention system for docs and TOC  
    - Add tools/validate\_docs.py: 4-check freshness validator  
        - Check 1: Cerebro.toc file list vs CEREBRO.md module table  
        - Check 2: Cerebro.toc file list vs docs/AGENT\_CONTEXT.md module table  
        - Check 3: docs/INDEX.md broken file references (recursive search)  
        - Check 4: Version consistency across Cerebro.toc, CEREBRO.md, AGENT\_CONTEXT.md  
        - Exit code 0 = clean, 1 = drift found  
    - Update tools/bump\_version.py:  
        - Now also updates CEREBRO.md 'Current Stable' header (was only doing changelog)  
        - Now also updates docs/AGENT\_CONTEXT.md 'Current Version' line  
    - Update .agent/skills/cerebro-governance/SKILL.md:  
        - Added 'Doc Freshness Checklist' section with validate\_docs.py gate  
        - Updated Commit & Release Gates to include validate\_docs.py run  
    - Update .agent/workflows/implement-feature.md:  
        - validate\_docs.py added as first item in Step 4 Pre-Completion Checks  
    - Update .agent/workflows/deploy-release.md:  
        - validate\_docs.py added as Step 1 pre-release gate  
        - 'What this does' updated to document new bump\_version.py behavior  
- docs: AI-agent-focused documentation cleanup  
    - Create docs/AGENT\_CONTEXT.md: 60-second quick reference with current  
      version (0.10.20), accurate module inventory from Cerebro.toc, 5 core  
      invariants, and navigation map for agents  
    - Create docs/proposals/ROADMAP\_NOTICE.md: agent signal that proposals/  
      contains future plans, not current spec  
    - Create docs/archive/AGENTS\_DO\_NOT\_READ.md: hard exclusion barrier for  
      historical documents  
    - Create .agent/tasks/archive/AGENTS\_DO\_NOT\_READ.md: same barrier for  
      completed task files  
    - Move AI\_AGENT\_ONBOARDING.md to docs/archive/ (replaced by AGENT\_CONTEXT.md)  
    - Move docs/AI\_SESSION\_2025-12-30.md to docs/archive/ (session log)  
    - Move docs/proposals/SUPABASE\_SYNC.md to docs/archive/proposals/ (implemented in SPEC.md §7)  
    - Move 18 completed .agent/tasks/ files to .agent/tasks/archive/  
    - Overwrite GEMINI.md: strip duplicate mandates to pointer + Planning Gate only  
    - Update CLAUDE.md Stage 1: add docs/AGENT\_CONTEXT.md to required reading  
    - Update CEREBRO.md: fix version 0.6.3 -> 0.10.20; replace stale 14-row  
      module table with accurate 24-row table from Cerebro.toc  
    - Update docs/SPEC.md: status DRAFT -> ACTIVE, version 1.1 -> 1.2  
    - Update PROJECT\_STATE.md: version 2.0 -> 2.1, Last Updated 2026-03-11  
    - Update docs/INDEX.md: replace broken DISTRIBUTION.md Tier 2 reference  
      with AGENT\_CONTEXT.md entry  
- docs: add ABOUT.md  
