[sudoTomas]

What changed

• Settlement (trader.learning.settlement, migration 0018_learning.sql): every journaled decision with a decision payload (open, close, hold, shadow included) settles 5 of its symbol's sessions after the session it was made in. Outcomes come from daily bars fetched on use; nothing is stored except the outcome: forward return, benchmark return (SPY for equities/ETFs, BTC/USD for crypto), excess return, direction (+1/-1/0), and correct (NULL for a hold). settled_at is the end of the exit bar. decision_settlements and lessons are append-only (trigger).
• reflect Role: in ROLE_KINDS (chat), registry ROLES, Spend-cap ROLES, the Probe contracts and the desk Models page. Its .env chain follows the research chain: TRADER_RESEARCH_* if set, else a non-reasoning Grok (TRADER_REFLECT_XAI_MODEL, default grok-4.20-0309-non-reasoning, sharing the process's one xAI client) with the decide client as backstop. Metered under reflect, so a Spend cap applies. It writes a 2-4 sentence Lesson per settled decision, newest first, at most TRADER_REFLECT_MAX_PER_PASS per pass. A capped or down Role ends the pass, which resumes on the next one.
• lessons Source (loop/sources.py): a Bot's latest 3 Lessons for the symbol (whole entries, 1200-char budget). It only reads Lessons whose available_at (the Settlement's settled_at) is at or before the read's instant. Live reads use now and replay reads use the step's as_of. Source version = the Lesson ids read. Off per Bot: Bot Flip briefs into the decide lane (was EAI-192) #1 turns it on with TRADER_LESSONS_ENABLED, other Bots by adding lessons to their spec sources. Blind replay drops it, because Lessons are free text that can name the asset.
• Scorecard (trader.learning.scorecard): for each seat (decide = the Draft from raw_output before any critic, each analyst:<lane>, critic as a call on the Draft's direction: approve +1, shrink +0.5, veto -1), it reports hit rate and slugging on excess return, and pooled rank IC of signed conviction vs forward return, at the 5-day horizon.
• Surfaces: service queries scorecard and lessons and command settle_decisions; API GET /scorecard, GET /lessons, POST /settlement/run; MCP get_scorecard, get_lessons, settle_decisions; CLI trader scorecard, trader lessons, trader settle; the desk shows a Scorecard card on the Decisions page. Replay gains lessons (service/API/CLI --lessons) and config.bot_id.
• CONTEXT.md: Settlement, Lesson, Scorecard; reflect added to Role. Settings documented in docs/configuration.md / .env.example.

Acceptance

• Settlement tests on fixture bars: test_a_decision_settles_five_sessions_after_the_session_it_was_made_in, the pending cases, crypto vs BTC, and the pass end to end (test_a_pass_settles_every_journaled_decision_and_writes_lessons).
• Replay test that a Lesson settled after the bar is never read: test_a_replay_never_reads_a_lesson_settled_after_the_bar.
• Scorecard numbers checked against a hand-worked example (worked in the test docstring): test_the_scorecard_matches_a_hand_worked_example.
• CONTEXT.md terms: Settlement, Lesson, Scorecard.

How to switch it on

1. TRADER_SETTLEMENT_ENABLED=true starts a background pass every TRADER_SETTLEMENT_INTERVAL_SECONDS (default 3600). It needs market-data credentials. trader settle runs one pass on demand either way.
2. Optional: set a reflect Spend cap or route reflect in a Profile.
3. Feed Lessons into a prompt (this changes decide behaviour, so it goes through the decide-change gate): replay with --lessons first, then TRADER_LESSONS_ENABLED=true for Bot Flip briefs into the decide lane (was EAI-192) #1, or add lessons to another Bot's sources.

Everything defaults off. Deploying this changes no live behaviour.

Notes

• Point-in-time overlap with Point-in-time clamp + SEC EDGAR, Polymarket, StockTwits/Reddit Sources #142: the lessons Source filters by its own available_at (repo query plus a defence-in-depth filter in the Source). It is not a general clamp; Point-in-time clamp + SEC EDGAR, Polymarket, StockTwits/Reddit Sources #142's clamp can subsume it.
• Tests: 950 passed (19 new in tests/test_learning.py); ruff clean; config reference in sync.

Closes #143

https://claude.ai/code/session_01UDNLNu854ULHbHSL59UJKu