sasedev-knowledge/docs/plans/002-V0_0_2_GIT_SYNC_PLAN.md

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 :

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 :

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 :

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/<source-key>.git ;
• les snapshots vivent sous snapshots/<source-key>/<resolved-revision> ;
• 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 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 exclusivement l'hygiène de fin de fichier, la portée de la gate Markdown, le formatage rustfmt et la construction interne de GitSourceKey. Il n'ajoute aucune capacité Git et ne modifie ni les dépendances ni les frontières de la tranche.

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.