docs: documentation + gate de phase compose, fin Phase 2 (v0.14.0)

docs/need-review.md (cycle complet : états, sursis, gatekeeper, cron,
review, rollback). CHLOVA_PHASE dans .env.example + compose (défaut 1).
risk-tiers + README : application par phase. Compose revalidé, 45 tests,
0 vuln.

Palier de risque : n/a (doc + config).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

docs/need-review.md

@@ -0,0 +1,57 @@
+# Cycle "need review" (Phase 2)
+
+> Pièce maîtresse. Tout asset/op privilégié est sous review avant exécution.
+> Voir `docs/risk-tiers.md` (paliers) et `docs/security.md` (sécurité).
+
+## Asset & états
+Un asset (table SQLite `assets`, `src/gatekeeper/repository.ts`) suit :
+- **PROVISOIRE** : créé et exécutable, sursis de 7 jours (réservé au palier
+  `reversible`).
+- **APPROUVÉ** : review OK → permanent, plus d'alertes.
+- **REFUSÉ** : review KO → désactivé.
+- **BLOQUÉ** : sursis écoulé OU palier `privileged` (aucun sursis) → non
+  exécutable ; toute tentative lève une alerte.
+
+Champs : `id, type, version, risk_tier, status, created_at, expires_at,
+exec_count, commit_link, doc_link`.
+
+## Règle de sursis (non négociable)
+- `reversible` → PROVISOIRE 7 j (`createAsset` pose `expires_at = +7j`).
+- `privileged` → **BLOQUÉ immédiat, aucun sursis** (`expires_at = null`).
+- Le LLM ne peut jamais reclasser un asset (`assertNoEscalation` :
+  `privileged → reversible` interdit). Le palier vient des annotations MCP.
+
+## Gatekeeper (`src/gatekeeper/gatekeeper.ts`)
+Vérifie le statut **avant chaque exécution** (`canExecute`) :
+- lecture seule → autorisée, sans asset ;
+- privilégié inconnu → enregistré **BLOQUÉ** + exécution refusée + hook d'alerte ;
+- privilégié **APPROUVÉ** → exécuté, `exec_count` incrémenté ;
+- REFUSÉ / BLOQUÉ / sursis expiré → refusé.
+
+Branché via `GatekeeperGuard` (interface `Guard` ; la boucle agent est inchangée).
+
+## Cron (`src/gatekeeper/review.ts`)
+`startExpiryCron` passe horairement les PROVISOIRE échus en BLOQUÉ
+(`expireProvisional`). `runExpiryOnce` = un passage (testable).
+
+## Review (humaine, hors LLM)
+Commandes owner Telegram (`src/surfaces/commands.ts`) :
+`/pending`, `/approve <id>`, `/refuse <id>`, `/help`. Le LLM n'y a pas accès :
+seul l'humain change un statut.
+
+## Gate de phase
+`CHLOVA_PHASE` (défaut 1). Phase 1 : aucun outil mutant exposé, `ReadOnlyGuard`.
+Phase 2 : tous les outils exposés, `GatekeeperGuard`, cron + review actifs.
+Passage à `CHLOVA_PHASE=2` requis pour toute écriture (et `PORTAINER_READ_ONLY`
+peut alors valoir `false`).
+
+## Rollback
+- Repasser `CHLOVA_PHASE=1` → écriture désactivée, retour au cerveau read-only.
+- `git revert` du commit de l'asset fautif ; redeploy version N-1 (GitOps).
+- Un asset REFUSÉ reste tracé (audit) ; suppression via op SQL manuelle si besoin.
+
+## Reste à faire (Phase 3+)
+- Alertes mail via n8n (1ʳᵉ exéc provisoire, digest quotidien, rappel J-1,
+  alerte BLOQUÉ) — actuellement un simple hook de log `onBlockedAttempt`.
+- Auto-extension : CHLOVA génère commit + version + doc d'un asset **avant**
+  de le passer en need-review (Phase 4).

docs/risk-tiers.md

@@ -30,7 +30,9 @@
 - Ceci fait l'objet d'un test dédié (`gatekeeper.test.ts`) : tentative de
   reclassement → rejet.
 
-## Phase 1 (lecture seule)
-En Phase 1, **seuls les outils `reversible` (read-only) sont exposés** au LLM.
-Les outils mutants/`privileged` ne sont même pas branchés. Le gatekeeper et la
-classification sont posés comme interfaces, prêts pour la Phase 2.
+## Application par phase
+- **Phase 1** (`CHLOVA_PHASE=1`, défaut) : seuls les outils `reversible`
+  (read-only) sont exposés ; les `privileged` ne sont pas branchés.
+- **Phase 2** (`CHLOVA_PHASE=2`) : tous les outils exposés, mais chaque op
+  `privileged` passe par le **gatekeeper** (BLOQUÉ jusqu'à review). Voir
+  `docs/need-review.md`.