# GOAP & Dynamic Navigation Standards

This document defines how GramPilot handles high-level pathfinding and navigation across the Instagram app.

## 1. Goal-Oriented Action Planning (GOAP)
- **No Hardcoded Paths:** The bot must never follow rigid, procedural step-by-step instructions (e.g., "click home, then click search, then type").
- **State-Driven Execution:** Navigation is handled by the `GoalPlanner` and `GoalExecutor`. The agent evaluates its *current state* (via the `TelepathicEngine`) and defines a *target state* (the Goal).
- **Dynamic Routing:** The `GoalPlanner` queries the `QNavGraph` (backed by Qdrant memory) to find the shortest/optimal sequence of actions to bridge the gap between the current state and the target state.

## 2. Intent Over Execution
- **Navigation Intent:** When the bot wants to move, it sets an `Intent` (e.g., "NAVIGATE_TO_USER_PROFILE"). It does *not* care about how to get there. The GOAP engine calculates the intermediate hops required based on its learned memory of the UI graph.
- **Fall-Through Healing:** If an intermediate hop fails (e.g., the bot expected to see the Explore tab but saw a Modal), the `SituationalAwarenessEngine` clears the modal, the `TelepathicEngine` re-evaluates the state, and the GOAP loop *re-plans* dynamically.

## 3. The QNavGraph (Qdrant Navigation Memory)
- **Graph Nodes:** Every unique UI screen perceived is a node in the graph, hashed by its structural XML signature.
- **Graph Edges:** Every successful interaction (`EscapeAction` or `Intent` execution) that transitions the bot from Node A to Node B is recorded as a directed edge.
- **Continuous Discovery:** If GOAP cannot find a path to the goal in `QNavGraph`, the bot switches to "Discovery Mode", randomly exploring safe UI elements (guided by `available_actions` and LLM hints) until it maps a path to the target.

## 4. Infinite Recursion Guards
- **Synthetic Intent Tracking:** The `GoalPlanner` must track failed or cycling intents to prevent infinite loops (the "feed refresh trap").
- If the agent detects it is bouncing between the same states without making progress toward the Goal, it must escalate to a higher-level reset (e.g., `app_start`) or fail gracefully rather than doomscrolling indefinitely.
