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

4
Cargo.toml
View File

@@ -1,5 +1,5 @@
# file: Cargo.toml # file: Cargo.toml
# version: 17 # version: 18
[workspace] [workspace]
resolver = "3" resolver = "3"
@@ -14,7 +14,7 @@ members = [
] ]
[workspace.package] [workspace.package]
version = "0.0.2-alpha.1" version = "0.0.2-alpha.1.fix.1"
edition = "2024" edition = "2024"
publish = false publish = false
repository = "https://git.sasedev.com/Sasedev/sasedev-knowledge" repository = "https://git.sasedev.com/Sasedev/sasedev-knowledge"

2
VERSION
View File

@@ -1 +1 @@
0.0.2-alpha.1 0.0.2-alpha.1.fix.1

204
deltas/0.0.2/alpha.1.fix.1.md Normal file
View File

@@ -0,0 +1,204 @@
<!-- file: deltas/0.0.2/alpha.1.fix.1.md -->
<!-- version: 1 -->
# Delta 0.0.2-alpha.1.fix.1 — restructuration du plan de release
## Base requise
Partir de l'état `0.0.2-alpha.1` après application et commit du history :
```text
deltas/0.0.2/alpha.1.md présent et historique
history/0.0.2/alpha.1.md FAIL
```
Le delta `alpha.1` historique ne doit pas être réécrit.
La version devient :
```text
0.0.2-alpha.1.fix.1
```
## Objet
Corriger uniquement le défaut documentaire observé pendant la revue d'`alpha.1` :
- réaligner le plan `0.0.2` sur le patron de pilotage éprouvé par le plan `0.0.1` ;
- replacer toutes les tranches sous `## Trajectoire prévisionnelle` avec des titres `###` ;
- restaurer un `## Scope` global distinct du `## Hors scope` ;
- ajouter `## État acquis et questions ouvertes` ;
- ajouter `## Déclencheurs de REPLAN` ;
- ajouter `## Revue d'horizon` ;
- ordonner les sections de manière cohérente avec la fondation ;
- ajouter une gate explicite empêchant une nouvelle dérive structurelle du plan.
Le fix ne change ni le choix du backend `git`, ni l'ownership de `knowledge-git-lib`, ni le layout mirror/snapshot, ni le scope fonctionnel prévu de `0.0.2`.
Aucun code fonctionnel n'est ajouté.
## Scope
REPLACE :
```text
VERSION
Cargo.toml
docs/plans/002-V0_0_2_GIT_SYNC_PLAN.md
docs/validation/001-VALIDATION_MATRIX.md
```
ADD :
```text
deltas/0.0.2/alpha.1.fix.1.md
```
DELETE : aucun.
Le history `history/0.0.2/alpha.1.md` doit déjà être présent dans la base mais n'est pas inclus dans ce delta.
Aucun fichier sous `crates/` ou `Web/` n'est modifié.
## Structure attendue du plan
Le plan doit présenter, dans cet ordre :
```text
## Statut et sources
## Mission
## État acquis et questions ouvertes
## Scope
## Hors scope
## Stratégie de validation
## Trajectoire prévisionnelle
### alpha.1 — ...
### alpha.2 — ...
### alpha.3 — ...
### alpha.4 — ...
### beta.1 — ...
### rc.1 — ...
### rel.1 — ...
## Déclencheurs de REPLAN
## Clôture et transition
## Revue d'horizon
```
Les détails des tranches restent des forecasts et ne doivent pas être confondus avec le scope global de la release.
## Gate opérateur
Après application du history `alpha.1`, commit/push de cet état, puis application du présent delta :
```bash
test "$(cat VERSION)" = '0.0.2-alpha.1.fix.1'
grep -F 'version = "0.0.2-alpha.1.fix.1"' Cargo.toml
grep -A2 '^## Statut$' history/0.0.2/alpha.1.md | grep -Fx 'FAIL'
git diff --check
python3 - <<'PY'
from pathlib import Path
import re
path = Path("docs/plans/002-V0_0_2_GIT_SYNC_PLAN.md")
text = path.read_text(encoding="utf-8")
lines = text.splitlines()
assert lines[0] == "<!-- file: docs/plans/002-V0_0_2_GIT_SYNC_PLAN.md -->"
assert lines[1] == "<!-- version: 2 -->"
required_h2 = [
"## Statut et sources",
"## Mission",
"## État acquis et questions ouvertes",
"## Scope",
"## Hors scope",
"## Stratégie de validation",
"## Trajectoire prévisionnelle",
"## Déclencheurs de REPLAN",
"## Clôture et transition",
"## Revue d'horizon",
]
positions = [lines.index(heading) for heading in required_h2]
assert positions == sorted(positions), positions
trajectory_start = lines.index("## Trajectoire prévisionnelle")
replan_start = lines.index("## Déclencheurs de REPLAN")
trajectory = lines[trajectory_start + 1:replan_start]
for phase in ("alpha.1", "alpha.2", "alpha.3", "alpha.4", "beta.1", "rc.1", "rel.1"):
assert any(line.startswith(f"### {phase} — ") for line in trajectory), phase
for line in lines:
assert re.fullmatch(r"## (?:alpha|beta|rc|rel)\\..*", line) is None, line
for phrase in (
"0.0.2-alpha.1` est `FAIL`",
"alpha.1.fix.1",
"REPLAN obligatoire si",
"État courant : **non réalisée**.",
"Aucune version postérieure à `0.0.2` n'est réservée",
):
assert phrase in text, phrase
print("Knowledge 0.0.2-alpha.1.fix.1 plan structure audit: clean")
PY
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 fmt --all -- --check
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
(
cd Web/knowledge-template-lab
npm ci
npm run typecheck
npm run build
)
git diff --name-only -- crates Web
git add -A
git diff --cached --check
git status --short
```
Attendus spécifiques :
- `Knowledge 0.0.2-alpha.1.fix.1 plan structure audit: clean` ;
- `git diff --name-only -- crates Web` vide ;
- aucun `history/0.0.2/alpha.1.fix.1.md` avant réception des résultats opérateur ;
- aucun changement de comportement Git ou Web.
Les warnings Sass déjà observés dans Bootstrap ne constituent pas à eux seuls un `FAIL` si `npm run build` reste `PASS`.
## Revue opérateur complémentaire
Vérifier que :
- le plan se lit d'abord au niveau release (`Mission`, `Scope`, `Hors scope`) puis au niveau tranches sous `Trajectoire prévisionnelle` ;
- les déclencheurs de REPLAN sont suffisamment explicites pour empêcher l'élargissement silencieux d'une tranche ;
- les questions ouvertes restent différées jusqu'à la tranche qui les consomme ;
- la revue d'horizon ne pré-réserve pas de version suivante ;
- aucune décision technique validée par l'étude Git n'a été changée par simple restructuration documentaire.
## Transition
### PASS
Produire `history/0.0.2/alpha.1.fix.1.md`, appliquer ce history, committer/pousser le fix, puis seulement préparer `0.0.2-alpha.2`.
### FAIL / PARTIAL / BLOCKED
Conserver le résultat réel dans `history/0.0.2/alpha.1.fix.1.md` et rester dans le scope `alpha.1` avec `alpha.1.fix.2` si nécessaire.

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

@@ -1,21 +1,23 @@
<!-- file: docs/plans/002-V0_0_2_GIT_SYNC_PLAN.md --> <!-- 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 # 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 ```text
Knowledge tag stable v0.0.1 Knowledge tag stable v0.0.1
Knowledge commit stable 98ec46fe73bd50dacbe6be220650d87dd2000b74 Knowledge commit stable 98ec46fe73bd50dacbe6be220650d87dd2000b74
Knowledge archive SHA-256 1f0b2cfaecee1cbee621abb9c3c95811773ebfc17c374c4369fdc220bcf7d72d Knowledge archive SHA-256 1f0b2cfaecee1cbee621abb9c3c95811773ebfc17c374c4369fdc220bcf7d72d
Knowledge publish report sasedev-knowledge-0.0.1-publish.001-report.md = PASS Knowledge publish report sasedev-knowledge-0.0.1-publish.001-report.md = PASS
start prompt prompts/002-V0_0_2_START_PROMPT.md 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 ```text
PGR stable tag v0.1.3 PGR stable tag v0.1.3
@@ -24,11 +26,13 @@ PGR archive SHA-256 f3a7dffd5fe0fd3542e6b5207fda0b94bca2bd05bd5a54542d0a08d
PGR publish report pgr-0.1.3-publish.001-report.md = PASS 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 ## 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 ```text
source locale/remote source locale/remote
@@ -39,174 +43,229 @@ source locale/remote
-> résultat de synchronisation changed/unchanged -> 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 ; - PGR `v0.1.3` est la baseline applicable au projet existant ;
- `knowledge-git-lib` comme owner de l'implémentation et de la configuration physique Git ; - les changements PGR Java/Maven/Gradle/Android ne deviennent pas applicables à Knowledge ;
- racine d'état explicite hors dépôt source ; - le `DEFER` Tauri reste inchangé ;
- mirrors sous `repositories/<source-key>.git` ; - le backend initial utilise un processus `git` contrôlé via `std::process::Command`, sans shell ;
- snapshots sous `snapshots/<source-key>/<resolved-revision>` ; - `knowledge-git-lib` possède l'implémentation et la configuration physique Git ;
- source locale clonée avec `--mirror --no-local` ; - la racine d'état Git généré est explicite et hors du dépôt source ;
- résolution vers un commit réel avant création de snapshot ; - les mirrors vivent sous `repositories/<source-key>.git` ;
- état root exclusif au processus/backend pour cette release ; - les snapshots vivent sous `snapshots/<source-key>/<resolved-revision>` ;
- dernière révision précédente fournie par l'appelant tant que PostgreSQL reste hors scope ; - une source locale est clonée avec `--mirror --no-local` afin d'éviter une dépendance implicite aux objets du dépôt source ;
- scheduler périodique concret différé, mais le signal `Periodic` conserve la même voie de synchronisation ; - une référence est résolue vers un commit réel avant matérialisation d'un snapshot ;
- aucun backend secondaire `gix`/`git2` tant qu'un besoin observé ne le justifie. - 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 ## Hors scope
Restent explicitement hors `0.0.2` : `0.0.2` n'implémente pas :
- API Gitea/GitHub/GitLab ; - API Gitea/GitHub/GitLab ;
- webhooks forge ; - webhooks de forge ;
- pull/merge requests ; - pull/merge requests ;
- branch/commit/rebase/merge/push de publication ; - branch/commit/rebase/merge/push de publication ;
- PostgreSQL et migrations ; - PostgreSQL et migrations ;
- persistance durable de l'état de sync ; - persistance durable de l'état de synchronisation ;
- parsing final PGR/HOWTO/snippet ; - parsing final PGR/HOWTO/snippet ;
- moteur de recherche ; - moteur de recherche ;
- auth/admin ; - authentification ou administration ;
- worker réseau séparé ; - worker réseau séparé ;
- cache Git partagé simultanément par plusieurs processus ; - 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. - 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 ## 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 - `alpha.1` et son fix utilisent une gate documentaire/gouvernance, avec validation explicite de la structure du plan ;
cargo fmt --all -- --check - 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 ;
python3 -B scripts/audit_rust_test_layout.py crates - les propriétés Git fonctionnelles sont prouvées avec de vrais repositories temporaires locaux, pas seulement avec des mocks du runner ;
python3 -B scripts/audit_rust_blank_lines.py crates - aucun accès Internet ni aucune forge publique ne doit être nécessaire pour prouver le chemin Git générique ;
python3 -B scripts/audit_rust_item_spacing.py crates - les tests de source locale et remote locale doivent distinguer initialisation, refresh, résolution et snapshot ;
python3 -B scripts/audit_rust_module_order.py crates - les erreurs doivent être testées sans exposer de secret ou argument sensible ;
python3 -B scripts/audit_rust_trait_import_blocks.py crates - 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 ;
python3 -B scripts/audit_rust_reexport_blocks.py crates - aucun `PASS` assistant ne remplace le résultat opérateur ;
python3 -B scripts/audit_rust_export_completeness.py --root . --summary-only - un `FAIL`, `PARTIAL` ou `BLOCKED` est historisé avant correction.
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. ## 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 ## 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 Aucune version postérieure à `0.0.2` n'est réservée par le présent plan.
delta -> application -> gate opérateur -> history réel -> commit/push -> tranche suivante/fix
```
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.

26
docs/validation/001-VALIDATION_MATRIX.md
View File

@@ -1,5 +1,5 @@
<!-- file: docs/validation/001-VALIDATION_MATRIX.md --> <!-- file: docs/validation/001-VALIDATION_MATRIX.md -->
<!-- version: 18 --> <!-- version: 19 -->
# Matrice de validation Knowledge # Matrice de validation Knowledge
@@ -519,3 +519,27 @@ git --version
``` ```
`alpha.1` ne prétend pas encore valider `knowledge-git-lib` puisqu'aucune implémentation fonctionnelle n'existe dans cette tranche. La séquence mirror/refresh/resolve/worktree documentée dans l'étude est une prévalidation de conception, pas une gate produit. `alpha.1` ne prétend pas encore valider `knowledge-git-lib` puisqu'aucune implémentation fonctionnelle n'existe dans cette tranche. La séquence mirror/refresh/resolve/worktree documentée dans l'étude est une prévalidation de conception, pas une gate produit.
## Gate de `0.0.2-alpha.1.fix.1`
Le fix reste documentaire et ne change aucune décision technique Git. Il doit prouver :
- `VERSION = 0.0.2-alpha.1.fix.1` et `[workspace.package].version` identique ;
- history `history/0.0.2/alpha.1.md` présent avec statut réel `FAIL` et committé avant application du fix ;
- delta historique `deltas/0.0.2/alpha.1.md` inchangé ;
- `docs/plans/002-V0_0_2_GIT_SYNC_PLAN.md` en version documentaire `2` ;
- présence, dans cet ordre, des sections `Statut et sources`, `Mission`, `État acquis et questions ouvertes`, `Scope`, `Hors scope`, `Stratégie de validation`, `Trajectoire prévisionnelle`, `Déclencheurs de REPLAN`, `Clôture et transition`, `Revue d'horizon` ;
- toutes les tranches prévues `alpha.1`, `alpha.2`, `alpha.3`, `alpha.4`, `beta.1`, `rc.1` et `rel.1` déclarées en titres `###` sous `## Trajectoire prévisionnelle` ;
- aucun titre `## alpha.*`, `## beta.*`, `## rc.*` ou `## rel.*` dans le plan ;
- le `FAIL` documentaire d'`alpha.1` et le rôle correctif d'`alpha.1.fix.1` explicitement documentés ;
- scope global et hors-scope de `0.0.2` distincts du forecast tranche par tranche ;
- déclencheurs de REPLAN couvrant au minimum dérive de responsabilités, forge obligatoire, capacités Git supplémentaires, concurrence de l'état, changement substantiel des contrats et accumulation de fixes ;
- revue d'horizon explicitement non réalisée avant `beta.1`, sans version postérieure à `0.0.2` réservée ;
- aucun changement sous `crates/` ou `Web/` ;
- aucune dépendance, crate, route ou comportement Git ajouté par le fix ;
- headers/liens Markdown, hygiène texte et audits Rust existants propres ;
- Cargo/Clippy/tests workspace et baseline Web toujours propres malgré le bump de version ;
- `Cargo.lock` reste ignoré/non suivi et `package-lock.json` reste versionné ;
- `git diff --cached --check` propre avant commit.
Le `PASS` du fix ferme `alpha.1` et autorise uniquement la préparation de `0.0.2-alpha.2`.

146
history/0.0.2/alpha.1.fix.1.md Normal file
View File

@@ -0,0 +1,146 @@
<!-- file: history/0.0.2/alpha.1.fix.1.md -->
<!-- version: 1 -->
# History 0.0.2-alpha.1.fix.1 — restructuration du plan de release
## Statut
PASS
La gate opérateur de `0.0.2-alpha.1.fix.1` exécutée le `2026-09-28` est propre.
## Baseline opérateur
`alpha.1` `FAIL` a été historisé, committé et poussé avant application du fix :
```text
history/0.0.2/alpha.1.md = FAIL
commit ab1e5fd
message 0.0.2-alpha.1
branch master
push origin/master PASS
```
Le push observé a avancé `origin/master` de `98ec46f` à `ab1e5fd`.
## Version et prérequis
Les contrôles passent :
```text
VERSION 0.0.2-alpha.1.fix.1
Cargo workspace version 0.0.2-alpha.1.fix.1
history alpha.1 FAIL
```
`git diff --check` est propre.
## Structure du plan
L'audit dédié passe :
```text
Knowledge 0.0.2-alpha.1.fix.1 plan structure audit: clean
```
Il confirme notamment :
- l'ordre attendu des sections de niveau `##` ;
- `Scope` et `Hors scope` globaux séparés de la trajectoire ;
- les tranches `alpha.1`, `alpha.2`, `alpha.3`, `alpha.4`, `beta.1`, `rc.1` et `rel.1` sous `## Trajectoire prévisionnelle` avec des titres `###` ;
- l'absence de titres de tranche au niveau `##` ;
- la présence des déclencheurs de `REPLAN` ;
- la revue d'horizon explicitement non réalisée ;
- l'absence de réservation d'une version postérieure à `0.0.2`.
Le fix ne modifie aucune décision technique Git prise par l'étude `004`.
## Rust
Les audits structurels passent :
```text
Rust test-layout audit: clean (7 crate(s))
Rust blank-line audit: clean (18 file(s))
Rust item-spacing audit: clean (18 file(s))
Rust module-order audit: clean (18 file(s))
Rust trait-import-block audit: clean (18 file(s))
Rust re-export-block audit: clean (18 file(s))
Rust export completeness audit: 0 candidate(s) across 7 package(s)
```
Les commandes Cargo passent :
```text
cargo fmt --all -- --check PASS
cargo metadata --format-version 1 --no-deps PASS
cargo check --workspace PASS
cargo clippy --workspace --all-targets --all-features
-- -D warnings PASS
cargo test --workspace --all-targets --all-features PASS
```
Tests observés :
```text
knowledge-domain-lib : 3 PASS
knowledge-git-api : 1 PASS
knowledge-sync-api : 1 PASS
knowledge-web-lib : 4 PASS
launchers : 0 test chacun
```
## Web
Les commandes suivantes passent :
```text
npm ci
npm run typecheck
npm run build
```
npm observe `43` packages audités et `0` vulnérabilité.
Le warning `@parcel/watcher@2.6.0` relatif à `allowScripts` reste observable sans approbation automatique.
Les warnings de dépréciation Sass provenant de Bootstrap restent non bloquants. Vite transforme `63` modules et termine le build avec succès.
## Scope et hygiène Git
Le contrôle suivant reste vide :
```text
git diff --name-only -- crates Web
```
Le fix n'a donc modifié aucun code Rust ni aucun fichier Web.
Après staging, `git diff --cached --check` passe et le staging observé avant ajout du présent history est exactement :
```text
M Cargo.toml
M VERSION
A deltas/0.0.2/alpha.1.fix.1.md
M docs/plans/002-V0_0_2_GIT_SYNC_PLAN.md
M docs/validation/001-VALIDATION_MATRIX.md
```
## Décision
`0.0.2-alpha.1.fix.1` est `PASS`.
Le défaut documentaire d'`alpha.1` est fermé sans modification de son scope fonctionnel ni des décisions Git déjà retenues.
La transition autorisée est :
```text
appliquer ce history
-> git add / diff --cached --check / status
-> commit exact "0.0.2-alpha.1.fix.1"
-> push origin master
-> vérifier le workspace propre
-> préparer seulement ensuite 0.0.2-alpha.2
```
`alpha.2` peut matérialiser le premier backend Git réel dans `knowledge-git-lib`, dans les limites du plan corrigé.