autoquant

Imported from ea28/autoquant (AGENTS.md). Install upstream with npx skills add ea28/autoquant. Copyright stays with the author.

Agent Operating Manual

This is the canonical rulebook for Codex candidate runs in this repo.

Mission

Improve strategy.py for Kalshi KXBTC15M inside a fixed arena.

You are not here to rewrite the harness. You are here to produce a better strategy under controlled evaluation.

Editable surface

Codex candidates may edit:

• strategy.py

Codex candidates may read:

• workspace_artifacts/workspace_manifest.json
• workspace_artifacts/strategy_frontier.md
• workspace_artifacts/agent_context.json
• workspace_artifacts/recent_lessons.json
• program.md
• README.md
• research_notes.md
• arena.py
• loop.py
• kalshi_autoresearch/
• docs/

Codex candidates must not edit:

• research_notes.md
• arena.py
• loop.py
• anything under kalshi_autoresearch/
• schemas, dependencies, or package metadata

Codex candidates must explicitly state which lane they touched, or which class of change they made if the work was about session validity, replay/live mismatch, feed handling, or maker auto-disable rules.

Required reading order

Before editing, read these in order.

If an artifact below is marked when present, read it if it exists and continue if it does not. Some operator-root sessions will lag the latest artifact set.

1. workspace_artifacts/workspace_manifest.json
2. workspace_artifacts/strategy_frontier.md
3. workspace_artifacts/agent_context.json
4. workspace_artifacts/recent_lessons.json
5. workspace_artifacts/session_validity.json
6. workspace_artifacts/session_compare.json
7. workspace_artifacts/missed_opportunities.json
8. workspace_artifacts/lane_metrics.json
9. workspace_artifacts/feed_health_summary.json
10. workspace_artifacts/order_funnel.json when present
11. workspace_artifacts/fill_reconciliation.json when present
12. workspace_artifacts/repo_map.md
13. workspace_artifacts/strategy_quickref.md
14. workspace_artifacts/candidate_output.schema.json
15. workspace_artifacts/promotion_policy.md
16. strategy.py

Treat that order as intentional. It goes from evaluation context, to editing guardrails, to output contract, to promotion rubric, to code.

Fallback when workspace_artifacts/ is missing

Direct root-repo Codex sessions may not have a pre-seeded workspace_artifacts/ directory.

If that directory is missing, use this fallback order instead:

1. AGENTS.md
2. program.md
3. docs/repo-map.md
4. docs/strategy-quick-reference.md
5. python3 arena.py agent-context --write-workspace-artifacts
6. python3 arena.py scoreboard
7. strategy.py

Do not fail just because workspace_artifacts/ is absent. That directory is guaranteed in candidate workspaces created by loop.py, but not necessarily in the operator root.

In the operator root, treat workspace_artifacts/ as generated state. Refresh it with:

python3 arena.py agent-context --write-workspace-artifacts

Objective

Primary objective:

• edge over baselines

Fixed baselines:

• no_trade
• always_yes
• always_no

Important secondary diagnostics:

• Sharpe ratio
• net PnL per episode
• total net PnL within one split only
• max drawdown
• order count / fill count

Optimize for repeatable, risk-adjusted edge. Do not optimize for one lucky replay window.

Current taker lane family:

• momentum_follow
• opening_value_v2
• binary_value
• stale_book_repricing
• late_value_rescue
• deep_value_v2

Current engine posture:

• taker lanes are the default promotable surface
• maker logic is allowed only as a guarded hybrid branch
• maker logic must auto-disable whenever queue awareness, passive-fill realism, or order lifecycle integrity is weak
• a candidate must not assume maker fills or queue priority without saying why the maker branch would stay enabled

Promotion model

There are three different concepts:

1. research champion
2. promotion eligibility
3. deployment readiness

They are not the same.

Promotion eligibility

A candidate is eligible only if it:

• compiles
• changes only strategy.py
• improves train mean_edge_dollars versus the current champion
• improves validation mean_edge_dollars versus the current champion
• improves holdout mean_edge_dollars versus the current champion
• keeps validation mean_edge_dollars positive
• keeps holdout mean_edge_dollars positive
• keeps validation median_edge_dollars non-negative
• keeps holdout median_edge_dollars non-negative
• meets the paired train win-rate threshold
• meets the paired validation win-rate threshold
• passes the runtime promotion gate

Promotion recommendation

You must still explicitly choose one of:

• promote
• keep_testing
• discard

Outperforming is necessary. It is not sufficient.

Recommend:

• promote only when the candidate is quantitatively stronger and still strategically trustworthy
• keep_testing when the result is promising but too narrow, fragile, or incomplete
• discard when the change is not worth carrying forward even if one metric improved

Deployment readiness

A research champion is not automatically safe for any live or “real strategy” branch.

Use python3 arena.py scoreboard in the operator repo to inspect readiness.

Deployment readiness is stricter than research promotion. The current readiness gate requires:

• positive train mean_edge_dollars
• positive train sharpe_ratio
• positive validation mean_edge_dollars
• positive validation median_edge_dollars
• positive validation sharpe_ratio
• positive validation total_net_pnl_dollars
• positive holdout mean_edge_dollars
• positive holdout median_edge_dollars
• positive holdout sharpe_ratio
• positive holdout total_net_pnl_dollars

Live-demo readiness is a separate gate from deployment readiness. It requires explicit session validity, feed health, and enough completed demo sessions to make session-level Sharpe meaningful.

Session validity semantics

Use these meanings consistently when reading live/demo artifacts:

• valid: the session reached a tradeable Kalshi market with a fresh actionable book, at least one fresh fast spot feed, and credible order/fill reconciliation
• invalid_startup: startup never reached a tradeable market before timeout
• feed_starved: the market existed but required feeds never became safely fresh
• empty_book_startup: the market existed but the book stayed empty or non-actionable
• market_roll_interrupted: the session lost actionability during a roll before the active window could be completed

Older artifacts may collapse empty_book_startup into invalid_startup or stale_kalshi. Treat those as environment invalidations, not as strategy wins.

Safety

• Demo-first by default.
• Candidate workspaces do not contain secrets.
• Candidate subprocesses also run with Kalshi and Polymarket env vars scrubbed.
• If uncertain, prefer lower-risk changes and better diagnostics.

Workspace artifacts

Every candidate workspace includes workspace_artifacts/ with:

• workspace_manifest.json: machine-readable workspace contract, commands, reading order, and no-change policy
• strategy_frontier.md: short dynamic summary of the champion's strengths, weaknesses, and next hypotheses
• agent_context.json: current scoreboard, recent results, recent lessons, latest session summary, and suggested commands
• recent_lessons.json: compact structured lessons from recent research notes
• repo_map.md: where things live and what they do
• strategy_quickref.md: short editing and context API reference
• candidate_output.schema.json: exact response contract
• promotion_policy.md: quantitative gate plus qualitative promotion rules
• session_validity.json
• session_compare.json
• missed_opportunities.json
• lane_metrics.json
• feed_health_summary.json
• order_funnel.json when available
• fill_reconciliation.json when available
• train_bank.json
• validation_bank.json

Read those first. They are the candidate-safe context layer.

Order funnel artifacts

When present, the order-funnel artifacts are the primary explanation for under-trading or over-canceling:

• order_funnel.json: counts from strategy intent through risk block, submit, acknowledge, working, cancel, partial fill, full fill, exit, and flatten
• fill_reconciliation.json: exchange-versus-local order, fill, and position agreement

If you are proposing a more aggressive strategy, you must explain which part of the funnel should improve and why.

Candidate-safe commands

These commands should work inside a candidate workspace:

python3 -m json.tool workspace_artifacts/workspace_manifest.json
sed -n '1,220p' workspace_artifacts/strategy_frontier.md
python3 -m json.tool workspace_artifacts/agent_context.json
python3 arena.py replay --strategy strategy.py --bank workspace_artifacts/train_bank.json
python3 arena.py replay --strategy strategy.py --bank workspace_artifacts/validation_bank.json
python3 arena.py inspect-live --series KXBTC15M --feed-mode hybrid --wait-seconds 4

Context API reminders

• on_market_open is time-bounded.
• ctx.current_time is set during on_market_open.
• ctx.current_tick is also available during on_market_open when the runtime has an opening snapshot.
• ctx.market_metadata(ticker) returns immutable market metadata.
• ctx.recent_reference_ticks(...) and ctx.latest_reference_tick(...) expose Binance, Coinbase, and Chainlink RTDS when available.
• ctx.recent_peer_market_snapshots(...) and ctx.latest_peer_market_snapshot(...) expose the matching Polymarket peer market when available.
• ctx.market_metadata(ticker) should be treated as the source of truth for the active market's immutable metadata.

Strategy design guidance

• Prefer one bounded idea at a time.
• Run the visible workspace replay commands before responding unless you are making a deliberate no-op discard.
• If no safe improvement is justified, it is acceptable to leave strategy.py unchanged, set files_touched to [], and recommend discard.
• Respect fees and spreads.
• Value lanes may use spot direction as a confidence penalty, not a universal veto.
• If touching maker behavior, treat maker auto-disable as a guardrail, not as a failure. The correct behavior can be to fall back to taker-only mode.
• Do not compare raw total_net_pnl_dollars across train, validation, and holdout unless the banks have the same episode count. Use median_edge_dollars, mean_edge_dollars, net_pnl_per_episode_dollars, mean_return_pct, and sharpe_ratio for cross-split comparisons.
• The hidden holdout is operator-only. Candidate agents should optimize against train and validation, then let the harness decide whether the change survives the hidden holdout gate.
• Treat Binance and Coinbase as spot proxies, not settlement truth.
• Treat Polymarket as a peer market, not settlement truth.
• Treat Polymarket as read-only in this repo. Do not design around placing Polymarket orders.
• Treat stale feeds as missing data.
• Avoid assumptions about maker fills or queue position.
• Maker work is only a valid promotion target when the candidate can explain why maker auto-disable would remain off and why the replay/live path is still trustworthy.
• Leave enough diagnostics in on_episode_end for later agents to understand why the strategy traded or stayed out.
• If replay and live behavior diverge, prefer diagnosing that mismatch over broadening the strategy blindly.

Strategy file organization

Keep strategy.py readable. Prefer edits within these internal sections:

1. parameters and thresholds
2. lifecycle hooks
3. signal construction
4. entry logic
5. exit logic
6. diagnostics and math helpers

Do not turn the file into an unstructured threshold dump.

Notes policy

Do not edit research_notes.md directly.

Instead, return:

• hypothesis
• expected_signal
• risk_changes
• change_summary
• diff_checklist
• lessons_applied
• guardrail_checks
• files_touched
• regression_risks
• why_this_should_beat_baselines
• rollback_if
• notes_for_next_agent
• follow_up_experiments
• promotion_recommendation
• promotion_rationale

When possible, make the change classification explicit in change_summary and notes_for_next_agent:

• strategy-lane
• session-validity
• replay/live-mismatch
• feed-robustness
• prompt/docs

New reporting requirements:

• In change_summary, explicitly include:
  • change_class=...
  • lane=... or lane=none
  • engine_mode_target=taker|maker|hybrid|maker-auto-disable
• In guardrail_checks, explicitly say whether maker should remain enabled for the touched scenario or auto-disable.
• In notes_for_next_agent, explicitly state the expected order-funnel effect:
  • more intents
  • better submit-to-ack
  • better ack-to-fill
  • fewer stale cancels
  • cleaner fill reconciliation
  • or stricter maker shutdown

Do not add new top-level JSON fields unless the schema is updated. Put the extra reporting inside the existing required fields.

The runtime appends the relevant parts into the shared journal after the run.