From d9e6551fbc808ac448d6c5726ddd0e0587f8b846 Mon Sep 17 00:00:00 2001 From: Claude Date: Sun, 24 May 2026 16:23:18 +0000 Subject: [PATCH] =?UTF-8?q?docs(roadmap):=20inscribe=20V4=20UX/DX=20resear?= =?UTF-8?q?ch-informed=20backlog=20(=C2=A72.4)=20+=20scope=20corrections?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Intake from a UX/DX comparative review (Mem0, Letta .af, Zep, LangGraph, AGENTS.md, Cursor, Obsidian, Logseq, 1Password, Bitwarden, KeePassXC, ComfyUI workflow JSON) summarised into actionable backlog items only — the source report is not copied into the repo. Changes: - ROAD-TO-V4-GA.md §0: explicit V4 scope corrections (maintainer validation 2026-05-24) — generic continuity (media/project) is V4 via RFC-001; baseline gaming.klickd is V4 conditional on optional + registry-based; 3D / spatial / CAD / printing is V5 track and does not block v4.0.0. - ROAD-TO-V4-GA.md §2.4: new UX/DX-driven backlog with R4- IDs and P0/P1/P2 priorities — user.klickd 7-step wizard with reload verification (R4-P0-1), KLICKD_E_* i18n actionable error messages (R4-P0-2), 5 downloadable persona example profiles (R4-P0-3), formal deprecation policy (R4-P0-4), minimal media.klickd (R4-P1-1), minimal project.klickd + AGENTS.md export (R4-P1-2), published JSON Schema v4 + offline validator (R4-P1-3), optional registry-based gaming.klickd baseline (R4-P1-4), QR/deeplink onboarding subject to zero-server architecture review (R4-P1-5/R4-P2-1), progressive compression preview (R4-P2-2), preferred_model routing hint (R4-P2-3), shared_context family UI (R4-P2-4), IANA MIME (R4-P2-5). - ROAD-TO-V4-GA.md §2.4 R4-Anti-Patterns: opposable list A1-A6 — JSON wall, silent migration, hidden cloud coupling, schema inflation, spec-first without examples, non-actionable errors. Every v4+ PR must justify it does not introduce these. - ROAD-TO-V4-GA.md §5: status updated post-merge PR #35 (SHA 891e7581); next recommended PR is the SPEC normative v4 promotion (P0-1). - New V4-UX-DX-RESEARCH-NOTES.md: intake summary linking back to §2.4, documenting the comparative sources, decisions, anti-patterns, and scope corrections. Non-normative, docs-only. Strict governance: no SPEC / schema / SDK / vector change; no publish (npm / PyPI / Zenodo / IANA); no tag; no locked_* field touched; no destructive change. Co-Authored-By: Claude Opus 4.7 --- docs/roadmap/ROAD-TO-V4-GA.md | 173 +++++++++++++++++++++++- docs/roadmap/V4-UX-DX-RESEARCH-NOTES.md | 164 ++++++++++++++++++++++ 2 files changed, 335 insertions(+), 2 deletions(-) create mode 100644 docs/roadmap/V4-UX-DX-RESEARCH-NOTES.md diff --git a/docs/roadmap/ROAD-TO-V4-GA.md b/docs/roadmap/ROAD-TO-V4-GA.md index 131a5bc..93e2a5a 100644 --- a/docs/roadmap/ROAD-TO-V4-GA.md +++ b/docs/roadmap/ROAD-TO-V4-GA.md @@ -35,6 +35,26 @@ Principe directeur, hérité de RFC-004 : **« Never break the soul. »** Aucune étape ne doit dégrader, deviner, ou inventer un champ déjà écrit par un utilisateur en v2.5 / v3.x / v3.5.1 / v4-preview. +### Corrections de périmètre V4 (validation maintainer 2026-05-24) + +Suite à la revue comparative UX/DX du 2026-05-24 (cf. intake détaillé dans +[`V4-UX-DX-RESEARCH-NOTES.md`](./V4-UX-DX-RESEARCH-NOTES.md) §3) et la +validation explicite du maintainer post-Acceptance Checklist V4 : + +1. **Continuité générique (media / project) = V4.** Les benchmarks et + évidence de continuité d'état génériques (références hash, `continuity_state`, + `next_action`) sont **dans le périmètre V4** via [RFC-001 `media_profile` v1](../rfcs/RFC-001-media-profile-v1.md) + — déjà `Accepted` — et l'extension `project.klickd` minimale (cf. §2.4 + R4-P1-2). +2. **Baseline NPC / gaming = V4 conditionnel.** Un profil `gaming.klickd` + baseline est dans le périmètre V4 **uniquement si optionnel et + registry-based** (cf. §2.4 R4-P1-4). Il ne doit pas alourdir + l'onboarding `user.klickd` ni devenir un MUST de la SPEC v4. +3. **3D / spatial / CAD / printing = V5 track.** Tout rendu 3D, capture + spatiale, CAO, ou flux d'impression 3D est **hors périmètre V4** et + **ne bloque pas** le tag `v4.0.0`. Ces sujets restent en piste V5 + (forward-looking) sans champ normé en v4. + --- ## 1. Distinction preview vs GA @@ -223,6 +243,152 @@ Chaque entrée précise : *Objet → Livrables → Critères de sortie (Definiti agent IA, tandis qu'un *creator core* capture l'identité créative d'un humain producteur de média. +### 2.4 Backlog UX/DX-driven (intake recherche comparative — 2026-05-24) + +> **Source intake :** [`V4-UX-DX-RESEARCH-NOTES.md`](./V4-UX-DX-RESEARCH-NOTES.md) +> (revue Mem0, Letta `.af`, Zep, LangGraph, AGENTS.md, Cursor, Obsidian, +> Logseq, 1Password, Bitwarden, KeePassXC, ComfyUI workflow JSON, +> 2026-05-24). Décisions actionnables uniquement — le rapport source +> intégral n'est **pas** copié dans le repo. +> +> Les identifiants utilisent le préfixe `R4-` pour ne pas entrer en +> collision avec les items P0/P1/P2 numérotés en §2.1–2.3. La priorité +> P0/P1/P2 reste la dimension portante. + +#### R4-P0-1 — Wizard `user.klickd` 7 étapes avec rechargement de vérification + +- **Objet :** interface guidée (web component / page dédiée) qui génère un `user.klickd` valide **sans exposer le JSON brut**. Étape 6 = recharger le fichier dans le wizard avant de quitter — non-négociable. +- **Pourquoi :** 1Password, Obsidian, Bitwarden convergent ; sans wizard avec rechargement, `.klickd` reste réservé aux développeurs et l'onboarding crée des fichiers non-réouvrables. +- **Livrables :** spec UX dans [`docs/ux/V4-UX-SPEC.md`](../ux/V4-UX-SPEC.md), maquette des 7 écrans, contrat des erreurs aux étapes 4 (passphrase) et 6 (rechargement). +- **DoD :** chaque étape a un seul choix dominant ; étape 6 produit un succès ou un message d'erreur orienté utilisateur (cf. R4-P0-2) ; aucun écran n'expose un payload JSON brut. +- **Garde-fou anti-pattern :** A1 (mur JSON), A5 (spec-first sans exemples), A6 (erreurs non actionnables). +- **Périmètre :** docs-only pour la spec UX. L'implémentation du wizard est tracée séparément côté `klickd.app` (hors-repo) et ne bloque pas le tag `v4.0.0` côté format — mais bloque l'adoption non-développeur. +- **Dépendances :** P0-1 (SPEC normative v4), R4-P0-2 (messages d'erreur), R4-P0-3 (profils d'exemple). + +#### R4-P0-2 — Messages d'erreur `KLICKD_E_*` i18n orientés utilisateur + +- **Objet :** table `error_messages` mappant **chaque** code `KLICKD_E_*` à un message utilisateur + action recommandée, en FR/EN/DE/LB (langues officielles du projet). +- **Pourquoi :** Bitwarden et KeePassXC : codes seuls inutilisables par non-développeurs. Couvre l'anti-pattern A6. +- **Livrables :** `docs/errors/KLICKD_ERRORS.md` (table normative non-secrète), exemples par code, contrat de fallback (code anglais si la langue n'est pas couverte). +- **DoD :** chaque code `KLICKD_E_*` documenté dans la spec a une ligne `code → message FR/EN/DE/LB → action`. Au moins une action ne renvoie **jamais** « contactez le support » (autonomie utilisateur). +- **Garde-fou anti-pattern :** A6. +- **Périmètre :** docs-only. Les SDKs Python/JS ne sont pas modifiés tant que P0-3/4 n'attaquent pas l'API publique de validation. +- **Dépendances :** P0-1. + +#### R4-P0-3 — Profils d'exemple téléchargeables (5 personas) + +- **Objet :** 5 fichiers `.klickd` v4 valides + décryptables avec une **passphrase de test publique** (jamais un secret réel), couvrant : élève terminale (éducation, FR), chef de projet PME (work, FR), développeur full-stack (work, EN), créateur média (creator, preview `media.klickd`), joueur RPG (gaming, preview `gaming.klickd`). +- **Pourquoi :** Letta `.af` montre que des exemples téléchargeables accélèrent l'adoption développeur. Sans fichier de référence, les tiers implémentent depuis la spec et divergent. +- **Livrables :** dossier `examples/v4/personas/`, README expliquant la passphrase de test (réutiliser celle déjà utilisée par les fixtures non-secrets actuels — pas de nouveau secret), checklist de validation contre les vectors v4 stricts (P0-6). +- **DoD :** chaque fichier passe la validation stricte v4 (P0-2/P0-6) sans warning ; chaque fichier round-trip via les SDKs (P0-3/P0-4) ; aucune donnée personnelle ni secret réel. +- **Garde-fou anti-pattern :** A5 (spec-first sans exemples). +- **Dépendances :** P0-2, P0-3, P0-4, P0-6. + +#### R4-P0-4 — Politique de dépréciation V4 formelle + +- **Objet :** document `docs/spec/DEPRECATION_POLICY_V4.md` définissant explicitement le cycle de vie d'un champ (`active` → `deprecated` → `removed`), la règle de marquage (`deprecated` après Vx+2 si <10 % d'usage observé sur les vectors / exemples / fixtures de référence), et la garantie de lecture silencieuse des champs `deprecated` par les readers v4. +- **Pourquoi :** `.klickd` v3.2 → v3.4 a ajouté 26 champs sans politique de sortie. Sans politique de dépréciation, le schéma grossit indéfiniment et les agents hallucinent des champs. +- **Livrables :** `DEPRECATION_POLICY_V4.md` (normatif post-P0-1), section dédiée dans la SPEC v4, ajout d'un bloc `deprecated_fields[]` au schéma envelope (informationnel, non-bloquant). +- **DoD :** la politique distingue *deprecated dans la SPEC* (champ encore valide mais discouraged) et *removed* (champ supprimé du schéma) ; aucune suppression sans transition `deprecated` d'au moins une version mineure ; le `deprecated_fields[]` est purement documentaire, jamais utilisé pour rejeter. +- **Garde-fou anti-pattern :** A4 (inflation schéma). +- **Dépendances :** P0-1. + +#### R4-P1-1 — `media.klickd` minimal (alignement RFC-001) + +- **Objet :** confirmer le **noyau minimal** déjà spécifié par [RFC-001 `media_profile` v1](../rfcs/RFC-001-media-profile-v1.md) (`Accepted`) — `project_name`, `assets[]` (label, path / `cas://blake3:`, hash, software, last_modified), `continuity_state`, `next_action` — et confirmer que le **rendu 3D / spatial / CAD / printing reste V5**, hors périmètre V4. +- **Pourquoi :** ComfyUI workflow JSON valide qu'un format de continuité média peut tenir en 3 champs requis. La continuité générique (référence média + état) est V4 ; le rendu spatial est V5. +- **Livrables :** note de cadrage dans RFC-001 ou dans la SPEC §33 (post-P0-1) confirmant la frontière V4 ↔ V5. +- **DoD :** la SPEC v4 normative énonce que `media_profile` v1 (V4) ne couvre **pas** 3D/spatial/CAD/printing ; un test négatif vérifie que ces sections, si présentes, sont préservées verbatim mais non interprétées. +- **Garde-fou anti-pattern :** A4 (inflation schéma). +- **Dépendances :** P0-1, RFC-001 (`Accepted`). + +#### R4-P1-2 — `project.klickd` minimal + export AGENTS.md + +- **Objet :** profil `project.klickd` minimal (dev / repo) avec champ `agents_md_content` (string Markdown) **auto-généré** depuis `stack`, `repo_url`, `decisions_locked[]`, `next_milestone`, `tests_required[]`. Le wizard pose 5 questions et produit à la fois le `.klickd` chiffré ET un AGENTS.md prêt à committer. +- **Pourquoi :** AGENTS.md est le standard de facto 2025-2026 (20+ outils). Un `project.klickd` qui exporte un AGENTS.md valide multiplie l'interopérabilité de `.klickd` dans les workflows dev. +- **Livrables :** RFC dédiée (à ouvrir, statut `Draft`) ou extension de RFC-001 — décision dans la PR de spec. +- **DoD :** le mapping `project.klickd` → AGENTS.md est déterministe ; l'AGENTS.md produit passe les linters connus (markdownlint) ; aucun secret n'entre dans l'AGENTS.md (R4-P0-2 : warning si tentative). +- **Garde-fou anti-pattern :** A1 (mur JSON, l'AGENTS.md est l'interface humaine), A3 (couplage cloud — `project.klickd` reste local-first). +- **Dépendances :** P0-1, R4-P0-3. + +#### R4-P1-3 — JSON Schema v4 publié à URL stable + validateur testable + +- **Objet :** publier `klickd-v4.schema.json` (cf. P0-2) à une **URL stable** (`schema.klickd.app` ou GitHub raw versionné) et fournir un **validateur web minimal** *zero-server* (tout client-side, comme le viewer P1-5). +- **Pourquoi :** ComfyUI publie son schema et référence un repo RFC. Sans schema publié, les tiers divergent. +- **Livrables :** redirect ou fichier statique à URL stable, validateur web (`demo/validator/`), CI qui valide `examples/v4/**` contre le schéma à chaque PR. +- **DoD :** URL résolvable et stable post-tag v4.0.0 ; validateur fonctionne offline ; aucun upload / télémétrie. +- **Garde-fou anti-pattern :** A3 (couplage cloud — le validateur doit fonctionner hors-ligne). +- **Dépendances :** P0-2. + +#### R4-P1-4 — `gaming.klickd` baseline optionnelle (registry-based) + +- **Objet :** profil `gaming.klickd` baseline minimale — `character_name`, `game`, `continuity_state`, `next_session_trigger`, `npc_memory[]` — **uniquement** activable via le registre de domaines, jamais via l'onboarding `user.klickd` principal. +- **Pourquoi :** la portabilité de contexte narratif NPC a une valeur réelle (cross-save gaming est verrouillé par les plateformes, mais le contexte narratif est platform-agnostic). Néanmoins, alourdir le path d'onboarding principal serait une régression UX. +- **Livrables :** RFC dédiée (à ouvrir, statut `Draft`), exemple non-normatif dans `examples/v4/personas/` (cf. R4-P0-3), note dans la SPEC §33 (post-P0-1) clarifiant qu'un reader v4 **doit** ignorer en silence un payload `domain: gaming` s'il ne déclare pas la facette. +- **DoD :** zéro impact sur l'onboarding `user.klickd` ; le profil est optionnel et registry-based ; aucun champ `gaming.*` n'est requis dans le schéma envelope v4. +- **Garde-fou anti-pattern :** A1 (mur JSON), A4 (inflation schéma). +- **Périmètre V4 confirmé :** baseline gaming est **V4 si et seulement si** optionnel + registry-based. +- **Dépendances :** P0-1, R4-P0-4. + +#### R4-P1-5 / R4-P2-1 — QR / deeplink onboarding trigger (conditionnel) + +- **Objet :** mode d'onboarding trigger générant un **QR code** (ou deeplink local `klickd://load?...`) pour le provisioning d'un `.klickd` sur un nouvel agent / nouvel appareil. Inspiré du Secret Key 1Password. +- **Pourquoi UX :** geste « scanner pour transférer mon identité IA » est immédiatement compréhensible. Couvre le cross-device sans introduire de compte. +- **Risque architecture :** une URL temporaire de téléchargement réintroduit une dépendance serveur — *contradiction directe* avec la claim « zero-server pour les fichiers `.klickd` ». +- **Décision :** **P1 conditionnel → P2 si revue architecture zero-server bloque.** À trancher entre : + - (a) **QR embarque le fichier complet** (taille ≤ 3 KB compressé) — zero-server, contrainte taille forte ; + - (b) **deeplink local** (`klickd://load?token=...`) sans réseau, repose sur intent OS et fichier déjà transféré par canal hors-bande ; + - (c) **abandon V4** si aucune variante zero-server n'est viable — repousser post-GA. +- **Livrables :** note d'architecture dans [`docs/ux/V4-UX-SPEC.md`](../ux/V4-UX-SPEC.md), décision tranchée par RFC dédiée. +- **DoD :** la décision ne casse pas la claim zero-server ; aucune URL temporaire serveur n'est introduite tacitement. +- **Garde-fou anti-pattern :** A3 (couplage cloud masqué). +- **Dépendances :** P0-1, revue architecture explicite par Vince. + +#### R4-P2-2 — `compression_policy.mode: "progressive"` (preview avant application) + +- **Objet :** nouveau mode de compression qui affiche à l'utilisateur « taille actuelle → taille après compression » et permet l'annulation avant écriture. +- **Pourquoi :** LangGraph documente que les checkpoints créent « une croissance de stockage significative ». La compression silencieuse érode la confiance. +- **Livrables :** extension non-bloquante de la `compression_policy` (post-P0-1), pas de champ requis ajouté. +- **DoD :** `mode: "progressive"` est *opt-in* ; les modes existants restent inchangés. +- **Garde-fou anti-pattern :** A2 (migration silencieuse). +- **Dépendances :** P0-1. + +#### R4-P2-3 — `preferred_model` (réservé depuis v3.4) → routing hint normalisé V4 + +- **Objet :** finaliser la sémantique de `preferred_model` : **hint, pas obligation**, un reader peut l'ignorer mais **doit** logger l'override. +- **Pourquoi :** champ réservé depuis v3.4 sans contrat — les intégrateurs divergent. +- **Livrables :** ajout dans la SPEC §33 normative (post-P0-1) d'une règle 2119 (MAY pour le respect, SHOULD pour le log). +- **DoD :** zéro changement breaking ; la SPEC v4 normative cadre l'intent. +- **Dépendances :** P0-1. + +#### R4-P2-4 — UI dédiée `shared_context` (Plan Famille) + +- **Objet :** interface dédiée pour configurer `visible_to_members` et `private_fields` sans éditer le JSON brut. +- **Pourquoi :** champ avancé v3.4 avec implications RGPD ; sans UI, les parents exposent des données sensibles (mood, struggles) par accident. +- **Livrables :** spec UX dans [`docs/ux/V4-UX-SPEC.md`](../ux/V4-UX-SPEC.md). Implémentation tracée hors-repo côté `klickd.app`. +- **DoD :** zéro champ JSON n'est exposé directement ; le default est *private*. +- **Garde-fou anti-pattern :** A1 (mur JSON). +- **Dépendances :** P0-1, R4-P0-1 (wizard pattern). + +#### R4-P2-5 — IANA MIME `application/vnd.klickd+json` + +- **Objet :** doublon volontaire de P2-1 (déjà tracé). Reste P2, post-tag GA, processus administratif externe. +- **Statut :** noté pour cohérence de la table ; voir P2-1 pour le tracking canonique. + +#### R4-Anti-Patterns — liste opposable + +Tout PR v4+ (RFC, spec, schéma, SDK, exemple) **doit** justifier, si la +question se pose, en quoi elle n'introduit aucun des anti-patterns +suivants. Liste détaillée et exemples concrets dans +[`V4-UX-DX-RESEARCH-NOTES.md`](./V4-UX-DX-RESEARCH-NOTES.md) §2. + +- **A1 — Mur JSON.** Pas de payload brut affiché à l'utilisateur final. +- **A2 — Migration silencieuse.** Toute migration émet un `migration_report` (RFC-004) ET un message utilisateur orienté action. +- **A3 — Couplage cloud masqué.** Pas de dépendance serveur tacite ; toute intégration sync requiert consentement explicite et changement de claim. +- **A4 — Inflation schéma.** Pas d'ajout de champ sans politique de dépréciation associée (R4-P0-4). +- **A5 — Spec-first sans exemples.** Toute RFC `Accepted` ou section SPEC normative est accompagnée d'au moins un exemple complet et valide. +- **A6 — Erreurs non actionnables.** Tout nouveau code `KLICKD_E_*` est accompagné d'un message utilisateur + action (R4-P0-2). + --- ## 3. Gouvernance & règles d’exécution @@ -266,7 +432,8 @@ L’ordre suivant minimise le re-travail : > > - La PR #30 « rfc(v4): promote RFC-001 / RFC-002 / RFC-004 from Draft to Proposed » a été mergée le 2026-05-23 (docs-only). > - La PR « docs(rfc): add V4 acceptance checklist » a introduit l'[**Acceptance Checklist V4**](../rfcs/ACCEPTANCE_CHECKLIST_V4.md) (critères C1–C16 pour `Proposed → Accepted`, I1–I9 pour `Accepted → Implemented`), docs-only. -> - La PR courante « rfc(v4): promote RFC-001 / RFC-002 (v1 core) / RFC-004 from Proposed to Accepted » applique ce checklist aux trois RFCs cibles. Acceptance = docs-only, aucun SDK / schéma / vector / publish / tag. +> - La PR « rfc(v4): promote RFC-001 / RFC-002 (v1 core) / RFC-004 from Proposed to Accepted » (#35) a été mergée le 2026-05-24 (SHA `891e7581`). Acceptance = docs-only, aucun SDK / schéma / vector / publish / tag. +> - La PR courante (docs-only) inscrit le **backlog UX/DX-driven** §2.4 et l'intake [`V4-UX-DX-RESEARCH-NOTES.md`](./V4-UX-DX-RESEARCH-NOTES.md). Aucune modification SPEC / schéma / SDK / vector / publish. Justification : promouvoir RFC-001 / RFC-002 (v1 core) / RFC-004 de `Proposed` à `Accepted` est le préalable explicite de P0-1 (SPEC normative v4). Le @@ -278,7 +445,9 @@ La séquence après merge de la PR d'acceptance est : 1. ~~**PR « rfc(v4): promote RFC-001 from Proposed to Accepted »**~~ — incluse dans la PR groupée d'acceptance (2026-05-24). 2. ~~**PR « rfc(v4): promote RFC-002 (v1 core) from Proposed to Accepted »**~~ — idem. 3. ~~**PR « rfc(v4): promote RFC-004 from Proposed to Accepted »**~~ — idem. -4. **PR « spec(v4): begin promoting §33 preview wording toward normative (P0-1) »** — démarre la phase SPEC normative maintenant que les trois RFCs sont en `Accepted`. +4. ~~**PR « rfc(v4): promote RFC-001 / RFC-002 (v1 core) / RFC-004 from Proposed to Accepted »**~~ — mergée 2026-05-24 (PR #35, SHA `891e7581`). +5. **PR courante** (docs-only) — inscrit le backlog UX/DX-driven §2.4 et l'intake [`V4-UX-DX-RESEARCH-NOTES.md`](./V4-UX-DX-RESEARCH-NOTES.md). Confirme les corrections de périmètre V4 §0 (continuité générique V4, baseline gaming V4-conditionnel, 3D/spatial/CAD/printing V5). +6. **PR suivante recommandée — `spec(v4): begin promoting §33 preview wording toward normative (P0-1)`** — démarre la phase SPEC normative maintenant que les trois RFCs sont en `Accepted` et que le backlog UX/DX-driven est inscrit. Cette PR sera docs-only également (touche `SPEC.md` §33 — pas de schéma strict, pas de SDK, pas de vector), conformément à la règle §3.10. Aucune de ces PR ne déclenche un publish (npm / PyPI / Zenodo), un tag, ni une annonce externe. Elles restent docs-first conformément à la règle §3.10. diff --git a/docs/roadmap/V4-UX-DX-RESEARCH-NOTES.md b/docs/roadmap/V4-UX-DX-RESEARCH-NOTES.md new file mode 100644 index 0000000..08dc3bc --- /dev/null +++ b/docs/roadmap/V4-UX-DX-RESEARCH-NOTES.md @@ -0,0 +1,164 @@ +# V4 UX/DX research notes (intake) + +> **Status:** Draft · NON-NORMATIVE · backlog intake summary. +> **Scope:** synthétise les décisions actionnables tirées d'une revue +> comparative UX end-user / DX développeur (Mem0, Letta `.af`, Zep, +> LangGraph, AGENTS.md, Cursor rules, Obsidian, Logseq, 1Password, +> Bitwarden, KeePassXC, ComfyUI workflow JSON) menée le **2026-05-24**. +> Ce document **ne copie pas** le rapport source intégral — il en +> extrait les décisions backlog et les anti-patterns à inscrire dans +> [`ROAD-TO-V4-GA.md`](./ROAD-TO-V4-GA.md) §2.4. +> +> **Aucun changement** : SPEC, schéma, SDK, vector, tag, publish. + +--- + +## 0. Pourquoi cette note + +La V4 GA est gouvernée par la roadmap normative +[`ROAD-TO-V4-GA.md`](./ROAD-TO-V4-GA.md). Avant que la SPEC §33 ne soit +promue normative (P0-1), nous avons besoin que le backlog reflète aussi +la **réalité d'adoption** observée dans les écosystèmes voisins +(local-first PKM, gestionnaires de mots de passe, fichiers d'agent +portables, workflows IA générative). + +Cette note est l'intake : une liste minimale d'items P0/P1/P2 issus de +la revue, et une liste d'anti-patterns que V4 doit éviter. Les items +eux-mêmes vivent dans §2.4 de la roadmap. + +--- + +## 1. Décisions actionnables (synthèse) + +### 1.1 P0 — bloquants GA (UX/DX-driven) + +1. **`user.klickd` 7-step wizard avec rechargement de vérification + obligatoire.** Inspiré de 1Password Emergency Kit, Obsidian vault + setup, Bitwarden import. Étape 6 = recharger le fichier généré avant + la fin du wizard. Sans cette étape, l'onboarding crée des fichiers + que l'utilisateur ne sait pas réouvrir. +2. **Messages d'erreur i18n orientés utilisateur pour tous les codes + `KLICKD_E_*`.** Une table `error_messages` (FR/EN/DE/LB) mappant chaque + code à un message orienté utilisateur + une action recommandée. + Bitwarden et KeePassXC sont la référence : `[ligne] [type] "nom" : + champ X dépasse N caractères` est actionnable, `KLICKD_E_FORMAT` + seul ne l'est pas. +3. **Profils d'exemple téléchargeables (5 personas).** Letta publie des + `.af` d'exemple — c'est ce qui a accéléré l'adoption développeur. + Cinq fichiers `.klickd` valides + décryptables (passphrase de test + non-secret, déjà-publique) : élève terminale, chef de projet, dev, + créateur média (preview `media.klickd`), joueur (preview + `gaming.klickd`). +4. **Politique de dépréciation formelle.** `.klickd` a ajouté 26 champs + en v3.4. Sans politique, le schéma devient ingérable et les agents + hallucinent des champs. Règle proposée : tout champ ajouté en Vx + passe à `deprecated` en Vx+2 s'il n'apparaît pas dans ≥10 % des + fichiers d'exemple. Un `deprecated` est ignoré silencieusement par + les readers v4 mais reste documenté pour migration. + +### 1.2 P1 — bloquants adoption (UX/DX-driven) + +1. **`media.klickd` minimal (RFC-001 v1, déjà `Accepted`).** Noyau : + `project_name`, `assets[]` (label, path, hash, software, + last_modified), `continuity_state`, `next_action`. Pattern repris de + ComfyUI workflow JSON (références hash, pas de binaire dans le + fichier). **Périmètre V4 confirmé** : la continuité générique + (référence média + état de continuité) est V4. Le rendu 3D / CAD / + spatial / printing reste **V5 track** et ne doit pas bloquer V4. +2. **`project.klickd` minimal avec export AGENTS.md.** Champ + `agents_md_content` (string Markdown) auto-généré à partir des + champs `stack`, `repo_url`, `decisions_locked`, `next_milestone`. + AGENTS.md est le standard de facto 2025-2026 (20+ outils). Permettre + l'export depuis un `project.klickd` chiffré multiplie + l'interopérabilité. +3. **JSON Schema v4 publié et testable.** Au-delà de P0-2 (schéma + strict côté repo), publier le schéma à une URL stable (cf. ComfyUI + workflow_json) et fournir un validateur web minimal (zero-server, + tout côté client). Ne pré-engage pas l'IANA MIME (P2-1). +4. **`gaming.klickd` baseline optionnelle (registry-based).** Profil + **registré** (ne s'active que si `domain: gaming`), noyau minimal : + `character_name`, `game`, `continuity_state`, `next_session_trigger`, + `npc_memory[]`. **Périmètre V4 confirmé** par Vince : baseline NPC / + gaming est V4 *uniquement si* optionnel et registry-based — il ne + doit jamais alourdir l'onboarding `user.klickd` principal. +5. **QR / deeplink onboarding trigger** — classé **P1/P2 conditionnel, + subject to zero-server architecture review.** Le pattern 1Password + QR de provisioning est attractif UX, mais une URL temporaire de + téléchargement réintroduit une dépendance serveur en contradiction + avec la claim « zero-server pour les fichiers `.klickd` ». À + trancher : (a) QR encode le fichier complet (taille ≤ 3 KB + compressé), zéro-serveur ; (b) QR encode un *deeplink* local + (`klickd://load?token=...`) sans réseau ; (c) abandon si aucune + variante n'est zero-server. + +### 1.3 P2 — souhaitable / extension (UX/DX-driven) + +1. **`compression_policy.mode: "progressive"` avec preview** — montrer + « taille actuelle → taille après compression » avant d'appliquer. + Évite la méfiance LangGraph (« checkpoints créent une croissance de + stockage significative »). +2. **`preferred_model` (réservé depuis v3.4) → routing hint normalisé + V4** — clarifier sémantiquement : hint, pas obligation ; un reader + peut l'ignorer mais doit logger l'override. +3. **`shared_context` (Plan Famille) UI dédiée** — RGPD : sans UI, + `visible_to_members` / `private_fields` se configurent en JSON brut, + ce qui expose des données sensibles (mood, struggles) par accident. +4. **IANA MIME `application/vnd.klickd+json`** — déjà tracé en P2-1 + roadmap actuelle. Confirmation : reste P2, post-tag GA. + +--- + +## 2. Anti-patterns à éviter (V4) + +| # | Anti-pattern | Observé chez | Garde-fou V4 | +|---|---|---|---| +| A1 | **Mur JSON.** Afficher le payload brut à l'utilisateur. | Premières versions LangGraph, exports Logseq, specs `.klickd` v2.x exposées directes. | Le wizard cache le JSON. L'utilisateur ne voit jamais qu'un résumé (`nom · domaine · dernière session`). | +| A2 | **Migration silencieuse.** Lire un fichier d'une version antérieure sans informer des champs manquants ou dépréciés. | ComfyUI v0.4 → v1.0 (champs ignorés), Cursor `.cursorrules` → `.cursor/rules/`. | RFC-004 `migration_report` obligatoire + UX message orienté utilisateur (« profil v2 mis à jour vers v4, données intactes »). | +| A3 | **Couplage cloud masqué.** Prétendre local-first tout en nécessitant un appel serveur. | OpenMemory MCP (clé API OpenAI obligatoire), Obsidian Sync payant. | Toute intégration `session_metadata` / sync future requiert consentement explicite + changement de claim. Pas de sync serveur par défaut. | +| A4 | **Inflation schéma.** Ajouter des champs à chaque version sans déprécier. | `.klickd` v3.2 → v3.4 (26 nouveaux champs). | Voir P0-4 (politique de dépréciation formelle). | +| A5 | **Spec-first sans exemples.** Documentation exhaustive mais exemples fragmentaires. | Spec `.klickd` actuelle (exemples par section, pas fichiers complets valides). | Voir P0-3 (5 profils d'exemple complets téléchargeables, passphrase test publique). | +| A6 | **Erreurs non actionnables.** Codes machine seuls (`KLICKD_E_FORMAT`) sans message + action. | LangGraph pré-v0.3 (stacktrace Python brut), premiers workflows ComfyUI (nœud « invalid » sans localisation). | Voir P0-2 (table `error_messages` i18n, code → message utilisateur + action). | + +--- + +## 3. Corrections de périmètre V4 (validation Vince 2026-05-24) + +Ces corrections explicites du périmètre V4 sont issues de la revue : + +1. **Continuité générique (media / project) = V4.** Les benchmarks et + évidence de continuité d'état génériques (références hash, état de + continuité, prochain action) sont **dans le périmètre V4** via + RFC-001 (`media_profile`) — déjà `Accepted`. La couche + `project.klickd` minimale (P1.2 ci-dessus) suit le même cadrage. +2. **Baseline NPC / gaming = V4, conditionnel.** Un profil + `gaming.klickd` baseline est **dans le périmètre V4** uniquement si + *optionnel* et *registry-based*. Il ne doit pas alourdir + l'onboarding `user.klickd`, ne pas devenir un MUST de la SPEC v4, et + rester ignorable par tout reader v4 ne déclarant pas la facette + `domain: gaming`. +3. **3D / spatial / CAD / printing = V5 track.** Tout ce qui touche au + rendu 3D, à la capture spatiale, à la CAO, ou aux flux d'impression + 3D, est **hors périmètre V4** et n'entre pas dans la séquence GA. + Ces sujets restent en piste V5 (forward-looking), n'introduisent + aucun champ normé en v4, et **ne bloquent pas** le tag `v4.0.0`. + +--- + +## 4. Notes de gouvernance pour cette intake + +- Cette note **n'introduit aucun champ normé**, **ne modifie aucun + schéma**, **ne touche aucun SDK ou vector**, et **ne déclenche aucun + publish** (npm / PyPI / Zenodo / IANA). +- Les items concrets sont inscrits dans + [`ROAD-TO-V4-GA.md`](./ROAD-TO-V4-GA.md) §2.4 sous un préfixe `R4-` + (R pour *research-informed*) afin de ne pas collisionner avec les + identifiants P0/P1/P2 existants. +- Les anti-patterns A1–A6 sont citables depuis n'importe quelle RFC ou + PR de revue. Toute nouvelle RFC v4+ devra justifier en quoi elle + *n'introduit pas* ces anti-patterns. +- La validation maintainer (Vince, 2026-05-24, `Go` post-audit + Acceptance Checklist) confirme les corrections de périmètre §3. + +--- + +*Document vivant — toute modification passe par une PR docs-only.*