# Plan 0.0.2 — Git générique et synchronisation de lecture ## Statut et sources Plan actif de la release `0.0.2`, ouvert depuis la stable Knowledge `v0.0.1` publiée et vérifiée. Sources autoritaires de reprise : ```text Knowledge tag stable v0.0.1 Knowledge commit stable 98ec46fe73bd50dacbe6be220650d87dd2000b74 Knowledge archive SHA-256 1f0b2cfaecee1cbee621abb9c3c95811773ebfc17c374c4369fdc220bcf7d72d Knowledge publish report sasedev-knowledge-0.0.1-publish.001-report.md = PASS Knowledge start prompt prompts/002-V0_0_2_START_PROMPT.md ``` La baseline PGR réévaluée au démarrage de cette release est : ```text PGR stable tag v0.1.3 PGR stable commit fe80dbbb737390a7ea99df27d979bd59ccfb86e3 PGR archive SHA-256 f3a7dffd5fe0fd3542e6b5207fda0b94bca2bd05bd5a54542d0a08d635a5d6ee PGR publish report pgr-0.1.3-publish.001-report.md = PASS ``` Le passage de PGR `v0.1.1` à `v0.1.3` est traité comme adoption d'un projet existant via `230-ADOPTION`. Les artefacts historiques de `0.0.1` ne sont pas réécrits. `0.0.2-alpha.1` est `FAIL` pour défaut de structure du présent plan malgré des contrôles techniques propres. `alpha.1.fix.1` a corrigé uniquement ce cadrage documentaire et sa gate opérateur est `PASS`. `alpha.2` peut donc matérialiser le premier backend Git réel. ## Mission `0.0.2` doit rendre réellement utilisable le chemin de lecture Git générique sans rendre une forge particulière obligatoire : ```text source locale/remote -> mirror contrôlé -> refresh -> résolution vers commit -> snapshot/worktree déterministe -> résultat de synchronisation changed/unchanged ``` La release doit transformer les contrats passifs de `0.0.1` en un backend Git de lecture testable, reproductible et remplaçable, tout en gardant Git autoritaire pour le contenu et la persistance métier hors de ce scope. ## État acquis et questions ouvertes Décisions déjà matérialisées par le cadrage `alpha.1` et non remises en cause par son `FAIL` documentaire : - PGR `v0.1.3` est la baseline applicable au projet existant ; - les changements PGR Java/Maven/Gradle/Android ne deviennent pas applicables à Knowledge ; - le `DEFER` Tauri reste inchangé ; - le backend initial utilise un processus `git` contrôlé via `std::process::Command`, sans shell ; - `knowledge-git-lib` possède l'implémentation et la configuration physique Git ; - la racine d'état Git généré est explicite et hors du dépôt source ; - les mirrors vivent sous `repositories/.git` ; - les snapshots vivent sous `snapshots//` ; - une source locale est clonée avec `--mirror --no-local` afin d'éviter une dépendance implicite aux objets du dépôt source ; - une référence est résolue vers un commit réel avant matérialisation d'un snapshot ; - la racine d'état reste exclusive à une instance/processus pour `0.0.2` ; - la révision précédemment observée reste fournie par l'appelant tant que la persistance PostgreSQL est hors scope ; - `gix` et `git2` restent des alternatives différées, pas des backends ajoutés par symétrie. Questions laissées ouvertes jusqu'à la tranche qui les consomme : - politique de nettoyage/rétention des snapshots ; - besoin réel de supporter submodules ou Git LFS dans cette release ; - besoin réel d'une crate `knowledge-app-lib` pour l'orchestration partagée ; - mécanisme concret de scheduler périodique, volontairement non requis pour prouver le cas d'usage de synchronisation ; - prochaine mission/version après `0.0.2`, à décider uniquement lors de la revue d'horizon. ## Scope `0.0.2` inclut : - adoption PGR applicable au projet existant ; - étude et choix documenté du backend Git initial ; - matérialisation de `knowledge-git-lib` lorsqu'une responsabilité runtime réelle existe ; - configuration explicite d'une source Git locale ou remote et d'une racine d'état ; - création/inspection d'un mirror contrôlé ; - refresh idempotent des refs utiles ; - résolution d'une référence vers un commit ; - matérialisation et validation d'un snapshot/worktree détaché adressé par révision ; - cas d'usage de synchronisation distinguant `Changed` et `Unchanged` à partir de la révision précédente fournie par l'appelant ; - tests unitaires et d'intégration avec repositories Git temporaires locaux ; - validation de non-régression des contrats/domaines déjà stables ; - réconciliation documentaire, candidate et fermeture stable de la release. La création d'une crate supplémentaire d'orchestration n'appartient au scope que si une responsabilité partagée réelle est démontrée ; elle n'est pas imposée par le plan. ## Hors scope `0.0.2` n'implémente pas : - API Gitea/GitHub/GitLab ; - webhooks de forge ; - pull/merge requests ; - branch/commit/rebase/merge/push de publication ; - PostgreSQL et migrations ; - persistance durable de l'état de synchronisation ; - parsing final PGR/HOWTO/snippet ; - moteur de recherche ; - authentification ou administration ; - worker réseau séparé ; - cache Git partagé simultanément par plusieurs processus ; - scheduler périodique concret sans besoin démontré ; - backend secondaire `gix`/`git2` sans replanification motivée ; - changement de rendu/UI Web. ## Stratégie de validation Les gates suivent [`../validation/001-VALIDATION_MATRIX.md`](../validation/001-VALIDATION_MATRIX.md) et restent proportionnées au scope modifié. Principes : - `alpha.1` et son fix utilisent une gate documentaire/gouvernance, avec validation explicite de la structure du plan ; - toute tranche modifiant Rust rejoue `cargo fmt`, les audits Rust applicables, `cargo metadata`, `cargo check`, Clippy strict et les tests ciblés/workspace nécessaires ; - les propriétés Git fonctionnelles sont prouvées avec de vrais repositories temporaires locaux, pas seulement avec des mocks du runner ; - aucun accès Internet ni aucune forge publique ne doit être nécessaire pour prouver le chemin Git générique ; - les tests de source locale et remote locale doivent distinguer initialisation, refresh, résolution et snapshot ; - les erreurs doivent être testées sans exposer de secret ou argument sensible ; - la baseline Web est une non-régression : les gates npm/Vite et smokes HTTP sont rejoués lorsqu'une tranche peut les affecter et pendant la stabilisation ; - aucun `PASS` assistant ne remplace le résultat opérateur ; - un `FAIL`, `PARTIAL` ou `BLOCKED` est historisé avant correction. ## Trajectoire prévisionnelle ### alpha.1 — adoption PGR, étude et cadrage Fermer les prérequis du prompt `002` avant toute implémentation Git fonctionnelle : adoption PGR, inventaire des contrats existants, étude comparative `git`/`gix`/`git2`, ownership de `knowledge-git-lib`, layout de l'état généré, plan et gate de release. Le résultat opérateur initial est **FAIL** : les contrôles techniques transmis sont propres, mais le plan `0.0.2` ne respectait pas le patron de pilotage déjà établi par `0.0.1` (scope global absent, trajectoire hors section dédiée, niveaux de titres incorrects, déclencheurs de REPLAN et revue d'horizon absents). `alpha.1.fix.1` corrige uniquement cette structure documentaire, ajoute la gate de non-régression correspondante et ne modifie aucune décision technique de l'étude Git. Aucun fichier sous `crates/` ou `Web/` n'est modifié dans `alpha.1` ou son fix. La gate opérateur de `alpha.1.fix.1` est **PASS**. ### alpha.2 — contrats minimaux et backend process Statut opérateur : **à valider**. Le delta matérialise le premier backend réel sans encore prétendre couvrir tout le cycle de synchronisation. Les choix concrets de la tranche sont : configuration publique `GitBackendConfig`/`GitSourceConfig`, runner process strictement interne, erreurs publiques redacted par construction et `source-key` hexadécimale déterministe dérivée du `SourceId`. Le scope reste : - créer `knowledge-git-lib` avec responsabilité réelle ; - introduire uniquement les types/configurations nécessaires aux sources et à la racine d'état ; - encapsuler `std::process::Command` derrière un composant interne testable, sans shell ; - construire les arguments Git comme arguments séparés ; - valider les chemins et l'ownership de l'état généré ; - implémenter l'initialisation et l'inspection minimale du mirror ; - étendre `knowledge-git-api` uniquement si un besoin de contrat public est déjà démontré ; - tester configuration, chemins, arguments, erreurs et redaction. La tranche ne crée ni dépendance forge, ni scheduler, ni persistance. Si la surface « configuration + runner + mirror » ne peut plus être validée proprement comme une seule responsabilité, REPLAN avant d'ajouter du scope. ### alpha.3 — refresh, résolution et snapshot réel Compléter le chemin de lecture Git sur de vrais repositories temporaires : - refresh idempotent du mirror ; - résolution typée d'une référence vers un commit ; - refus des références invalides ou non résolubles ; - préparation d'un worktree/snapshot détaché adressé par révision ; - validation d'un snapshot existant avant réutilisation ; - preuve d'un changement de révision après ajout d'un commit source ; - preuve qu'aucune API de forge n'est nécessaire. Les tests doivent exercer la frontière publique du backend et les effets Git réels. Une imitation complète de `git` par mocks ne constitue pas la preuve principale de cette tranche. ### alpha.4 — cas d'usage de synchronisation Composer les primitives Git en un cas d'usage réellement consommable : - enchaîner refresh, résolution, comparaison avec `previous_revision` et snapshot ; - retourner explicitement un résultat `Unchanged` ou `Changed` avec la révision observée ; - rendre la synchronisation explicite utilisable par un appelant ; - vérifier que `RepositorySyncTrigger::Periodic` peut emprunter la même voie sans matérialiser un scheduler artificiel ; - garder la persistance de dernière révision hors scope. `knowledge-app-lib` n'est créée que si cette orchestration possède effectivement un ownership partagé et évite une duplication réelle. Sinon la tranche reste dans les crates déjà justifiées. ### beta.1 — réconciliation et revue d'horizon Réconcilier le plan avec l'implémentation réellement obtenue : - inventorier les contrats et crates effectivement matérialisés ; - vérifier les `DEFER` et hors-scope ; - retirer ou corriger les hypothèses de forecast devenues fausses ; - vérifier l'absence de dépendance forge/PostgreSQL/auth/admin ; - rejouer les gates Rust/Git et la non-régression Web utile ; - décider si une prochaine mission est suffisamment claire pour engager une version suivante ; - ne réserver aucun numéro futur par défaut. Aucune grande fonctionnalité nouvelle n'entre en beta. ### rc.1 — candidate stable Geler le scope fonctionnel de `0.0.2` et exécuter la gate complète de release candidate. La RC doit notamment : - ne pas introduire de nouvelle fonctionnalité ; - confirmer la cohérence des histories et deltas de `0.0.2` ; - confirmer la reproductibilité des tests Git locaux ; - rejouer Cargo/Clippy/tests, audits applicables, baseline Web, manifest Vite et smokes HTTP ; - confirmer l'absence de dépendance forge/PostgreSQL/auth/admin hors scope ; - confirmer l'état de la revue d'horizon et du handoff suivant s'il existe. Un défaut fonctionnel important découvert en RC impose un retour de phase ou un REPLAN ; il ne doit pas être absorbé silencieusement dans la promotion stable. ### rel.1 — fermeture stable Promotion mécanique de la candidate validée vers `0.0.2` : - porter `VERSION = 0.0.2` et la version workspace identique ; - stabiliser `README.md`, `ROADMAP.md`, `CHANGELOG.md`, l'index et le présent plan ; - conserver tous les histories `FAIL`/`PASS` réels ; - préparer un prompt de reprise uniquement si la revue d'horizon a réellement engagé une prochaine release ; - rejouer la gate pré-tag complète ; - produire le history `rel.1` uniquement après résultats opérateur ; - après `PASS`, committer/pousser le produit stable, créer/pousser le tag annoté `v0.0.2`, télécharger l'archive du tag et produire séparément `publish.001`. La publication post-tag ne peut pas être anticipée dans le delta `rel.1`. ## Déclencheurs de REPLAN REPLAN obligatoire si : - une tranche accumule plusieurs responsabilités non prévues qui ne peuvent plus être validées proprement ensemble ; - le backend process ne peut pas satisfaire les propriétés de sécurité/déterminisme sans introduire un shell ou une dépendance plus large ; - une opération Git fondamentale exige finalement une API de forge ; - les sources réelles exigent submodules, Git LFS ou une autre capacité qui change substantiellement le modèle de snapshot ; - le modèle de `source-key` ou de chemins ne peut pas garantir isolation et absence de collision sans modifier les contrats publics ; - le partage de la racine d'état entre plusieurs processus devient nécessaire et impose verrouillage/coordination ; - l'extension de `knowledge-git-api` change de manière substantielle les contrats validés en `0.0.1` ; - l'orchestration de synchronisation crée une duplication réelle qui impose un nouvel owner commun non prévu ; - des mesures concrètes rendent le backend process inadéquat et justifient de réévaluer `gix` ou `git2` ; - trois fixes ou plus apparaissent sur une même tranche ; - une nouvelle stable PGR modifie un owner réellement applicable au scope courant ; - un prérequis externe invalide la mission de `0.0.2`. Un REPLAN modifie le présent plan de manière explicite ; il ne doit pas être masqué par un simple élargissement opportuniste d'un delta. ## Clôture et transition - documentation durable : réconciliée à chaque tranche qui change un contrat, puis revue globalement en `beta.1` ; - `CHANGELOG.md` : consolidé en candidate/stable sans catalogue de fixes internes inutile ; - `ROADMAP.md` : revue d'horizon en `beta.1`, sans création automatique d'une prochaine version ; - prompt/handoff suivant : créé uniquement si une prochaine mission est réellement décidée ; - fermeture du plan : `rel.1` ou son fix établissant la stable ; - publication : commit produit `0.0.2`, tag stable `v0.0.2`, archive du tag puis rapport post-tag séparé ; - toute tranche suit `delta -> gate opérateur -> history réel -> commit/push -> tranche suivante ou fix`. ## Revue d'horizon État courant : **non réalisée**. Aucune version postérieure à `0.0.2` n'est réservée par le présent plan. La revue appartient à `beta.1` et doit s'appuyer sur le backend Git réellement éprouvé, les DEFER encore ouverts et les besoins produit observés. Elle peut : - engager une prochaine release avec mission explicite ; - maintenir les domaines futurs non numérotés ; - reclasser un besoin différé si les preuves obtenues le justifient. Elle ne doit pas transformer automatiquement PostgreSQL, parsing/index, propositions/admin/auth, forge ou publication en prochaine version uniquement parce que ces domaines sont connus.