Cerebro

v0.10.21 (2026-03-12)

Full Changelog

• 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