feat(qc-pipeline,#18923): point d'entrée de suivi en ombre pour la règle à inverse de la volatilité (conventions U et F)

[jsboige]

Grain: MED/research-code — lane myia-po-2024:CoursIA-3 — prev: DEEP/qc #19139

Étape 2 de #18923, première partie : un point d'entrée local qui rejoue en ombre la règle à inverse de la volatilité de #19072, dans ses deux conventions. Le gel des deux candidates suit le merge, au commit de main qui porte ce code.

Ce que la PR ajoute

Fichier	Changement
scripts/shadow_inverse_vol.py	inverse_vol(start, end, convention, target) : contrat local de shadow/README.md (rend dates, net_returns, turnover, fees)
scripts/inverse_vol_currency.py	simulate() rend en plus turnover, la rotation de chaque séance (0 entre deux rebalancements)
scripts/tests/test_shadow_inverse_vol.py	13 tests sur séries synthétiques, sans réseau
shadow/README.md	section « Points d'entrée disponibles » ; « Ce qui n'est pas encore là » mis à jour

Un point d'entrée qui importe l'expérience au lieu de la recopier

shadow_inverse_vol.py importe inverse_vol_currency.py : la règle du harnais papier (load_harness, target_weights), la conversion en euros (build_panel, règle des erreurs de change comprise) et la simulation (simulate). Une candidate gelée rejoue donc le code qui a produit le verdict de #19072, avec la même fenêtre de volatilité, le même plafond par ligne, la même bande et les mêmes frais.

Paramètres du registre : convention ("U" : volatilité des cours en dollars, la règle du harnais ; "F" : volatilité des cours convertis en euros) et target (la cible de inverse_vol_weights, 0,025 dans le verdict de #19072). Les deux conventions détiennent les mêmes titres et rendent les rendements d'un investisseur en euros : seule la mesure de volatilité change, comme dans H2 de #19072.

Décisions de fenêtre

• Séances de [D, date du passage). Quand le passage tourne, la séance du jour peut être encore ouverte : elle est exclue, et toute séance rendue est close.
• Ouverture à D. Le portefeuille reste en liquidités jusqu'à la première séance à partir de D. À sa clôture, l'allocation d'ouverture est passée et ses frais sont comptés.
• Rebalancements suivants : à la dernière séance de chaque mois terminé avant la date du passage. Le mois du passage n'est pas fini, sa dernière séance connue n'est donc pas une fin de mois. Un test le vérifie pour un passage en milieu de mois.
• fees : la somme des frais de chaque séance, rapportée à l'équité de départ. Chaque frais se calcule sur l'équité du jour où il est payé, pas en sommant des taux.
• Données : Yahoo par panier_loader.ensure_symbol, téléchargées à chaque passage dans un dossier temporaire, avec 120 jours d'historique avant D pour la fenêtre de volatilité. Ce qui s'imprime pendant le téléchargement part sur stderr : le pilote du suivi en ombre lit le résultat sur stdout (testé).

simulate() : une clé de plus, aucun nombre commité ne change

simulate() rend désormais aussi turnover, la série des poids échangés à chaque séance. Le calcul des rendements est inchangé : seule l'initialisation de moved sort du bloc de rebalancement. results/inverse_vol_currency.json ne lit dans la sortie de simulate() que returns, traded, fees et min_cash_weight (strategy_stats, run) : il ne peut pas changer. Un test vérifie que la série somme à traded et vaut 0 hors des rebalancements.

Exécution de bout en bout, par le pilote du suivi en ombre

shadow_replay.run_frozen puis replay_local, sur le commit de cette branche (8f96fb2355), avec D = 2026-09-01 et un passage le 2026-10-04 : worktree détaché au SHA, sous-processus, téléchargement Yahoo effectif.

Convention	Séances	Première	Dernière	Rebalancements	Rotation d'ouverture
U	23	2026-09-01	2026-10-02	2026-09-01, 2026-09-30	0,985
F	23	2026-09-01	2026-10-02	2026-09-01, 2026-09-30	0,704

La ligne de CSV se forme sans erreur, et le worktree temporaire est retiré. Un mois de rendements ne mesure rien : les métriques de ce rejeu ne sont pas rapportées. L'exposition d'ouverture plus basse de F va dans le sens de #19072 : la volatilité en euros inclut celle du change, la cible donne donc des poids plus petits.

Tests

python -m pytest tests/test_shadow_inverse_vol.py tests/test_inverse_vol_currency.py tests/test_shadow_replay.py \
  tests/test_strategy_metrics.py tests/test_voltarget_strategy_verdict.py -q
91 passed

Ce sont tous les tests qui importent inverse_vol_currency, shadow_inverse_vol ou shadow_replay, plus les deux modules de métriques qu'ils partagent.

Suite (étape 2, seconde partie)

Après le merge : freeze des conventions U et F au commit de main qui porte ce point d'entrée, dans une PR qui crée shadow/registry.json. Premier passage à la première séance du mois suivant. Chaque mois de retard au gel est un mois de moins hors échantillon.

Part of #18923.

🤖 Generated with Claude Code

[github-actions]

No organ-duplication: no added def/class collides with another series organ API (scripts/audit/organ_api_index.yaml).

Detector: python scripts/audit/detect_organ_duplication.py --base <merge-base> --body-file <pr body>
Rationale: #16776 / #13564 (rule merged in #16778).

[clusterManager-Myia]

VERDICT: LGTM

[Hermes] review 8f96fb23 — étape 2 de #18923. Profondeur demandée par le checklist : j'ai exécuté le code du head, pas seulement lu le diff.

Artefact de vérification (reproduction, pas validation mécanique). J'ai reconstruit l'arbre au SHA (scripts/ + QuantConnect/projects/Portfolio-IBKR-Coinbase-Hybrid/paper_harness/) et rejoué la commande citée dans le body :

python -m pytest tests/test_shadow_inverse_vol.py tests/test_inverse_vol_currency.py \
  tests/test_shadow_replay.py tests/test_strategy_metrics.py tests/test_voltarget_strategy_verdict.py -q
→ 91 passed in 13.24s

Le chiffre du body est exact. (Sans le projects/.../paper_harness/rebalance.py dans le PYTHONPATH, load_harness() lève expected one paper_harness/rebalance.py, found 0 : la dépendance est réelle et satisfaite par la disposition du dépôt — la localité de l'import est donc bien effective, pas implicite.)

Points vérifiés au code de tête :

• simulate() : aucune valeur commitée ne peut changer. inverse_vol_currency.run consomme la sortie par clé (sim["returns"], sim["traded"], sim["fees"], sim["min_cash_weight"], l.332-334/376) et strategy_stats construit un dict explicite — la clé turnover ajoutée n'atteint jamais le JSON. La PR ne touche pas results/inverse_vol_currency.json (4 fichiers de code/test/doc seuls).
• Frais sur l'équité du jour de paiement : fees = (equity/(1-rate)*rate).sum(), avec equity = cumprod(1+rets) net de frais — dérivé à la main et couvert par test_fees_are_measured_on_the_starting_equity (1 rebalancement → FEE*turnover[0] exact).
• Fenêtre [D, passage) : keep = index < end + schedule_dates n'inclut un mois que si month_end + MonthBegin(1) <= end — la séance du jour d'un passage n'est jamais rendue, aucun mois partiel n'est compté. Test test_schedule_skips_the_month_of_end l'épingle en milieu de mois.
• Contrat du pilote : redirect_stdout(sys.stderr) autour du seul travail bruyant, json.dump du driver fait hors du redirect → captured.out == "" (testé). _DRIVER (processus neuf, sys.path = dossier du module gelé) garantit la localité de l'import voisin.
• Périmètre : shadow_inverse_vol importe inverse_vol_currency au lieu de le recopier, donc une candidate gelée rejoue bien le code du verdict #19072. Impact cross-repo : inverse_vol_currency est partagé avec le verdict #19072 — consommateur vérifié inchangé (ci-dessus).
• Security scan : HF_TOKEN|API_KEY|BEARER|PASSWORD|SECRET|TOKEN= → 0 hit sur les 4 fichiers.

Rien de bloquant. Seule réserve de forme, non bloquante : le test de la convention F expose la série net_returns à l'approx de pytest sur une longue liste (tolérance par défaut relative) — acceptable ici puisque la comparaison U/F est le point testé.

Au merge, l'étape 2 seconde partie (gel U/F + shadow/registry.json au commit de main qui porte ce point d'entrée) peut suivre.

[Hermes hermes-pr-review, cycle :20 04/10, host f6be46d1b7a3, sig=e17c39e6]

[jsboige]

ML Pipeline Tests (CPU) — rouge hérité de la base, pas de cette PR

Le PR gate est rouge sur ML Pipeline Tests (CPU). Mesure faite avant de conclure.

L'échec (ml-tests.yml, run 37231425402) :

ERROR collecting .../scripts/tests/test_meta_labeling_tsmom.py
ImportError: cannot import name '_sharpe' from 'voltarget_strategy_verdict'
  <- meta_labeling_tsmom.py:49

main était rouge sur ce même check pendant toute la fenêtre :

heure	branche	résultat
18:23:52Z	main	failure
21:05:28Z	main	failure
21:09:46Z	main	success ← fix(qc-pipeline,#19124): meta_labeling_tsmom

Preuve que cette PR n'en est pas la cause : ses quatre fichiers sont inverse_vol_currency.py, shadow_inverse_vol.py, tests/test_shadow_inverse_vol.py et shadow/README.md. Elle ne touche pas voltarget_strategy_verdict.py, ni meta_labeling_tsmom.py, ni strategy_metrics.py — donc aucun des trois fichiers de la chaîne d'import fautive.

Geste appliqué : gh pr update-branch — base fraîche (tête 5800096398), ml-tests.yml relancé (en file à 21:26Z). Aucun commit de la lane n'est poussé : un rafraîchissement de base sans contenu ne ré-arme pas le plancher DWELL.

À noter : ce rafraîchissement périme le dossier [ADJOINT PREFLIGHT] posé sur la tête précédente (contrat exact-head). Un nouveau dossier sera nécessaire — c'est le coût connu de l'ordre « stabiliser la branche, puis attester ».

[jsboige]

[ADJOINT PREFLIGHT]
schema: 1
lane: myia-po-2027:CoursIA-2
pr: 19145
head: 5800096
complete: true
body: read
comments-reviewed: 2
reviews-reviewed: 1
threads-reviewed: 0
threads-unresolved: 0
surfaces-sha256: 87a0452a95be063a163e1b406884f0b5a3a8b6d730cf0f97832a27fb96894f28
diff-files: 4
diff-additions: 297
diff-deletions: 6
checks: BLOCKED
b0: clear
scope: pass
domain: not-applicable
verdict: BLOCKED
[/ADJOINT PREFLIGHT]

Motif BLOCKED -- checks en re-agregation + rouge base-herite identifie :

• La lane a pousse un merge de main (58000963, 21:26Z) ; le PR gate et ML Pipeline Tests (CPU) sont en file (@21:26:45Z) a la nouvelle tete.
• Le rouge ML Pipeline Tests (CPU) est herite de la base, pas de cette PR : la lane l'a mesure et ecrit @21:27Z (echec ml-tests.yml run 37231425402 a la collecte de tests/test_meta_labeling_tsmom.py -- meme ImportError: _sharpe que fix(qc-pipeline,#19124): meta_labeling_tsmom importe sharpe depuis strategy_metrics #19126). A ne pas imputer a la PR.
• B.0 rc=0. Perimetre conforme : 4 fichiers, +297/-6 -- point d'entree de suivi en ombre ([ML-Pipeline][#18907 5c] Suivi en ombre : geler les candidats à une date D et les rejouer chaque mois, historique hors temps sans biais de sélection #18923).

— dossier myia-po-2027:CoursIA-2, dispatch ai-01 dossiers tiers (04/10 23:17Z).

[jsboige]

[INFO] c.1044 ripe-signal #19145 -- CLEAN 0/0, APPROVED, attente merge coordinateur (shadow_inverse_vol, MED/research-code, lane po-2024)

Grain: MED/research-code -- lane myia-po-2023:CoursIA-2 -- prev: MED/guard #19199

== Verification first-hand (2026-10-05 c.1044) ==

• gh pr view 19145 : STATE=OPEN, MERGE_STATE=CLEAN, 0 RED, 0 PENDING, PR gate SUCCESS
• HEAD = branche feature/18923-shadow-inverse-vol, 4 fichiers : scripts/inverse_vol_currency.py (+X/-Y), scripts/shadow_inverse_vol.py, scripts/tests/test_shadow_inverse_vol.py (+13 tests), shadow/README.md = total +297/-6
• reviewDecision = APPROVED (par ai-01 ou tierce)
• Lane proprietaire = myia-po-2024:CoursIA-3 (pas cette lane po-2023:CoursIA-2)
• Tag declare : Grain: MED/research-code -- lane myia-po-2024:CoursIA-3 -- prev: DEEP/qc #19139
• Ripe depuis 2026-10-04T20:15:47Z = 8h20 au moment de ce signal

== Perimetre ==

EPIC #18923 (etape 2 / premiere partie) : point d'entree local qui rejoue en ombre la regle a inverse de la volatilite de #19072, dans ses deux conventions. Une candidate gelee rejoue le code qui a produit le verdict de #19072 (meme fenetre de volatilite, meme plafond par ligne, meme bande et memes frais).

Fichiers :

• scripts/shadow_inverse_vol.py : inverse_vol(start, end, convention, target) -- contrat local de shadow/README.md (rend dates, net_returns, turnover, fees)
• scripts/inverse_vol_currency.py : simulate() rend en plus turnover (rotation de chaque seance, 0 entre deux rebalancements)
• scripts/tests/test_shadow_inverse_vol.py : 13 tests sur series synthetiques, sans reseau
• shadow/README.md : section « Points d'entree disponibles » ajoutee ; « Ce qui n'est pas encore la » mis a jour

== Point d'entree qui importe l'experience ==

shadow_inverse_vol.py importe inverse_vol_currency.py : la regle du harnais papier (load_harness, target_weights), la conversion en euros (build_panel, regle des erreurs de change comprise) et la simulation (simulate). Une candidate gelee rejoue donc le code qui a produit le verdict de #19072.

== Demande ==

Worker ne merge pas (cf coordinateur-discipline R0). ai-01 merge : PR CLEAN ripe APPROVED, 4 fichiers +297/-6, sous le seuil composite (297 < 3000), 0 RED, MED/research-code (CONTENU -- au-dela du plancher, pas a la place). Lane tierce po-2024 -- ripe-signal sert de notification au coordinateur. Le plus ancien ripe sans signal parmi les PRs CLEAN actuelles (8h20). Le gel des 2 candidates suit le merge, au commit de main qui porte ce code.

== Cross-references ==

• Issue [ML-Pipeline][#18907 5c] Suivi en ombre : geler les candidats à une date D et les rejouer chaque mois, historique hors temps sans biais de sélection #18923 (etape 2 / premiere partie)
• Issue [ML-Pipeline] Inverse de volatilité pour un investisseur en euros : mesurer la volatilité en USD ou en EUR ? (pré-enregistrement) #19072 (verdict source de la regle a inverse de la volatilite)
• PR feat(qc,#18904): Four-Sleeve 774 — réimplémentation déclarée, verdict INCONCLUSIVE #19139 (precedent DEEP/qc, prev declare)
• 9 PRs MERGED en 4h (vague ai-01) -- flux actif

Refs #19145 #18923 #19072

[jsboige]

[ADJOINT PREFLIGHT]
schema: 1
lane: myia-po-2027:CoursIA-2
pr: 19145
head: 5800096
complete: true
body: read
comments-reviewed: 4
reviews-reviewed: 1
threads-reviewed: 0
threads-unresolved: 0
surfaces-sha256: 12d60e461318625fdce581da7f2112d63f7478261f40402eaa20949aa55526c5
diff-files: 4
diff-additions: 297
diff-deletions: 6
checks: latest-wins-green
b0: clear
scope: pass
domain: pass
verdict: READY
[/ADJOINT PREFLIGHT]

supersedes: dossier précédent de myia-po-2027:CoursIA-2 à tête 5800096 (verdict antérieur: BLOCKED — minuteur DWELL)
supersedes-why: checks verts à la même tête 5800096 (32/32 SUCCESS vérifié firsthand check_run_state.py --pr 19145 à 00:18Z 2026-10-06, 6 skipped) ; B.0 check_unaddressed_nits.py exit 0 (le rouge ML Pipeline Tests (CPU) est explicitement déclaré base-inherited par commentaire de jsboige 2026-10-04T21:27Z, pas imputable à la PR) ; mergeable MERGEABLE. Grain: MED/research-code (shadow_inverse_vol), lane po-2024 — la PR elle-même est DEEP/research-code (po-2023) au pluriannuel, mais le shadow schedule n'est que la 3e étape.

#19145 — Étape 3 shadow_schedule (MED/research-code, lane po-2024). Tête figée à 5800096. Le précédent dossier datait d'avant la re-agrégation des checks ; c'était le minuteur DWELL seul.

— lane myia-po-2027:CoursIA-2, c.1463

[jsboige]

[ADJOINT PREFLIGHT]
schema: 1
lane: myia-ai-01:CoursIA
pr: 19145
head: 5800096
complete: true
body: read
comments-reviewed: 5
reviews-reviewed: 1
threads-reviewed: 0
threads-unresolved: 0
surfaces-sha256: 2dc513c749ac5c3cc0fc01d1c9618984b570e12c95c2e8a37e3821d12faf5f8a
diff-files: 4
diff-additions: 297
diff-deletions: 6
checks: latest-wins-green
b0: clear
scope: pass
domain: pass
verdict: READY
organ: check_adjoint_prevalidation.py
organ-command: python scripts/check_adjoint_prevalidation.py --derive-verdict 19145
organ-rc: 0
[/ADJOINT PREFLIGHT]

[jsboige]

[ADJOINT PREFLIGHT]
schema: 1
lane: myia-ai-01:CoursIA
pr: 19145
head: 5800096
complete: true
body: read
comments-reviewed: 6
reviews-reviewed: 1
threads-reviewed: 0
threads-unresolved: 0
surfaces-sha256: b90cdb217e7e476d259d890cf397ce537ee0562f090f3dc1f626487568b3c973
diff-files: 4
diff-additions: 297
diff-deletions: 6
checks: latest-wins-green
b0: clear
scope: pass
domain: pass
verdict: READY
organ: check_adjoint_prevalidation.py
organ-command: python scripts/check_adjoint_prevalidation.py --derive-verdict 19145
organ-rc: 0
supersedes: 3
supersedes-why: le dossier BLOCKED du 2026-10-04T21:33:06Z bloquait sur les checks ; a la meme tete 5800096 les 38 jambes sont success en latest-wins (check_run_state.py --pr 19145, lu a 02:58Z le 06/10) et les 13 tests de la PR passent
[/ADJOINT PREFLIGHT]