test-topic-123-perfected

📝 OMP & Testing Master Cheat Sheet

┌────────────────────────────────────────────────────────────────────────┐
│                        📝 OMP SYNTHESIS CONTROL BOARD                  │
├───────────────────┬──────────────────────┬─────────────────────────────┤
│ 🧼 SWARM & AGENTS  │ 🧠 STACK REFLECTION  │ ⚡ CONDENSATION & FORMATTING │
├───────────────────┼──────────────────────┼─────────────────────────────┤
│ 1. Python Evals   │ 1. Core Integrations │ 1. High-density Tables      │
│ 2. Testing Layers │ 2. Observability     │ 2. Visual Emojis Landmarks  │
│ 3. Naming Rules   │ 3. CLI & Web Config  │ 3. Markdown Dashboards      │
└───────────────────┴──────────────────────┴─────────────────────────────┘

🚀 Architecture & Infrastructure

• Ompycord Colocation: Run discord.py alongside FastAPI. Disable native signals on Uvicorn (server.install_signal_handlers = lambda: None).
• Telemetry Context: Carry context via Node/Bun AsyncLocalStorage. Use safe lazy dynamic imports (await import('langfuse').catch(...)).
• Environment Isolation: Keep a clean codebase. Distinguish test data from production traffic completely.
• Automated TTL: Automate dummy infrastructure cleanup via TTL (auto_ttl_days: 1).

📦 Swarm Orchestration & Agents

🛠️ Domain	💡 Implementation Standard
Agent Provisioning	Use agent_type="task" for filesystem writes. Reviewers are strictly read-only!
Persona Injection	Inject personas directly into the prompt string. The role kwarg is invalid for agent().
Output Scoring	Enforce JSON schemas when scoring outputs to avoid breaking diff-based exit conditions.
Validation Gates	Delegate pipeline validation to gatekeeper agents to halt loops with dummy configs.

🔧 Codebase Tooling & Commands

🛠️ Tool	✅ Action & Command
Prettier / ESLint	Ignore quartz/local-plugins in workspace configs to prevent overwrite loops.
Quartz UI	Strip emojis from Explorer using regex mapFn: /[\p{Emoji_Presentation}\p{Extended_Pictographic}\uFE0F]/gu.
Quartz Mermaids	Always wrap edge labels in double quotes (`—>
WordPress Builds	Edit JS/PHP inside src/. Always run npm run build from the plugin root directory.
WP-CLI Execution	Run sudo -u www-data wp in restricted /var/www/ directories to prevent permissions errors.
Secure Web Writes	Use sudo -u www-data tee path/to/file > /dev/null << 'EOF' instead of standard bash redirects.
OMP CLI	Execute debugging CLI commands strictly under a real PTY (pty: true).

💡 Best Practices & Testing

• Structured Naming: Replace generic placeholders (like test-topic-123) with namespaced formats: [env].[region].[service].[data-type]. Append versions (v1) and use strict lowercase.
• Local Verification: Use dummy placeholders strictly for rapid local verification, never in shared environments.
• Test Independence: Assert strictly on behavioral outcomes. Tests must run independently without relying on shared state.
• Lifecycle Policy: Enforce a strict lifecycle management policy for all test topics to ensure immediate cleanup.

🚨 Gotchas / Traps / Warnings

• Generic Placeholders (test-topic-123): NEVER deploy generic strings in shared/production environments. They obscure observability, pollute metrics, and introduce collision risks.
• Read-Only Reviewers: Agents tagged agent_type="reviewer" cannot write to the filesystem. NEVER attempt I/O with them.
• Brittle Tests: Over-reliance on internal implementation details breaks tests during refactoring.
• Direct Build Edits: Modifying build/ files in WordPress directly is an anti-pattern and will be overwritten by builds.
• Shared Test State: Designing tests that rely on shared state from previous tests guarantees cascading failures.
• Signal Overlap: Never allow signal handlers to clash when co-locating asynchronous frameworks like Uvicorn and Discord.py.