feat(executor): routing-time max-spread gate for live BUY entries

[eaitbrahim]

Fixes #350.

What

A live BUY whose previewed book shows (best_ask − best_bid) / mid at or beyond execution.max_entry_spread_pct (new execution: config section, default 0.005 = 50bp) is refused after the preview and before the confirm gate and placement — so a thin book cannot be entered at a moment its spread alone makes the fill economics materially worse than the cost model assumes. The refusal is recorded in ExecutionResult.vetoed_by (tokens max_entry_spread / book_unreadable, the same one-legible-token shape rail violations use) and logged at WARNING as a structured event (executor.entry_spread_refused with the measured spread, threshold and product; executor.entry_book_unreadable for the fail-closed arm).

This is the live-path half of the spread guardrail whose sizing half (#358) caps every Tier-2 addition at a 2% target weight.

Design decisions

• Post-preview placement, deliberately. guards.check is broker-less by design, and the book exists only in the broker.preview_order result — so this is a routing-time gate beside the eighteen rails, not a numbered guards.check rail (no renumbering anywhere). It consumes the same preview fix(executor): warn loudly when a conditional entry price is overridden by market routing (#260) #332's _warn_if_market_routing_overrides_entry reads: one helper (_preview_book — bid/ask read independently, missing-keys/NaN/non-finite/non-positive-safe), two consumers. The fix(executor): warn loudly when a conditional entry price is overridden by market routing (#260) #332 warning keeps its exact behavior and position; the gate runs after it, before confirm/place.
• BUY-only. Exits, exit brackets, stop rolls and scale-outs are never gated — the same principle that makes rail 17 halt entries, not exits. A spread gate that trapped an exit would strand a position in exactly the book conditions the rule said to leave.
• Paper mode never runs the gate. _paper_enter fills synthetically without a preview, so the paper-hourly profile accrues no evidence about this gate — a reason it ships before any live resumption, not before paper expansion.
• Fail-closed on an unreadable book. A live BUY whose preview carries no readable bid AND ask (missing keys, NaN, non-finite, non-positive, or spread arithmetic that overflows — the chore(fidelity): close Phase 9's loose ends — alias, stale docstrings, telemetry overflow guard #336 extreme-exponent hazard, refused here rather than swallowed as telemetry) is refused with the distinct book_unreadable reason. "Cannot know" is a different fact from "too wide". Verified the real venue's preview carries both sides: cb_client.preview_order maps best_bid/best_ask to Decimal (tests/fixtures/cb_preview_order.json), and the port's Preview.detail carries them as strings.
• 50bp default anchored to feat(backtest): per-product slippage scaled from liquidity — assumed, capped, and reported (#259) #334's SLIPPAGE_CAP_PCT: the backtest never assumes more than 50bp per-leg slippage on even the thinnest book, so a spread AT the cap has consumed the model's entire worst-case cost estimate and the taker fee rides outside it — hence the boundary is >= (fail-closed), unlike fix(executor): warn loudly when a conditional entry price is overridden by market routing (#260) #332's strictly-greater visibility threshold. Validated on load to (0, 0.10]; violations raise ConfigError naming execution.max_entry_spread_pct.

Test-side consequence (honestly reported)

The shared test fakes' bookless default previews modelled a shape the real venue does not return, and under a fail-closed gate every "normal successful BUY" test through them would refuse. The fakes (tests/execution/test_executor.py, tests/test_agent.py, tests/test_cli.py, tests/execution/test_reconcile.py) now carry both book sides, and the one #332 test that borrowed the default preview as its degraded/bookless shape (test_a_preview_without_a_book_quote_is_silent_not_fatal) constructs that shape explicitly — meaning unchanged, sourcing changed. The golden config fixtures were regenerated via the documented script; the defaults golden now pins execution.max_entry_spread_pct = 0.005.

Docs

• docs/operator-runbook.md: the Tier-2 guardrail story — sizing half (feat(paper-hourly): expand the universe 8->19, Tier-2 capped at 2% target weight #358's 2% cap) + live-path half (this gate), and why paper accrues no evidence about it.
• README.md + docs/fiqh-basis.md: the gate described beside the rails enumeration as exactly what it is (BUY-only, live-only, fail-closed); the "eighteen rails" count is unchanged because this is not a numbered rail.
• Shipped config templates (keel/templates/config.yaml + repo config.yaml, config.live.yaml) document the knob.

Gates

• uv run pytest -q — 2965 passed, 1 skipped
• uv run ruff check keel tests packages — clean
• uv run mypy — clean

[sonarqubecloud]

Quality Gate passed

Issues
1 New issue
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud