AGENTS.md

Guidance for coding agents working on the Insane Search route learning role.

Project Overview

Route learning records which generic fetch route last worked for a host and device class, then promotes that route on later visits. It is an optimization layer, not a correctness layer: all errors are swallowed, stale entries expire, overflow is capped, and failed learned routes are evicted after repeated real blocks.

Project Map

skills/insane-search/engine/learning.py defines enabled(), default_path(), key_for(), lookup(), record_success(), record_failure(), TTL pruning, cap enforcement, and failure-strike logic.
skills/insane-search/engine/fetch_chain.py looks up a learned route before _fetch_core() and records success or failure after the run.
skills/insane-search/engine/tests/test_u5.py covers the learning store and route promotion behavior.
skills/insane-search/engine/tests/test_u1.py and test_u4.py cover scheduler and session behavior that learning must not break.
skills/insane-search/engine/bias_check.py protects source files from site-specific branching.

Setup Commands

bashcd skills/insane-search
python3 engine/tests/test_u5.py
python3 engine/tests/test_u1.py
python3 engine/bias_check.py

Change Rules For Agents

Keep learning best-effort; read and write errors must never break fetch().
Store route identity as transform, impersonation, referer, and phase.
Key learned routes by host and device class, not full URL path.
Promote learned routes before the normal diversity grid without deleting alternate candidates.
Strike learned routes only for real route failures such as exhausted, challenge, or blocked.
Do not strike on rate limits, unknown errors, budgets, auth-required, not-found, or success.
Keep TTL and maximum-entry pruning in place.
Keep source code site-agnostic; per-host learning belongs in data, not branches.

Verification

bashcd skills/insane-search
python3 engine/tests/test_u5.py
python3 engine/tests/test_u1.py
python3 engine/bias_check.py

When changing eviction logic, include tests for real failures, transient outcomes, TTL pruning, cap pruning, and route promotion order.

Security Notes

The learning store must contain only generic route metadata. Do not store cookies, response bodies, account identifiers, credentials, headers, or private target details.

PR Checklist

Learning can be disabled.
Corrupt or missing data loads as empty.
Route promotion does not remove alternate attempts.
Failure strikes are limited to real blocks.
test_u5.py and bias_check.py pass.

Insane Search Route Learning Agent Guide