# GramPilot Core Development Rules

This document codifies the core architectural and development principles for the GramPilot (Instagram Bot) project.

## 1. 100% AUTONOMOUS "TESLA" FSD PHILOSOPHY (ABSOLUTE DIRECTIVE)
- **Zero Static Navigation Code:** GramPilot is a "Full Self-Driving" (FSD) agent. You are FORBIDDEN from using brittle heuristics, static UI locators (XPaths), fixed string searches, or hardcoded navigation sequences.
- **Structural Perception Only:** The bot must rely entirely on its `SituationalAwarenessEngine` to structurally "read" the XML dump, understand context, and resolve the correct layout using Qdrant vector memory.
- **Dynamic Fallbacks:** If the UI updates, the bot must not crash. It must fall back to LLM reasoning, dynamically find the right button, and learn the new layout asynchronously.
- **Self-Healing Memory:** If the Qdrant DB learns a false positive (e.g., misclassifying a normal screen as an `OBSTACLE_MODAL`), the LLM must detect this, emit `false_positive`, and the engine will autonomously overwrite the corrupted vector back to `NORMAL`.

## 2. Strict Test-Driven Development (TDD)
- **Red, Green, Refactor:** Never write a single line of production code without a failing test proving its necessity.
- **Real-World Fixtures Only:** Tests must use high-fidelity, real-world XML UI dumps (`tests/fixtures/`). Mocks must never fake or obscure structural UI realities.
- **Hermetic Test Isolation:** Tests must be deterministic. Use centralized stubs (e.g., `mock_sae_perceive` in `conftest.py`) to bypass local LLM/Qdrant latency for pure logic tests, while keeping full E2E perception tests in `test_e2e_sae.py`.
- **Zero Flakiness:** The E2E test suite is the ultimate gatekeeper. State leakage between tests is unacceptable.

## 3. Qdrant as the Neural Brain
- **Persistent Perception:** Qdrant is the persistent memory of the bot (`ScreenMemoryDB`, `NavigationMemoryDB`). It is the absolute source of truth for UI layouts.
- **Vector-Based Sub-Second Recalls:** Instead of running an LLM on every screen, the bot hashes and compresses the XML layout, converts it to an embedding, and queries Qdrant. If the similarity threshold (>0.90) is met, the bot knows instantly what to do based on past experience.
- **Learning Loop:** Only when Qdrant fails (a novel screen) does the LLM step in. The LLM's solution is then verified, and if successful, embedded into Qdrant. Thus, the bot gets faster and smarter with every run, transitioning from expensive AI reasoning to instant vector recalls.

## 4. Tooling and Infrastructure
- **Memory Purging:** Use `blank_start: true` in `test_config.yml` to trigger a system-wide Qdrant wipe when the persistent navigation graph becomes irreparably poisoned.
- **Fixture Synchronization:** Use `scripts/sync_fixtures.py` to capture and integrate real-world XML dumps into the test suite.
- **LLM Fallback:** The LLM is a *fallback* for novel UI states, not the primary navigation driver. It is used to suggest escape plans (`EscapeAction`) which are then executed, verified, and learned by Qdrant.

## 5. Code Quality
- **Modular Plugin Architecture:** Interaction loops (e.g., Reels, Story viewing, Profiling) must remain decoupled via the `PluginRegistry`.
- **Max 500 LoC:** No module should exceed 500 lines of code. Divide and conquer responsibilities immediately if approaching this limit.
