From 84c01eb8e819295043c700d22ac0e13146c546a3 Mon Sep 17 00:00:00 2001 From: SinuS Von SifriduS Date: Mon, 28 Sep 2026 16:03:46 +0200 Subject: [PATCH] 0.0.2-alpha.1.fix.1 --- Cargo.toml | 4 +- VERSION | 2 +- deltas/0.0.2/alpha.1.fix.1.md | 204 +++++++++++++ docs/plans/002-V0_0_2_GIT_SYNC_PLAN.md | 371 +++++++++++++---------- docs/validation/001-VALIDATION_MATRIX.md | 26 +- history/0.0.2/alpha.1.fix.1.md | 146 +++++++++ 6 files changed, 593 insertions(+), 160 deletions(-) create mode 100644 deltas/0.0.2/alpha.1.fix.1.md create mode 100644 history/0.0.2/alpha.1.fix.1.md diff --git a/Cargo.toml b/Cargo.toml index b3c3eea..145b891 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -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" diff --git a/VERSION b/VERSION index 4e71452..8070797 100644 --- a/VERSION +++ b/VERSION @@ -1 +1 @@ -0.0.2-alpha.1 +0.0.2-alpha.1.fix.1 diff --git a/deltas/0.0.2/alpha.1.fix.1.md b/deltas/0.0.2/alpha.1.fix.1.md new file mode 100644 index 0000000..52b61d7 --- /dev/null +++ b/deltas/0.0.2/alpha.1.fix.1.md @@ -0,0 +1,204 @@ + + + +# 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] == "" +assert lines[1] == "" + +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. diff --git a/docs/plans/002-V0_0_2_GIT_SYNC_PLAN.md b/docs/plans/002-V0_0_2_GIT_SYNC_PLAN.md index e600275..daecb8f 100644 --- a/docs/plans/002-V0_0_2_GIT_SYNC_PLAN.md +++ b/docs/plans/002-V0_0_2_GIT_SYNC_PLAN.md @@ -1,34 +1,38 @@ - + # 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/.git` ; -- snapshots sous `snapshots//` ; -- 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/.git` ; +- les snapshots vivent sous `snapshots//` ; +- 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. diff --git a/docs/validation/001-VALIDATION_MATRIX.md b/docs/validation/001-VALIDATION_MATRIX.md index 474b20a..6fe2531 100644 --- a/docs/validation/001-VALIDATION_MATRIX.md +++ b/docs/validation/001-VALIDATION_MATRIX.md @@ -1,5 +1,5 @@ - + # 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`. diff --git a/history/0.0.2/alpha.1.fix.1.md b/history/0.0.2/alpha.1.fix.1.md new file mode 100644 index 0000000..42b2e3e --- /dev/null +++ b/history/0.0.2/alpha.1.fix.1.md @@ -0,0 +1,146 @@ + + + +# 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é.