Add prompt route simulation checks

docs/prompt-pool-routing-map.md

@@ -980,6 +980,32 @@ pair metadata through the core Python APIs, then verifies:
   Python formatter APIs for metadata-driven pair inputs, so ComfyUI wrappers
   cannot silently drift from route behavior.
 
+## Route Simulation Helper
+
+For prompt-quality edits, run the simulation helper before and after changing
+wording or route selection:
+
+```bash
+python tools/prompt_route_simulation.py --fail-on-issues
+```
+
+The script builds representative single-row and Insta/OF pair routes, formats
+them through Krea2, SDXL, and training-caption paths, and reports structured
+issues for:
+
+- formatter routes falling back away from metadata;
+- raw builder labels leaking into Krea output;
+- duplicate negative-prompt comma items;
+- softcore prompt noise;
+- POV routes emitting third-person camera text or losing first-person wording;
+- selected hardcore position filters appearing in `position_keys` but not as
+  the primary `position_key`;
+- pose-axis rerolls changing cast/scene metadata or failing to move pose/action
+  metadata.
+
+Use `--json --include-prompts` when you need the exact raw and formatted text
+for debugging a route.
+
 ## Editing Cheatsheet
 
 | Symptom | First file/function to inspect |
@@ -1097,8 +1123,9 @@ Before changing prompt behavior:
 3. Decide whether the bug is selection, raw wording, camera adaptation, or
    formatter rewrite.
 4. Edit the smallest owning pool/template/function.
-5. Re-run a small simulation with fixed person/scene/category seeds and only the
-   target axis varied.
+5. Re-run `python tools/prompt_route_simulation.py --fail-on-issues` or a
+   similarly small simulation with fixed person/scene/category seeds and only
+   the target axis varied.
 
 The repo may have unrelated dirty files during interactive prompt work. Always
 stage only the intended files for commits.