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 source PGR explicitement 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. 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 démontre le chemin Git réel mais sa gate est FAIL sur hygiène/formatage/documentation de test ; alpha.3.fix.1 corrige ces défauts et enregistre le REPLAN décrit ci-dessous.

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. 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/<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 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 opérateur initial : FAIL.

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

Finaliser l'adoption PGR v0.1.3 comme migration ponctuelle, sans transformer PGR en dépendance documentaire permanente :

• inventorier les owners/contrats PGR réellement retenus par Knowledge ;
• produire un mapping durable ADOPT / KEEP-LOCAL / OVERRIDE / DEFER fondé sur la baseline locale actuelle ;
• pour chaque ADOPT, identifier l'owner local qui possède effectivement le contrat ;
• adapter et matérialiser localement uniquement les règles, templates/configurations et audits nécessaires au développement de Knowledge ;
• ne pas recopier mécaniquement l'arborescence ou les textes PGR lorsque RULES.md ou un owner local plus adapté suffit ;
• faire de PGR v0.1.3 une provenance d'adoption figée, et non une « baseline courante » à recharger ;
• établir que les futurs prompts de démarrage partent de la baseline Knowledge locale et ne demandent une consultation PGR que si une réévaluation PGR est explicitement dans leur scope ;
• vérifier que les règles de gouvernance, workflow, documentation, validation, Rust/Cargo et Web réellement nécessaires sont compréhensibles et applicables depuis le dépôt Knowledge seul.

La même tranche audite l'organisation interne des crates :

• lib.rs reste la façade publique/documentation de crate ;
• les types, traits et implémentations sont déplacés vers des modules nommés selon leur responsabilité lorsqu'ils forment une responsabilité distincte ;
• les crates knowledge-git-api et knowledge-sync-api sont examinées en priorité ;
• api.rs n'est pas imposé comme nom générique : préférer des modules tels que reference, revision, snapshot, repository, signal ou autre ownership réel ;
• les petites crates/fichiers ne sont pas découpés artificiellement uniquement pour satisfaire une forme ;
• les réexports publics restent centralisés à la crate root et les consommateurs externes continuent d'utiliser la façade stable.

Cette tranche ne change pas la sémantique Git prouvée par alpha.3 et ne matérialise pas encore le cas d'usage Changed / Unchanged.

alpha.5 — 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 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 : 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.