docs(research): the fill-model hazard in externally-sourced strategies (#529)

[eaitbrahim]

Closes #529. Milestone: Strategy-API expressiveness. Docs only — no code paths touched; suite green (uv run pytest -q: 4340 passed, 3 skipped).

Where the doc landed, and why

docs/experiments/2026-08-27-external-strategy-evaluation-hazard.md (plus a newest-first index entry in docs/experiments/README.md).

Chosen over docs/research/ because the cost-restatement corpus the issue names ("alongside the cost-restatement documents") lives in docs/experiments/ — the 08-12 fee curve and the 08-13 restatement are the two records every number in this hazard cites — and because docs/experiments/ is where the scout skill already directs a proposer to read before writing any output. That is the meet-point the acceptance bar describes. The doc states up front that it reports no new measurement; it is the reading-side analogue of the invariants the 08-13 record demanded.

Section shape

1. The hazard — the Jesse self.buy = qty, entry idiom vs keel's fix(strategy): fill entries at the next bar's open, as production's market orders do #258 next-bar-open market fill; the worked example with both numbers; the compounding with ~2.5% round-trip friction ("optimistic on both axes at once").
   • 1.1 A caveat the worked example must not lose — carried verbatim in spirit from the 08-13 record §3.1: 0.92 → 0.77 is not evidence that resting entries add edge (both sides lose gross; the filter separated bad from worse). It is evidence for The live executor discards a rule's conditional entry price and routes a market order regardless #260's landmine. This prevents the doc from being read as an argument for Route a rule's conditional entry as a genuine resting order (limit/stop) — deferred until a price-conditional rule earns it #333.
2. Why a document and not code — nothing to enforce; the engines are already correct; the hazard is in how a human reads someone else's backtest.
3. The four questions — each with what to establish / why it matters here (measured keel anchors) / what a wrong answer costs: fill model, cost regime, sample size & window, capability (Route a rule's conditional entry as a genuine resting order (limit/stop) — deferred until a price-conditional rule earns it #333/Broker port has no bracket/OCO order kind — live trailing stops, BE-rolls and scale_out are blocked on it #502/C7 — Rules are not pluggable, though brokers are #447/The live executor discards a rule's conditional entry price and routes a market order regardless #260).
4. The checklist — a copy-paste markdown form: the four questions as yes/no/unknown prompts ("unknown is a real answer") plus a proceed/do-not-port verdict, answered before porting effort.
5. Where this is enforced for machine-generated proposals — the scout skill's cost_regime/sample_size/evaluation_window citation fields are the same discipline; the two are kept in step.
6. Provenance of every number — a table mapping each figure to its record of origin.

Cross-reference points (the acceptance criterion)

Three places, each one where a person proposing a candidate would actually see it:

1. .claude/skills/keel-asset-scout/SKILL.md (Output 3a, the parameter-proposal section that already frames claims against the fill model) — pointer to the doc, with the instruction that a research brief that has not answered its four questions is not yet interpretable. Force-added per that file's own tracking convention (.claude/ is gitignored).
2. docs/superpowers/specs/2026-08-23-strategy-api-expressiveness-prd.md §4.2 — a "Documented (Document the fill-model hazard when evaluating an externally-sourced strategy #529)" cite-back blockquote, making the PRD's second success criterion traceable to where it landed.
3. docs/superpowers/specs/2026-07-24-llm-asset-proposer-design.md §B (the "Strategy proposer — future, own spec" scope) — one line: any future strategy-proposer spec inherits the hazard and must route proposals through the checklist.

Plus the docs/experiments/README.md index entry (corpus convention, not counted as a cross-reference).

Provenance of each number (all verified against source before writing)

Number	Source
gross PF 0.9292 → 0.7736, median n 60 → 124, n≥100 cells 4 → 14	docs/experiments/2026-08-13-restated-under-a-production-faithful-engine.md §3 table
gross 0.9219 → 0.7736, median n 58 → 124; "the doubling is the count of those trades"; entry = signal_candle.high + buffer_ticks	same, §3.1
next-bar-open market fill; order_type="market", limit_price=None; "free optionality … and unbounded patience"	same, §1 (#258); confirmed against keel/strategy/backtest.py and keel/execution/executor.py on this branch
round-trip friction 2.50% taker / 1.30% maker (2 × fee_pct + 2 × slippage_pct)	docs/experiments/2026-08-12-fee-curve-and-rsi-meanrev.md
rsi_meanrev 1.1631 at median n=38 / 0.8396 across 82 cells at n≥100	same 08-13 doc §4. Note, stated in the doc itself: the issue's pairing spans engines — 1.1631@38 is the old-engine anchor, 0.8396@82-cells is the faithful-engine n≥100 figure. The doc gives both engine columns (old: 1.1631 → 0.8938 across 76 cells; faithful: 1.1251@42 → 0.8396 across 82) so the level shift is shown to hold within either engine, not as an artifact of the correction.
ZEC-turtle 1.555 gross, three consecutive losing years, 92.7% of PnL in 2025–26	08-13 doc §2
"cost-bound, not signal-bound"; capability → #333/#447/#502 map; Jesse idiom	docs/superpowers/specs/2026-08-23-strategy-api-expressiveness-prd.md §0/§2/§3

One nuance recorded rather than flattened: the 08-13 source carries slightly different medians for the same comparison (§3 table: 60 → 124 and 0.9292; §3.1: 58 → 124 and 0.9219 — both round to the issue's "0.92 → 0.77" and "doubled trade count"). The doc cites both exactly as printed instead of picking one.

Issue #257 vs #258 (issue vs fix) is disambiguated on first mention ("since #258 (the fix for #257)"), since backtest.py cites #257 and the experiments corpus cites #258.

Not done, deliberately

• No new measurement, no .py driver — the doc says so up front; every figure is a citation.
• No resting-entry support — Route a rule's conditional entry as a genuine resting order (limit/stop) — deferred until a price-conditional rule earns it #333 remains deferred on its own terms (the doc's §1.1 exists to stop it being read that way).
• PR left open for review; not merged.