spec(v4): R4-P0-4 — politique de dépréciation V4 formelle (docs-only)

[Davincc77]

Résumé

Inscrit R4-P0-4 (ROAD-TO-V4-GA §R4-P0-4) : politique de dépréciation V4 formelle sous docs/spec/DEPRECATION_POLICY_V4.md, aux côtés des contrats normatifs déjà inscrits par R4-P0-1 (user.klickd wizard) et R4-P0-2 (KLICKD_E_* i18n).

Le document est normatif (RFC 2119 / RFC 8174), docs-only, et couvre exactement les exigences DoD du backlog plus les garde-fous opératoires associés.

Couverture normative

Section	Contenu
§2	Terminologie (field, lifecycle state, carry/deprecation/removal version, reference corpus, safety/locked fields)
§3	Cycle de vie active → deprecated → removed
§3.2	Gate combiné Vx+2 AND <10 % d'usage sur le corpus de référence (tests/vectors_v40*, examples/v4/**, registry/) — refinement normatif explicite de la disjonction du backlog
§3.3	Conditions de deprecated → removed (≥ 2 minor de dwell, migrateur shippé, corpus nettoyé, release notes) ; interdiction stricte du saut active → removed
§4	Comportement reader : lecture silencieuse des deprecated, préservation verbatim inconditionnelle, log dev jamais KLICKD_E_* utilisateur, strict mode OPTIONNEL non-default
§5	Comportement writer : interdiction d'émettre un deprecated dans un fichier neuf, préservation byte-equal sur round-trip, alignement RFC-004 pour les migrations
§6	Bloc envelope OPTIONNEL deprecated_fields[] purement documentaire, jamais utilisé pour rejeter, jamais authoritative (le SPEC et le registre §8 le sont)
§7	Guidance migration : replacement / information_preserving / information_lossy ; alignement migration_report (RFC-004) ; anti-pattern A2
§8	Removed-fields registry (table normative dans la SPEC body post-R4-P0-1)
§9	Exception champs locked / safety : ethics.locked_actions, decisions_locked[], kdf / cipher, data_integrity.integrity_warning, set AAD — RFC dédiée OBLIGATOIRE pour toute retraite
§10	Interaction avec préservation des champs inconnus (§33.7) : préservation inconditionnelle quel que soit le lifecycle state
§11	Règles semver v4+ (major / minor / patch / pré-release)
§12	Processus de proposition de changement (active → deprecated, deprecated → removed, retraite d'urgence, retrait de dépréciation)
§13	Lifecycle des identifiants registry — règle registry-first opérative sur A4
§14	Garde-fous opératoires A4 (6 gates : justification, lifecycle, sunset, replacement, vector, schema)

Périmètre

Docs-only. Ce PR :

• n'ajoute aucun champ requis (le bloc deprecated_fields[] §6 est OPTIONNEL, additif, informationnel) ;
• ne modifie aucun vector ;
• ne touche pas aux SDKs (Python ni @klickd/core) ;
• ne change pas le schéma strict ;
• ne déclenche aucune release : pas de tag, pas de latest npm/PyPI, pas de DOI Zenodo, pas de bump de version SDK ;
• n'implémente pas R4-P0-1 (la promotion §33 viendra et déplacera le registre §8 dans la SPEC body) ;
• ne relâche ni ne modifie le contrat de forward-compatibility §33.7 ni les invariants privacy §33.10 — au contraire, il compose explicitement avec §33.7 (§10 du document).

Fichiers modifiés

• docs/spec/DEPRECATION_POLICY_V4.md (nouveau, 814 lignes)
• SPEC.md (ajout §33.13 — pointeur normatif vers le document)
• docs/roadmap/ROAD-TO-V4-GA.md (ajout d'une ligne Statut: sous R4-P0-4)

Conformité DoD R4-P0-4

Critère DoD	Statut	Référence
Distinguer deprecated dans la SPEC (champ valide mais discouraged) de removed (champ supprimé du schéma)	✅	§3.2 vs §3.3
Aucune suppression sans transition deprecated d'au moins une version mineure	✅	§3.3 (≥ 2 minor de dwell, interdiction explicite du saut active → removed)
deprecated_fields[] purement documentaire, jamais utilisé pour rejeter	✅	§6 (rules 1, 2, 5)
Politique distingue deprecated (encore lu) de removed (plus interprété, toujours préservé verbatim)	✅	§4.2 vs §4.3 + §10
Lecture silencieuse des champs deprecated par les readers v4	✅	§4.2
Garde-fou A4 (inflation schéma)	✅	§14 (6 gates opératoires)
Cible déclarée du backlog : Vx+2 OR <10 % usage	✅ refiné en Vx+2 AND <10 % usage	§3.2 (avec justification normative explicite)

Garde-fous anti-pattern

• A4 — Inflation schéma : levé par le document lui-même (c'est sa raison d'être). §14 énonce les 6 gates opératoires que tout PR v4 ajoutant un champ doit satisfaire.
• A2 — Migration silencieuse : §7.4 réaffirme l'obligation de migration_report (RFC-004) ; §7.3 impose un avis utilisateur en cas de perte d'information.
• A5 — Spec-first sans exemples : §12.1 et §12.2 imposent au moins un vector positif par PR de dépréciation / suppression.
• A6 — Erreurs non actionnables : §4.2 et §4.3 interdisent explicitement de surface un KLICKD_E_* utilisateur pour un champ deprecated/removed.

Test plan

• Tous les liens relatifs de DEPRECATION_POLICY_V4.md résolvent (script Python ad-hoc — All relative links OK).
• Les 5 liens relatifs ajoutés en SPEC §33.13 résolvent.
• Les CI cross-impl vectors (Python v2.5+v3.0+v4-preview, JavaScript hash-wasm Argon2id, @klickd/core integrity) doivent rester vertes (aucun vector ni SDK ni schéma modifié).
• Alignement SDK (log développeur de la dépréciation §4.2) — différé à une track SDK ultérieure (P0-3 / P0-4 SDK alignment).
• Déplacement du registre §8 dans la SPEC body normative — différé au PR de promotion R4-P0-1 (§33 → normatif).

Prochaine étape

Après merge de ce PR, les trois contrats normatifs P0 docs-only sont inscrits :

• R4-P0-1 (onboarding wizard) ✅
• R4-P0-2 (KLICKD_E_* i18n) ✅
• R4-P0-4 (deprecation lifecycle) ✅ (ce PR)

Les tracks restantes pour fermer la phase P0 sont non-docs-only (P0-2 schéma strict, P0-3 SDK Python, P0-4 SDK JS, P0-5 migrateur, P0-6 vectors stricts) et requièrent une décision explicite de Vince avant ouverture, conformément à la gouvernance §3 du backlog (aucun publish sans Vince).

🤖 Generated with Claude Code