Pre-register the offside-capitulation evaluation and hand off its execution

[mspinola]

Description

"Offside capitulation evaluation": the phrase names a concept the workspace has vocabulary for but no measurement of — crowdmon's offside term (crowding = lopsided / offside / trapped) and the npf/cotmetrics capitulation signal family. This PR pre-registers a first-look event study and hands its execution to a trusted-network session, because this sandbox's network policy blocks cftc.gov and every probed price host (the same block the NPF variance check hit).

• docs/handoffs/2026-08-23-offside-capitulation-evaluation.md — the frozen design. Offside = adverse ≥1σ 4-week move against a trailing NPF extreme; capitulation = top-decile one-week unwind of the crowded net; outcome = forward σ-scaled returns signed so the washout (claim A) and stampede (claim B) folk readings — both of which cotmetrics itself carries, in FLAG_BULL_CAPITULATION vs CAPITULATION/COMMS_CAPITULATION — predict opposite signs. Controls and the recentred block-bootstrap p inherit the forced-flow verdict's mean-reversion lesson up front. Declared readings: 18; primaries: the two 4-week event readings; pre-committed verdict rules including an "insufficient data" outcome.
• scripts/offside_capitulation_check.py — the executable form, in the npf_check.py mold: downloads CFTC Legacy zips (same URLs as providers/cftc.py) and stooq daily continuous closes, with a local-CSV fallback and an honest degraded COT-only mode. --selftest runs the full pipeline on synthetic data offline and passes in this sandbox in ~0.5s.
• .gitignore — excludes the script's download cache.

Results, when the executing session pushes them, land as new dated docs/analysis/ files on this branch; §§1–5 of the handoff and the script's frozen parameters are not to be edited.

Fixes # (no linked issue — task arrived as a branch assignment)

Type of change

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• This change requires a documentation update

Checklist:

• My code follows the style guidelines of this project
• I have performed a self-review of my own code
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation
• My changes generate no new warnings
• I have run tests (e.g. pytest) and they pass locally — the existing suite is untouched by this additive change; the new script's --selftest passes
• Any dependent changes have been merged and published in downstream modules — n/a, self-contained

---

Generated by Claude Code

[mspinola]

Closing as covered, never executed (no results were produced on this branch).

The question this pre-registers, whether an offside crowd's capitulation is followed by continuation or reversal in price, was taken up in npf the same day this spec was written, in work this cloud sandbox could not see:

• npf PR #214 (docs/handoffs/2026-08-23-offside-capitulation-prereg.md): offside predicts capitulation only as a proxy for the adverse move itself.
• npf PR #215 (2026-08-23-loss-recency-capitulation-prereg.md): capitulation timing follows the recency of the loss, not its depth.
• npf PR #217 (2026-08-23-capitulation-price-prereg.md): does capitulation carry price information? Price axis an ex-ante null.
• 2026-08-24-disjoint-window-capitulation-prereg.md: the disjoint-window test of whether capitulation moves price, frozen and awaiting its review pass. That is the live form of the remaining question.

Two further reasons not to move it into npf and run it: npf's review seam (added 2026-08-24) requires a separate review session before any spec with a new outcome variable or conditioning window executes, and this spec's 18 declared readings would add looks to a family whose price question already returned a null. Its placement was also against ADR-0007 (a price-outcome script reading marketdata bars inside cotdata), as its own ownership note said.

The branch claude/offside-capitulation-evaluation-b55iv9 is left in place as the record.