--- name: aegis-roll-decision-framework description: How to read and relay a roll analysis of roll_analysis.py, for the Aegis Structuring Desk. A roll is a close plus an open, judged as a fresh trade; what the analysis covers (the short call of a covered call, the long put of a protective put, the short put of a cash-secured put, a collar's two legs) and what is planned; the replacement set; the objective, its score and its tie-breaks; the statuses and the FAILS_CRITERION labels (credit_only for a net debit, strike_floor below the stock cost, earnings and ex_dividend inside the new call's life, the bands, unpriced quotes) and how the owner's row tags and criteria accept them; the approval-level check; why no candidate passing is a complete answer and CLOSE or LET_ASSIGN remain choices; the link to the Exit Sentinel's plan words; and why it never runs in a routine. The desk never places anything; the owner decides and acts in the brokerage account. license: MIT metadata: version: "0.1.0" author: FairGradient category: structuring --- # The roll decision framework A roll analysis prices the replacement candidates for the short call of a covered call, labels each one against the owner's own criteria in `structuring.toml`, and scores them on the owner's objective. When at least one passes every criterion, it names the one with the highest score as the best candidate. The Aegis Structuring Desk runs the tool `roll_analysis.py` only when the owner asks, after the owner's tap on its Ask-first card, and posts the text verbatim. The desk never places anything: the owner decides, supplies the limit and acts in the brokerage account. The examples are synthetic: runs on copies of `tests/fixtures/desk` with the fixture criteria written by `desk_init.py` and acknowledged, on 2026-11-03 at 19:50 UTC with the regular quotes. ```text python3 /workspace/aegis-grok-desk/scripts/roll_analysis.py --trade AG-20261020-01 --desk-root /workspace/aegis-desk ``` ## A roll is a close plus an open - A roll closes the held short call at its fresh ask and opens a new call at its fresh bid. Those are two trades, and the new call is judged as a fresh trade: every candidate shares the same close, so the score reads the new call alone. - The net credit per share is the new call's bid minus the held call's ask. A negative net credit is a net debit. The candidates list prints it per share (`credit 0.05`, `debit 0.70`), and the best candidate's checks in all, for example `credit 0.05 (10.00 in all)`. - The best candidate's group block shows the group's maximum loss, maximum profit, breakeven and delta now and after both legs. The tools compute them; a Bot never does. - Keeping the call, closing it, or letting it go to expiry are choices too. A CLOSE or a LET_ASSIGN ticket prices them (`aegis-ticket-and-unwind-order`). ## What the analysis covers - The open short call of a `covered_call` group, on a symbol held in `positions.csv`, judged under `[roll]`. Chains are fetched only for that group's underlying. - The open long put of a `protective_put` group, judged under `[protective_put]`: every put of a later standard monthly inside its `dte`, ranked by its objective (`stress_cost_per_day` by default). The best candidate opens the new put at its ask first, then closes the held put at its bid, and each check reads the net cost per day added. - The open short put of a `cash_secured_put` group, judged under `[roll]` as a short call's roll is: the bands, the minimum credit and the roll test, with a put's time value (`bid - max(0, K - S)`). `strike_floor` and `ex_dividend` are call rules and are not read; earnings inside the new put's life still count. The best candidate closes the held put at its ask first, then opens the new one at its bid, and a note gives the cash each put secures (the desk does not see the cash balance). - Where a short put's holder may do better exercising it than holding it (the long put's two tests: absolute delta 0.80 or more, or in the money with a time value below the interest on its strike), the answer carries an `early-assignment note:`: the short put can be assigned before expiry. - A `collar` group's two legs, replaced as a unit and judged under `[collar]`: every pair of a later standard monthly inside its `dte` and floor and cap bands, the new collar's own net debit against `max_net_debit`, ranked by its objective. The best candidate's four legs open the new put, close the held put, close the held call and open the new call (protected and covered at every step); its checks add the roll's net per share, and with no best candidate both held legs' closes are quoted. A ticket for one pair names its expiration and both strikes. - Any other structure is NOT_APPLICABLE with its reason; a vertical's roll is a ROLL ticket the owner names, at the same width (`aegis-ticket-and-unwind-order`). - Weekly expirations: a section with `expirations = "weekly"` adds the week-end expirations (a Friday, or the Thursday before a holiday Friday) to the standard monthlies, in a `dte` window of at most 21 days, and the notes name the mode. Daily expirations are never listed. - An index underlying (the data source cannot quote index options) and the structure's section disabled (`[roll] enabled = false` for a covered call or a cash-secured put, `[protective_put] enabled = false` for a protective put, `[collar] enabled = false` for a collar) are NOT_APPLICABLE too. ```text NOT_APPLICABLE | AG-20261101-06 roll analysis | AG-20261101-06 is a call credit vertical: the roll analysis covers the short call of a covered call, the long put of a protective put, the short put of a cash-secured put and the two legs of a collar; a vertical's roll is a ROLL ticket you name, at the same width ``` ## The replacement set - Every call of every standard monthly expiration that the underlying lists, later than the held call's expiration, with its calendar days to expiry inside `[roll] dte`. With the fixture's window `[40, 75]` from 2026-11-03 that is 2026-12-18 and 2027-01-15. - The window spans at most 90 days, so at most four monthly chains are needed. No new fetch starts once a run has made 40 requests, and a run fetches at most 4 chains. The WMT run above made 7 requests: the quotes (2: stocks and options), the expirations (1) and two chains (2 each: the contract listing, then the snapshots). - If an expiration in the window cannot be served, the analysis is UNAVAILABLE: no best candidate is named on partial data. If not one candidate can be priced, it is UNAVAILABLE too: `no candidate in your window could be priced`, with the reason. - A window that holds no listed standard monthly is NOT_APPLICABLE. Synthetic, a copy whose `[roll] dte` is `[80, 100]`: `no listed standard monthly expiration lies inside your roll window of 80 to 100 calendar days`. ## The objective and the score The roll's objective is `extrinsic_per_day`: the bid's time value per calendar day, in percent of the share price. - Time value E = bid - max(0, S - K), with S the underlying's mid and K the strike. The score is E / S / T x 100, with T the calendar days to expiry, quantized to 4 decimals. Higher ranks first. - It uses only the fresh bid the owner could expect, the spot and the strike. It carries no forecast and no claim about how the trade turns out. The fixed line says so: `the score ranks the candidates only on the objective you chose; it is not a forecast`. - Ties break in a fixed order: the net credit (higher first), the absolute delta (lower first), the expiration (earlier first), the strike (higher first), then the contract. A tie that was broken prints `tie on extrinsic_per_day broken by `. ## Statuses and labels Each candidate gets one status, with every reason listed (the JSON's `status` and `reasons`): | Status | Meaning | | --- | --- | | `ELIGIBLE` | it passed every criterion | | `FAILS_CRITERION` | it fails `credit_only`, `strike_floor`, `earnings` or `ex_dividend` | | `OUTSIDE_BANDS` | it falls outside `dte`, `abs_delta`, `min_credit` or `max_spread_pct` | | `UNPRICED` | its quote cannot price it: missing, stale, one side stale, crossed, a zero bid, too wide, listed more than once with different quotes, or no implied volatility | The precedence is UNPRICED, then OUTSIDE_BANDS, then FAILS_CRITERION, then ELIGIBLE. The list puts ELIGIBLE first, then FAILS_CRITERION and OUTSIDE_BANDS (each by score and tie-breaks), then UNPRICED. In the text both failing tiers print alike: a red status mark naming the keys, and under the candidates list of an answer with no best candidate, ` fail : `; an unpriced quote prints `not priced` and ` not priced: `. The counts keep the unpriced apart (` not priced`): a candidate the desk could not price was never judged against the criteria. | Key | Fails when (the fixture's value) | Its words in the text | | --- | --- | --- | | `credit_only` | the roll is a net debit; a zero net passes (`true`) | `a net debit of ` | | `strike_floor` | the new strike is below the held strike and below the stock cost (`cost_basis`) | `strike below your stock cost ` | | `earnings` | an earnings release falls after the held call's cutoff and no later than the new call's; a release after the close on the new call's last trading day counts (`exclude`) | `earnings on (