thetabook 2.2.3__tar.gz → 2.4.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (144) hide show
  1. {thetabook-2.2.3 → thetabook-2.4.0}/CHANGELOG.md +514 -0
  2. {thetabook-2.2.3 → thetabook-2.4.0}/CLAUDE.md +9 -5
  3. {thetabook-2.2.3 → thetabook-2.4.0}/CONTRIBUTING.md +7 -6
  4. {thetabook-2.2.3 → thetabook-2.4.0}/PKG-INFO +2 -2
  5. {thetabook-2.2.3 → thetabook-2.4.0}/README.md +54 -14
  6. {thetabook-2.2.3 → thetabook-2.4.0}/ROADMAP.md +37 -3
  7. {thetabook-2.2.3 → thetabook-2.4.0}/pyproject.toml +10 -3
  8. thetabook-2.4.0/scripts/demo.sh +488 -0
  9. thetabook-2.4.0/src/thetabook/CLAUDE.md +55 -0
  10. thetabook-2.4.0/src/thetabook/analysis/vrp.py +181 -0
  11. thetabook-2.4.0/src/thetabook/backtest/__init__.py +17 -0
  12. thetabook-2.4.0/src/thetabook/backtest/data.py +418 -0
  13. thetabook-2.4.0/src/thetabook/backtest/engine.py +123 -0
  14. thetabook-2.4.0/src/thetabook/backtest/grid.py +531 -0
  15. thetabook-2.4.0/src/thetabook/backtest/manifest.py +302 -0
  16. thetabook-2.4.0/src/thetabook/backtest/metrics.py +240 -0
  17. thetabook-2.4.0/src/thetabook/backtest/report.py +732 -0
  18. thetabook-2.4.0/src/thetabook/backtest/signals.py +112 -0
  19. thetabook-2.4.0/src/thetabook/backtest/strategies/__init__.py +122 -0
  20. thetabook-2.4.0/src/thetabook/backtest/strategies/dual_momentum.py +115 -0
  21. thetabook-2.4.0/src/thetabook/backtest/strategies/sector_rotation.py +173 -0
  22. {thetabook-2.2.3 → thetabook-2.4.0}/src/thetabook/cli/__init__.py +3 -0
  23. {thetabook-2.2.3 → thetabook-2.4.0}/src/thetabook/cli/_shared.py +40 -3
  24. {thetabook-2.2.3 → thetabook-2.4.0}/src/thetabook/cli/adjust.py +2 -9
  25. thetabook-2.4.0/src/thetabook/cli/backtest.py +334 -0
  26. {thetabook-2.2.3 → thetabook-2.4.0}/src/thetabook/cli/bs.py +16 -6
  27. {thetabook-2.2.3 → thetabook-2.4.0}/src/thetabook/cli/chain.py +8 -5
  28. {thetabook-2.2.3 → thetabook-2.4.0}/src/thetabook/cli/em.py +16 -4
  29. {thetabook-2.2.3 → thetabook-2.4.0}/src/thetabook/cli/evaluate.py +8 -0
  30. thetabook-2.4.0/src/thetabook/cli/greeks.py +59 -0
  31. {thetabook-2.2.3 → thetabook-2.4.0}/src/thetabook/cli/hv.py +10 -0
  32. {thetabook-2.2.3 → thetabook-2.4.0}/src/thetabook/cli/leg_mark.py +2 -1
  33. {thetabook-2.2.3 → thetabook-2.4.0}/src/thetabook/cli/positions.py +10 -3
  34. {thetabook-2.2.3 → thetabook-2.4.0}/src/thetabook/cli/roll.py +4 -2
  35. {thetabook-2.2.3 → thetabook-2.4.0}/src/thetabook/cli/skills.py +3 -3
  36. thetabook-2.4.0/src/thetabook/cli/vrp.py +134 -0
  37. {thetabook-2.2.3 → thetabook-2.4.0}/src/thetabook/config.py +72 -1
  38. thetabook-2.4.0/src/thetabook/ideas/adjust.py +1976 -0
  39. thetabook-2.4.0/src/thetabook/ideas/core.py +1413 -0
  40. thetabook-2.4.0/src/thetabook/ideas/evaluate_idea.py +1515 -0
  41. {thetabook-2.2.3 → thetabook-2.4.0}/src/thetabook/ideas/manage_ideas.py +7 -0
  42. thetabook-2.4.0/src/thetabook/ideas/roll_scenarios.py +896 -0
  43. thetabook-2.4.0/src/thetabook/leg_parse.py +534 -0
  44. {thetabook-2.2.3 → thetabook-2.4.0}/src/thetabook/market/_schwab.py +29 -0
  45. {thetabook-2.2.3 → thetabook-2.4.0}/src/thetabook/market/bars.py +225 -87
  46. {thetabook-2.2.3 → thetabook-2.4.0}/src/thetabook/market/chains.py +89 -11
  47. {thetabook-2.2.3 → thetabook-2.4.0}/src/thetabook/market/dividends.py +41 -3
  48. thetabook-2.4.0/src/thetabook/market/leg_inputs.py +168 -0
  49. {thetabook-2.2.3 → thetabook-2.4.0}/src/thetabook/market/leg_marks.py +5 -2
  50. {thetabook-2.2.3 → thetabook-2.4.0}/src/thetabook/market/prices.py +173 -7
  51. thetabook-2.4.0/src/thetabook/market/vol_lookup.py +527 -0
  52. {thetabook-2.2.3 → thetabook-2.4.0}/src/thetabook/models.py +216 -12
  53. {thetabook-2.2.3 → thetabook-2.4.0}/src/thetabook/paths.py +82 -1
  54. {thetabook-2.2.3 → thetabook-2.4.0}/src/thetabook/portfolio/accounts.py +303 -106
  55. {thetabook-2.2.3 → thetabook-2.4.0}/src/thetabook/portfolio/csv_parsers/empower.py +4 -0
  56. {thetabook-2.2.3 → thetabook-2.4.0}/src/thetabook/portfolio/csv_parsers/fidelity.py +36 -9
  57. {thetabook-2.2.3 → thetabook-2.4.0}/src/thetabook/portfolio/csv_parsers/schwab.py +6 -0
  58. {thetabook-2.2.3 → thetabook-2.4.0}/src/thetabook/portfolio/diff_snapshots.py +12 -8
  59. {thetabook-2.2.3 → thetabook-2.4.0}/src/thetabook/portfolio/get_positions.py +0 -32
  60. thetabook-2.2.3/src/thetabook/pricing/greeks.py → thetabook-2.4.0/src/thetabook/portfolio/greeks_book.py +168 -299
  61. {thetabook-2.2.3 → thetabook-2.4.0}/src/thetabook/portfolio/options_book.py +217 -124
  62. thetabook-2.4.0/src/thetabook/pricing/leg_greeks.py +76 -0
  63. {thetabook-2.2.3 → thetabook-2.4.0}/src/thetabook/skills/lint.py +6 -4
  64. {thetabook-2.2.3 → thetabook-2.4.0}/src/thetabook/skills/parse.py +14 -0
  65. {thetabook-2.2.3 → thetabook-2.4.0}/src/thetabook/skills/policy.py +7 -0
  66. {thetabook-2.2.3 → thetabook-2.4.0}/src/thetabook/skills/render.py +3 -3
  67. {thetabook-2.2.3 → thetabook-2.4.0}/src/thetabook/templates/config.toml.example +15 -0
  68. {thetabook-2.2.3 → thetabook-2.4.0}/src/thetabook/templates/idea.md +10 -2
  69. {thetabook-2.2.3 → thetabook-2.4.0}/src/thetabook/templates/journal.md +1 -1
  70. thetabook-2.4.0/src/thetabook/tickers.py +464 -0
  71. {thetabook-2.2.3 → thetabook-2.4.0}/src/thetabook/wiki/render.py +15 -1
  72. {thetabook-2.2.3 → thetabook-2.4.0}/uv.lock +123 -148
  73. thetabook-2.2.3/src/thetabook/CLAUDE.md +0 -46
  74. thetabook-2.2.3/src/thetabook/analysis/vrp.py +0 -145
  75. thetabook-2.2.3/src/thetabook/cli/greeks.py +0 -46
  76. thetabook-2.2.3/src/thetabook/cli/vrp.py +0 -80
  77. thetabook-2.2.3/src/thetabook/ideas/adjust.py +0 -1279
  78. thetabook-2.2.3/src/thetabook/ideas/core.py +0 -486
  79. thetabook-2.2.3/src/thetabook/ideas/evaluate_idea.py +0 -992
  80. thetabook-2.2.3/src/thetabook/ideas/roll_scenarios.py +0 -572
  81. thetabook-2.2.3/src/thetabook/leg_parse.py +0 -201
  82. thetabook-2.2.3/src/thetabook/market/vol_lookup.py +0 -223
  83. thetabook-2.2.3/src/thetabook/tickers.py +0 -218
  84. {thetabook-2.2.3 → thetabook-2.4.0}/.env.example +0 -0
  85. {thetabook-2.2.3 → thetabook-2.4.0}/.git-blame-ignore-revs +0 -0
  86. {thetabook-2.2.3 → thetabook-2.4.0}/.github/workflows/ci.yml +0 -0
  87. {thetabook-2.2.3 → thetabook-2.4.0}/.github/workflows/publish.yml +0 -0
  88. {thetabook-2.2.3 → thetabook-2.4.0}/.gitignore +0 -0
  89. {thetabook-2.2.3 → thetabook-2.4.0}/.python-version +0 -0
  90. {thetabook-2.2.3 → thetabook-2.4.0}/AGENTS.md +0 -0
  91. {thetabook-2.2.3 → thetabook-2.4.0}/LICENSE +0 -0
  92. {thetabook-2.2.3 → thetabook-2.4.0}/SECURITY.md +0 -0
  93. {thetabook-2.2.3 → thetabook-2.4.0}/src/thetabook/__init__.py +0 -0
  94. {thetabook-2.2.3 → thetabook-2.4.0}/src/thetabook/analysis/__init__.py +0 -0
  95. {thetabook-2.2.3 → thetabook-2.4.0}/src/thetabook/analysis/em.py +0 -0
  96. {thetabook-2.2.3 → thetabook-2.4.0}/src/thetabook/analysis/hv.py +0 -0
  97. {thetabook-2.2.3 → thetabook-2.4.0}/src/thetabook/analysis/scenarios.py +0 -0
  98. {thetabook-2.2.3 → thetabook-2.4.0}/src/thetabook/analysis/ta.py +0 -0
  99. {thetabook-2.2.3 → thetabook-2.4.0}/src/thetabook/cache.py +0 -0
  100. {thetabook-2.2.3 → thetabook-2.4.0}/src/thetabook/cli/CLAUDE.md +0 -0
  101. {thetabook-2.2.3 → thetabook-2.4.0}/src/thetabook/cli/accounts.py +0 -0
  102. {thetabook-2.2.3 → thetabook-2.4.0}/src/thetabook/cli/bars.py +0 -0
  103. {thetabook-2.2.3 → thetabook-2.4.0}/src/thetabook/cli/diff.py +0 -0
  104. {thetabook-2.2.3 → thetabook-2.4.0}/src/thetabook/cli/dividends.py +0 -0
  105. {thetabook-2.2.3 → thetabook-2.4.0}/src/thetabook/cli/earnings.py +0 -0
  106. {thetabook-2.2.3 → thetabook-2.4.0}/src/thetabook/cli/ideas.py +0 -0
  107. {thetabook-2.2.3 → thetabook-2.4.0}/src/thetabook/cli/import_csv.py +0 -0
  108. {thetabook-2.2.3 → thetabook-2.4.0}/src/thetabook/cli/init.py +0 -0
  109. {thetabook-2.2.3 → thetabook-2.4.0}/src/thetabook/cli/migrate_home.py +0 -0
  110. {thetabook-2.2.3 → thetabook-2.4.0}/src/thetabook/cli/price.py +0 -0
  111. {thetabook-2.2.3 → thetabook-2.4.0}/src/thetabook/cli/refresh.py +0 -0
  112. {thetabook-2.2.3 → thetabook-2.4.0}/src/thetabook/cli/scenarios.py +0 -0
  113. {thetabook-2.2.3 → thetabook-2.4.0}/src/thetabook/cli/snapshot.py +0 -0
  114. {thetabook-2.2.3 → thetabook-2.4.0}/src/thetabook/cli/ta.py +0 -0
  115. {thetabook-2.2.3 → thetabook-2.4.0}/src/thetabook/cli/tickers.py +0 -0
  116. {thetabook-2.2.3 → thetabook-2.4.0}/src/thetabook/cli/wiki.py +0 -0
  117. {thetabook-2.2.3 → thetabook-2.4.0}/src/thetabook/ideas/__init__.py +0 -0
  118. {thetabook-2.2.3 → thetabook-2.4.0}/src/thetabook/log.py +0 -0
  119. {thetabook-2.2.3 → thetabook-2.4.0}/src/thetabook/market/__init__.py +0 -0
  120. {thetabook-2.2.3 → thetabook-2.4.0}/src/thetabook/market/earnings.py +0 -0
  121. {thetabook-2.2.3 → thetabook-2.4.0}/src/thetabook/portfolio/__init__.py +0 -0
  122. {thetabook-2.2.3 → thetabook-2.4.0}/src/thetabook/portfolio/csv_parsers/__init__.py +0 -0
  123. {thetabook-2.2.3 → thetabook-2.4.0}/src/thetabook/portfolio/csv_parsers/_base.py +0 -0
  124. {thetabook-2.2.3 → thetabook-2.4.0}/src/thetabook/portfolio/import_csv_snapshot.py +0 -0
  125. {thetabook-2.2.3 → thetabook-2.4.0}/src/thetabook/portfolio/scaffold.py +0 -0
  126. {thetabook-2.2.3 → thetabook-2.4.0}/src/thetabook/preflight.py +0 -0
  127. {thetabook-2.2.3 → thetabook-2.4.0}/src/thetabook/pricing/__init__.py +0 -0
  128. {thetabook-2.2.3 → thetabook-2.4.0}/src/thetabook/pricing/bs.py +0 -0
  129. {thetabook-2.2.3 → thetabook-2.4.0}/src/thetabook/skills/__init__.py +0 -0
  130. {thetabook-2.2.3 → thetabook-2.4.0}/src/thetabook/skills/install.py +0 -0
  131. {thetabook-2.2.3 → thetabook-2.4.0}/src/thetabook/skills/models.py +0 -0
  132. {thetabook-2.2.3 → thetabook-2.4.0}/src/thetabook/skills/registry.py +0 -0
  133. {thetabook-2.2.3 → thetabook-2.4.0}/src/thetabook/templates/README.md +0 -0
  134. {thetabook-2.2.3 → thetabook-2.4.0}/src/thetabook/templates/accounts.toml.example +0 -0
  135. {thetabook-2.2.3 → thetabook-2.4.0}/src/thetabook/templates/learnings.md +0 -0
  136. {thetabook-2.2.3 → thetabook-2.4.0}/src/thetabook/templates/skill.md +0 -0
  137. {thetabook-2.2.3 → thetabook-2.4.0}/src/thetabook/templates/skills/setup-thetabook.md +0 -0
  138. {thetabook-2.2.3 → thetabook-2.4.0}/src/thetabook/templates/wiki/index.md +0 -0
  139. {thetabook-2.2.3 → thetabook-2.4.0}/src/thetabook/templates/wiki/log.md +0 -0
  140. {thetabook-2.2.3 → thetabook-2.4.0}/src/thetabook/templates/wiki/overview.md +0 -0
  141. {thetabook-2.2.3 → thetabook-2.4.0}/src/thetabook/templates/wiki/strategy.md +0 -0
  142. {thetabook-2.2.3 → thetabook-2.4.0}/src/thetabook/templates/wiki/underlying.md +0 -0
  143. {thetabook-2.2.3 → thetabook-2.4.0}/src/thetabook/wiki/__init__.py +0 -0
  144. {thetabook-2.2.3 → thetabook-2.4.0}/src/thetabook/wiki/lint.py +0 -0
@@ -5,6 +5,520 @@ All notable changes to this project are recorded here. Format loosely follows
5
5
 
6
6
  ## [Unreleased]
7
7
 
8
+ ## [2.4.0] — 2026-11-21
9
+
10
+ **M26: duplicated rules consolidated.** Rules that two or more commands each computed with their own code now have one owner each, in #126–#139. **Some numbers change.** `thetabook greeks` uses broker Greeks and a dividend yield per ticker. `evaluate` and `adjust` value option underlyings at a live spot even when the snapshot is fresh. `adjust --save` no longer puts a roll's realized P&L into the risk budget. That covers spot, per-leg Greeks, the horizon expiry, ATM IV, forward/Black-76 inputs, dividend yield, pricing defaults, expired-leg settlement, risk budgets, leg parsing, snapshot rows, event windows and share counting. The entries below marked "(M26)" are the user-visible results. The rule → owner table is in [docs/duplicated-rules-audit.md](docs/duplicated-rules-audit.md#outcome).
11
+
12
+ ### Added
13
+
14
+ - **`[market] rate`, `fallback_vol` and `fallback_div_yield` in `personal/config.toml`** set the risk-free rate, flat fallback vol and dividend yield for every pricing command, with built-in defaults of 0.045, 0.25 and 0.0. `config.py` owns them as `config.DEFAULT_RATE`, `DEFAULT_VOL` and `DEFAULT_DIV_YIELD`, replacing copies in `evaluate`, `adjust`, `greeks`, `roll`, `bs` and the shared CLI help (M26, audit item 11b). `--help` shows the resolved default instead of a hard-coded number. A value out of range, such as a percent written as `rate = 4.5`, warns and falls back. See [behaviors.md](docs/behaviors.md) "Pricing defaults: rate, fallback vol, dividend yield".
15
+ - **`thetabook positions --rate`** sets the rate used to discount a VIX-family forward.
16
+
17
+ ### Changed
18
+
19
+ - **`thetabook greeks` now uses broker Greeks by default and prices each underlying with its own dividend yield, so its numbers change** (M26, audit item 3). It used to recompute every leg with Black-Scholes at one `q` for the whole book (`--div-yield`, else 0), while `evaluate` and `adjust` passed Schwab's Greeks through and priced at each ticker's fetched yield. One short XYZ 105C at S = 100, 60 DTE, chain IV 30%, read −38.99 delta / +4.33 theta in `greeks` and −38.00 / +5.00 in `evaluate`. With no broker Greeks and a 3% yield, `greeks` read −38.99 and `evaluate` −37.26. Both now read −38.00 / +5.00 and −37.26. `greeks` gains `--greeks-source chain|bs` (default `chain`), as on `evaluate` and `adjust`. `--div-yield` still sets one yield for every underlying; without it each one is auto-fetched through `market.dividends.resolve_div_yield`. The footer now lists the Greeks sources (`*Greeks sources: 3 schwab, 1 chain-iv-bs*`) and each option underlying's yield. **A VIX leg is now always recomputed with Black-76 on its expiry's forward, in all three commands**, even under `--greeks-source chain`: Schwab's VIX deltas exceed 1.0 on deep ITM calls, and `evaluate` and `adjust` used to pass them through (a short 2× VIX 10C read −224 delta, beyond the −200 a 2-lot can carry; it now reads −198.85, as `greeks` did). One owner, split by layer: `market.leg_inputs.resolve_leg_inputs` decides the inputs and `pricing.leg_greeks.leg_greeks` does the arithmetic. `core.compute_greeks` and `aggregate_greeks` both call the pair, and `pricing.greeks.compute_position_greeks` is gone. Broker Greeks are now validated before any of the three commands uses them. A Schwab `-999` sentinel row used to read +99,900 delta on one short contract in `evaluate` and `adjust`, and a row with zero gamma / theta / vega read 0 / 0 / 0. A row is refused if:
20
+ - delta is outside [−1, 1];
21
+ - gamma or vega is negative;
22
+ - any value is a `-999` sentinel;
23
+ - gamma, theta and vega are all zero on a live contract.
24
+
25
+ A refused row is priced with Black-Scholes, tagged `bs (broker greeks rejected)`, with one warning per run naming the contracts. `compute_greeks` no longer rounds per leg. Rounding is display-only, and `evaluate`'s Net row and `greeks`' TOTAL row are the sum of the rounded rows shown above them. `greeks --no-fetch` help now says option chains and dividend yields are still fetched. See [behaviors.md](docs/behaviors.md) "One leg's Greeks: one owner".
26
+ - **`evaluate` and `adjust` ask one function which dividend yield to price an underlying with** (M26, audit item 11a). Each held an identical copy of the sequence: `--div-yield`, else the fetched yield, else `[market] fallback_div_yield`. `market.dividends.resolve_div_yield` now owns it, with the same `override` / `auto` / `default` labels and the same warning on a failed fetch, so output is unchanged. A refinement such as `q = r` for forward-settled underlyings now lands in both commands at once. `roll` now uses it too (see Fixed). `greeks` moved onto it later in M26 (see the `thetabook greeks` entry above). See [behaviors.md](docs/behaviors.md) "Which yield an underlying is priced with: one owner".
27
+ - **Three duplicated rules whose copies agreed now have one owner each; output is unchanged** (M26, audit 12a and the leftovers of 12b). `ideas.core.classify_event` owns the `none` / `in_window` / `after_expiry` / `failed` taxonomy for earnings and ex-dividend dates, which `evaluate` and `adjust` each inlined twice. `core.check_event` wraps it with the fetch and the `lookup failed` warning. The window stays `[today, max_expiry]`, closed at both ends: an event today or on the expiry date is in window, the day after expiry is `after_expiry`, and anything before today is `none`. `market.vol_lookup.prices_off_forward` owns "does this leg get a forward" (forward-settled and `days_to_expiry > 0`). `VolResolver.bs_inputs` reads it, as do `positions`' three copies: forward resolution, the `fwd` column and the `--no-fetch` warning. `analysis.vrp.select_expiry` counts DTE with `models.days_to_expiry` instead of an inline copy. See [behaviors.md](docs/behaviors.md) "Earnings and ex-div windows: one owner" and "Black-Scholes inputs: one owner".
28
+ - **`/diff` slash command renamed to `/snapshot-diff`** (`.claude/commands/snapshot-diff.md`). The bare `/diff` name collided with Claude Code's diff-panel plugin, which refused to register and disabled its panel for the session. The `thetabook diff` CLI subcommand is unchanged.
29
+ - **`.claude/commands/` now passes `thetabook skills lint` with no errors.** Every command declares `name`, and the wording of `/accounts-init` and `/close` avoids ticker-shaped words beside `personal/` paths.
30
+ - **`skill-personal-pii-in-body` ignores the `YYYY`, `MM`, `DD` and `NNN` path placeholders.** A real ticker on the same line still fires.
31
+ - **`pricing/` is pure, and `greeks` aggregation moved to `portfolio/greeks_book.py`** (M26, audit item 10). `pricing/greeks.py` loaded snapshots and fetched spot, chains and dividend yields, so `pricing/` imported `market/`, `portfolio/` and `paths`, against the one-way layer rule. `aggregate_greeks`, `format_greeks_markdown`, `load_snapshot` and the equity extractors now live in `thetabook.portfolio.greeks_book`; `pricing/` keeps `bs` and `leg_greeks`, and strict mypy covers `thetabook.pricing.*`. The unused argparse `main()` is gone (`thetabook greeks` is the entry point). `validate_option_symbol` moved from `portfolio/get_positions.py` to `leg_parse.py`, beside the regex it wraps. `tests/pricing/test_layer_rule.py` fails if a `pricing` module imports a higher layer or a network library, directly (`ast`) or transitively (a fresh interpreter's `sys.modules`).
32
+ - **Share counts in `greeks` and `positions --equity` floor, as `adjust`'s always did** (M26, audit item 12d). They used `int()`, which truncates, so −10.5 shares showed −10 there and −11 in `adjust`. Every displayed count is now `leg_parse.whole_shares` of the exact quantity: −11 in all three, and `greeks`' TOTAL shares is the sum of the floored rows. Delta still uses the exact −10.5, and so does the check that decides whether `greeks` prints its concentration and SPY-equivalent warnings. See [behaviors.md](docs/behaviors.md) "Share legs in idea files".
33
+
34
+ ### Fixed
35
+
36
+ - **`greeks` no longer crashes on an option row with no OCC symbol and no expiration date, and `adjust BRKB` finds the `BRK/B` positions** (M26, audit item 10). `greeks`, `positions` and `adjust` each read the snapshot's option rows with their own copy of the rule. A row with neither a parsable symbol nor `optionExpirationDate` was skipped by `positions` and `adjust` but kept by `greeks`, which raised `TypeError: fromisoformat: argument must be str` and printed nothing. `adjust` matched the underlying by exact string, so `adjust BRKB --close …` exited `No BRKB … position found in snapshot` on a book `greeks` showed holding `BRK/B`. One owner now: `leg_parse.snapshot_option_rows` for option rows and `models.snapshot_share_rows` for share rows, typed and `tickers.canonicalize`'d. A row missing an underlying, expiration, call/put or strike is skipped with a warning naming the command and what was missing, in all three. `adjust` canonicalizes its argument, so `adjust BRKB` reports `BRK/B`. Other visible changes from the same rule:
37
+ - `roll BRKB` finds the `BRK/B` short legs (it exited `No short C positions on BRKB in snapshot`).
38
+ - A snapshot that spells one ticker two ways, such as shares as `BRKB` and options on `BRK/B`, now shows one `BRK/B` underlying in `greeks` and `positions`. Its shares and options sit on one row, so Opt Pos and delta change and the `No price for BRK/B` warning goes away. The snapshot spot fallback (`resolve_spot`, `core.stock_price_from_snapshot`) looks a ticker up by its canonical form too, so `evaluate` / `adjust` on a `BRKB` idea find shares held under either spelling.
39
+ - A flat option row (long = short) is skipped before its symbol is read, so an unparseable symbol on it no longer warns.
40
+
41
+ On a book with none of these, `greeks`, `positions` and `adjust` print the same output as before. See [behaviors.md](docs/behaviors.md) "Which positions a snapshot holds: one owner".
42
+ - **`accounts check-idea` reads an idea's legs with the parser `evaluate` uses** (M26, audit item 9). It scanned the whole body for any line shaped like a contract with a `qty=`, while `evaluate` reads only `## Structure`. A single short XYZ 90 P plus an exit-plan line `XYZ 2027-01-15 90 P qty=+1 buy back at 50%` was one leg to `evaluate` and two to `check-idea`, which deferred a "multi-leg" structure, so an account forbidding `naked-put` raised nothing. `accounts.read_structure` now calls `leg_parse.parse_structure_body`, and the naked-leg label, the declared cover, the constructive-sale note and the cover hint all read that one parse. Share legs come through as `StockLeg`s, and long shares on the short call's underlying cover it inside `is_naked_short`. `accounts.structure_shares`, `accounts.extract_legs_from_body`, the `accounts.Leg` dataclass and `leg_parse.find_legs_in_text` are gone. **Legs written outside `## Structure` no longer count**, so an idea whose legs are only in a bullet list elsewhere now gets a new `structure` finding instead of a leg check. That finding appears when the section can't be read: on every account when the parser refuses it (say, a share line without `cost_basis=`), and on an account with a `naked-*` ban when the section is missing or lists no legs. See [behaviors.md](docs/behaviors.md) "Which legs an idea holds: one owner".
43
+ - **`vrp`, `em --source iv`, `evaluate` and `adjust` read one ATM implied vol** (M26, audit item 6). There were two estimators. `vrp` and `em` took the strike nearest spot with any truthy IV, which let Schwab's `-999` sentinel (`-9.99` after the chain's `/100`) through: with it on the ATM call, `vrp` read an ATM IV of −484.5% and a negative IV/HV ratio, and `em --source iv` crashed with `sigma must be non-negative (got -4.845)`. `evaluate` and `adjust` paired the nearest call and the nearest put independently, so with no IV on the ATM put they averaged the 100 call with the 105 put. `market.vol_lookup.atm_iv_from_chain` now owns the estimator for all four: among strikes within `spot ± max(10%, $5)`, the call+put straddle at the strike nearest spot where both sides carry a finite, positive IV; failing that, the nearest single usable side; ties to the lower strike. The window is in the owner so `evaluate`'s full chain and `vrp`'s windowed fetch see the same strikes. A chain with usable IV only outside it is a miss: `vrp`/`em` exit 1, and `evaluate`/`adjust` show `(flat)`. `vrp.atm_iv` is a thin wrapper over it and returns an `AtmIv` (`iv`, `strike`, `basis`) instead of a `(strike, iv)` tuple. On the 100-put-missing chain `vrp`/`em` move from 0.30 to 0.33; on the sentinel chain from −4.845 to 0.33, and `evaluate`/`adjust` from 0.30 to 0.33. **`evaluate`/`adjust` PoP and `vrp`/`em` figures can shift slightly** on any chain where the two estimators used to differ. A chain with no usable IV still exits 1 from `vrp` and `em` with the same message, now including an all-sentinel chain, which used to crash. A chain served by yfinance alone is now refused by `vrp` and `em --source iv` with a `chain came from yfinance only` warning. Before, any positive yfinance `impliedVolatility` was used, despite the documented Greeks-bearing-source contract. `fetch_chain` rows (and `thetabook chain --json`) now carry a `source` field naming the source that served them. `vrp` names the basis (`call+put avg`, `call only`, `put only`) and `em` labels a single-side IV. See [behaviors.md](docs/behaviors.md) "ATM implied vol: one owner".
44
+ - **`evaluate` and `adjust` now use a live spot for an option underlying even when the snapshot is fresh** (M26, audit item 2). They used the snapshot's share price while `snapshot_is_stale` said it was fresh, which only means "taken after the last 4pm ET close", and fetched only when it was stale. `greeks` and `positions` have always fetched an option underlying live (#72), so a fresh snapshot at 100 against a live 104 gave `greeks` 104 and `evaluate` `Stock price $100.00` for the same short 105 C. All four now read 104. `market.prices.resolve_spot` owns the rule for `evaluate`, `adjust`, `greeks`, `positions` and `roll`. An override (`--stock-price`, `--prices`) wins. Otherwise an option underlying is fetched live, and the snapshot price is the fallback, with a new `no live quote for XYZ; using the snapshot price …` warning. Share-only tickers keep the old rule. An underlying held only as options, with no share row, no longer makes a fresh-snapshot `evaluate` or `adjust` exit 1 with "Could not determine stock price". It gets the live quote, as the stale path and `greeks` already did. With no snapshot at all, `evaluate` now fetches instead of exiting. `evaluate` and `adjust` print the source of a live spot (`XYZ $104.00 — source: Schwab (real-time)`). `greeks` and `positions` now treat a live quote of 0 as a miss, where `greeks` used to take it. A zero or negative override (`--prices XYZ=0`, `--stock-price 0`) now leaves the ticker unpriced, with a warning: `greeks` skips its option Greeks, and `evaluate` / `adjust` exit 1. Before, it reached Black-Scholes and crashed with `ValueError: math domain error` whenever the underlying had options. With XYZ held in two accounts whose snapshot rows imply different prices, the snapshot fallback in `greeks` and `positions` (`--no-fetch`, or a live miss) now takes the first account's row, as `evaluate`, `adjust` and `greeks`' own share extraction already did. Before, it took the last. `market.prices.parse_prices` is the one `--prices` parser, replacing copies in `evaluate` and `greeks`, with the same warnings. `em` and `vrp` are unchanged. See [behaviors.md](docs/behaviors.md) "Which spot an option position is valued at: one owner".
45
+ - **Every command reads the same "latest" snapshot** (M26, audit item 12c). There were four loaders with four error policies, and only `thetabook snapshot` and `accounts totals` / `check-portfolio` had the worktree fallback to the main repo's `personal/snapshots/latest.json`. From a worktree with no `latest.json` of its own, `evaluate`, `adjust`, `roll`, `greeks`, `positions` and the per-account checks saw no snapshot while `thetabook snapshot` reported one. `paths.load_snapshot` is now the one loader, and each caller picks its policy for a missing or corrupt file: `raise` (`evaluate`, `adjust`, `roll`, `diff`), `warn` (per-account checks) or `exit` (`greeks`, `positions`, `accounts totals`, `check-portfolio`). A corrupt snapshot under `greeks` or `positions` prints one `Error:` line instead of a traceback. An explicit `$THETABOOK_HOME` now switches the worktree fallback off. Before, a worktree run with `THETABOOK_HOME` pointing at an empty home read the main repo's real snapshot from `thetabook snapshot` and `accounts totals` while `--date` read the empty home. See [behaviors.md](docs/behaviors.md) "Loading a snapshot: one owner".
46
+ - **`roll` prices off the shared owners for marks, IV, dividend yield and Black-Scholes inputs** (M26, audit item 5). `roll` (`ideas/roll_scenarios.py`) had private copies of each, and they broke on rows the owners already handle. A `0.0` chain IV, common on yfinance, raised `ZeroDivisionError`. Schwab's `-999` no-IV sentinel printed `IV=-999.0%` and a `BS model net: +77.95/sh` on a $2.60 option. A missing bid became a fake mid, so bid 0 / ask 2.70 read as 1.35. Per leg, `roll` now uses:
47
+ - `core.chain_pick` for the mark (mid, else last trade);
48
+ - `VolResolver.resolve_leg_iv` for IV;
49
+ - `market.dividends.resolve_div_yield` for `q`, with `--div-yield` as the override;
50
+ - `VolResolver.bs_inputs` for the BS price and `q`.
51
+
52
+ The two bad-IV rows above now price at the flat `[market] fallback_vol`, read `IV=25.0% (flat default)`, give a BS net of −0.06/sh, and warn. What still errors and what now falls back:
53
+ - **Exits 1, as before:** a requested `--open` or `--close` strike with no chain row at all, which is usually a typo (unless it's a closing strike the snapshot holds, which takes the snapshot's mark); a live expiry whose chain is empty or whose fetch failed; `--open` at a past expiry. A `--also` strike with no row is still skipped with a warning, but the `Option A (...)` label no longer names it. With no `--also` strike on the chain, the comparison is skipped with a warning, where it used to print an empty grid.
54
+ - **Falls back, labelled and warned:** a row with zero or sentinel IV takes the flat IV. A row with no bid/ask takes the last trade, then the snapshot's mark for a closing leg, then a Black-Scholes estimate, or intrinsic for a leg expiring today.
55
+ - **Settles:** a closing leg past expiry settles through `core.Settler`, as in `adjust`: intrinsic at the expiry-date close, or spot with a warning. That fixed amount is its close cost across the grid, and neither the chain nor the snapshot is asked. A short 95 C that expired yesterday with spot at 100 and a stale 0.40 snapshot mark reads as a −3.90/sh debit. `main` exited 1 on it.
56
+
57
+ A dividend payer is priced with its fetched yield, shown as `Div yield: 3.1% (auto)`. It was `q = 0`. A VIX roll prices each leg off its expiry's parity forward with `q = r` and names the forward. It priced off spot. `load_positions_for_underlying` moves from `adjust` into `ideas/core.py`, and `adjust` re-exports it, so `roll_scenarios` no longer imports from `adjust` or `evaluate_idea`. Leg rows now read `mark=… (source) IV=… (source)`, and the cost line reads `Market roll cost (N leg(s) not at chain mid)` when a leg wasn't marked at mid. See [behaviors.md](docs/behaviors.md) "`roll` inputs: on the shared owners".
58
+ - **`evaluate --days` prices VIX legs off the forward** (M26). The mid-curve priced each leg off spot with the dividend yield, while the same run's Greeks and PoP used the parity forward with `q = r` (Black-76). On a long VIX 15C marked at its 3.98 mid against an 18.40 forward, T+0 at spot read −$187.18 instead of ≈ $0. Each row's spot `p` now prices off `p · F/S`. `VolResolver.bs_inputs` is the one owner of which price and `q` a leg's Black-Scholes takes. It replaces copies in `compute_greeks`, `adjust` (`leg_underlying_px` is now `leg_bs_inputs`, which also returns `q_eff`) and `aggregate_greeks`. `days_to_expiry` moves to `models.py`, replacing two definitions and eight inline copies (audit item 12b). See [behaviors.md](docs/behaviors.md) "Black-Scholes inputs: one owner".
59
+ - **`evaluate` settles option legs past expiry, as `adjust` does** (M26). `evaluate` kept an expired leg in its payoff, extremes, breakevens, Greeks, marks walk and price domain. An expired short 150 P beside a 30-day 160/170 call spread at S = 160 read max loss −$15,050, while `adjust` read −$50 for the same legs: the spread's −$250 debit plus the put's +$200, which expired worthless. `core.settle_position` now owns the split for both commands, built on `core.Settler` / `settle_into`. An in-the-money equity or ETF leg becomes its share delivery, and anything else becomes cash at intrinsic on the expiry-date close. The option itself drives nothing. Both commands now read −$50 / +$950 / PoP 48.9% / DTE 30 on that position. A new `Settled legs` row names each settled leg, what it was settled against and what it became. The spot fallback warns as it does in `adjust`. A live-marks run measures from today, so it leaves settled cash out. The expired leg is no longer walked for a quote, so it can't turn a run `live-with-misses`. A position whose every leg has expired evaluates as its realized cash and any delivered shares. The write-once `max_gain` / `max_loss` budget comes from the structure alone: the open legs plus any delivered shares, never settled cash. Every budget writer (first seed, `--reseed-budget`, the ±inf heal, the #99 migration) reads it. Before, a naked short AAPL 200 C that expired worthless healed its `-.inf` budget to `max_loss: 300.0`, the realized profit, which `check_idea` then sized as a $300 loss. An SPX position seeded −$10,000 frozen and −$2,000 live; both modes now seed −$2,000. Share legs net per underlying before the budget is measured (`core.open_structure`), so shares a delivery closed carry their locked-in P&L into neither extreme. A covered call called away beside an open 160/170 call spread seeded `max_loss: 0.0` and can now bind at −$250. With every leg settled and nothing open after netting, the budget is left as it is, `--reseed-budget` included, and the run says so. A budget `max_loss` is never written above $0. The #99 migration is skipped while a leg is settled. `evaluated_max_*` keep the settled cash. `check_idea` now reads a positive `evaluated_max_loss` as no loss, where its `abs()` used to make that a loss. The double-count hint for shares listed beside a delivery now tells a delivery that adds to them from a covered call called away. See [behaviors.md](docs/behaviors.md) "Expired legs in `evaluate` and `adjust`: one owner".
60
+ - **`evaluate` and `adjust` agree on which expiry sets a position's horizon** (M26). `evaluate` took the first-*listed* option leg for its DTE row, ATM IV, forward and PoP `T`, while `adjust` and `evaluate --days DTE` took the shortest-dated leg. A put diagonal (long 100 P at 120 DTE, short 95 P at 30 DTE) read DTE 120 / PoP 36.9% or DTE 30 / PoP 26.7% depending on which line was written first. `core.position_horizon` now owns the choice, the shortest-dated leg that hasn't expired, and all three callers use it. A leg past expiry no longer becomes `evaluate`'s horizon or pins `--days DTE` at 0. See [behaviors.md](docs/behaviors.md) "Position horizon: one owner".
61
+
62
+ - **`adjust --save` budgets no longer include the roll's realized P&L** (M26, audit item 8). `--save` wrote the after-scenario's max profit and max loss into the write-once `max_gain` / `max_loss` budget and into `evaluated_max_*`. Those figures include the closed leg's realized P&L and any cash from legs that settled at expiry, but the saved `## Structure` carries neither. The first `evaluate` of the file measured the Structure alone and disagreed. Write-once and the `analytic` stamp then kept the wrong budget for the life of the file. A roll that realized −$250 and opened a short 95 P at $2.00 saved `max_loss: -9550.0`, and `evaluate` measured −$9,300. It now saves −$9,300 / +$200, and the first `evaluate` leaves both pairs as written. The realized P&L now appears in the file's `## Context` as a `Realized:` line, with the leg each amount came from. `adjust`'s before/after table still includes it. A `--save` that leaves nothing open writes a blank budget, where it used to seed the realized P&L as both `max_gain` and `max_loss`. `core.structure_budget` is the one owner of the budget, shared by `evaluate` and `adjust --save`. `save_as_idea` no longer takes the `before` / `after` scenarios. See [behaviors.md](docs/behaviors.md) "The risk budget of a structure: one owner".
63
+ - **`adjust --save` no longer rounds half strikes** (M26). Strikes were written with `{strike:.0f}`, which rounds half to even, so a roll into a 52.5 put was saved as a 52 put (7.5 → 8, 22.5 → 22). The next `evaluate` priced a contract nobody holds, and that file seeded the write-once `max_gain` / `max_loss` budget. Labels disagreed the same way: `positions` showed 52.5 while `evaluate` and `adjust` showed 52, and `roll-scenarios` truncated with `int()`. `leg_parse.format_option_line` is now the one writer of an option Structure line, and `leg_parse.contract_label` / `format_strike` the one label and strike formatter, used by every command. See [behaviors.md](docs/behaviors.md) "Writing and labelling an option leg".
64
+ - **`positions` derives a VIX forward at the run's rate.** `options_book.resolve_forwards` called `VolResolver.resolve_forward` without a rate, so it took that method's own `0.045` default, while `evaluate --rate 0.05` discounted parity at 5%. The same leg could read two forwards, and so two cushions. `resolve_forward` no longer has a rate default, so every caller must pass one.
65
+ - **`adjust` values contracts at or past expiry correctly.** Three connected defects, all in `ideas/adjust.py`:
66
+ - A contract **past expiry** now settles at intrinsic on the **expiry-date close**, read from the historical-bars backbone (`market.bars.close_on`). An in-the-money contract on an equity or ETF is physically settled, so it becomes its **share delivery** at the strike, premium in the basis (`core.delivery_leg`). Only cash-settled index roots (`tickers.is_cash_settled`) and out-of-the-money contracts become cash. Before, a closing or assigned leg used the snapshot's pre-expiry mark and an opening leg was priced at $0. A short AAPL 150 P (avg $2.00, snapshot mark $0.40) that expired with AAPL at $160 realized $160 and a $40 debit. It now realizes $200 with no debit, in both `--marks` modes. With no expiry close it settles against today's spot and warns. This replaces #106's "past expiry, so not quoted" warning, which said the price was wrong without fixing it.
67
+ - A contract **expiring today** with no chain quote is priced at **intrinsic** (Black-Scholes at `T = 0`; premium source `intrinsic`, was `none`). It was $0, which understated a short 190 C with spot at $200 by $1,000 a contract.
68
+ - An **expired option no longer drives the scenario.** The shortest-expiry pick chose it, so a negative DTE floored the horizon at one day, ATM IV was looked up on a chain that no longer exists, and its payoff was integrated over an `S_T` it can't reach. A worthless expired short 150 P beside a 30-day call spread read PoP 100.0% (83.2% settled), max loss −$14,620 (−$620) and a phantom breakeven at $146.20. It is now replaced by what it became: delivered shares, or a cash constant in the realized offset. The option itself sets no horizon, IV, forward, extremes or Greeks.
69
+
70
+ Premium source `expired` is now `settlement`. `--save` writes a delivery as its share line and a cash settlement to `## Context`. `--close` of an in-the-money equity option past expiry warns that it was delivered, not closed, and `--assign` of one that expired worthless warns that it wasn't assigned. Tests stub the close via `args._close_fetcher`, `Settler(close_fetcher=...)` or the new autouse `bars.close_on` stub. See [behaviors.md](docs/behaviors.md) "Contracts at or past expiry in `adjust`".
71
+
72
+ - **`adjust --assign` no longer counts the put premium twice.** It added the put's close-at-mark P&L, `qty × 100 × (mark − premium)`, to the realized offset *and* folded the premium into the share basis. Assignment delivers shares at the strike and doesn't buy the put back, so in `effective` mode nothing else is realized, and in `strike` mode only the premium is. A short 520 P (avg $4.00, mark $2.50) showed a phantom +$150. Assigned past expiry at a $10.00 settlement, a short 150 P showed a phantom −$800, moving the breakeven from $144 to $148. The closing line now reads `**Assigned:**` and says what was booked. The put's mark is no longer asked for, since nothing uses it: a live run whose lookup for it missed used to read `frozen-fallback` and warn about a stale mark that appeared nowhere in the output.
73
+ - **`adjust --assign` refuses cash-settled index roots.** An expired in-the-money SPX 6000 P (close $5,900) was assigned into +100 "shares" of the index at $5,980, a −$598,000 max loss beside the before column's −$8,000 cash settlement. `tickers.CASH_SETTLED` also gains the roots a CSV import can carry as the underlying: NDXP, RUTW, VIXW and XND, beside SPXW. `market_symbol` now sends each to its index (`SPXW` → `$SPX`, `NDXP` → `$NDX`), so its expiry close, quote and chain are found rather than falling back to spot, and VIXW is forward-settled like VIX.
74
+ - **`bars.close_on` no longer stops at a tail source that lacks the date.** `get_bars` keeps the first tail source with any rows, so Schwab returning the days around an expiry but not the expiry itself ended the cascade, and the contract settled against today's spot. `_fetch_tail(require=day, after=source)` re-asks only the sources after the one that answered, and counts one only if it has a positive close for that date.
75
+
76
+ - **`thetabook skills lint`, `render-readme` and `show` no longer crash on a skill that fails schema validation.** A file missing `name` raised an uncaught pydantic `ValidationError` and stopped the run. It's now reported per file, naming the bad field.
77
+ - **One marks label, derived from the legs, instead of six places answering
78
+ "is this run live?"**
79
+ ([#104](https://github.com/subsriram/thetabook/issues/104)). `evaluate`
80
+ decided whether a run was live in five places that could disagree, and
81
+ `adjust` added a sixth. Two opposite regressions inside one PR came from
82
+ exactly that: shares re-marking to spot under a label claiming entry
83
+ (−$17,272 on a covered call against −$17,000 live and −$14,772 frozen, in
84
+ the number `max_position_pct` is enforced against), and then the per-leg
85
+ marks table disappearing on a partial chain miss — the one case where its
86
+ `src` column is worth reading.
87
+
88
+ `core.apply_marks` now walks every leg once, stamps each leg's
89
+ `mark_source`, and `core.label_for` *derives* the run's label from what it
90
+ stamped. `frozen-fallback` became "no leg carries a live source" — a fact
91
+ about the legs rather than a branch computed beside the share gate, which
92
+ is the seam that produced the first regression. Shares are just another leg
93
+ the walk visits, and the walk commits **one baseline for the whole position
94
+ or none**.
95
+
96
+ Visible fix: the stdout banner printed the *requested* mode, so a run whose
97
+ chain lookups all failed said `Marks: live` above a table and a frontmatter
98
+ that both said `frozen-fallback`. Banner, metric row and frontmatter now
99
+ read one derived value, and `core.marks_cell` is the single owner of when
100
+ the bid/mid/ask pick gets named. `adjust` had the same defect and now
101
+ reports what resolved (`frozen-fallback` when every quote fell back to the
102
+ snapshot and Black-Scholes) rather than what was asked for.
103
+
104
+ One question deliberately survives separately: whether live was
105
+ *requested*, which still gates whether a per-leg marks table exists at all.
106
+ Collapsing it into the label is the second regression above.
107
+
108
+ `adjust`'s retained legs keep measuring from their cost basis — that frame
109
+ is what makes its before/after comparison apples to apples, and it is why
110
+ its max loss agrees with `evaluate --marks frozen`. Re-marking them to now
111
+ while `realized_offset` still measured from entry would rebuild the same
112
+ two-baseline blend on the other side; the snapshot-derived legs are now
113
+ stamped `frozen` to say so.
114
+
115
+ Follow-ups from review. `evaluate`'s assignment-risk check measured
116
+ extrinsic against `leg.premium`, which on a frozen or fallback run is the
117
+ entry premium. It now takes today's chain mid, as `adjust` already did,
118
+ through one shared `core.assignment_mark_for`. In `adjust`, a leg past
119
+ expiry, opened or closed, no longer asks the chain or counts as a miss, so
120
+ modelling an assignment the day after expiry doesn't read as an outage. It
121
+ warns instead that the price it used (the snapshot's pre-expiry mark for a
122
+ close, $0 for an open) is not the settlement value. One expiring today
123
+ still asks, and its miss still counts. A degraded label warns on stderr as
124
+ it does in `evaluate`, naming each leg that fell back. In the per-leg marks
125
+ table, a `stale` option leg shows no current mark and stays out of Net MTM
126
+ rather than counting as $0; shares keep their drift, which spot makes
127
+ exact. The "usable chain mark"
128
+ rule now lives once, in `core.chain_pick`, for `evaluate`'s walk and both
129
+ of `adjust`'s resolvers, and a marks mode other than `live` / `frozen` is
130
+ refused by the walk itself as well as by `--marks`.
131
+
132
+ ## [2.3.0] — 2026-11-01
133
+
134
+ The first release since v2.2.3. It adds a backtester for systematic
135
+ strategies whose live signal is the backtest's own last row,
136
+ share legs in idea files, and a run of risk-correctness fixes that change
137
+ the numbers `evaluate` records.
138
+
139
+ **Expect existing ideas to move on their next `evaluate`.** PoP now
140
+ integrates a ±5σ grid instead of the ±2σ display domain
141
+ ([#96](https://github.com/subsriram/thetabook/issues/96)); max gain / loss
142
+ are computed in closed form and can read `Unbounded`
143
+ ([#99](https://github.com/subsriram/thetabook/issues/99)), with a one-time,
144
+ announced migration of budgets the old math got wrong; and a covered
145
+ structure keeps evaluating as naked until its shares are declared in
146
+ `## Structure` ([#102](https://github.com/subsriram/thetabook/issues/102)).
147
+ **Re-import Schwab or Empower CSV snapshots that hold options**: their
148
+ `averagePrice` was stored per contract, 100× too large
149
+ ([#109](https://github.com/subsriram/thetabook/pull/109)).
150
+
151
+ ### Added
152
+
153
+ - **`thetabook backtest`: hypothetical strategy backtests, with the live
154
+ signal on the same code path**
155
+ ([#108](https://github.com/subsriram/thetabook/issues/108);
156
+ [#110](https://github.com/subsriram/thetabook/pull/110),
157
+ [#114](https://github.com/subsriram/thetabook/pull/114),
158
+ [#115](https://github.com/subsriram/thetabook/pull/115)). A new
159
+ workflow-layer `backtest/` package and a `backtest list | run | grid |
160
+ signal` sub-app, driven by `/backtest`. `run` builds a total-return panel
161
+ from the bars stitch plus cash dividends and enforces signal-at-close →
162
+ trade at close t+lag → earn from t+lag+1, with non-zero costs and short
163
+ borrow by default. It reports against the strategy's benchmark, the
164
+ equal-weight universe and cash, with t-stats on every active return.
165
+ `signal` is the last completed rebalance of that same simulation, not a
166
+ second implementation, so the weekly call can't drift from the backtest
167
+ that justified it. Two strategies ship: `sector-rotation` (11 SPDR sectors,
168
+ weekly) and `dual-momentum` (SPY / TLT / GLD vs BIL, monthly).
169
+
170
+ `grid` sweeps `--vary` over one data panel, prints how many configurations
171
+ were tried, ranks on in-sample Sharpe only, and reports the **deflated
172
+ Sharpe** (Bailey & López de Prado 2014) of the winner. The paper's §6
173
+ worked example is a known-answer test. `--prior-trials` counts searches
174
+ done elsewhere, and `--walk-forward` re-picks the best config per fold and
175
+ chains the tests into one out-of-sample series.
176
+
177
+ `--save` on `run` / `grid` writes an immutable manifest to
178
+ `$THETABOOK_HOME/backtests/`: the JSON payload plus the code version, git
179
+ SHA, argv, params, a panel fingerprint and a UTC timestamp. The file is
180
+ create-only and chmod 0444, an identical re-run is reported rather than
181
+ duplicated, and stdout is byte-identical with or without the flag. This is
182
+ the package's third write boundary, and `personal/backtests` is now a
183
+ reserved skill write path. Everything prints as *hypothetical backtested
184
+ performance*. Conventions are in
185
+ [docs/behaviors.md](docs/behaviors.md) "Backtests".
186
+
187
+ - **Share legs in idea files**
188
+ ([#102](https://github.com/subsriram/thetabook/issues/102),
189
+ [#103](https://github.com/subsriram/thetabook/pull/103)). `## Structure`
190
+ now takes `TICKER shares qty=+100 cost_basis=150.00` beside option lines.
191
+ Shares were previously dropped on both the read and the `adjust --save`
192
+ write side, so every covered call, buy-write or collar evaluated as naked:
193
+ after #99 that meant a confident `Unbounded` on a position bounded at
194
+ −$14,772, printed beside a net delta of the wrong sign. `cost_basis` is
195
+ required, and a share line without it is refused rather than skipped,
196
+ since a zero default reports a profit as the max loss. `evaluate` gives
197
+ share legs their own Greeks and marks rows. `adjust` carries snapshot
198
+ shares through before and after, so `adjust --assign --save` writes a file
199
+ that evaluates as the covered position it modelled. A structure carrying
200
+ shares must sit on a single underlying. `accounts.check_idea` drops its
201
+ snapshot-derived cover guard and sizes off `evaluated_max_loss` alone.
202
+ Its unbounded-loss message names the share-line syntax.
203
+
204
+ - **`scripts/demo.sh`, a guided walkthrough**
205
+ ([#109](https://github.com/subsriram/thetabook/pull/109)). It runs the
206
+ main loop (snapshot, diff, positions, Greeks, account rules,
207
+ vol/TA/scenarios, chain, ideas, evaluate, adjust/roll, wiki) against a
208
+ throwaway `$THETABOOK_HOME` seeded with a fictional book, so no real
209
+ account data appears on screen. Market data is live, borrowed from your
210
+ `.env` and Schwab token. It refuses to run against, inside, or around
211
+ your real home. Supports `--auto`, `--from N`, `--verbose` and `--reset`.
212
+ Dev checkout only, since `scripts/` isn't in the wheel.
213
+
214
+ - **Index options now work: `VIX`, `SPX`, `NDX` and 22 more CBOE roots**
215
+ ([#91](https://github.com/subsriram/thetabook/issues/91)). Schwab's canonical
216
+ form for an index carries a `$` prefix. Bare `VIX` failed on the chains
217
+ endpoint with HTTP 400, and — worse — on the *quotes* endpoint with HTTP
218
+ **200 plus an `errors` payload**, so nothing raised and `thetabook price VIX`
219
+ degraded silently through Massive to yfinance. Meanwhile the expiration
220
+ endpoint accepts either form, so `chain VIX` listed 13 expirations and then
221
+ priced nothing, which reads as "VIX has no options". It does — cash-settled
222
+ European on the SOQ, carrying none of the roll decay that makes VXX a poor
223
+ substitute for expressing a vol view.
224
+
225
+ A new `INDEX_ALIASES` map covers 25 verified roots — 10 with listed options
226
+ (`SPX`, `NDX`, `RUT`, `DJX`, `OEX`, `XEO`, `XSP`, `MRUT`, `VIX`, `SPESG`)
227
+ and 15 quote-only vol/stat indices. Every entry was checked against live
228
+ Schwab: bare returns nothing, `$`-prefixed returns a real quote.
229
+
230
+ It is deliberately **separate from `TICKER_ALIASES`** and applied only at
231
+ the market-data boundary, via `tickers.market_symbol()`. `canonicalize` —
232
+ which feeds snapshot symbols, CSV imports, idea-file legs and OCC roots —
233
+ never sees the `$`. Folding the two together would have written
234
+ `$SPX 260116P05000000` on CSV import against the API's
235
+ `SPX 260116P05000000` (so `diff` reported a phantom close *and* a phantom
236
+ open for one position), silently dropped a `$VIX …` line from an idea's
237
+ `## Structure` block, and — worst — priced a genuine equity at the index
238
+ level had one ever listed under a root like `OEX`. The `$` now stays on the
239
+ wire and out of everything persisted.
240
+
241
+ `price` / `chain` / `em --source iv` / `hv` / `vrp` all work on index roots
242
+ now.
243
+
244
+
245
+ - **`evaluate` labels its probabilities as risk-neutral and reports
246
+ `E[payoff]`** ([#88](https://github.com/subsriram/thetabook/issues/88)).
247
+ `Prob. of profit` / `Expected profit` / `Expected loss` were printed with no
248
+ indication they're computed under the pricing measure — drift `r - q`, not
249
+ the instrument's actual expected return. On equities the gap is small; on
250
+ leveraged and volatility ETPs it's 2–3×. A VXX spread was written up as a
251
+ "~1-in-5" trade at PoP 21.1% when the real-world figure is nearer 1-in-10
252
+ with negative expected value. The conditional rows are now marked as
253
+ conditional, and the probability-weighted `E[payoff]` — the only one of the
254
+ three that carries information about edge — sits alongside them. It lands
255
+ ≈ $0 for a fairly-priced structure, which is the signal.
256
+
257
+ The expectations integrate over their own ±5σ grid rather than the ±2σ
258
+ display domain the P&L table is drawn from. `pnl_price_domain` sizes the
259
+ latter for plotting, and at ±2σ the tails still hold ~5% of the mass — for
260
+ an undefined-risk short, exactly where the loss is unbounded. Clamping it to
261
+ the boundary doesn't blur the answer, it inverts it: a fairly-priced ATM
262
+ short call integrated over the display grid reported **+$9.77** against a
263
+ true **−$10.96**, phantom edge on a zero-edge trade. On the wider grid the
264
+ clamped mass is under one part in a million, and `E[payoff]` reproduces the
265
+ closed form `−qty·100·premium·(1 − e^{rT})` to the cent for naked calls,
266
+ puts, longs, and verticals alike.
267
+
268
+ - **`thetabook vrp --dte N`** ([#89](https://github.com/subsriram/thetabook/issues/89)
269
+ Part B). `vrp` sampled the front expiry, which on a liquid name is routinely
270
+ 0–3 DTE — noisy and unrelated to any dated structure. QQQ's 0-DTE ratio read
271
+ **1.12 in the morning and 0.98 the same afternoon** while the Dec 101-DTE leg
272
+ actually being traded sat at **1.78**. `--dte N` selects the nearest expiry at
273
+ least N days out; the sampled DTE is now repeated on the `IV/HV` line (the one
274
+ people copy), a ≤ 7 DTE sample warns, and an unreachable horizon says what it
275
+ sampled instead.
276
+
277
+ - **Structural-decay warnings on `hv` / `em` / `vrp`**
278
+ ([#89](https://github.com/subsriram/thetabook/issues/89) Part A). Realized
279
+ close-to-close vol on a rolling-futures or leveraged-reset product describes
280
+ the current regime rather than the risk being traded: VXX printed HV20 27.1%
281
+ at HV-rank 5.0% while its own ATM IV was ~60%. A static
282
+ `STRUCTURAL_DECAY_TICKERS` list (vol ETPs, leveraged index and single-stock
283
+ funds) drives an advisory warning in each command where its own output is the
284
+ misleading part. Static rather than inferred on purpose — classifying decay
285
+ from price history is its own problem, and a false positive on an ordinary
286
+ equity is worse than a missed exotic.
287
+
288
+ ### Fixed
289
+
290
+ - **Max gain / loss were read off the display grid, understating tail
291
+ risk** ([#99](https://github.com/subsriram/thetabook/issues/99),
292
+ [#101](https://github.com/subsriram/thetabook/pull/101)). They were
293
+ `np.max` / `np.min` over the S ± 30% plotting domain, so any extreme
294
+ outside it was reported at the edge. A 182-DTE AAPL short 160 put read
295
+ −$3,285.62 against a true −$15,535.62, and that is the figure
296
+ `max_position_pct` enforces, so a position 4.7× over its limit passed
297
+ silently. Widening the grid isn't enough: a put bottoms out at S_T = 0,
298
+ which no lognormal grid reaches. P&L at expiry is piecewise-linear with
299
+ kinks only at the strikes, so evaluating at 0, at each strike and along
300
+ the final ray's slope is exact. Unbounded structures now report `±inf`,
301
+ render `Unbounded`, and raise a distinct `max_position_pct` violation.
302
+ `adjust` shows `unbounded → bounded` instead of a NaN delta. Budgets the
303
+ old math got wrong are re-seeded once, with a stderr warning, and stamped
304
+ `budget_basis: analytic`. Budgets it got right, including hand-declared
305
+ ones, are left alone.
306
+
307
+ - **The price behind a cushion or a PoP is now named**
308
+ ([#100](https://github.com/subsriram/thetabook/issues/100),
309
+ [#101](https://github.com/subsriram/thetabook/pull/101)). `positions`
310
+ measured a VIX cushion against the forward while printing spot beside it,
311
+ so a row like "−7.7% cushion on a 17 call at $15.72 spot" was impossible
312
+ on its face. A `fwd` column now shows the reference, and only when some
313
+ row is forward-settled. `?` marks a forward that didn't resolve, such as
314
+ under `--no-fetch`. `adjust` tracks the forward per scenario, so a roll
315
+ across expiries renders `(fwd $18.42 → $19.05)` instead of naming only
316
+ the new leg's future.
317
+
318
+ - **CSV-imported option `averagePrice` was per contract, not per share**
319
+ ([#109](https://github.com/subsriram/thetabook/pull/109)). The Schwab and
320
+ Empower importers divided total cost basis by contract count, so a short
321
+ call sold for $6.20 landed as `620`. Every consumer reads that field per
322
+ share, and `adjust` on such a snapshot reported a $123,170 realized P&L on
323
+ a $410 buyback. Fidelity reads the broker's own per-share column and is
324
+ unchanged. Snapshots imported before this fix keep the inflated value
325
+ until the CSVs are re-imported.
326
+
327
+ - **Deep bar history comes from yfinance when defeatbeta has no coverage**
328
+ ([#111](https://github.com/subsriram/thetabook/issues/111),
329
+ [#112](https://github.com/subsriram/thetabook/pull/112)). The whole window
330
+ used to go through the live cascade, and Schwab's deep daily history
331
+ carries weekend-dated copies of Friday's close, missing sessions, bad
332
+ prints, and a pre-2020 XLE series 4–15% off. yfinance (defeatbeta's own
333
+ upstream) now serves everything older than 14 days, and the live cascade
334
+ only that tail. Weekend-dated daily rows are dropped from every source
335
+ with one warning, and the sources used are recorded on the frame.
336
+
337
+ - **defeatbeta history was 404ing for every uncached ticker**
338
+ ([#113](https://github.com/subsriram/thetabook/pull/113)). The upstream
339
+ dataset moved its parquet files under `data/US/`, which defeatbeta-api
340
+ 0.0.57 hard-coded the old way, so `hv` / `ta` / `scenarios` silently fell
341
+ back to the live cascade. The floor is now `defeatbeta-api>=0.0.63`, and
342
+ the output-silencing wrapper is updated for its new logging (nltk is gone).
343
+
344
+ - **Fidelity CSV edge cases**
345
+ ([3385271](https://github.com/subsriram/thetabook/commit/3385271)).
346
+ Schwab-held options inside a Fidelity FullView export
347
+ (`PUT AMD$475 EXP 07/17/26`, no option root) warn and are skipped, with a
348
+ pointer to `thetabook refresh`, instead of mis-parsing. Header detection
349
+ is case-insensitive, and a missing `Average Cost Basis` column no longer
350
+ raises.
351
+
352
+ - **VIX options were priced off spot, not the futures curve they reference**
353
+ ([#96](https://github.com/subsriram/thetabook/issues/96)). VIX options settle
354
+ to the SOQ and reference the VIX *future* for their expiry; no cash-and-carry
355
+ links future to spot, so no `r`/`q` choice bridges them. On 2026-09-08 spot
356
+ was 15.72 against an October forward of 18.42 — 17.2% contango — and pricing
357
+ off spot underpriced the chain by **56% at the money and 85% on the wings**,
358
+ while centring every probability on a price the contract never settles
359
+ against. "VIX above 18 at expiry" read **21.5%** off spot against **51.2%**
360
+ off the forward.
361
+
362
+ `VolResolver.resolve_forward()` derives the forward from put-call parity on
363
+ the chain already fetched — `F = K + (C − P)·e^{rT}`, median across strikes
364
+ carrying both legs, so one stale wing can't move it. Resolution is per leg,
365
+ since the forward is per expiry and a calendar spread carries a different one
366
+ on each. It feeds `compute_greeks`, `evaluate`'s PoP / `E[payoff]` /
367
+ expectation grid, `adjust`'s opening marks and scenario PoP, portfolio Greeks
368
+ aggregation, and `positions` cushion — where a VIX 20 call reads +27.2% OTM
369
+ off spot and **+8.6%** off the forward.
370
+
371
+ Pricing on that path uses **Black-76** (`q = r`), not Black-Scholes with the
372
+ spot swapped — the forward already embeds the carry, so leaving `q` at 0
373
+ applied it twice. The error is signed opposite by side: calls were overpriced
374
+ (+1.2% to +7.1%) and **puts underpriced** (−9.8% to −1.4%), so a short VIX 15
375
+ put — the position this work is built around — was marked 5.2% light.
376
+
377
+ `tickers.FORWARD_SETTLED` holds `VIX` alone: the other vol indices share the
378
+ structure but CBOE delisted their options. SPX / NDX / RUT are excluded for a
379
+ different reason — they settle on the index itself, so spot *is* the
380
+ underlying and ordinary carry already gives the forward. Every command-level
381
+ caller warns when parity can't be derived rather than silently using spot —
382
+ including `positions --no-fetch`, which can't derive one at all — and both
383
+ `evaluate` and `adjust` name the forward in their headers.
384
+
385
+ PoP now integrates the same ±5σ grid the expectations use, in both `evaluate`
386
+ and `adjust`. The old ±2σ display domain closed an unbounded profitable
387
+ *region* at its edge, so **recorded PoP moves for most structures**, not just
388
+ forward-settled ones. What matters is whether the profitable region is
389
+ bounded on both sides, not whether P&L is capped:
390
+
391
+ | structure | before | after |
392
+ | --- | ---: | ---: |
393
+ | AAPL 182-DTE short put | 62.5% | 73.3% |
394
+ | AAPL 6-month 170/180 debit call vertical | 38.7% | 49.5% |
395
+ | AAPL iron condor 150/160/190/200 | 36.6% | 36.6% |
396
+
397
+ A debit vertical's profit region is `[breakeven, ∞)` even though its P&L is
398
+ capped, so it moves; an iron condor is bounded on both sides and does not.
399
+ The new figures are the correct ones — the old domain simply stopped
400
+ integrating at `S ± 30%` — but expect existing ideas' recorded PoP to change
401
+ on the next `evaluate`.
402
+
403
+ Schwab's broker Greeks for VIX remain suspect — 10 of 36 October calls report
404
+ delta > 1.0 — and are untouched here; `--greeks-source bs` forces the
405
+ corrected path.
406
+
407
+ - **Schwab has never served option expirations**
408
+ ([#91](https://github.com/subsriram/thetabook/issues/91)).
409
+ `list_expirations_schwab` read `year` / `month` / `day` out of
410
+ `expirationList`, keys the payload has never carried — it returns
411
+ `{"expirationDate": "2026-10-21", …}`. It therefore returned `None` for
412
+ *every* ticker and the cascade quietly fell through to yfinance:
413
+ 15-minute-delayed, and empty for index roots, which is what made #91 look
414
+ like an entitlements problem. The test fixture encoded the same invented
415
+ shape, which is why it survived; it now pins a payload captured live.
416
+
417
+ - **Ticker aliases didn't reach the bars backbone**
418
+ ([#91](https://github.com/subsriram/thetabook/issues/91)). `get_bars` never
419
+ canonicalized, so the alias map applied to the live price cascade but not to
420
+ history: `thetabook price BRKB` worked while `thetabook hv BRKB` silently
421
+ returned nothing. Canonicalization now happens at `get_bars` — the one
422
+ chokepoint every bars consumer passes through — matching what `prices.py`
423
+ and `chains.py` already do at their entry points.
424
+
425
+
426
+ - **Schwab HTTP errors now surface the response body**
427
+ ([#91](https://github.com/subsriram/thetabook/issues/91)).
428
+ `raise_for_status()` renders only the status line, so a Schwab 400 arrived as
429
+ `Client error '400 Bad Request' for url ...` with no hint of what Schwab
430
+ objected to — and for a rejected symbol form the body is the whole diagnosis.
431
+ All six Schwab read call sites now append a truncated excerpt.
432
+
433
+ - **`chain` explains the listable-but-unpriceable case**
434
+ ([#91](https://github.com/subsriram/thetabook/issues/91)). Schwab's two
435
+ endpoints disagree about symbology: `chain VIX` lists 13 expirations — implying
436
+ the symbol is fine — and then every strike lookup returns empty, so the
437
+ reasonable conclusion is "VIX has no options". It does; VIX options are
438
+ cash-settled European and carry none of the roll decay that cost a VXX
439
+ position 79.3% over three years while VIX itself rose 9.6%. The no-contracts
440
+ path now names index symbology as the likely cause, but only in that
441
+ contradictory case — a date that isn't listed gets different advice, and a
442
+ ticker with no options gets the plain message.
443
+
444
+
445
+
446
+ - **Idea frontmatter and the `## Evaluation` body could disagree about
447
+ max gain/loss** ([#92](https://github.com/subsriram/thetabook/issues/92)).
448
+ `update_idea_file` set `max_gain` / `max_loss` only when unset, while the
449
+ body section was regenerated on every run — so a re-evaluated idea carried a
450
+ frozen frontmatter and a fresh body contradicting each other in the same
451
+ file, with nothing marking which was current (observed: `max_gain: 4490.0`
452
+ against a body reading `$4,480.00`, both written by `evaluate` hours apart).
453
+
454
+ Beyond cosmetics: `accounts.check_idea` enforces `max_position_pct` off the
455
+ frontmatter, so the risk check read a figure the body had already moved past,
456
+ and nothing bounded the gap — an idea first evaluated months ago kept its
457
+ original numbers forever.
458
+
459
+ **The enforced number is deliberately unchanged.** `check_idea` still reads
460
+ the same frozen `max_loss` it always did; what the split fixes is that the
461
+ file no longer presents two contradictory figures under one name, and the
462
+ frozen one is now labelled as what it is. A position limit *should* bind on
463
+ the risk accepted at entry rather than on a mark that moves under you — so
464
+ don't expect `max_position_pct` to start tracking the live number.
465
+
466
+ Split into two pairs. `max_gain` / `max_loss` stay write-once and become the
467
+ **author-declared risk budget**; new `evaluated_max_gain` /
468
+ `evaluated_max_loss` refresh every run. `check_idea` enforces the budget and
469
+ falls back to the computed value only when none was set, so a position limit
470
+ binds on the risk accepted at entry rather than on a mark that moves under
471
+ you, and ideas predating the field stay checkable. Existing files keep
472
+ loading unchanged; the new keys appear on the next `evaluate`.
473
+
474
+ `thetabook evaluate --reseed-budget` re-declares the budget from the current
475
+ run. Write-once with no writer would be a trap: every value in a pre-split
476
+ file was machine-written (one reads `-1223.1980000000003`, float noise off
477
+ `np.min` rather than a number anyone declared), and freezing those forever
478
+ while making them the sole input to a risk rule needs a way out that isn't
479
+ hand-editing frontmatter the CLI otherwise owns.
480
+
481
+ `adjust --save` seeds both pairs, and the wiki ideas roll-up now shows
482
+ `evaluated_max_loss` — it's the cross-session review surface, so it should
483
+ carry what the position risks now rather than the frozen seed.
484
+
485
+ Also routes `evaluate`'s write notice through `log.note` to **stderr** —
486
+ stdout is reserved for parseable output, and a status line there is easy to
487
+ miss when output is piped or read by an agent.
488
+
489
+
490
+
491
+ - **`adjust`'s BS-estimated opening premium used flat vol, not chain IV at the
492
+ strike** ([#32](https://github.com/subsriram/thetabook/issues/32)). When
493
+ `--open` / `--add` got a leg with no `premium=` and the chain had no usable
494
+ quote, `resolve_opening_mark` priced it off the flat 25% default — while
495
+ `compute_greeks` priced the *same hypothetical leg in the same scenario* off
496
+ the chain's IV at that strike. The premium and the Greeks then disagreed
497
+ about what the position was worth inside a single invocation.
498
+
499
+ The two lookups diverge precisely where it hurts: a chain can cover a strike
500
+ for **IV** but not for a usable **quote** — an illiquid wing with no
501
+ bid/ask, a yfinance row carrying `implied_vol` and nothing else, or an
502
+ earnings-week wing where IV ramps. The BS fallback now resolves IV per-leg
503
+ through `VolResolver.resolve_leg_iv`, the same call the Greeks make, so one
504
+ sigma drives both. The error was not small on wings: a 45-DTE OTM call at a
505
+ 62% chain IV prices at **$6.96** against **$0.53** at flat 25%, since option
506
+ value is sharply convex in vol when far OTM.
507
+
508
+ Priority is unchanged from the Greeks path — `--vol` override → chain IV at
509
+ the exact strike → flat default — and both the sigma and its provenance are
510
+ now recorded on the leg (`premium_iv`, `premium_iv_source`) and surfaced in
511
+ the comparison table as `bs @ 62% chain IV`, `bs @ 30% --vol override`, or
512
+ `bs @ 25% flat default`, so a BS-estimated premium is auditable instead of
513
+ an unattributed number. This applies under `--marks frozen` too: frozen
514
+ skips the live chain for *marks*, but the Greeks resolve per-leg chain IV in
515
+ a frozen run regardless, so exempting the premium there would have left the
516
+ same divergence alive. Only a resolver-less caller uses the flat vol.
517
+
518
+ The report header now reads `Vol: chain IV (per-leg)` instead of a single
519
+ flat number whenever `--vol` is absent — it previously printed `Vol: 25%`
520
+ above a table row reading `bs @ 62% chain IV`.
521
+
8
522
  ## [2.2.3] — 2026-09-08
9
523
 
10
524
  Housekeeping release, plus the last uncovered corner of Schwab's 7-day