# Plan 0.0.2 — Git générique et synchronisation de lecture ## Statut et sources Plan historique de la stable `0.0.2`, ouverte 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 source PGR explicitement 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. `v0.1.3` constitue une provenance d'adoption, pas une dépendance normative vivante : les futurs démarrages Knowledge doivent partir des règles locales et ne consultent PGR que lorsqu'une nouvelle adoption est explicitement engagée. `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` a été fermée par `alpha.2.fix.2` `PASS`. `alpha.3` a été fermée par `alpha.3.fix.1` `PASS`. `alpha.4` a été fermée par `alpha.4.fix.1` `PASS`, terminant l'adoption PGR comme migration ponctuelle. `alpha.5` est `PASS` et ferme le scope fonctionnel alpha avec `knowledge-app-lib` et le cas d'usage partagé `Changed` / `Unchanged`. `beta.1` est `PARTIAL`; `beta.1.fix.1` est `FAIL`; `beta.1.fix.2` est `PASS` et ferme la stabilisation beta. `rc.1` est `PASS` et valide la candidate complète. `rel.1` est la tranche courante de promotion mécanique pré-tag vers la stable `0.0.2`. ## 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. Elle doit également terminer l'adoption PGR engagée au démarrage en rendant Knowledge autonome : règles applicables adaptées/possédées localement, PGR conservé comme provenance et non chargé automatiquement à chaque reprise. ## É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 source d'adoption explicitement retenue pour `0.0.2`, tandis que la baseline normative courante doit être possédée localement par Knowledge ; - 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. - `knowledge-app-lib` est matérialisée en `alpha.5` comme owner du cas d'usage partagé refresh / résolution / comparaison / snapshot. 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 ; - 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 initial : **FAIL**. `alpha.2.fix.1` corrige l'hygiène de fin de fichier, la portée de la gate Markdown, le formatage rustfmt et la construction interne de `GitSourceKey`, mais sa gate reste **FAIL** sur une unique violation `clippy::implicit_return` dans une closure de test. `alpha.2.fix.2` corrige exclusivement ce retour implicite, sans modification du backend, de l'API, des dépendances ou du comportement Git. Sa gate opérateur est **PASS** et ferme `alpha.2`. 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 Statut initial : **FAIL**. `alpha.3.fix.1` : **PASS**. Tranche fermée. La tranche a matérialisé et prouvé sur de vrais repositories temporaires : - enregistrement explicite des configurations physiques dans `GitBackend` ; - implémentation réelle de `knowledge-git-api::GitRepository` par `knowledge-git-lib` ; - extension minimale du contrat avec `GitSnapshot` / `prepare_snapshot` ; - refresh idempotent du mirror via `remote update --prune` ; - résolution typée avec `rev-parse --verify --end-of-options ...^{commit}` ; - worktree/snapshot détaché adressé par révision ; - validation du `HEAD` et de l'état propre avant réutilisation ; - changement de révision après ajout d'un commit source ; - rejet d'une référence invalide et d'un snapshot sale. Les tests fonctionnels passent, mais la gate complète échoue sur trois défauts de conformité : ligne vide terminale dans la matrice, formatage rustfmt d'un test `knowledge-git-api` et documentation de crate manquante dans le test d'intégration `git_read_path`. `alpha.3.fix.1` corrige exclusivement ces défauts techniques et enregistre le présent REPLAN. Il ne modifie pas le comportement Git déjà prouvé. La revue de tranche a déclenché un REPLAN explicite : l'autonomie normative après adoption PGR et l'organisation interne des crates doivent être traitées avant l'orchestration de synchronisation. ### alpha.4 — autonomie normative et structure interne des crates Statut opérateur initial : **FAIL**. `alpha.4.fix.1` : **PASS**. Tranche fermée. La matérialisation normative, les audits locaux, les façades crate-root, rustfmt et les métadonnées sont propres. La compilation échoue uniquement parce que `GitReference` et `GitRevision`, déplacés dans leurs modules propriétaires, tentent encore de construire leurs tuple structs privés via les réexports crate-root. `alpha.4.fix.1` corrige exclusivement ces deux constructions avec `Self(...)`, sans modifier l'API publique, les owners locaux, les templates, les audits ni les comportements Git/sync. Finaliser l'adoption PGR `v0.1.3` comme migration ponctuelle et rendre Knowledge autonome pour les sessions suivantes. Scope : - matérialiser six owners locaux : gouvernance, workflow, documentation, validation, Rust/Cargo et frontend Web, avec les contrats opérationnels réellement nécessaires (lifecycle/versioning, fixes/REPLAN, delta/history/handoff, rôles documentaires et catégories de preuve) ; - produire `docs/architecture/003-PGR_ADOPTION_MAP.md` avec le mapping `ADOPT / KEEP-LOCAL / OVERRIDE / DEFER` et les owners Knowledge réels ; - conserver PGR `v0.1.3` uniquement comme provenance de l'adoption ; - fournir des templates locaux de nouvelle session, plan de release, handoff opérateur et crate bibliothèque ; - adopter localement les audits Markdown headers/liens/tables utiles au dépôt ; - ajouter un audit Knowledge garantissant que les `src/lib.rs` des crates bibliothèque restent des façades ; - réorganiser `knowledge-git-api` en modules `reference`, `revision`, `snapshot`, `repository` sans modifier son API crate-root ; - réorganiser `knowledge-sync-api` en modules `signal` et `event_source` sans modifier son API crate-root ; - auditer les autres crates et ne pas les découper davantage lorsqu'elles respectent déjà le contrat de façade ; - conserver inchangée la sémantique Git prouvée par `alpha.3`. Hors scope : - aucune consultation d'une version PGR postérieure à `v0.1.3` ; - aucune copie mécanique de tous les owners/skeletons/templates PGR ; - aucun changement de comportement Git, forge, PostgreSQL, auth/admin ou Web runtime ; - aucun `knowledge-app-lib` ni cas d'usage `Changed` / `Unchanged` avant `alpha.5`. Gate attendue : audits Markdown locaux, audit d'autonomie, audits Rust incluant la façade crate-root, rustfmt/check/Clippy, tests ciblés des deux crates `-api` et `knowledge-git-lib`, puis tests workspace. `Web/` doit rester sans diff. ### alpha.5 — cas d'usage de synchronisation La matérialisation de l'orchestration confirme un ownership application partagé : `knowledge-app-lib` devient justifiée et doit éviter que les trois launchers recomposent chacun le même flux. Scope : - créer `knowledge-app-lib` comme façade bibliothèque mince de cas d'usage partagés ; - enchaîner refresh, résolution, comparaison avec `previous_revision` et snapshot ; - retourner explicitement `RepositorySyncOutcome::Unchanged` ou `RepositorySyncOutcome::Changed` avec la révision observée ; - préparer le snapshot uniquement lorsque la révision diffère de celle fournie par l'appelant ; - consommer `RepositorySyncSignal` sans donner de sémantique autoritaire à sa cause ; - prouver qu'une cause `Periodic` emprunte exactement le même cas d'usage qu'une cause explicite sans matérialiser de scheduler ; - garder la persistance de dernière révision, PostgreSQL, worker réseau, forge et publication Git hors scope. La gate Rust applique désormais explicitement `cargo fmt --all`, puis `cargo fmt --all -- --check`, avant les audits du code Rust. Cette normalisation précède les contrôles structurels afin que les audits observent l'état réellement formaté. ### beta.1 — réconciliation et revue d'horizon Statut opérateur : **PARTIAL**. La tranche n'ajoute aucune grande fonctionnalité. La réconciliation documentaire, les audits Rust/Git, la baseline Web, le manifest Vite et la revue d'horizon passent. La gate générée a toutefois omis les trois smokes HTTP alors que la stratégie de validation du présent plan les exige pendant la stabilisation. `beta.1.fix.1` corrige le contrat de smoke et acquiert effectivement les trois smokes HTTP, mais reste `FAIL` parce que son audit Python de stabilisation contient une chaîne mal quotée et que `001-VALIDATION_MATRIX.md` introduit une ligne vide supplémentaire à EOF. `beta.1.fix.2` corrige uniquement ces deux défauts de gate, rend durable la règle d'un unique LF terminal et retire les modifications persistantes d'options shell des gates interactives. Aucun code produit, contrat métier, package ou scope fonctionnel n'est modifié. La réconciliation doit : - inventorier les neuf packages et contrats effectivement matérialisés ; - confirmer `knowledge-git-lib` comme backend Git et `knowledge-app-lib` comme owner du cas d'usage partagé ; - vérifier les `DEFER` et hors-scope encore valides ; - corriger les formulations durables héritées de `0.0.1` qui utilisent encore des numéros d'alpha non qualifiés ; - confirmer l'absence de dépendance forge/PostgreSQL/auth/admin et d'écriture Git ; - rejouer la gate Rust/Git et la non-régression Web utile ; - produire une étude de réconciliation durable ; - réaliser la revue d'horizon sans réserver de numéro futur par défaut. Résultat de revue proposé et soumis à la gate beta : aucune prochaine mission n'est suffisamment décidée pour engager une version postérieure à `0.0.2`. Les domaines futurs restent non numérotés. ### rc.1 — candidate stable Statut opérateur : **PASS**. `beta.1.fix.2` est `PASS`. Le scope fonctionnel de `0.0.2` est gelé et la candidate doit exécuter la gate complète de release sans introduire de changement produit. 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 réévaluation PGR explicitement engagée révèle un changement substantiel d'un contrat déjà adopté par Knowledge ; - 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 et fondé sur la baseline normative locale Knowledge ; aucune consultation PGR automatique n'y est ajouté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 : **réalisée ; stabilisation beta et candidate `rc.1` fermées `PASS`; `rel.1` en promotion stable pré-tag**. Résultat : aucune version postérieure à `0.0.2` n'est réservée. Les domaines futurs restent non numérotés parce qu'aucune mission suivante ne possède encore un scope et un ordre suffisamment décidés. Les besoins différés confirmés incluent notamment : PostgreSQL/migrations, parsing/index, propositions/admin/auth, adapter de forge, écriture/publication Git, scheduler concret, submodules/LFS, politique de rétention des snapshots et partage multi-processus de la racine Git. Une future mission pourra être engagée depuis la stable `0.0.2` lorsqu'un besoin produit ou d'exploitation choisira explicitement l'un de ces axes. Elle devra repartir de la baseline locale Knowledge et ne consultera PGR que si une réévaluation PGR est elle-même explicitement dans le scope.