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

Plan 0.0.2 — Git générique et synchronisation de lecture

Baseline autoritaire

La release part exclusivement de :

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
start prompt              prompts/002-V0_0_2_START_PROMPT.md

La baseline PGR applicable est réévaluée au démarrage et devient :

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 une adoption d'un projet existant et active l'owner 230-ADOPTION pour cette migration. Les artifacts historiques 0.0.1 ne sont pas réécrits.

Mission

0.0.2 rend réellement utilisable le chemin de lecture Git générique :

source locale/remote
  -> mirror contrôlé
  -> refresh
  -> résolution vers commit
  -> snapshot/worktree déterministe
  -> résultat de synchronisation changed/unchanged

La forge reste optionnelle et absente du chemin générique.

Décisions fermées avant alpha.1

L'étude ../studies/004-V0_0_2_GIT_IMPLEMENTATION_STUDY.md fixe les décisions suivantes :

• backend initial par processus git contrôlé, sans shell ;
• knowledge-git-lib comme owner de l'implémentation et de la configuration physique Git ;
• racine d'état explicite hors dépôt source ;
• mirrors sous repositories/<source-key>.git ;
• snapshots sous snapshots/<source-key>/<resolved-revision> ;
• source locale clonée avec --mirror --no-local ;
• résolution vers un commit réel avant création de snapshot ;
• état root exclusif au processus/backend pour cette release ;
• dernière révision précédente fournie par l'appelant tant que PostgreSQL reste hors scope ;
• scheduler périodique concret différé, mais le signal Periodic conserve la même voie de synchronisation ;
• aucun backend secondaire gix/git2 tant qu'un besoin observé ne le justifie.

Hors scope

Restent explicitement hors 0.0.2 :

• API Gitea/GitHub/GitLab ;
• webhooks forge ;
• pull/merge requests ;
• branch/commit/rebase/merge/push de publication ;
• PostgreSQL et migrations ;
• persistance durable de l'état de sync ;
• parsing final PGR/HOWTO/snippet ;
• moteur de recherche ;
• auth/admin ;
• worker réseau séparé ;
• cache Git partagé simultanément par plusieurs processus ;
• changement de rendu/UI Web.

alpha.1 — adoption PGR, étude et cadrage

Objectif : fermer les prérequis du prompt de démarrage sans introduire de runtime Git incomplet.

Scope prévu :

• vérifier la stable Knowledge et son rapport post-tag ;
• adopter explicitement PGR v0.1.3 pour le scope applicable via 230-ADOPTION ;
• préserver comme historiques les références PGR v0.1.1 propres à la fondation 0.0.1 ;
• inventorier les contrats domain/git-api/sync-api ;
• comparer processus Git, gix et git2 ;
• décider knowledge-git-lib comme owner concret de configuration/backend ;
• décider le layout des copies Git générées ;
• établir ce plan et la gate de release.

Aucun fichier sous crates/ ou Web/ n'est modifié dans cette tranche.

Statut opérateur : à valider.

alpha.2 — contrats minimaux et backend process

Forecast :

• matérialiser knowledge-git-lib ;
• ajouter uniquement les types/configurations nécessaires à une source locale ou remote et à la racine d'état ;
• encapsuler std::process::Command derrière un runner testable ;
• implémenter l'initialisation/inspection du mirror contrôlé ;
• étendre knowledge-git-api seulement si le besoin de snapshot le requiert déjà à cette tranche ;
• tests unitaires de validation de configuration, chemins, arguments, erreurs et redaction.

La tranche ne doit pas encore créer de dépendance forge ou de scheduler.

Forecast non validé ; peut être scindé si la surface devient trop large.

alpha.3 — refresh, résolution et snapshot réel

Forecast :

• refresh idempotent du mirror ;
• résolution typée d'une référence vers un commit ;
• préparation du worktree détaché adressé par révision ;
• validation d'un snapshot existant avant réutilisation ;
• tests d'intégration Cargo avec repositories temporaires locaux ;
• preuve du changement de révision après un nouveau commit source ;
• preuve qu'aucun accès à une forge publique n'est nécessaire.

Les tests doivent exercer la frontière publique de knowledge-git-lib et non une imitation de commandes.

alpha.4 — cas d'usage de synchronisation

Forecast :

• matérialiser knowledge-app-lib si l'orchestration partagée démontre bien cet ownership ;
• enchaîner refresh, resolve, comparaison avec previous_revision et snapshot ;
• retourner explicitement Unchanged ou Changed avec la révision observée ;
• synchronisation explicite réellement utilisable ;
• vérifier qu'un signal Periodic peut emprunter exactement le même cas d'usage sans matérialiser artificiellement un scheduler ;
• conserver la persistance de dernière révision hors scope.

Si l'orchestration peut rester plus simple sans nouvelle crate tout en évitant la duplication entre launchers, la tranche peut être replanifiée ; aucune crate n'est créée par symétrie.

beta.1 — réconciliation

Forecast :

• réconcilier documentation, contrats et implémentation réellement obtenue ;
• vérifier tous les DEFER ;
• retirer les hypothèses de plan devenues fausses ;
• confirmer absence de régression Web/Actix/Maud/Vite ;
• exécuter les gates Rust complètes ;
• décider, à partir du retour réel, si une release suivante doit être engagée et laquelle ;
• ne pas réserver automatiquement un numéro futur.

Aucune grande fonctionnalité nouvelle ne doit être introduite en beta.

rc.1 — release candidate

Forecast :

• aucune nouvelle fonctionnalité ;
• gate documentaire, Rust, Web et Git complète sur l'état final ;
• aucune dépendance forge/PostgreSQL/auth/admin ;
• candidat stable uniquement si les tests locaux Git réels sont propres et reproductibles.

Un FAIL produit rc.1.fix.1, jamais un PASS fictif.

rel.1 — clôture stable

Forecast :

• promotion mécanique après history RC PASS ;
• version stable 0.0.2 ;
• stabilisation README/ROADMAP/CHANGELOG/index/plan ;
• création d'un prompt de reprise uniquement si la revue d'horizon a réellement engagé une prochaine release ;
• gate pré-tag complète ;
• history rel.1 produit seulement à partir des résultats opérateur ;
• commit stable 0.0.2, push, tag annoté v0.0.2, archive du tag puis rapport publish.001 seulement après PASS.

Stratégie de validation

La validation doit rester proportionnée mais la mission Git exige des preuves réelles, pas uniquement des mocks.

À partir de la première tranche fonctionnelle :

cargo fmt --all -- --check
python3 -B scripts/audit_rust_test_layout.py crates
python3 -B scripts/audit_rust_blank_lines.py crates
python3 -B scripts/audit_rust_item_spacing.py crates
python3 -B scripts/audit_rust_module_order.py crates
python3 -B scripts/audit_rust_trait_import_blocks.py crates
python3 -B scripts/audit_rust_reexport_blocks.py crates
python3 -B scripts/audit_rust_export_completeness.py --root . --summary-only
cargo metadata --format-version 1 --no-deps
cargo check --workspace
cargo clippy --workspace --all-targets --all-features -- -D warnings
cargo test --workspace --all-targets --all-features

Les tests Git utilisent des repositories temporaires locaux. Une preuve live vers une forge ou Internet reste une gate externe séparée et non requise par le chemin générique.

La baseline Web reste non-régression. Les gates npm/build/manifest et les smokes HTTP sont rejoués dans les tranches de stabilisation ou si une modification peut les affecter ; alpha.1 n'altère aucun fichier Rust/Web.

Clôture et transition

Le CHANGELOG ne reçoit pas de catalogue de tranches. Il est consolidé au stade de candidate/stable avec les changements utiles de la release.

ROADMAP ne réserve actuellement aucune version après 0.0.2. La revue d'horizon appartient à beta.1 et doit se baser sur le backend réellement éprouvé.

Le workflow demeure :

delta -> application -> gate opérateur -> history réel -> commit/push -> tranche suivante/fix

Aucun history PASS n'est fourni avec ce plan.