@neikyun/ciel 6.14.0 → 6.14.2

package/assets/.claude/skills/ciel/reference.md

@@ -0,0 +1,171 @@
+# Ciel — Reference
+
+Detailed philosophy, full Guards table, and research basis. Loaded on-demand when the orchestrator needs deep context.
+
+---
+
+## Philosophy
+
+> *"Understand before generating. Verify before claiming done."*
+
+LLMs code by statistical pattern-matching, not reasoning. Ciel forces understanding — framework philosophy, data flow tracing, alternatives consideration, hostile self-critique — before, during, and after code generation.
+
+A thinking process — not a mechanical checklist. Apply with judgment. Adapt depth to risk.
+
+Named after the Primordial Sage from *Tensei Shitara Slime Datta Ken* — the advisor who reasons at infinite speed before Rimuru acts.
+
+---
+
+## Skill catalog (33 skills)
+
+### Orchestrator (1)
+- `ciel` — this skill, routes to the others
+
+### Workflow (15) — replaces the old monolithic pipeline
+
+| Skill | Replaces | Mandatory for |
+|-------|----------|---------------|
+| `depth-classifier` | Depth Gauge table | Ambiguous depth |
+| `quoi-framer` | CRÉER step 1 QUOI | All |
+| `avec-quoi-versioner` | CRÉER step 2 AVEC QUOI | Standard + Critical |
+| `stride-analyzer` | CRÉER step 4 SÉCURITÉ (3 passes) | Critical |
+| `pattern-fitness-check` | CRÉER step 5 CODEBASE fitness | All |
+| `evaluer-sizer` | CRÉER step 6 ÉVALUER | Standard + Critical |
+| `flux-narrator` | CRÉER step 7 FLUX | Standard + Critical |
+| `faire-gatekeeper` | CRÉER step 8 FAIRE gates | All |
+| `security-regression-check` | CRÉER step 8b | Critical |
+| `relire-critic` | CRÉER step 9 RELIRE | All (inline for Trivial, agent for Standard+) |
+| `prouver-verifier` | CRÉER step 10 PROUVER | All |
+| `critiquer-auditor` | Full CRITIQUER 7-step flow | PR/audit reviews |
+| `meta-critiquer` | META-CRITIQUER 30s reflection | All |
+
+### Research (6) — isolated fork via researcher agent
+
+| Skill | Purpose |
+|-------|---------|
+| `research-web-sources` | WebFetch official docs + WebSearch best practices |
+| `research-github-issues` | `site:github.com/[lib]/issues` for symptoms |
+| `research-forums` | StackOverflow, Reddit, HN fallback |
+| `validate-source-credibility` | Score sources (official > maintainer > GH > SO > blog) |
+| `synthesize-findings` | Merge outputs into FINDINGS / ANTI-PATTERNS / PHILOSOPHY / API SURFACE / UNCERTAINTIES |
+| `fact-check-claims` | Grep source or fetch docs before asserting |
+
+### Domain (11) — auto-activated by paths glob
+
+| Skill | Paths trigger |
+|-------|---------------|
+| `frontend-mastery` | React/Vue/Svelte files |
+| `backend-mastery` | Server framework files |
+| `database-mastery` | `*.sql`, `migrations/**`, `prisma/**` |
+| `security-hardening` | `auth/**`, `security/**`, Token/Password/Secret names |
+| `api-architecture` | `routes/**`, `controllers/**`, `*.proto` |
+| `observability` | logging/metrics/tracing code |
+| `performance-engineering` | Performance-tagged tasks |
+| `refactoring-patterns` | Refactor tasks or duplication ≥ 2 |
+| `ts-js-patterns` | `.ts`, `.tsx`, `.js`, `.jsx` files |
+| `cicd-pipeline-designer` | `.github/workflows/**` |
+| `mcp-configurator` | `.mcp.json`, MCP configuration |
+
+### Meta (5) — self-improvement
+
+| Skill | Purpose |
+|-------|---------|
+| `ciel-improve` | Analyze sessions → propose skill rewrites (patch-set for approval) |
+| `skill-creator` | Create new skill from conversation pattern (validated scaffold) |
+| `skill-variant-evaluator` | AutoResearch: generate + eval + compare skill variants |
+| `learnings-capture` | Mine conversation for corrections → append to learnings.md or overlay |
+| `patch-spec` | Shared patch-set format for ciel-improve + skill-freshness-auditor |
+
+| Skill | Paths trigger |
+|-------|---------------|
+| `frontend-mastery` | React/Vue/Svelte files |
+| `backend-mastery` | Server framework files |
+| `database-mastery` | `*.sql`, `migrations/**`, `prisma/**` |
+| `security-hardening` | `auth/**`, `security/**`, Token/Password/Secret names |
+| `api-architecture` | `routes/**`, `controllers/**`, `*.proto` |
+| `observability` | logging/metrics/tracing code |
+| `performance-engineering` | Performance-tagged tasks |
+| `refactoring-patterns` | Refactor tasks or duplication ≥ 2 |
+
+### Utility (9)
+
+| Skill | Purpose |
+|-------|---------|
+| `commit-writer` | Conventional-format commit messages |
+| `pr-opener` | Open PR with Closes #N, body composition inline |
+| `issue-closer` | Close linked issues with evidence comment |
+| `changelog-updater` | Append versioned entry with fix/revert ratio |
+| `branch-setup` | Create type/N-slug branch from issue |
+| `branch-cleaner` | Delete merged branches safely |
+| `pr-merger` | Merge PRs with branch protection awareness |
+| `release-publisher` | Signed tag + GitHub Release + Sigstore attestations |
+| `issue-creator` | Create GitHub issue with structured body |
+
+### Meta (4) — self-improvement
+
+| Skill | Purpose |
+|-------|---------|
+| `ciel-improve` | Analyze sessions → propose skill rewrites (patch-set for approval) |
+| `skill-creator` | Create new skill from conversation pattern (validated scaffold) |
+| `skill-variant-evaluator` | AutoResearch: generate + eval + compare skill variants |
+| `learnings-capture` | Mine conversation for corrections → append to learnings.md or overlay |
+
+---
+
+## Guards — 39 failure modes
+
+| Failure mode | How it manifests | Guard |
+|---|---|---|
+| Skipping RECHERCHE | "I already know this" / zero research output | "I already know this" = the red flag. Min: 1 WebSearch + 1 finding |
+| False confidence | "I'm sure this API exists" without evidence | Verify before asserting. No citation = don't know it |
+| Imports missing | Runtime ImportError on first run | API surface: read signatures of every called file before writing |
+| DB columns wrong | Query crashes with "column does not exist" in prod | Verify real schema (migration or `pg_attribute`) before any query |
+| Test URL mismatch | Test passes locally, fails in CI — MSW intercepts wrong host | FLUX test: trace request host:port vs handler host:port |
+| Mock lifecycle error | Mock returns undefined / stale data | FLUX test: when does mock execute — module load or function call? |
+| Pattern copied blindly | Correct syntax, wrong semantics | Fitness check: same problem? same constraints? Any no → adapt |
+| Prior AI pattern | Existing code contradicts official docs | Pattern contradicts docs → DO NOT FOLLOW. Docs > existing code |
+| Degeneration of thought | Self-critique finds 0 issues — same blind spots reinforced | Dispatch critic agent (fresh context) |
+| Context overflow (silent) | Agent report < 200 tokens on Standard task | Re-dispatch with narrower scope. Truncated report = incomplete FAIRE |
+| No alternative | "Obviously the right approach" | Alternatives gate: name X over Y or back to ÉVALUER |
+| Framework bypass | `window.location` in React, `for`+raw SQL, `catch→null`, `as X` cast | Idiomatic gate: justify every bypass signal |
+| Scope drift | "Simple fix" grows to 7 files | Alignment checkpoint at 3+ files: re-read QUOI |
+| Removing without understanding | Removed X → breaks UX nobody tested | Removal gate: Who uses it? What replaces it? What degrades? |
+| Proposing without calculating | "Let's cache all 3826 manga" — fails arithmetic | ÉVALUER sizing: back-of-envelope BEFORE proposing |
+| Debugging wrong layer | 3 CSS fixes when bug was `navigate()` silent fail | 3-layer triage: handler called? simplest action works? only then CSS |
+| Coding without mental model | Code pattern-matches but breaks — data flow not understood | FLUX: narrate full data flow before writing |
+| First draft = final draft | Code works but messy | RELIRE: hostile critic before PROUVER |
+| Fixation after failure | Same fix attempted 3 times, same result | After 2 failures: STOP. List 3 completely different approaches |
+| TDD inversion | Tests written after implementation — pass by definition | Write failing test FIRST (RED) |
+| Coverage theater | 95% coverage, zero meaningful assertions | Does this test verify behavior, or just execute code? |
+| Confirmation bias | Tests only prove it works, never that it fails | Constraint synthesis: write 3 constraints BEFORE checking logs |
+| Over-engineering | Change solves the problem but adds unnecessary complexity | Counterfactual: "What if we do NOTHING?" |
+| Process bloat | SKILL.md grows, steps take longer than the task | Anti-entropy: every addition must simplify OR catch a real failure |
+| Stale overlay | Overlay says React 18, project is React 19 | Per-month: check overlay versions vs real installed |
+| Security fix adds surface | Fix closes vuln A but opens new unguarded endpoint | `security-regression-check`: grep diff for new params, removed auth, new external calls |
+| CI ignored | "Staging works" declared while CI is red | `prouver-verifier` CI gate: `gh run list` must be success |
+| Draft PR left open | CI green but PR stays draft | `meta-critiquer`: CI green + draft → convert to ready |
+| Issue comment missing | Fix deployed but no evidence on the issue | Issue comment gate: add staging PID + AVANT/APRÈS before creating PR |
+| Version changelog missed | Using Ktor 3.x but researching Ktor 2.x docs | RECHERCHE: installed version changelog checked for breaking changes |
+| File re-read | Same file read 3 times in a session | After first read: note pointer. Re-read only if editing |
+| Dead-end loop | Same broken approach attempted in new session | Session progress file: write `.claude/session-progress.md` with failed approaches |
+| Dead code accumulation | Unused imports pile up across sessions | `meta-critiquer` #8: run ruff/knip/Detekt before session end |
+| sleep + tail anti-pattern | `sleep 2 && tail -5 logs/file.log` blocked by harness | Use Monitor for streaming, Bash run_in_background for one-shot waits |
+| Context window pollution | Large agent reports pasted verbatim — context burns fast | Agent result size cap: max 150 lines. Narrow scope if > 300 lines |
+| Dispatch gate bypass | >5 inline Bash/Read/Grep calls without any `Task()` on a Standard+ task | ABORT inline work, emit `Task(subagent_type="ciel-*")` immediately with `[ASSUMED]` markers for any inferred inputs |
+| Hook name drift | Consumer `settings.json` references a hook filename that does not exist in `hooks/` (silent "No such file or directory" on every tool call) | On every hook rename in the repo: grep all published `settings.json` templates and downstream consumer docs for the old name. Version-bump the plugin. |
+| Self-authored rule drift | A rule written in this session (e.g., a new SKILL.md paragraph, a new reference guard) is not reliably followed in subsequent turns; short-term memory decays across tool outputs and compacts. Observed in the v2.4.4→v2.4.7 audit where the `[CIEL N/5]` counter rule was applied exactly once before the agent forgot it. | Mechanical enforcement — hooks, gates, external state files — required for any rule that must hold across >5 turns. Pure SKILL.md text is advisory; without a hook-side counter or settings.json gate, the rule decays within 1-2 turns of its author writing it. v2.5.0 `pre-tool-count.sh` / `post-tool-count.sh` is the canonical example. |
+| Release discipline drift | `feat:`/`fix:` commits accumulate on default branch but VERSION / CHANGELOG / git tag / `gh release` never catch up. Pipeline step 16-17 (`changelog-updater` + `release-publisher`) are opt-in and only triggered on a version-bump PR that no one creates. Observed v2.0 → v2.5.1: 20+ features shipped, zero tags — fixed in the v2.6.0 rattrapage. | Stop-hook `release-gate` (v2.7.0 `hooks/stop.sh`) — when on the default branch AND 3+ conventional `feat:`/`fix:`/`feat!:`/`fix!:` commits exist past the last `git describe --tags --abbrev=0`, prepend a reminder to the meta-critiquer block. Snooze for 60 min: `touch .ciel-release-snooze`. Claude Code only in v2.7.0; OpenCode parity pending `session.idle` `.d.ts` verification. |
+
+---
+
+## Research basis
+
+- Audit of 675 commits (62.8% fix/revert with v1.x monolithic skill, 2026-04-04)
+- Anthropic Skills-first paradigm — "Stop building agents, build Skills" (Barry Zhang / Mahesh Murag, AI Engineer Code Summit)
+- [MAR — Multi-Agent Reflexion](https://arxiv.org/html/2512.20845) — degeneration of thought in single-agent critique
+- [SICA — Self-Improving Coding Agent](https://arxiv.org/html/2504.15228v2) — 17→53% improvement via self-edit + metrics
+- [Reflexion](https://arxiv.org/abs/2405.06682) — self-reflection improves problem-solving, p < 0.001
+- CriticBench 2024 — self-critique is the hardest critique mode for LLMs
+- [Process debt research](https://planally.com/why-process-debt-is-the-new-tech-debt/) — monolithic process = friction = skipping
+- OpenHands / JetBrains 2025 — observation masking reduces context burn
+- ACON 2025 — memory pointers reduce token usage 40-60% on file-heavy tasks

package/assets/.claude/skills/cloud/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: cloud
+description: "Cloud — IAM least privilege comme principe zero, multi-account, cost optimization, auto-scaling, managed services vs DIY. À charger quand on conçoit une architecture cloud."
+---
+
+# Cloud
+
+**Principe premier :** Le cloud n'est pas "des serveurs chez Amazon" — c'est un modèle de responsabilité partagée où la sécurité est programmatique. La console AWS/GCP n'est PAS ton interface de gestion — c'est une porte dérobée pour le debugging. Tout doit être Infrastructure as Code. Le principe zéro est IAM least privilege : chaque service, chaque humain, chaque pipeline a EXACTEMENT les permissions nécessaires et rien de plus. Une permission de trop = une surface d'attaque inutile. Le second principe est que le cloud est un abonnement, pas un achat — chaque ressource qui tourne coûte de l'argent, 24/7.
+
+## Checklist
+- [ ] IAM least privilege : chaque rôle/service a les permissions minimales — revu trimestriellement
+- [ ] Infrastructure as Code (Terraform/Pulumi/CloudFormation) — zéro ressource créée à la main
+- [ ] Environnements séparés (comptes/projects différents) — la dev ne touche pas la prod
+- [ ] Données chiffrées au repos (S3 SSE, RDS encryption, EBS encryption) et en transit (TLS)
+- [ ] Auto-scaling configuré avec min/max et métriques pertinentes
+- [ ] Budget alerts à 80% et 100% + cost anomaly detection
+- [ ] Multi-AZ sur toute charge de production — une AZ peut tomber
+
+## Anti-patterns
+### IAM AdministratorAccess partout
+**Ce qu'on voit :** chaque service, chaque dev, chaque pipeline a `AdministratorAccess` "pour pas être bloqué". Une clé IAM qui fuit = accès root au compte.
+**Pourquoi c'est dangereux :** IAM n'est pas un obstacle — c'est la SEULE chose qui empêche un attaquant (ou un bug) de supprimer toute ton infrastructure. Un `terraform destroy` accidentel avec des droits admin = tout est perdu. Sans IAM strict, le blast radius d'une fuite de credentials est le compte entier.
+**Faire plutôt :** politiques IAM minimales. `s3:GetObject` sur CE bucket, pas `s3:*`. `ec2:Describe*` pour le monitoring, pas `ec2:TerminateInstances`. Policies gérées en Terraform, pas dans la console. Revue trimestrielle avec IAM Access Analyzer.
+
+### Tout dans le même compte
+**Ce qu'on voit :** dev, staging, prod dans le même compte AWS. Le stagiaire teste un script qui supprime toutes les instances.
+**Pourquoi c'est dangereux :** sans isolation de blast radius, un incident en dev peut détruire la production. Les limites de service (1000 instances, 100 DBs) sont partagées. Les coûts sont mélangés — impossible de savoir ce que coûte la prod vs la dev.
+**Faire plutôt :** comptes séparés par environnement. AWS Organizations ou GCP Folders. Accès cross-account pour les besoins légitimes, jamais l'inverse.
+
+### Facture = surprise de fin de mois
+**Ce qu'on voit :** personne ne regarde les coûts cloud. Un dev lance une instance GPU p3.16xlarge pour tester. Facture x10 à la fin du mois.
+**Pourquoi c'est dangereux :** le cloud facture à l'usage, 24/7. Chaque ressource oubliée coûte. Sans monitoring des coûts, tu découvres les problèmes quand la facture arrive — 30 jours trop tard.
+**Faire plutôt :** budget alerts à 80% et 100%. Tags de coût obligatoires (project, team, environment). Revue mensuelle. Instances non utilisées automatiquement arrêtées (Dev/Staging la nuit, week-end).
+
+## Patterns
+### IAM least privilege
+**Quand :** toute ressource cloud.
+**Comment :** chaque rôle a `Effect: Allow` uniquement sur les actions et ressources nécessaires. Pas de wildcard `Resource: "*"`. Pas de `Action: "*"`. Utiliser des conditions (IP source, MFA, tags). Partir de zéro et ajouter ce qui est nécessaire, pas l'inverse.
+
+### Multi-AZ
+**Quand :** toute charge de production.
+**Comment :** déployer sur au moins 2 zones de disponibilité. Load balancer répartit. RDS Multi-AZ (standby dans une autre AZ, failover automatique). Si une AZ tombe, le service continue. Coût : ~2× l'infra, mais l'alternative c'est le downtime.

package/assets/.claude/skills/code-quality/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: code-quality
+description: "Code Quality — linting, formatage, analyse statique, dette technique, conventions, complexite cyclomatique. A charger quand on parle de qualite ou standards de code."
+---
+
+# Code Quality
+
+**Principe premier :** La qualite du code ne se mesure pas en "proprete" esthetique — elle se mesure en temps de comprehension pour le prochain developpeur. Un code "sale" mais compris en 30 secondes est meilleur qu'un code "propre" qui prend 10 minutes a decoder. Le linter et le formatter existent pour ELIMINER les debats de style, pas pour les multiplier. Si une regle de linting genere des discussions en code review, elle est contre-productive — desactive-la. Le standard de qualite n'est pas la perfection, c'est la consistance : le code doit avoir l'air ecrit par une seule personne, meme si l'equipe a 10 developpeurs.
+
+## Checklist
+- [ ] Le projet a un linter (ESLint, Biome, Ruff, Clippy) avec des regles strictes mais non controversees
+- [ ] Le formatage est automatise (Prettier, dprint, gofmt) — zero debat de style en code review
+- [ ] La complexite cyclomatique est limitee (max 15-20 par fonction) et mesuree dans la CI
+- [ ] Les fichiers sont limits en taille (max 300-500 lignes) — au-dela, splitter
+- [ ] Les commentaires expliquent le POURQUOI, pas le QUOI (le code dit deja QUOI)
+- [ ] Le code mort est supprime, pas commente — git garde l'historique
+- [ ] La duplication est toleree jusqu'a 3 occurrences — abstraire au 4e usage, pas au 2e (Rule of Three)
+
+## Anti-patterns
+### Linting maximaliste
+**Ce qu'on voit :** 200 regles ESLint activees. `no-console`, `no-param-reassign`, `max-lines-per-function: 20`, `no-else-return`. Chaque commit declenche 15 erreurs qui ne sont PAS des bugs.
+**Pourquoi c'est dangereux :** le linter n'est plus un outil — c'est un obstacle. Les devs le contournent (`eslint-disable` partout), le resultat est pire que pas de linter du tout. La fatigue du linter cree une culture ou les avertissements sont ignores.
+**Faire plutot :** regles qui attrapent des BUGS, pas des preferences : `no-undef`, `no-unused-vars` (erreur, pas warning), `no-unsafe-*`. Formatage automatique, pas manuel. Tout le reste : warning ou off. L'objectif est zero faux positifs, pas un score de linting eleve.
+
+### Refactoring sans filet
+**Ce qu'on voit :** "je refactore cette classe pour la rendre plus propre." 2 semaines plus tard, 40 fichiers modifies, fonctionnalites cassees, aucun test ajoute.
+**Pourquoi c'est dangereux :** le refactoring sans tests n'est pas du refactoring — c'est de la reecriture. Sans filet, chaque changement est un risque. Le "clean code" qui casse la production n'est pas propre — il est dangereux.
+**Faire plutot :** tests AVANT refactoring. Si le code n'a pas de tests, en ecrire (characterization tests). Refactoring en petits pas, commit par commit. Si un test casse, revert immediatement.
+
+### Abstraction prematuree (DRY abuse)
+**Ce qu'on voit :** deux fonctions de 3 lignes qui se ressemblent → abstraction dans une classe mere. La 3e utilisation arrive, difference subtile → `if (specialCase)`. 4e utilisation → 4 parametres de configuration. L'abstraction est devenue plus complexe que le code duplique.
+**Pourquoi c'est dangereux :** le mauvais DRY crée du couplage. Une abstraction prematuree lie ensemble des concepts qui evoluent differemment. Le cout de changer l'abstraction (tous les appels) depasse le cout de la duplication (2-3 endroits).
+**Faire plutot :** Rule of Three : dupliquer jusqu'a 3 fois. A la 3e occurrence, abstraire. L'abstraction a maintenant 3 cas reels pour etre testee. Si la 4e occurrence ne rentre pas, l'abstraction etait prematuree — splitter.
+
+## Patterns
+### Boy Scout Rule
+**Quand :** maintenance quotidienne.
+**Comment :** "laisse le code plus propre que tu ne l'as trouve." Un petit nettoyage a chaque commit : renommer une variable, extraire une fonction, supprimer du code mort. Pas de refactoring massif — des micro-ameliorations continues.
+
+### Static analysis in CI
+**Quand :** toute PR.
+**Comment :** le linter + l'analyse statique tournent dans la CI. Bloquant sur les regles de securite et de bug. Non-bloquant (annotation dans la PR) pour les suggestions de style. Exemple : `eslint --max-warnings 0` pour les regles d'erreur, `--quiet` pour le reste.

package/assets/.claude/skills/code-review/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: code-review
+description: "Code Review — PR hygiene, review checklist, constructive feedback, security review, Boy Scout Rule. À charger quand on fait ou reçoit une revue de code."
+---
+
+# Code Review
+
+**Principe premier :** La code review n'est pas un gate de qualité — c'est un outil de partage de connaissance. Le but #1 n'est pas de trouver des bugs (les tests et la CI font ça), c'est de s'assurer que le code est compréhensible par quelqu'un qui ne l'a pas écrit. Un bug trouvé en review est un échec des tests. Une incompréhension en review est un échec du code. La métrique n'est pas "nombre de commentaires" mais "est-ce que je pourrais maintenir ce code sans parler à l'auteur ?"
+
+## Checklist
+- [ ] La PR fait < 400 lignes — sinon, découper
+- [ ] Les tests existent, passent, et couvrent les cas limites
+- [ ] La description explique le POURQUOI, pas le QUOI (le diff montre le quoi)
+- [ ] Les noms sont explicites — pas de `x`, `data`, `tmp`, `result`, `handle()`
+- [ ] Pas de code mort, pas de TODO sans ticket, pas de commentaire qui ment
+- [ ] La sécurité est vérifiée : injection, auth, PII exposé
+
+## Anti-patterns
+### PR de 2000 lignes
+**Ce qu'on voit :** une PR avec 15 fichiers, 3 fonctionnalités, et une description "Refactoring + nouvelle feature + fix bug".
+**Pourquoi c'est dangereux :** impossible à review correctement. Le cerveau humain ne peut pas traiter 2000 lignes de diff. Les bugs passent. La review dure 2h et personne ne la fait sérieusement. Les grosses PRs sont le symptôme d'un découpage du travail mal fait.
+**Faire plutôt :** PR < 400 lignes. Une fonctionnalité, un fix, un refactoring par PR. Petits merges fréquents. Si le changement est gros → feature flag + PRs incrémentales.
+
+### Feedback sur la personne
+**Ce qu'on voit :** "c'est nul", "refais tout", "pourquoi t'as fait comme ça ?" — ton condescendant.
+**Pourquoi c'est dangereux :** ça ne tue pas que l'humeur — ça tue les futures PRs. L'auteur évite de soumettre, ou soumet en cachette. La qualité baisse par peur du feedback. Le coût est à long terme.
+**Faire plutôt :** "Cette approche a le risque X" (pas "tu as mal fait"). Suggestion, pas ordre : "Est-ce qu'on pourrait... ?". Le feedback cible le code, jamais la personne.
+
+### LGTM reflex
+**Ce qu'on voit :** "LGTM" sur une PR de 500 lignes, 2 minutes après l'ouverture.
+**Pourquoi c'est dangereux :** c'est un non-review. Le reviewer n'a pas lu le code. L'auteur n'apprend rien. Les bugs passent. Pire : ça donne une fausse confiance ("c'est reviewé").
+**Faire plutôt :** si tu n'as pas le temps, ne review pas. Si tu review, passe au moins 15 min et trouve au moins UNE chose (positive ou à améliorer). Une review qui ne produit aucun commentaire n'est pas une review.
+
+## Patterns
+### PR template
+**Quand :** toute PR.
+**Comment :** template concis : contexte, changements, captures/évidence, points d'attention pour le reviewer. L'auteur remplit. Le reviewer a tout le contexte. 2 minutes de remplissage = 15 minutes gagnées en review.
+
+### Boy Scout Rule
+**Quand :** tout fichier touché.
+**Comment :** laisser le code plus propre qu'on ne l'a trouvé. Renommer une variable confuse. Extraire une fonction de 30 lignes. Ajouter un test manquant. Pas de refactoring massif — juste le petit coup de balai.

package/assets/.claude/skills/communication/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: communication
+description: "Communication Technique — documentation, diagrammes C4, RFC, post-mortem, presentation, spec writing. A charger quand on communique sur un sujet technique."
+---
+
+# Communication Technique
+
+**Principe premier :** La communication technique n'est pas "ecrire ce qu'on sait" — c'est faire comprendre ce que l'autre a besoin de savoir. Le plus grand piege de la communication d'expert : la malediction du savoir. Tu sais tellement bien ton sujet que tu ne peux plus imaginer ce que c'est de ne pas le savoir. Resultat : tu sautes des etapes, utilises du jargon, assumes des prerequis — et ton interlocuteur est perdu. La regle d'or : si tu ne peux pas expliquer ton design a un dev qui vient d'arriver, ton design n'est pas pret. Pas parce que le dev est novice — parce que la clarte est un test de comprehension. Si c'est flou dans ta tete, c'est flou sur le papier.
+
+## Checklist
+- [ ] La documentation est dans le repo, versionnee avec le code — pas dans Confluence/Notion qui se perime
+- [ ] Les decisions techniques sont communiquees avec le POURQUOI (contexte, alternatives) — pas juste la solution
+- [ ] Les diagrammes utilisent un standard reconnu (C4, UML sequence, Mermaid) — pas un outil proprietaire
+- [ ] Les specs sont ecrites avant le code, lues par l'equipe, et amendees — pas "le code est la spec"
+- [ ] Les post-mortems sont blameless : ce qui s'est passe, pourquoi, comment eviter que ca se reproduise
+- [ ] La communication est adaptee au public : C4 level 1 pour stakeholders, level 3 pour devs
+- [ ] Les PR descriptions expliquent le contexte et les trade-offs — pas juste "fixes bug"
+
+## Anti-patterns
+### Documentation dans un outil separe
+**Ce qu'on voit :** specs dans Confluence, designs dans Notion, decisions dans Trello, code dans GitHub. Rien n'est a jour. Personne ne trouve rien.
+**Pourquoi c'est dangereux :** la documentation eloignee du code est de la documentation morte. Elle n'est pas versionnee avec le code qu'elle decrit. Elle n'est pas revue en PR. Elle pourrit independamment. Le nouveau dev lit la spec Confluence de 2023 et code un feature deja deprecie.
+**Faire plutot :** documentation dans le repo, en markdown, a cote du code qu'elle documente. `docs/architecture.md`, `docs/adrs/`, `services/orders/README.md`. La doc se review en PR comme le code. Si le code change, la doc change dans le meme commit.
+
+### Diagramme = oeuvre d'art
+**Ce qu'on voit :** 3 jours passes a faire un diagramme UML parfait dans un outil proprietaire. Le diagramme est beau. Le code change 2 semaines plus tard. Le diagramme n'est plus a jour et ne peut pas etre modifie (outil perdu, licence expiree).
+**Pourquoi c'est dangereux :** un diagramme est un outil de communication, pas un livrable. Passer 3 jours sur un diagramme qui sera obsolet dans 2 semaines est du gaspillage. L'outil proprietaire cree un barrier a la modification → le diagramme pourrit.
+**Faire plutot :** diagrammes en texte (Mermaid, PlantUML, Graphviz). Versionnes dans le repo. Render automatiquement dans la CI. Assez bons pour communiquer, pas parfaits. Si le diagramme prend plus d'1h, c'est qu'il est trop detaille.
+
+### Post-mortem = blame game
+**Ce qu'on voit :** incident → "qui a deploye ca ?" → recherche de coupable → le dev qui a deploye est blame. Prochaine fois, personne n'osera deployer.
+**Pourquoi c'est dangereux :** chercher un coupable garantit que les incidents futurs seront caches, pas corriges. Les gens ne signalent pas les quasi-incidents. La peur remplace l'apprentissage. L'organisation devient fragile parce qu'elle ne corrige pas ses processus.
+**Faire plutot :** post-mortem blameless. L'incident est cause par le SYSTEME, pas par l'individu. "Qu'est-ce qui dans notre processus a permis cette erreur ?" Action concrete sur le processus pour que ca ne se reproduise pas. L'auteur du deploiement participe au post-mortem sans crainte.
+
+## Patterns
+### C4 Model
+**Quand :** expliquer l'architecture a differents publics.
+**Comment :** 4 niveaux. Level 1 (Context) : le systeme dans son environnement — pour les stakeholders. Level 2 (Containers) : les briques majeures (app, DB, file system) — pour l'equipe tech elargie. Level 3 (Components) : l'interieur de chaque container — pour les devs. Level 4 (Code) : diagramme de classes — seulement si necessaire. Toujours commencer par le niveau 1, toujours avoir un titre et une legende.
+
+### Spec writing
+**Quand :** feature de > 1 semaine.
+**Comment :** ecrire la spec AVANT de coder. Sections : Problema (quoi et pourquoi), Solution proposee (comment), Alternatives considerees, Impact (migration, cout, risques), Plan de test. Review d'equipe avant implementation. La spec peut etre courte (1-2 pages) — le but est l'alignement, pas la perfection.

package/assets/.claude/skills/containers/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: containers
+description: "Containers — multi-stage builds, distroless, non-root, K8s health checks, resource limits, image immutability. À charger quand on travaille avec Docker ou Kubernetes."
+---
+
+# Containers
+
+**Principe premier :** Un container n'est pas une VM légère — c'est un process isolé. L'image Docker est un artefact immutable, pas un serveur maintenu à coup de `docker exec`. Chaque couche ajoutée est une surface d'attaque. Le but : l'image la plus petite possible. Et ne jamais tourner en root — non-root est la baseline, pas un bonus.
+
+## Checklist
+- [ ] Multi-stage build : builder (outils) → runtime (artefacts uniquement, minimal)
+- [ ] Image de base minimale : distroless ou Chainguard — pas de shell, pas de package manager
+- [ ] Container non-root (`USER 1001`) — `runAsNonRoot: true` dans K8s
+- [ ] Secrets injectés au runtime (K8s secrets, Vault) — pas dans l'image, pas en ARG
+- [ ] Ressources limitées (CPU/memory limits AND requests) — pas de "illimité"
+- [ ] Health checks : liveness, readiness, startup — les trois
+- [ ] Images taguées par version ET hash de commit — jamais `:latest`
+
+## Anti-patterns
+### Container en root
+**Ce qu'on voit :** Dockerfile sans `USER`. Le process tourne en root.
+**Pourquoi c'est dangereux :** container compromis = root inside → escalade possible vers l'hôte. La plupart des applications n'ont jamais besoin de root. C'est un défaut historique, pas une nécessité.
+**Faire plutôt :** `USER 1001:1001`. Distroless (pas de shell). `runAsNonRoot: true`, `readOnlyRootFilesystem: true` dans K8s.
+
+### Image obèse
+**Ce qu'on voit :** `FROM node:22` → image de 1.5 Go avec git, curl, npm, code source complet.
+**Pourquoi c'est dangereux :** pull lent = déploiement lent = rollback lent. Surface d'attaque maximale. Coût de stockage.
+**Faire plutôt :** multi-stage : builder compile → runtime minimal. `COPY --from=builder`. Distroless. Image < 100 Mo.
+
+### `:latest` partout
+**Ce qu'on voit :** `image: myapp:latest`. Impossible de savoir quelle version tourne.
+**Pourquoi c'est dangereux :** non-reproductible. Si `latest` change sur le registry, le prochain pod restart aura une version différente. Rollback impossible.
+**Faire plutôt :** tag sémantique + hash de commit. `myapp:v1.2.3`, `myapp:abc1234`. Immutable.
+
+## Patterns
+### Multi-stage build
+**Quand :** toute image qui compile du code.
+**Comment :** builder (`FROM golang:1.22 AS builder`) → compile → runtime (`FROM gcr.io/distroless/static`) → `COPY --from=builder /app/binary`. Résultat : un binaire et rien d'autre.
+
+### K8s health checks
+**Quand :** tout pod Kubernetes.
+**Comment :** liveness (process vivant ?), readiness (trafic OK ?), startup (init fini ?). Sans readiness, K8s envoie du trafic avant que l'app soit prête → erreurs en boucle.

package/assets/.claude/skills/cqrs/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: cqrs
+description: "CQRS & Event Sourcing — séparation lecture/écriture, projections, event store, eventual consistency. À charger quand les patterns de lecture et d'écriture divergent radicalement."
+---
+
+# CQRS & Event Sourcing
+
+**Principe premier :** CQRS n'est pas une architecture — c'est la reconnaissance d'un fait : lire et écrire sont deux opérations fondamentalement différentes. Une écriture doit protéger des invariants, une lecture doit être rapide et façonnée pour le client. Les forcer dans le même modèle crée un compromis qui ne satisfait ni l'un ni l'autre. L'event sourcing est orthogonal : c'est la décision de stocker des événements (faits) plutôt que l'état courant. CQRS + Event Sourcing n'est pas un package deal — tu peux faire du CQRS sans event sourcing.
+
+## Checklist
+- [ ] Le besoin de CQRS est avéré — les lectures et écritures ont VRAIMENT des patterns différents
+- [ ] Le modèle d'écriture protège les invariants (aggregates, validation)
+- [ ] Le modèle de lecture est optimisé pour les requêtes du client (dénormalisé, pré-calculé)
+- [ ] L'eventual consistency est assumée et documentée — pas de "surprise" pour les utilisateurs
+- [ ] Si event sourcing : l'event store est append-only, les projections sont reconstruisibles
+- [ ] Les événements sont versionnés (schema evolution) — un événement de 2024 doit être lisible en 2026
+
+## Anti-patterns
+### CQRS pour un CRUD
+**Ce qu'on voit :** CQRS + Event Sourcing pour un formulaire de contact. CommandBus, EventStore, Projections, ReadModels — pour stocker un nom et un message.
+**Pourquoi c'est dangereux :** le coût de cette architecture est énorme : eventual consistency, debugging complexe, replay à maintenir. Pour un CRUD, ce coût n'est jamais amorti. Tu passes 10× plus de temps sur l'infrastructure que sur la logique métier.
+**Faire plutôt :** CRUD simple. Repository pattern. Ajouter CQRS UNIQUEMENT quand les lectures sont ≥ 10× plus fréquentes que les écritures ET que les patterns divergent. Même là, commencer par du CQRS sans event sourcing.
+
+### Event sourcing sans besoin d'audit
+**Ce qu'on voit :** tout le système en event sourcing "au cas où on aurait besoin de l'historique". 200 événements par aggregate, replay de 30 secondes au démarrage.
+**Pourquoi c'est dangereux :** l'event sourcing a un coût permanent : snapshots, upcasters, replay, debugging d'event streams. Si le métier n'a pas besoin de l'historique complet des changements (audit, conformité, debug), ce coût est du gaspillage pur.
+**Faire plutôt :** stocker l'état courant. Logger les changements importants dans une table d'audit séparée (pas l'event store). Event sourcing UNIQUEMENT quand l'historique est une exigence métier, pas technique.
+
+### Projections non monitorées
+**Ce qu'on voit :** la projection de lecture est stale (lag de 50 000 événements). Personne ne le sait. Les utilisateurs voient des données vieilles de 10 minutes.
+**Pourquoi c'est dangereux :** l'eventual consistency sans monitoring devient de l'inconsistance tout court. Le lag des projections est la métrique #1 d'un système CQRS — si tu ne la mesures pas, tu ne sais pas dans quel état est ton système.
+**Faire plutôt :** métriques sur le lag des projections. Alerte si lag > N événements ou > M secondes. Read-model reconstruit automatiquement si trop de lag (pas de rattrapage infini).
+
+## Patterns
+### CQRS sans Event Sourcing
+**Quand :** lectures et écritures divergent mais l'historique n'est pas requis.
+**Comment :** command → validation → DB transactionnelle (état courant). Projection → vue dénormalisée mise à jour dans la même transaction ou via un worker. Pas d'event store, pas de replay. La complexité est proportionnelle au besoin.
+
+### Event Store
+**Quand :** l'historique complet est une exigence métier (finance, audit, conformité).
+**Comment :** append-only. Chaque événement = un fait passé (`OrderPlaced`, pas `PlaceOrder`). Projections = vues dérivables à tout moment. Snapshots réguliers pour éviter le replay complet.

package/assets/.claude/skills/crypto/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: crypto
+description: "Cryptographie — principes premiers (confidentialité/intégrité/authenticité), AES-GCM, bcrypt/argon2, TLS, PKI, rotation de clés, non-invention. À charger quand on manipule de la cryptographie."
+---
+
+# Cryptographie
+
+**Principe premier :** La cryptographie n'est pas une boîte à outils — c'est la science de transformer des problèmes de confiance en problèmes de gestion de clés. Chaque opération crypto répond à une des trois propriétés fondamentales : confidentialité (chiffrement), intégrité (hash, MAC), ou authenticité (signature). Si tu ne sais pas laquelle des trois tu cherches, tu ne devrais pas écrire de code crypto. Règle d'or : ne jamais inventer un algorithme, ne jamais implémenter un algorithme standard soi-même — utiliser une bibliothèque éprouvée (libsodium, Tink, WebCrypto).
+
+## Checklist
+- [ ] Les mots de passe sont hashés avec argon2id (ou bcrypt cost ≥ 12) — pas de SHA, pas de MD5
+- [ ] Le chiffrement utilise un algorithme authentifié (AES-256-GCM ou ChaCha20-Poly1305) — pas d'AES-ECB, pas de CBC sans HMAC
+- [ ] Les IV/nonces sont générés aléatoirement à chaque chiffrement — jamais réutilisés
+- [ ] Les clés sont stockées dans un KMS/HSM — pas dans le code, pas dans les variables d'environnement
+- [ ] TLS ≥ 1.2 partout, 1.3 si possible — certificats auto-renouvelés
+- [ ] La rotation des clés est automatisée (max 90 jours) et testée
+- [ ] Les algorithmes obsolètes sont bloqués (MD5, SHA1, DES, 3DES, RC4, RSA < 2048)
+
+## Anti-patterns
+### Chiffrement "maison"
+**Ce qu'on voit :** `function encrypt(text) { return Buffer.from(text).toString('base64'); }`. Ou pire : un algorithme inventé "parce que c'est plus simple".
+**Pourquoi c'est dangereux :** la cryptographie est le seul domaine où "ça marche" ne veut rien dire. Un algorithme cassé produit un output valide. La sécurité ne se teste pas — elle se prouve mathématiquement. Même les experts se font casser — ta solution maison n'a aucune chance.
+**Faire plutôt :** libsodium (recommandé pour toute nouvelle application), Tink (Google), ou le module `crypto` natif avec AES-256-GCM. Ces bibliothèques ont été auditées, attaquées, et corrigées par des cryptographes.
+
+### Clé statique éternelle
+**Ce qu'on voit :** la même clé AES utilisée depuis 3 ans pour chiffrer toutes les données. Pas de rotation, pas de plan de compromission.
+**Pourquoi c'est dangereux :** la rotation limite le rayon de l'explosion. Si une clé fuit et qu'elle chiffre 3 ans de données, TOUT est compromis. Avec une rotation à 90 jours, seules 90 journées sont exposées. La rotation n'est pas pour le cas où la clé est volée — c'est pour QUAND elle est volée.
+**Faire plutôt :** rotation automatique (AWS KMS, Vault, Google Cloud KMS). Les anciennes clés déchiffrent uniquement, ne chiffrent plus. La rotation est un exercice de routine, pas une urgence.
+
+### MD5/SHA1 pour les mots de passe
+**Ce qu'on voit :** `hashed_password = md5(password)` ou `sha1(password + salt)`.
+**Pourquoi c'est dangereux :** MD5 et SHA1 sont conçus pour être RAPIDES — c'est exactement l'inverse de ce qu'on veut pour des mots de passe. Un GPU peut tester des milliards de hashs par seconde. Avec un mot de passe faible, le compte est compromis en secondes.
+**Faire plutôt :** argon2id (vainqueur du Password Hashing Competition, recommandé par l'OWASP). Sinon bcrypt (cost ≥ 12) ou scrypt. Ces algorithmes sont lents ET résistants aux GPU/ASIC. 100ms par hash, c'est imperceptible pour l'utilisateur, dévastateur pour l'attaquant.
+
+## Patterns
+### AES-256-GCM (chiffrement authentifié)
+**Quand :** chiffrement de données au repos ou en transit.
+**Comment :** GCM fournit confidentialité + intégrité + authenticité en un seul mode. IV aléatoire de 12 bytes (jamais réutilisé avec la même clé). Tag d'authentification de 16 bytes vérifié AVANT de déchiffrer. Pas de padding (contrairement à CBC). L'échec de vérification du tag = données corrompues ou attaquées.
+
+### Argon2id (hash de mot de passe)
+**Quand :** stockage de mots de passe utilisateur.
+**Comment :** mémoire 64MB, itérations 3, parallélisme 4. Résistant aux GPU (mémoire), aux side-channel (data-dependent), et aux ASIC. Le sel est généré aléatoirement et stocké avec le hash. Augmenter les paramètres tous les 2 ans avec la puissance du matériel.
+
+### Rotation de clés automatisée
+**Quand :** toute clé qui chiffre des données en production.
+**Comment :** le KMS génère une nouvelle clé tous les 90 jours. L'ancienne clé passe en "decrypt only". Les nouvelles données sont chiffrées avec la nouvelle clé. Le déchiffrement essaie la clé courante, puis la liste des anciennes. La rotation est non-destructive et réversible.

package/assets/.claude/skills/data-engineering/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: data-engineering
+description: "Data Engineering — pipelines ETL/ELT, Spark/Airflow/dbt, data warehouses, streaming vs batch, qualite des donnees. A charger quand on construit des pipelines de donnees."
+---
+
+# Data Engineering
+
+**Principe premier :** Le data engineering n'est pas "deplacer des donnees de A a B" — c'est garantir que les bonnes donnees arrivent au bon moment avec la bonne qualite. La donnee est un passif jusqu'a ce qu'elle soit utilisable — un pipeline qui livre des donnees corrompues ou tardives est pire que pas de pipeline du tout (les decisions sont prises sur des donnees fausses). Le vrai defi n'est pas le volume (tout le monde peut scaler) — c'est la qualite, la fraicheur, et la gouvernance. Un pipeline doit etre idempotent (re-run = meme resultat), observable (chaque etape logue ce qu'elle a fait), et testable (tu peux verifier la sortie sans la comparer a elle-meme).
+
+## Checklist
+- [ ] Le pipeline est idempotent : re-run = meme resultat, pas de doublons, pas d'effet cumulatif
+- [ ] Les donnees sont validees a l'ingestion (schema, types, contraintes) — pas de "on verifiera plus tard"
+- [ ] Le lineage est documente (d'ou viennent ces donnees ? quelles transformations ?) — pas de mystere
+- [ ] Les PII sont anonymisees/scrubbees avant d'entrer dans le warehouse (pas dans les requetes)
+- [ ] Les incremental loads utilisent des watermarks fiables (pas `MAX(updated_at)` sur une table sans index)
+- [ ] Le monitoring couvre : fraicheur (age des donnees), volume (trop/pas assez), qualite (% de nulls)
+- [ ] Les backfills sont testees et reversibles — un backfill qui casse la production est un incident
+
+## Anti-patterns
+### Pipeline fragile aux changements de schema
+**Ce qu'on voit :** le pipeline fait `SELECT *` et insere dans une table cible. La source ajoute une colonne → le pipeline casse. La source supprime une colonne → le pipeline casse.
+**Pourquoi c'est dangereux :** les schemas evoluent, c'est normal. Un pipeline qui casse a chaque changement de schema est un pipeline qui passe plus de temps en panne qu'en production. Chaque panne = donnees manquantes = decisions sur des donnees incompletes.
+**Faire plutot :** definir un contrat de schema (schema registry, Avro, Protobuf). Evolution compatible : ajouter des colonnes optionnelles, jamais supprimer sans migration. Le pipeline lit les colonnes explicitement, pas `SELECT *`. Tests d'evolution de schema dans la CI.
+
+### "On nettoiera les donnees plus tard"
+**Ce qu'on voit :** ingestion brute de tout. "On fera la qualite dans le data warehouse." 6 mois plus tard : 500 To de donnees, 40% de valeurs nulles, colonnes inutilisables.
+**Pourquoi c'est dangereux :** la qualite des donnees se degrade avec le temps — chaque transformation ajoute une couche d'interpretation. Plus tu attends pour nettoyer, plus c'est dur et cher. Le data warehouse devient un data swamp.
+**Faire plutot :** validation a l'ingestion (schema, types, contraintes metier). Rejeter les donnees invalides dans une dead letter queue, pas dans le warehouse. Les donnees propres sont plus petites, plus rapides, plus utiles.
+
+### Pipeline = boite noire
+**Ce qu'on voit :** le pipeline tourne dans Airflow/Dagster. Pas de logs structures. "Le DAG a echoue" — aucun diagnostic possible sans regarder le code.
+**Pourquoi c'est dangereux :** sans observabilite, chaque echec est une enquete policiere. Les pipelines sont des programmes distribues — ils echouent pour 50 raisons differentes. Sans logs structures (combien de rows traitees, combien de temps par etape, quelles valeurs aberrantes), le MTTR est de l'ordre de l'heure.
+**Faire plutot :** chaque etape logue : nombre de records traites, duree, nombre d'erreurs/valides, watermark utilise. Dashboards de sante par pipeline. Alertes sur deviation (moins de donnees que d'habitude = probleme upstream).
+
+## Patterns
+### Medaillon architecture (Bronze/Silver/Gold)
+**Quand :** data lake ou data warehouse avec plusieurs consommateurs.
+**Comment :** Bronze = donnees brutes (ingestion, append-only, schema preserve). Silver = donnees nettoyees, deduplicatees, jointes. Gold = donnees metier agreggees, pretes pour la consommation. Chaque couche a un proprietaire et un SLA de fraicheur.
+
+### Watermark incremental
+**Quand :** pipeline qui traite des donnees par lots incrementaux.
+**Comment :** utiliser une colonne de watermark monotone (`updated_at`, `event_time`, `sequence_id`). Stocker le watermark precedent. Charger `WHERE updated_at > last_watermark`. Gerer les late arrivals avec une fenetre de tolerance (ex: recharger les 2 dernieres heures en plus du delta).

package/assets/.claude/skills/database-design/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: database-design
+description: "Database Design — le schema comme contrat, normalisation, indexation, migrations sans downtime, UUID vs bigint. À charger quand on crée ou modifie un schéma de base de données."
+---
+
+# Database Design
+
+**Principe premier :** Le schéma de base de données est le contrat le plus coûteux à modifier dans une application. Changer du code = redéployer (minutes). Changer un schéma avec 50M rows = migration potentiellement bloquante (heures ou jours). Le design de schéma est donc un exercice d'anticipation : tout ce qui est facile à changer plus tard peut être décidé plus tard ; tout ce qui est dur à changer doit être décidé maintenant. La normalisation n'est pas un dogme — c'est un défaut qui minimise la redondance. Dénormaliser doit être un choix explicite, pas un accident.
+
+## Checklist
+- [ ] Le schéma est en 3NF sauf raison explicite de dénormaliser (documentée)
+- [ ] Chaque table a une primary key — UUID v7 si distribué, bigint si centralisé
+- [ ] Les foreign keys sont définies ET indexées (intégrité + performance)
+- [ ] Les colonnes sont NOT NULL par défaut — nullable est l'exception, justifiée
+- [ ] Les migrations sont réversibles (up + down) et testées en rollback dans la CI
+- [ ] Les migrations sur grosses tables (> 1M rows) utilisent une stratégie sans lock (expand/contract ou gh-ost)
+- [ ] Pas de logique métier dans la DB — triggers et stored procedures = application
+
+## Anti-patterns
+### JSON pour tout
+**Ce qu'on voit :** `data JSONB NOT NULL` — nom, email, adresse, commandes, tout dans une colonne JSON. "C'est flexible".
+**Pourquoi c'est dangereux :** pas de typage, pas de contrainte, pas d'index utilisable. "Flexible" veut dire "le contrat n'existe pas". Impossible de faire un rapport sans parser toute la table. La DB devient un dump de documents sans structure.
+**Faire plutôt :** colonnes typées pour tout champ connu et requêté. JSONB réservé aux données vraiment variables (metadata, preferences, config). La structure est le produit — ne pas y renoncer pour de la flexibilité.
+
+### Migration = ALTER TABLE direct
+**Ce qu'on voit :** `ALTER TABLE orders ADD COLUMN status VARCHAR NOT NULL DEFAULT 'pending'` lancé sur une table de 10M rows à 14h en production.
+**Pourquoi c'est dangereux :** PostgreSQL locke la table entière pendant l'ALTER. Pour 10M rows, ça peut prendre 20 minutes. Tout le service est down — commandes, paiements, expéditions. La migration en une étape est la cause #1 des outages de DB.
+**Faire plutôt :** expand/contract en 3 étapes : (1) ADD COLUMN sans NOT NULL (instantané), (2) remplir par batches de 1000 rows avec des pauses, (3) ajouter NOT NULL après que toutes les rows ont une valeur. Chaque étape est une migration séparée, déployable et rollbackable indépendamment.
+
+### Index manquant sur FK
+**Ce qu'on voit :** `order_items.order_id REFERENCES orders(id)` sans index sur `order_id`. Un DELETE sur orders déclenche un seq scan de order_items.
+**Pourquoi c'est dangereux :** chaque DELETE/UPDATE cascadé parcourt toute la table enfant. Sur 10M de order_items, un DELETE d'une commande prend 30 secondes au lieu de 1ms. Deadlocks en cascade.
+**Faire plutôt :** règle mécanique : toute foreign key a un index. C'est vérifiable automatiquement (pghero, linter SQL). Pas d'exception.
+
+## Patterns
+### Expand/Contract (migration sans downtime)
+**Quand :** toute modification de schéma sur une table > 100K rows en production.
+**Comment :** Phase expand : ajouter (colonnes, tables) sans rien supprimer — l'ancien code continue de fonctionner. Phase migrate : backfill par batches. Phase contract : supprimer l'ancien après validation que tout le nouveau code est déployé. Minimum 2 PRs séparées.
+
+### UUID v7 pour PK distribuée
+**Quand :** besoin d'IDs uniques sans séquence centrale, triables chronologiquement.
+**Comment :** UUID v7 = timestamp (48 bits) + random (74 bits). Chronologiquement triable (contrairement à UUID v4), pas de fragmentation d'index B-tree. Généré côté application, pas de round-trip DB pour l'ID.
+
+### Index partiel
+**Quand :** une requête filtre sur une condition qui ne concerne qu'une petite fraction des rows.
+**Comment :** `CREATE INDEX idx_active ON orders (created_at) WHERE status = 'active'`. L'index est plus petit, plus rapide à scanner, plus rapide à mettre à jour. Ne pas indexer ce qui n'est jamais cherché.