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
# version: 17
# version: 18
[workspace]
resolver = "3"
@@ -14,7 +14,7 @@ members = [
]
[workspace.package]
version = "0.0.2-alpha.1"
version = "0.0.2-alpha.1.fix.1"
edition = "2024"
publish = false
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 -->
<!-- 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 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
@@ -24,11 +26,13 @@ PGR archive SHA-256 f3a7dffd5fe0fd3542e6b5207fda0b94bca2bd05bd5a54542d0a08d
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.

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

@@ -1,5 +1,5 @@
<!-- file: docs/validation/001-VALIDATION_MATRIX.md -->
<!-- version: 18 -->
<!-- version: 19 -->
# 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.
## 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é.