Sasedev/sasedev-knowledge
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

0.0.2-alpha.1.fix.1

Browse Source
This commit is contained in:
SinuS von SifriduS
2026-09-28 16:03:46 +02:00
parent ab1e5fd652
commit 84c01eb8e8
6 changed files with 593 additions and 160 deletions
Download Patch File Download Diff File Expand all files Collapse all files

371
docs/plans/002-V0_0_2_GIT_SYNC_PLAN.md
View File

@@ -1,34 +1,38 @@
<!-- file: docs/plans/002-V0_0_2_GIT_SYNC_PLAN.md -->
<!-- version: 1 -->
<!-- version: 2 -->
# Plan 0.0.2 — Git générique et synchronisation de lecture
## Baseline autoritaire
## Statut et sources
La release part exclusivement de :
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
start prompt prompts/002-V0_0_2_START_PROMPT.md
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 applicable est réévaluée au démarrage et devient :
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
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.
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` corrige uniquement ce cadrage documentaire avant toute implémentation Git.
## Mission
`0.0.2` rend réellement utilisable le chemin de lecture Git générique :
`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
@@ -39,174 +43,229 @@ source locale/remote
-> résultat de synchronisation changed/unchanged
```
La forge reste optionnelle et absente du chemin générique.
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.
## Décisions fermées avant `alpha.1`
## État acquis et questions ouvertes
L'étude [`../studies/004-V0_0_2_GIT_IMPLEMENTATION_STUDY.md`](../studies/004-V0_0_2_GIT_IMPLEMENTATION_STUDY.md) fixe les décisions suivantes :
Décisions déjà matérialisées par le cadrage `alpha.1` et non remises en cause par son `FAIL` documentaire :
- 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.
- 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 :
- forme exacte des types de configuration publics de `knowledge-git-lib` ;
- frontière exacte entre runner de processus interne et API publique ;
- modèle d'erreur précis du backend Git, notamment redaction des arguments sensibles ;
- politique de collision/normalisation de `source-key` et validation des chemins ;
- 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
Restent explicitement hors `0.0.2` :
`0.0.2` n'implémente pas :
- API Gitea/GitHub/GitLab ;
- webhooks forge ;
- webhooks de forge ;
- pull/merge requests ;
- branch/commit/rebase/merge/push de publication ;
- PostgreSQL et migrations ;
- persistance durable de l'état de sync ;
- persistance durable de l'état de synchronisation ;
- parsing final PGR/HOWTO/snippet ;
- moteur de recherche ;
- auth/admin ;
- 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.
## 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.
Les gates suivent [`../validation/001-VALIDATION_MATRIX.md`](../validation/001-VALIDATION_MATRIX.md) et restent proportionnées au scope modifié.
À partir de la première tranche fonctionnelle :
Principes :
```text
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
```
- `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.
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.
## Trajectoire prévisionnelle
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.
### 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 trajectoire normale ne reprend vers `alpha.2` qu'après `PASS` opérateur du fix.
### alpha.2 — contrats minimaux et backend process
Matérialiser le premier backend réel sans encore prétendre couvrir tout le cycle de synchronisation :
- 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
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.
- 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`.
`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é.
## Revue d'horizon
Le workflow demeure :
État courant : **non réalisée**.
```text
delta -> application -> gate opérateur -> history réel -> commit/push -> tranche suivante/fix
```
Aucune version postérieure à `0.0.2` n'est réservée par le présent plan.
Aucun history `PASS` n'est fourni avec ce 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.