Feat/ecosystem cartography

AGENTS.md

@@ -4,6 +4,8 @@
 You MUST read the rules relevant to your current task. Read R1 first.
 To read a rule, use your 'view_file' tool on the corresponding file in the master folder.
 
+**ALSO READ**: `DEV_RULES.md` in this repo — project-specific rules for bug resolution and code quality.
+
 ## Rule Index
 - **rule_01_foundation**: RULE 1: Read Rules First — MANDATORY
 - **rule_02_mom_test**: RULE 2: Mom Test Gate - Full Detail
@@ -50,3 +52,4 @@ To read a rule, use your 'view_file' tool on the corresponding file in the maste
 - **rule_97_launch_planning**: RULE 97: Launch Planning Master Template
 - **rule_98_prelaunch_verification**: RULE 98: Pre-Launch MVP Verification Protocol
 - **rule_99_acquisition_tracker**: RULE 99: Acquisition Tracker — Mémoire des Posts Marketing
+- **rule_107_upstream_pr_strategy**: RULE 107: Upstream PR Strategy - Credibility Through Merged Contributions

CHANGELOG.md

@@ -7,6 +7,35 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.3.2] - 2026-06-09
+
+### Added
+- **Multi-Repo Ecosystem cartography** (R105): NeuralDBG-Engine added as optional 4th component in [`docs/ecosystem.md`](docs/ecosystem.md); cross-repo SemVer tracking via new [`COMPATIBILITY_MATRIX.md`](COMPATIBILITY_MATRIX.md); "Écosystème (Multi-Repo)" section in `ROADMAP.md`.
+- **Composite-module hook support**: `dbg.register_composite_hook(module)` for `nn.MultiheadAttention` and other modules with no leaf submodules.
+- **Silent-loss and zero-leaf warnings**: detects loss=0 with non-zero gradients, and `register_full_backward_hook` no-op setups.
+- **MHA fully-masked-row remediation rule**: `apply_mha_mask_workaround()` in Neural-Agent, wired to NeuralDBG events.
+- **End-to-end Neural-Agent pipeline**: `diagnose -> fix -> validate -> apply -> re-run`, 87 tests passing.
+- **Bug catalog BUG-001..004**: MHA NaN, varlen_attn NaN, MPS gradients, Qwen3.5 SDPA gradient explosion.
+- **Public benchmark** (5 scenarios): all at 1.0 accuracy; comparison v2 vs W&B / MLflow / TensorBoard.
+- **Aquarium JSON export**: full schema (`schema/events.json`), 14 unit tests in `test_aquarium_export.py`.
+- **Phase 7 — Two-Package Architecture**: conditional import of `neuraldbg-engine` with seamless fallback in `neuraldbg` core.
+- **Zero-Warnings Policy**: `filterwarnings` in `pyproject.toml` drops warnings 616 → 5.
+- **Cross-repo contract**: `dbg.explain_failure()` and `events.json` schema v1 stable; `dbg` works without engine and without agent.
+
+### Changed
+- **PUBLIC → multi-repo narrative**: `ROADMAP.md` updated from "three-part" to "four-part" system (NeuralDBG, Neural-Agent, Aquarium, neuraldbg-engine).
+- **Upstream PR tracker** updated: 4 comments posted, 1 PR submitted (pytorch/pytorch#186786, OPEN).
+- **Benchmark table** expanded from 4 → 5 scenarios.
+
+### Fixed
+- Unicode/emoji terminal rendering encoding crash on Windows consoles for `quickstart.py`.
+- Mock comparison removed from `benchmark_public/` — replaced by real `real_comparison.py` (R79 honesty).
+- Deduplication of logical causal couplings in `detect_coupled_failures()` and Mermaid graph export.
+
+### Security
+- `assert` removed from production code paths (R39 compliance).
+- Bandit scan wired to pre-commit (skips B101 — acceptable for tests).
+
 ## [1.3.1] - 2026-05-20
 
 ### Added

COMPATIBILITY_MATRIX.md

@@ -0,0 +1,74 @@
+# COMPATIBILITY_MATRIX.md — NeuralSuite
+
+> Cross-repo SemVer matrix for the NeuralSuite ecosystem.
+> MANDATORY per R105. Update on every breaking change in a shared interface.
+
+## Versions
+
+| Repo                  | Current | Released     | Distribution                  | Owner class (R87) |
+|-----------------------|--------:|--------------|-------------------------------|-------------------|
+| `NeuralDBG`           |  1.3.2  | 2026-05-20 (1.3.1) | Public PyPI `neuraldbg`       | OWNED (LambdaSection) |
+| `Neural-Agent`        |  0.1.0  | not yet (dev)     | Private (closed beta)         | OWNED (LambdaSection) |
+| `Aquarium`            |  0.1.0  | MVP delivered     | Source (Tauri desktop)        | OWNED (LambdaSection) |
+| `NeuralDBG-Engine`    |  1.0.0  | 2026-06 (pkg)     | GitHub Packages (private)     | OWNED (LambdaSection, private) |
+
+## Pairwise Compatibility
+
+| Consumer \ Provider       | neuraldbg ≥1.3.0 | neuraldbg-engine ≥1.0.0 | events.json schema v1 |
+|---------------------------|:----------------:|:-----------------------:|:---------------------:|
+| `neural-agent` ≥0.1.0     | ✅ compatible    | n/a (consumes dbg API)  | n/a (in-process)      |
+| `aquarium` ≥0.1.0         | ✅ (reads JSON)  | n/a                     | ✅ strict (see schema/events.json) |
+| `neuraldbg` w/ `neuraldbg-engine` | n/a        | ✅ compatible (1.0.0+)  | n/a                   |
+| `neuraldbg` w/o engine    | n/a              | ✅ graceful fallback    | n/a                   |
+
+**Status legend**: ✅ compatible — 🟡 breaking-pending — ❌ incompatible
+
+## Shared Interface Contracts
+
+### 1. `dbg.explain_failure() -> list[CausalHypothesis]` (Python, in-process)
+- **Owner**: `NeuralDBG`
+- **Consumers**: `Neural-Agent`
+- **Stability**: stable since 1.3.0
+- **Required methods on `CausalHypothesis`**: `failure_type: str`, `root_cause_layer: str | None`, `root_cause_step: int | None`, `confidence: float`, `description: str`, `evidence: list[str]`, `remediation_hint: str | None`
+- **Bump rule**: any change to field types / removal = MAJOR bump in `neuraldbg` + MAJOR bump in `neural-agent`
+
+### 2. `events.json` (JSON, out-of-process)
+- **Owner**: `NeuralDBG` (writes), `Aquarium` (reads)
+- **Schema file**: `neuraldbg/schema/events.json`
+- **Stability**: versioned, see `schema_version` field
+- **Bump rule**: any required field added = MINOR bump + Aquarium update; any field removed/renamed = MAJOR bump + Aquarium update
+
+### 3. `NeuralDBG-Engine` import contract (Python, in-process, optional)
+- **Owner**: `NeuralDBG-Engine` (writes), `NeuralDBG` (reads)
+- **Discovery**: `importlib.util.find_spec("neuraldbg_engine")` + `from neuraldbg_engine import CausalEngine`
+- **Required class**: `CausalEngine(dbg)` with methods:
+  - `detect_gradient_transition(prev_norm, current_norm)`
+  - `classify_gradient_health(norm)`
+  - `classify_activation_health(stats)`
+- **Bump rule**: any method signature change = MAJOR bump in `neuraldbg-engine` + MINOR bump in `neuraldbg` core
+
+## Last Integration Test
+
+| Date       | Test                                    | Result |
+|------------|-----------------------------------------|--------|
+| 2026-06-08 | `tests/integration/test_lstm_demo.py`   | ✅ pass |
+| 2026-06-08 | `tests/integration/test_gan_demo.py`     | ✅ pass |
+| 2026-06-08 | `tests/integration/test_torch_compile_demo.py` | ✅ pass |
+| 2026-06-08 | `tests/integration/test_critical_scenarios.py` | ✅ pass |
+
+## Required Upgrade Paths
+
+### If `neuraldbg` moves to 2.0.0 (breaking):
+- `neural-agent` must move to 0.2.0 (consume new API)
+- `aquarium` must move to 0.2.0 (read new JSON schema)
+- `neuraldbg-engine` must be re-validated against new core (compatibility patch if needed)
+
+### If `events.json` schema moves to v2:
+- `neuraldbg` must write v2
+- `aquarium` must read v2 (with v1 → v2 migration helper)
+
+## Sync Coordination
+
+- **Branch strategy**: per R30 — each repo uses its own trunk (`main`), features in `feat/*`, fixes in `fix/*`
+- **Tag coordination**: SemVer tags on each repo, no lock-step. Cross-repo compatibility validated by integration test suite in `NeuralDBG/tests/integration/`
+- **CI cross-repo**: triggered manually for now (no monorepo CI). Run from `NeuralDBG/` after pulling latest `neural-agent` and `neuraldbg-engine` tags.

DEV_RULES.md

@@ -0,0 +1,181 @@
+# DEV_RULES.md — Règles spécifiques au développement NeuralDBG
+
+> Ces règles s'ajoutent aux kuro-rules générales.
+> Elles sont LIES au code, au repo, et au processus de résolution de bugs.
+> Lues obligatoirement en début de session avec R1.
+
+---
+
+## Règle D1 : Chaque bug DOIT améliorer NeuralDBG
+
+**Problème** : On documente des bugs sans que NeuralDBG évolue. Zéro valeur ajoutée.
+
+**Solution** : Pour CHAQUE bug chassé, AU MOINS une de ces livrables doit exister :
+1. Nouveau type d'événement dans le moteur (ex: `gradient_norm_spike`, `sdpa_fallback`)
+2. Nouvelle règle dans `remediation_rules.py` (Neural-Agent)
+3. Nouveau template dans `explain.py` (hypothèse causale)
+4. Nouveau test dans `tests/` qui valide la détection
+5. Amélioration d'un hook existant (ex: composite hook après BUG-001)
+
+**Vérification** :
+```
+AVANT de documenter un bug:
+  -> Qu'est-ce que NeuralDBG gagne ?
+  -> Si rien: ne pas créer le bug tracker, retourner au code
+```
+
+**Enforcement** : IF bug documented sans amélioration NeuralDBG -> SUPPRIMER le bug tracker.
+
+---
+
+## Règle D2 : Pas de workaround. Jamais.
+
+**Problème** : On écrit "workaround" au lieu de "fix". Un workaround n'est pas une résolution.
+
+**Solution** :
+- Si le bug est dans PyTorch/upstream → soumettre un PR qui le RÉSOUT (pas `warnings.warn`)
+- Si le bug est dans notre code → le corriger dans NeuralDBG/Neural-Agent
+- Si on ne peut pas résoudre → documenter POURQUOI on ne peut pas, puis passer à un autre bug
+- Le mot "workaround" est INTERDIT dans les livrables. Utiliser "fix" ou "resolution".
+
+**Vérification** :
+```
+grep -r "workaround" docs/ examples/ --include="*.md" --include="*.py"
+# Doit retourner 0 résultats
+```
+
+---
+
+## Règle D3 : Reproduction SANS hardware spécifique
+
+**Problème** : BUG-003 (MPS) et BUG-004 (GPU) nécessitent du hardware qu'on n'a pas. On les documente et on stagne.
+
+**Solution** : Pour chaque bug nécessitant du hardware absent :
+
+| Hardware manquant | Alternative |
+|-------------------|-------------|
+| GPU CUDA | Kaggle free (T4), Google Colab free (T4), `torch.compile` mode CPU avec simulation |
+| MPS (Apple Silicon) | Unit test sur le CODE PATH (pas le hardware) : mocker `torch.device("mps")`, tester la logique de gradient scaling |
+| Multi-GPU | `torchrun --nproc_per_node=1` + gradient accumulation simulation |
+| Modèle gros (72B) | Utiliser le plus petit modèle dispo (0.6B, 1.5B) qui reproduce le même pattern |
+
+**Pour MPS specifiquement** :
+- Lire le code source de `aten/src/ATen/native/mps/operations/` pour comprendre le path
+- Écrire un test qui valide le behavior attendu SANS exécuter sur MPS
+- Si le bug est numerical (mauvais gradients), reproduire la condition numerique sur CPU
+
+**Enforcement** : IF bug ne peut pas être reproduit -> écrire le test unitaire qui CATCHERAIT le bug si le hardware était disponible, PUIS passer au bug suivant.
+
+---
+
+## Règle D4 : PRs upstream = pipeline complet NeuralDBG + Neural-Agent
+
+**Problème** : PR #186631 (pytorch) fermée car c'était juste un `warnings.warn()`. Pas de valeur NeuralSuite.
+
+**Solution** : Chaque PR upstream doit contenir :
+1. **Detection** : montrer que NeuralDBG détecte le bug (ex: output de `explain_failure()`)
+2. **Resolution** : montrer que Neural-Agent propose/applique le fix
+3. **Preuve** : script de reproduction + log NeuralDBG avant/après fix
+4. **Code fix** : le vrai patch dans le code upstream
+
+**Template** : `.github/PR_TEMPLATES/upstream-fix.md`
+
+**Enforcement** : IF PR upstream sans démo NeuralDBG+Agent -> NE PAS SOUMETTRE.
+
+---
+
+## Règle D5 : Les bugs sont des features, pas de la documentation
+
+**Problème** : On crée des fichiers `BUG-XXX.md` qui sont juste des descriptions de bugs. Aucune valeur pour NeuralDBG.
+
+**Solution** : Chaque BUG-XXX.md doit contenir une section "NeuralDBG Improvement" qui détaille EXACTEMENT ce qui a changé dans le code :
+- Fichier modifié + ligne
+- Nouveau test ajouté
+- Nouveau type d'événement
+- Nouvelle hypothèse causale
+
+**Enforcement** : IF BUG-XXX.md sans section "NeuralDBG Improvement" avec code reference -> supprimer le fichier.
+
+---
+
+## Règle D6 : Alternatives hardware pour chaque bug
+
+### BUG-003 (MPS wrong gradients) — Plan de reproduction
+
+Le bug : PyTorch MPS retourne des gradients incorrects (pytorch#177116).
+
+**Pas besoin de hardware MPS pour** :
+1. Lire le code source PyTorch : `aten/src/ATen/native/mps/operations/Linear.mm`
+2. Écrire un test qui compare le gradient CPU vs la valeur attendue
+3. Montrer que NeuralDBG detecterait le gradient incorrect via `gradient_health_transition`
+4. Écrire la règle Neural-Agent qui suggererait "use CPU for gradient verification"
+
+**Action concrète** :
+```python
+# test_mps_gradient_detection.py
+# Test que NeuralDBG detecte un gradient incorrect PEU IMPORTE le device
+def test_gradient_injection_detected():
+    """Simule le bug MPS en injectant un gradient incorrect."""
+    model = nn.Linear(10, 5)
+    x = torch.randn(2, 10)
+    loss = model(x).sum()
+    loss.backward()
+    # Injecter le comportement MPS: gradient *= 0 (ou gradient = random)
+    with torch.no_grad():
+        model.weight.grad.fill_(0.0)  # simulation gradient zero
+    # NeuralDBG doit detecter ça
+    with NeuralDbg(model) as dbg:
+        # re-forward pour capturer
+        ...
+```
+
+### BUG-004 (Qwen3.5 SDPA) — Plan de reproduction
+
+Le bug : SDPA dense mask → Math backend → BF16 collapse → gradient explosion.
+
+**Pas besoin de GPU A100 pour** :
+1. Utiliser `Qwen/Qwen3-0.6B` (600M params, tourne sur T4 Colab free)
+2. Kaggle free (16h GPU/mois) — notebook déjà créé
+3. Google Colab free (T4 GPU, 4h/session)
+4. CPU : forcer SDPA sur petit modèle, vérifier le code path du mask
+
+**Action concrète** :
+- Kaggle notebook déjà prêt (`notebooks/train_neuralagent_kaggle.ipynb`)
+- Colab : même notebook, upload et exécuter
+- Vérifier que `attn_implementation="sdpa"` est bien utilisé
+
+---
+
+## Règle D7 : Checklist avant de dire "bug documenté"
+
+Pour chaque bug, AVANT de marquer comme "done" :
+
+- [ ] Script de reproduction créé et **testé** (pas juste écrit)
+- [ ] NeuralDBG amélioré (nouveau code, pas juste docs)
+- [ ] Test unitaire ajouté
+- [ ] Si hardware manquant : test unitaire qui catcherait le bug
+- [ ] PR upstream rédigée (pas juste un commentaire)
+- [ ] Aucun "workaround" dans les livrables
+
+---
+
+## Règle D8 : Reproduction distante (Remote Reproducer)
+
+**Problème** : 60%+ des data scientists travaillent sur CPU. Les bugs GPU/CUDA/MPS sont impossibles à reproduire localement. NeuralDBG devient inutile pour ces users.
+
+**Solution** : Module `neuraldbg.remote` qui envoie le script de reproduction vers un service GPU distant :
+- Phase 1 : Google Colab (gratuit, T4, upload manuel) — 2 semaines
+- Phase 2 : Kaggle (gratuit, 30h/mois, API automatique) — 2 semaines
+- Phase 3 : RunPod/Lambda (payant, A100, REST API) — 1 mois
+
+**Architecture** : `docs/REMOTE_REPRODUCE.md`
+
+**Impact marché** : TAM élargi de 40% (GPU users) à 100% (tous les users). Aucun outil de diagnostic ne fait ça.
+
+**Enforcement** : Ne PAS commencer l'implémentation tant que l'architecture n'est pas validée par CEO.
+
+---
+
+**Créé** : 2026-06-08
+**Trigger** : 4 bugs documentés, 1 seul a amélioré NeuralDBG (BUG-001), 0 résolus, 0 PRs soumises
+**Enforcement** : OBLIGATOIRE

ROADMAP.md

@@ -2,15 +2,29 @@
 
 > The complete toolkit for diagnosing and fixing deep learning training failures.
 
+## Écosystème (Multi-Repo)
+
+NeuralDBG fait partie d'un écosystème à 4 composants. Voir aussi :
+- [docs/ecosystem.md](file:///c:/Users/Utilisateur/Documents/NeuralDBG/docs/ecosystem.md) — Contrat d'intégration (MID ECO-001)
+- [COMPATIBILITY_MATRIX.md](file:///c:/Users/Utilisateur/Documents/NeuralDBG/COMPATIBILITY_MATRIX.md) — Matrice SemVer inter-repos
+
+| Composant | Rôle | Statut |
+|---|---|---|
+| **NeuralDBG** (ce repo) | Moteur de diagnostic causal | v1.3.2 ✅ |
+| **Neural-Agent** | Auto-correcteur | Pipeline built (closed beta) |
+| **Aquarium** | Visualiseur IDE (Tauri) | MVP livré, dormant |
+| **neuraldbg-engine** | Inférence causale avancée (optionnel) | v1.0.0 (registry privé) |
+
 ## What is NeuralSuite?
 
-NeuralSuite is a three-part system that catches training problems before they waste your GPU hours:
+NeuralSuite is a four-part system that catches training problems before they waste your GPU hours:
 
 | Component | What it does | Install |
 |-----------|-------------|---------|
 | **NeuralDBG** | Causal diagnostic engine — hooks into PyTorch, captures gradient/activation events, detects root causes | `pip install neuraldbg` |
 | **Neural-Agent** | Auto-corrector — diagnoses failures and applies source-level fixes to training scripts | `pip install neural-agent` |
 | **Aquarium** | Visualizer — interactive causal tree viewer for NeuralDBG exports | Desktop app (Tauri) |
+| **neuraldbg-engine** *(optional)* | Advanced causal inference — adds data anomaly, optimizer instability, cross-arch coupling detection | Private registry (closed beta) |
 
 ## Why NeuralSuite?
 
@@ -61,6 +75,17 @@ print(dbg.explain_failure())
 - [x] Tool comparison v2: NeuralDBG vs W&B vs MLflow vs TensorBoard
 - [ ] First upstream PR submitted
 
+### Upstream PR Tracker
+
+| Bug | Upstream Issue | PR Status | Merge Date |
+|-----|---------------|-----------|------------|
+| BUG-001 | pytorch/pytorch#41508 | Comment posted | - |
+| BUG-002 | pytorch/pytorch#176793 | PR #186786 submitted, comment posted | - |
+| BUG-003 | pytorch/pytorch#177116 | Comment posted | - |
+| BUG-004 | huggingface/transformers#44928 | Comment posted | - |
+
+**Comments posted**: 4 | **PRs submitted**: 1 | **Merged**: 0 | **Merge rate**: 0%
+
 ### v1.4.5 — Catalog Expansion (July-August 2026)
 - [ ] 10 real bugs cataloged (MHA, GNN, LSTM, GAN, diffusion, transformers, RL)
 - [ ] Reproducible public benchmark on 5+ real scenarios
@@ -77,7 +102,7 @@ print(dbg.explain_failure())
 
 ## Benchmark Results (v1.3.2)
 
-4 scenarios, healthy excluded from averages:
+5 scenarios, healthy excluded from averages:
 
 | Tool | Detection (loss-only) | Detection (+grad norms) | Localization |
 |------|:---------------------:|:-----------------------:|:------------:|

data/activation_stats_demo.npy.dvc

@@ -1,5 +1,5 @@
 outs:
-- md5: ce7ee96c89a375e54dc098570ce132e5
+- md5: ce7ee96c89a375e54dc098570ce132e5  # pragma: allowlist secret
   size: 6528
   hash: md5
   path: activation_stats_demo.npy

data/gradient_norms_demo.npy.dvc

@@ -1,5 +1,5 @@
 outs:
-- md5: 74df5c8478ca7f9834700e16fcdbbea7
+- md5: 74df5c8478ca7f9834700e16fcdbbea7  # pragma: allowlist secret
   size: 1728
   hash: md5
   path: gradient_norms_demo.npy

docs/LINEAR_CURSOR_SETUP.md

@@ -43,7 +43,7 @@ Creer un fichier secret local (hors repo) et le charger automatiquement:
 ```bash
 mkdir -p ~/.config/secrets
 cat > ~/.config/secrets/linear.env <<'EOF'
-export LINEAR_API_KEY='lin_api_xxx'
+export LINEAR_API_KEY='your_linear_api_key_here'  # pragma: allowlist secret
 EOF
 chmod 600 ~/.config/secrets/linear.env
 ```