Roll Check

Contract Roll Check

Detect and apply futures contract roll adjustments for active commodity positions.

Workflow

Step 1: Dry Run

Always start with a dry run to detect pending rolls without applying changes.

cd C:/Users/skf_s/Quantamental/production && python check_contract_rolls.py --dry-run

Step 2: Report Results

Present detected rolls using this format:

=== CONTRACT ROLL CHECK ===========================
Date: YYYY-MM-DD
Mode: dry-run

Checked: N active positions
Rolls detected: N

  commodity     old contract    new contract    old entry    adjusted entry    spread
  ----------    ------------    ------------    ---------    --------------    ------
  crude         CLK25           CLM25           63.4200      64.1800           +0.7600
  corn          ZCK25           ZCN25           452.2500     448.7500          -3.5000

Method: signal-date (new contract's close on original signal date)
===================================================

If no rolls detected, report that clearly and stop.

Step 3: Confirm with User

If rolls were detected and the --force argument was NOT passed:

• Show the user exactly what will change (commodity, old/new contract, price adjustment)
• Explain that this updates both Supabase and local live_signal.json files
• Wait for explicit confirmation before proceeding

If --force was passed as an argument to the skill, skip confirmation and proceed directly.

Step 4: Apply Rolls

After confirmation (or if --force):

cd C:/Users/skf_s/Quantamental/production && python check_contract_rolls.py

Step 5: Verify

After applying, verify the updates landed correctly:

1. Query Supabase to confirm signal_price and contract_ticker were updated for each rolled commodity:

SELECT commodity, signal_price, contract_ticker, contract_display, signal_date
FROM signals
WHERE commodity IN ('crude', 'corn')
ORDER BY signal_date DESC
LIMIT 10;

Use the Supabase MCP to run this query directly.

2. Check that local live_signal.json files were updated:

cat C:/Users/skf_s/Quantamental/outputs/<commodity>/live_signal.json

3. Report final verification:

=== ROLL VERIFICATION =============================
  commodity    supabase price    local price    contract    status
  ----------   ---------------   -----------    --------    ------
  crude        64.1800           64.1800        CLM25       OK
  corn         448.7500          448.7500       ZCN25       OK

All rolls verified.
===================================================

Arguments

• --force — Skip user confirmation, apply immediately after dry run
• No arguments — Interactive mode with confirmation prompt

Safety Notes

• The script has a double-adjustment guard: if contract_ticker in Supabase already matches the new contract, it skips that commodity
• Power markets and non-rolling commodities (ETFs, spot indices) are automatically excluded
• FLAT positions are skipped (no PnL impact from rolls)
• If historical price data is unavailable, the script falls back to current spread or zeroing

When to Use

• After the weekly pipeline run on Fridays
• When a user reports unexpected PnL jumps
• When contract expiry dates are approaching
• As part of the daily GitHub Actions check (daily-rollcheck.yml)
• Manually anytime during roll season (quarterly: March, June, September, December)