Skip to content

Plan dossier — CVN-N014-ED-S04 · Standard & docs (guideline + review gate)

Story : CVN-N014-ED-S04 (wp#245, GH #1108) · Epic : CVN-N014-ED · Dépend de : S01 (ADR-0100), S02 (pattern s43_io), S03 (lui a transféré l'enforcement). Dernière Story de l'Epic. Statut : plan révisé post-plan_review — impl conditionnée aux corrections P0 ci-dessous. Standard : ADR-0101.

plan_review — verdict & corrections (2026-06-07)

Session committee 59ba834a (issue #1108) — PASSED · code EXECUTION_RISK · consensus strong (5 experts). JSON : committee/sessions/59ba834a_committee.json.

Validé sans réserve : gate à la review (vs runtime) = bonne couche ; guideline dans documentation/process/ + lien ADR-0100 comme SSoT = correct ; exception single-pod phrasable.

Blocker (4/5 experts, dissent ml-engineer) — load-bearing : le gate planifié visait dags/** seul, mais le code de transport de l'incident fondateur vit dans src/ (src/commun/finetune/diagnostic/hamilton/s43_io.py). Les DAGs orchestrent ; la logique de transport large-data cross-pod est dans le code appelé par les KubernetesPodOperator/step-runners. Un gate dags/**-only aurait raté l'incident que l'Epic prétend empêcher. Le ml-engineer juge ça hors-scope ; on ne le suit pas : l'Epic ED vise le transport inter-task/cross-pod, pas le DAG authoring.

Corrections intégrées au plan (priorisées) : - P0 — élargir le scope du gate à la surface runtime réelle du transport : dags/** (wiring) + src/commun/finetune/** (logique diagnostic/step-code) + scripts/** (si step-scripts KPO). Voir §4.2 / §6 révisés. - P0 — classification par suspicion, pas seulement par chemin : déclencher sur np.savez/np.load/to_parquet/to_pickle/put_object/upload_fileobj//tmp-path/manifest S3/XCom-de-références. Nuance conservée : single-pod borné = allowed ; inter-task/pod = disallowed ; pass-by-ref S3 (manifest/clé XCom) = allowed. - P0 — exemples allowed/disallowed concrets dans le guideline. - P0 — adoucir la DoD : « structurellement empêché de revenir » → « fortement dissuadé / review-gated » (process+review = dissuasion forte, pas garantie technique absolue). - P1 — PR/fixture de régression du gate (promue de nice-to-have) : un faux workaround dans src/commun/finetune/** ET dans dags/** doit être flaggé ; un cleanup légitime ne doit pas l'être. - P1 — anti-désync .coderabbit.yaml ↔ prompt-library/review/coderabbit-path-instructions.yaml.

Partie I — Cadrage (lecteur)

0. Problématisation (sans jargon)

Le standard de transport inter-tâches existe désormais (object-storage XCom — S01 ; pass-by-référence S3 — S02 ; inventaire vide — S03). Mais sans une règle écrite + un filet à la review, la classe de bug revient : un futur auteur de DAG re-bricolera un stockage intermédiaire par-tâche (chemin S3 à la main, /tmp local, npz maison), et on re-tombera sur l'incident fondateur de l'Epic (s43 : prédictions perdues cross-pod). S04 codifie le standard (un guideline lisible, publié) et pose le gate (un item de review qui rejette tout nouveau stockage bricolé → return/pull). C'est le garde-fou anti-régression de l'Epic — celui à qui S03 a transféré l'enforcement.

0bis. Les constats sur lesquels on construit (vérifiés)

  1. ADR-0100 (standard de transport, S01) existe et est déjà référencé 11× dans documentation/.
  2. s43_io (S02) est le pattern de référence pass-by-référence-vers-S3 (run-isolé, schéma fail-loud, manifest) — prouvé cross-pod (smoke 5/5).
  3. S03 a transféré ici l'exigence normative « no new large-data cross-pod bespoke transport » (Option A — S03 a fermé sans bloquer sur S04).
  4. .coderabbit.yaml porte déjà des reviews.path_instructions par glob, dont des entrées dags/ (dags/launch__*.py, dags/dag_pte__*.py) — précédent direct pour ajouter le gate. Fichier hand-maintained (pas généré).
  5. Les guidelines du projet vivent dans documentation/process/ (ex. DIAGNOSTIC_HAMILTON_PATTERN.md, SKILL_AUTHORING_STANDARD.md).

1. User stories

  • En tant qu'auteur d'un nouveau DAG, je veux une page claire « comment passer des données entre tâches » (petit → XCom ; volumineux → return/pull, le backend gère ; jamais de store bricolé), pour faire bien du premier coup.
  • En tant que relecteur (CodeRabbit / comité), je veux un item de review automatique qui flague tout DAG écrivant un store intermédiaire à la main, pour que la régression soit attrapée à la PR, pas en prod.

2. Hypotheses (testable, EN)

  • H1 — A written guideline + a review gate prevent the regression that S01–S03 fixed. The bug class is "invisible to test + review" (Epic §0bis) → only a normative doc + a review-time flag catch it. Test: the guideline is live (200) and the CodeRabbit dags/** path-instruction flags a hand-rolled np.savez/put_object/to_parquet-to-path in a new DAG.
  • H2 — The gate belongs at review, not runtime. A runtime check can't tell "bespoke store" from "legitimate single-pod capture". A human/LLM reviewer with the rule can. Test: the path-instruction phrasing distinguishes cross-pod bespoke (reject) from single-pod-bounded (allow) — the S03 rule.
  • H3 — No code change is needed. S04 is a guideline (docs) + a CodeRabbit config entry — now spanning dags/** + src/commun/finetune/** + scripts/** (config globs, not code) — (+ its prompt-library mirror + a committee checklist note). Test: the merge diff touches only documentation/**, .coderabbit.yaml (+ mirror), mkdocs.yml. The P1 regression fixture is validation-only (demo PR), not part of S04's normative diff.

3. State of the art (EN)

  • CodeRabbit path_instructions (.coderabbit.yaml): per-glob natural-language review instructions — the project already uses them for src/commun/pipeline/**, dags/launch__*.py, etc. Adding a dags/** entry is the idiomatic gate.
  • ADR referencing (Epic §8): ADR-0100 is the SSoT; the guideline links to it rather than restating, so the rule has one home.
  • Reference pattern: s43_io (S02) + runbook s43 transport — the guideline points DAG authors at it for the large-data case.
  • Strangler-fig completion (S03): the inventory is empty; S04 is the fence that keeps it empty.

4. Definition of Done

  1. Guideline LIVE sur docs.cvntrade.eu — page documentation/process/INTER_TASK_DATA_TRANSPORT.md, dans la nav, URL 200 : petit → XCom natif ; volumineux → return/pull (le backend object-storage gère, ADR-0100) ; jamais de store bricolé par-tâche ; le cas large-data renvoie au pattern s43_io + runbook ; la règle single-pod (S03) explicitée avec exemples concrets allowed/disallowed (P0) : /tmp single-pod borné (producteur+consommateur même pod) = allowed ; /tmp/fichier local lu par une autre task/pod = disallowed ; pass-by-ref S3 (manifest + clé XCom, cf. s43_io) = allowed.
  2. Item de review EN PLACE — scope runtime réel (P0) : .coderabbit.yaml (+ le mirror prompt-library/review/coderabbit-path-instructions.yaml si sync) porte le path_instructions anti-bespoke-store sur dags/** (wiring) + src/commun/finetune/** (logique step-code, où vivait s43_io) + scripts/** (step-scripts KPO) — pas dags/** seul. Déclenchement par suspicion de transport large-data cross-pod : np.savez/np.load/put_object/upload_fileobj/to_parquet/to_pickle/chemin /tmp/manifest S3/XCom-de-références écrit par-tâche, et demande return/pull ou le pass-by-ref S3 partagé (exception : capture single-pod bornée) — référence ADR-0100.
  3. Note checklist comité : l'exigence ajoutée à la checklist de pr_review (le pendant humain du gate CR).
  4. Epic §8 : ADR-0100 référencé depuis le guideline (un home pour la règle).
  5. Régression du gate démontrée (P1, promue) : une fixture/PR de démo où un faux workaround dans src/commun/finetune/** ET dans dags/** est flaggé par le gate, et un cleanup légitime ne l'est pas.
  6. Pas de régression code : diff docs/config only (documentation/** + .coderabbit.yaml (+ mirror) + mkdocs.yml).

5. Consolidation

S04 scelle l'Epic : après que S01–S03 ont posé le standard et vidé l'inventaire, S04 garantit qu'il tient dans le temps — une page guideline lisible (le quoi faire) + un gate de review (le quoi rejeter) couvrant la surface runtime réelle du transport (DAG wiring + step-code src/commun/finetune/** + scripts/**), pas seulement les fichiers DAG. Le gate est volontairement à la review (pas runtime) : c'est le seul endroit où l'on distingue un store bricolé cross-pod (à rejeter) d'une capture single-pod légitime (à autoriser) — la règle de S03. Une fois S04 Closed, l'Epic CVN-N014-ED est complète : le bug « transport bricolé par-tâche » est corrigé (S01–S03) et la régression est fortement dissuadée et review-gated (S04) — un garde-fou robuste, pas une garantie technique absolue (le gate review reste tributaire de la vigilance humaine/LLM ; P1 = fixture de régression pour la valider, et un check CI statique reste une extension future possible).

Partie II — Plan

6. Design

  • Guideline : documentation/process/INTER_TASK_DATA_TRANSPORT.md — concis, orienté décision (un arbre : taille du payload ? JSON-sérialisable ? → XCom natif / return/pull / pass-by-ref-S3), liens ADR-0100 + s43_io + runbook, la règle single-pod avec exemples concrets allowed/disallowed (P0). Wiré dans la nav MkDocs (sous Process).
  • Review gate (P0 — scope corrigé) : le bloc path_instructions anti-bespoke-store dans .coderabbit.yaml couvre dags/**, src/commun/finetune/**, scripts/** (la surface runtime du transport — pas dags/** seul ; le bug fondateur s43_io.py est sous src/commun/finetune/**, qui a déjà une entrée CR → ajout co-localisé) :

    « Tout np.savez/np.load/put_object/upload_fileobj/to_parquet/to_pickle, ou chemin /tmp/fichier local/manifest S3/XCom-de-références, écrit par une tâche pour passer des données à une autre tâche/pod = anti-pattern (ADR-0100). Exiger return/xcom_pull (le backend object-storage gère l'offload) ou le pass-by-référence-S3 partagé (cvntrade_s3_manager, cf. s43_io). Déclenchement par suspicion (pas seulement par chemin touché). Exception : capture single-pod bornée (producteur+consommateur même pod) ; /tmp partagé entre tasks/pods = à rejeter. »

  • vérifier/synchroniser le mirror prompt-library/review/coderabbit-path-instructions.yaml (P1 — anti-désync : éditer la source, vérifier la relation source↔généré).
  • Comité : ajouter l'item à la checklist pr_review (où elle vit).
  • Validation du gate (P1, promue) : fixture/PR de démo — un faux workaround dans src/commun/finetune/** et dags/** doit être flaggé ; un cleanup légitime ne doit pas l'être.

7. Fichiers / actions

Fichier Action Prio
documentation/process/INTER_TASK_DATA_TRANSPORT.md créer le guideline (live) + exemples allowed/disallowed P0
mkdocs.yml wirer le guideline dans la nav (Process) P0
.coderabbit.yaml ajouter le path_instructions anti-bespoke-store sur dags/** + src/commun/finetune/** + scripts/** (gate, scope runtime) P0
prompt-library/review/coderabbit-path-instructions.yaml sync si mirror-source + vérifier la relation source↔généré P1
fixture/PR de démo du gate régression : workaround flaggé dans src/commun/finetune/** et dags/** ; cleanup légitime non-flaggé P1
doc-set S04 (hub + ce plan) ADR-0101 P0
OP Epic CVN-N014-ED : noter la clôture imminente (S04 = dernière) P0

8. Risques

  • R1 — guideline ignoré : un doc que personne ne lit. Mitigation : le gate CR est le filet actif (la page est la référence, le gate est l'enforcement).
  • R2 — faux positifs du gate CR : flaguer une capture single-pod légitime. Mitigation : l'instruction porte l'exception single-pod (règle S03) explicitement + exemples allowed/disallowed dans le guideline (P0).
  • R3 — mirror .coderabbit.yaml désynchronisé : éditer un côté seulement. Mitigation : vérifier la relation source↔généré ; éditer la source (P1).
  • R4 — pas de test runtime : assumé (H2 — le gate est à la review). Le « test » = une PR/fixture de démonstration où le gate flague un workaround volontaire — promu P1 (de optionnel à quasi-DoD §4.5).
  • R5 — dags/**-only raterait le bug fondateur (blocker plan_review) : le transport vit dans le step-code (src/), pas le wiring DAG. Mitigation (P0) : scope du gate étendu à src/commun/finetune/** + scripts/** + dags/**, déclenchement par suspicion. Limite résiduelle : un step-script KPO via image/commande custom hors de ces globs resterait non couvert → check CI statique = extension future (hors S04, à tracer si besoin).

9. Done-criteria (rappel)

Guideline live (200) + dans la nav (avec exemples allowed/disallowed) · item de review en place sur la surface runtime (.coderabbit.yaml dags/** + src/commun/finetune/** + scripts/**, déclenchement par suspicion + checklist comité) · ADR-0100 référencé depuis le guideline · fixture de régression du gate (P1) · diff docs/config-only → S04 Closed = Epic CVN-N014-ED complète (régression fortement dissuadée / review-gated).