From b9508b0228cb575b31a5838cd18a52cc5cac7ab6 Mon Sep 17 00:00:00 2001 From: SinuS Von SifriduS Date: Mon, 28 Sep 2026 22:30:15 +0200 Subject: [PATCH] 0.0.2-alpha.3.fix.1 --- Cargo.toml | 4 +- README.md | 6 +- RULES.md | 28 +- VERSION | 2 +- crates/knowledge-git-api/unit_tests/lib.rs | 7 +- .../knowledge-git-lib/tests/git_read_path.rs | 4 +- deltas/0.0.2/alpha.3.fix.1.md | 262 ++++++++++++++++++ docs/architecture/001-PROJECT_PROFILE.md | 8 +- docs/plans/002-V0_0_2_GIT_SYNC_PLAN.md | 69 +++-- docs/validation/001-VALIDATION_MATRIX.md | 25 +- history/0.0.2/alpha.3.fix.1.md | 173 ++++++++++++ 11 files changed, 538 insertions(+), 50 deletions(-) create mode 100644 deltas/0.0.2/alpha.3.fix.1.md create mode 100644 history/0.0.2/alpha.3.fix.1.md diff --git a/Cargo.toml b/Cargo.toml index 064f445..6bfad32 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -1,5 +1,5 @@ # file: Cargo.toml -# version: 22 +# version: 23 [workspace] resolver = "3" @@ -15,7 +15,7 @@ members = [ ] [workspace.package] -version = "0.0.2-alpha.3" +version = "0.0.2-alpha.3.fix.1" edition = "2024" publish = false repository = "https://git.sasedev.com/Sasedev/sasedev-knowledge" diff --git a/README.md b/README.md index f6bfe03..c930486 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,5 @@ - + # SaseDev Knowledge @@ -11,9 +11,9 @@ Le dépôt applicatif retenu est `sasedev-knowledge`. Le nom court du projet et La version courante est définie par [`VERSION`](VERSION). -`0.0.1` est la première stable de fondation de SaseDev Knowledge. `0.0.2-alpha.3` complète maintenant le chemin Git générique de lecture après fermeture de `alpha.2` par `alpha.2.fix.2` `PASS`. +`0.0.1` est la première stable de fondation de SaseDev Knowledge. `0.0.2-alpha.3` a démontré fonctionnellement le chemin Git générique de lecture, mais sa gate est `FAIL` sur hygiène/formatage/documentation de test. `0.0.2-alpha.3.fix.1` corrige ces défauts et enregistre un REPLAN de la release. -`knowledge-git-lib` implémente désormais `knowledge-git-api::GitRepository` pour des sources physiques enregistrées : mirror contrôlé, refresh avec pruning, résolution d'une référence vers un commit et snapshot/worktree détaché adressé par révision. Les preuves fonctionnelles reposent sur des repositories Git temporaires locaux et n'exigent aucune API de forge. +`knowledge-git-lib` implémente désormais `knowledge-git-api::GitRepository` pour des sources physiques enregistrées : mirror contrôlé, refresh avec pruning, résolution d'une référence vers un commit et snapshot/worktree détaché adressé par révision. Les preuves fonctionnelles reposent sur des repositories Git temporaires locaux et n'exigent aucune API de forge. Avant le cas d'usage de synchronisation, `alpha.4` rendra la gouvernance Knowledge autonome après l'adoption PGR et auditera l'organisation interne des crates ; l'ancien scope de synchronisation devient `alpha.5`. ## Topologie produit de fondation diff --git a/RULES.md b/RULES.md index 558ab8b..dddf634 100644 --- a/RULES.md +++ b/RULES.md @@ -1,5 +1,5 @@ - + # Règles SaseDev Knowledge @@ -9,13 +9,11 @@ Ce document gouverne le workspace applicatif `sasedev-knowledge` et sert de poin Le contenu éditorial publié par PGR, HOWTOs et snippets vit dans des dépôts Git distincts et conserve sa propre gouvernance. Les règles de ce dépôt ne transforment pas ces contenus en sous-modules normatifs de l'application. -## Baseline PGR +## Provenance PGR et autonomie normative La fondation stable `0.0.1` a été cadrée à partir de PGR `v0.1.1`. Cette référence reste historique et n'est pas réécrite rétroactivement. -À partir de `0.0.2-alpha.1`, Knowledge adopte comme baseline PGR courante la stable `v0.1.3`, vérifiée par `pgr-0.1.3-publish.001-report.md = PASS`. - -Identité de la baseline PGR courante : +Au démarrage explicite de `0.0.2`, Knowledge a réévalué PGR et retenu `v0.1.3` comme **source d'adoption** vérifiée par `pgr-0.1.3-publish.001-report.md = PASS` : ```text tag v0.1.3 @@ -23,9 +21,13 @@ commit fe80dbbb737390a7ea99df27d979bd59ccfb86e3 SHA-256 f3a7dffd5fe0fd3542e6b5207fda0b94bca2bd05bd5a54542d0a08d635a5d6ee ``` -La migration depuis `v0.1.1` suit `230-ADOPTION` : seuls les owners réellement applicables sont adoptés, les choix locaux compatibles sont conservés et l'historique `0.0.1` n'est pas réécrit pour simuler une conformité rétroactive. +Cette identité documente la provenance de l'adoption ; elle n'est pas une dépendance normative vivante. Une migration réussie doit laisser Knowledge autonome : les règles réellement retenues sont sélectionnées, adaptées et possédées localement par Knowledge. PGR n'est ni une dépendance runtime/build, ni un référentiel à charger automatiquement au début d'une version, d'une session ou d'une tranche. -Les contrats PGR adoptés sont instanciés localement dans ce dépôt. PGR n'est pas une dépendance runtime ou build de Knowledge. +Le prompt `prompts/002-V0_0_2_START_PROMPT.md` reste historique : sa vérification de la stable PGR courante appartenait à l'adoption explicitement engagée au démarrage de `0.0.2`. Ce comportement ne devient pas le modèle des futurs prompts Knowledge. + +Une future version de PGR n'a aucun effet automatique sur Knowledge. Elle n'est consultée que lorsqu'une réévaluation/adoption PGR est explicitement inscrite au scope d'une tranche ou d'une release. Cette réévaluation doit alors comparer la baseline locale Knowledge avec la version PGR choisie, classifier les décisions `ADOPT / KEEP-LOCAL / OVERRIDE / DEFER`, puis matérialiser localement les décisions retenues avant de refermer l'adoption. + +`0.0.2-alpha.4` est la tranche de réconciliation qui doit terminer l'autonomie normative de l'adoption `v0.1.3` : inventorier les owners réellement retenus, vérifier où chaque contrat nécessaire est possédé localement, adapter les règles/templates/audits manquants sans recopier mécaniquement l'arborescence PGR et supprimer les références externes nécessaires à la compréhension courante du projet. ## Owners PGR applicables @@ -47,7 +49,7 @@ La fondation retient les owners suivants dans leur scope réel : 700 famille framework pour les frameworks réellement utilisés ``` -Les skeletons `001-PROJECT_GOVERNANCE_FOUNDATION`, `002-RUST_CARGO_WORKSPACE` et `003-WEB_FRONTEND` restent les références de composition de l'état existant. L'adoption PGR `v0.1.3` ne les réapplique pas mécaniquement sur le projet déjà matérialisé. +Les skeletons `001-PROJECT_GOVERNANCE_FOUNDATION`, `002-RUST_CARGO_WORKSPACE` et `003-WEB_FRONTEND` documentent la provenance de composition de l'état existant. Ils ne sont pas des dépendances documentaires à relire pour développer Knowledge. `alpha.4` doit vérifier que les responsabilités effectivement retenues sont possédées localement avant de considérer l'adoption `v0.1.3` comme complètement matérialisée. Le profil `710-TAURI` reste `DEFER` / non applicable au produit Web actuel. Aucun skeleton Tauri n'est adopté. @@ -55,7 +57,7 @@ Les owners Java/Maven/Gradle réorganisés en PGR `0.1.2`, le profil Android ré ## Priorité et décisions locales -Les obligations PGR réellement adoptées priment sur une préférence locale de Knowledge dans le même scope. +Les contrats issus de PGR et explicitement adoptés par Knowledge deviennent des règles **locales Knowledge** après adaptation/matérialisation. C'est leur formulation locale qui gouverne ensuite le projet ; PGR conserve uniquement la provenance de la décision. Les choix propres au produit restent locaux lorsqu'aucun owner PGR plus spécifique ne les impose. C'est notamment le cas de l'architecture Git/forge/PostgreSQL, du choix Actix Web/Maud, de Bootstrap, de la topologie à trois applications Web et de la topologie des dépôts de contenu. @@ -67,7 +69,7 @@ Les décisions différées sont explicites dans [`docs/architecture/001-PROJECT_ `VERSION` est le repère canonique simple de la release unit applicative. -Knowledge adopte le workflow PGR : +Knowledge possède localement le workflow suivant, issu de l'adoption PGR : ```text delta -> application -> gate opérateur -> history observé -> application du history -> commit/push -> delta suivant @@ -101,7 +103,7 @@ knowledge-howtos-server knowledge-snippets-server ``` -Chaque package exécutable reste une couche de composition mince conformément au profil Rust/Cargo PGR. La logique partagée appartient aux crates `-lib` appropriées et ne doit pas être dupliquée entre les trois `main.rs`. +Chaque package exécutable reste une couche de composition mince conformément au contrat Rust/Cargo retenu localement par Knowledge. La logique partagée appartient aux crates `-lib` appropriées et ne doit pas être dupliquée entre les trois `main.rs`. Les trois applications peuvent être déployées, redémarrées et dimensionnées séparément. Cette séparation de launchers ne constitue pas une autorisation à fragmenter arbitrairement le domaine en microservices. @@ -245,9 +247,9 @@ Les responsabilités candidates sont documentées dans l'architecture. Une crate `alpha.3` matérialise ainsi `knowledge-git-api` pour la frontière `GitRepository` et `knowledge-sync-api` pour la frontière `RepositoryEventSource`. Ces crates restent passives, sans runtime ni logging propre, et dépendent seulement des types de domaine nécessaires. Les implémentations Git, hooks, polling, webhooks ou forge restent hors de ces crates de contrat. -Le profil Rust strict PGR s'applique aux crates matérialisées, notamment Rust 2024, `unsafe` interdit par défaut, lints stricts, exports publics maîtrisés et chemins intra-crate explicites via la façade crate-root. +Le contrat Rust strict retenu par Knowledge s'applique aux crates matérialisées, notamment Rust 2024, `unsafe` interdit par défaut, lints stricts, exports publics maîtrisés et chemins intra-crate explicites via la façade crate-root. `alpha.4` doit vérifier que l'ensemble des obligations réellement nécessaires de ce contrat est possédé localement sans devoir relire PGR. -Les audits read-only PGR sélectionnés avec les premiers contrats publics sont `audit_rust_blank_lines.py`, `audit_rust_item_spacing.py`, `audit_rust_module_order.py`, `audit_rust_trait_import_blocks.py`, `audit_rust_reexport_blocks.py` et `audit_rust_export_completeness.py`. L'audit `const` n'est pas sélectionné globalement : il reste opt-in par fichier lorsqu'un ordre mécanique de constantes est réellement approprié. +Les audits read-only sélectionnés et possédés localement avec les premiers contrats publics sont `audit_rust_blank_lines.py`, `audit_rust_item_spacing.py`, `audit_rust_module_order.py`, `audit_rust_trait_import_blocks.py`, `audit_rust_reexport_blocks.py` et `audit_rust_export_completeness.py`. L'audit `const` n'est pas sélectionné globalement : il reste opt-in par fichier lorsqu'un ordre mécanique de constantes est réellement approprié. ## Secrets et configuration locale diff --git a/VERSION b/VERSION index 5f57b5f..a23ee4b 100644 --- a/VERSION +++ b/VERSION @@ -1 +1 @@ -0.0.2-alpha.3 +0.0.2-alpha.3.fix.1 diff --git a/crates/knowledge-git-api/unit_tests/lib.rs b/crates/knowledge-git-api/unit_tests/lib.rs index ee995db..e088e9a 100644 --- a/crates/knowledge-git-api/unit_tests/lib.rs +++ b/crates/knowledge-git-api/unit_tests/lib.rs @@ -1,5 +1,5 @@ // file: crates/knowledge-git-api/unit_tests/lib.rs -// version: 2 +// version: 3 #[derive(Debug, Eq, PartialEq)] struct FakeGitError; @@ -40,9 +40,6 @@ fn generic_repository_contract_does_not_require_a_forge() { Err(_) => return, }; let snapshot_result = crate::GitRepository::prepare_snapshot(&repository, &source_id, &revision); - assert_eq!( - snapshot_result, - Ok(crate::GitSnapshot::new(revision, std::path::PathBuf::from("/controlled/snapshot"))) - ); + assert_eq!(snapshot_result, Ok(crate::GitSnapshot::new(revision, std::path::PathBuf::from("/controlled/snapshot")))); return; } diff --git a/crates/knowledge-git-lib/tests/git_read_path.rs b/crates/knowledge-git-lib/tests/git_read_path.rs index 6a554e7..b4a8ea9 100644 --- a/crates/knowledge-git-lib/tests/git_read_path.rs +++ b/crates/knowledge-git-lib/tests/git_read_path.rs @@ -1,5 +1,7 @@ // file: crates/knowledge-git-lib/tests/git_read_path.rs -// version: 1 +// version: 2 + +//! Integration tests for the real generic Git read path using local temporary repositories. fn test_root(label: &str) -> std::path::PathBuf { let nanos_result = std::time::SystemTime::now().duration_since(std::time::UNIX_EPOCH); diff --git a/deltas/0.0.2/alpha.3.fix.1.md b/deltas/0.0.2/alpha.3.fix.1.md new file mode 100644 index 0000000..b2739a2 --- /dev/null +++ b/deltas/0.0.2/alpha.3.fix.1.md @@ -0,0 +1,262 @@ + + + +# Delta 0.0.2-alpha.3.fix.1 — conformité alpha.3 et REPLAN d'autonomie Knowledge + +## Base requise + +Partir de `0.0.2-alpha.3` après application de son history réel `FAIL`, commit et push : + +```text +deltas/0.0.2/alpha.3.md présent et historique +history/0.0.2/alpha.3.md FAIL +``` + +Les deltas, histories et prompts antérieurs ne doivent pas être réécrits. + +La version devient : + +```text +0.0.2-alpha.3.fix.1 +``` + +## Causes du fix + +La gate opérateur d'`alpha.3` a confirmé le comportement Git réel mais a relevé trois défauts bloquants : + +1. `docs/validation/001-VALIDATION_MATRIX.md` possède une ligne vide terminale rejetée par `git diff --check` ; +2. `crates/knowledge-git-api/unit_tests/lib.rs` n'est pas au format exact attendu par rustfmt ; +3. `crates/knowledge-git-lib/tests/git_read_path.rs` ne possède pas de documentation de crate et échoue sous `-D missing-docs` lors de Clippy. + +La revue a aussi déclenché un REPLAN explicite : avant d'ajouter l'orchestration `Changed` / `Unchanged`, Knowledge doit terminer son autonomie normative après l'adoption PGR et auditer l'organisation interne de ses crates. + +## Scope technique du fix + +Le correctif technique est volontairement minimal : + +- retirer la ligne vide terminale fautive de la matrice ; +- appliquer le formatage rustfmt attendu au test de `knowledge-git-api` ; +- ajouter une documentation de crate au test d'intégration `git_read_path` ; +- conserver inchangés le backend Git, ses erreurs, son API publique et les deux scénarios d'intégration réels. + +Le comportement prouvé en `alpha.3` reste donc : mirror -> refresh -> résolution -> snapshot/worktree détaché -> validation/réutilisation. + +## REPLAN de `0.0.2` + +Le plan `docs/plans/002-V0_0_2_GIT_SYNC_PLAN.md` passe en version documentaire `7` et adopte la trajectoire suivante : + +```text +alpha.3 refresh / resolve / snapshot FAIL initial -> fix.1 +alpha.4 autonomie normative + structure crates +alpha.5 cas d'usage Changed / Unchanged +beta.1 réconciliation + revue d'horizon +rc.1 candidate stable +rel.1 fermeture stable +``` + +L'ancienne tranche `alpha.4` de synchronisation devient `alpha.5` sans changement de mission fonctionnelle. + +## Autonomie PGR enregistrée + +`RULES.md` et le profil projet distinguent désormais explicitement : + +```text +PGR v0.1.3 = provenance de l'adoption engagée pendant 0.0.2 +Knowledge = baseline normative locale après matérialisation +``` + +Les règles sont : + +- ne pas charger/rechercher automatiquement PGR au début de chaque version, session ou tranche ; +- ne pas faire dépendre un futur prompt de démarrage Knowledge d'une « stable PGR courante » ; +- consulter une nouvelle version PGR uniquement lorsqu'une réévaluation/adoption PGR est explicitement inscrite au scope ; +- lors d'une telle réévaluation, comparer la baseline locale puis classifier `ADOPT / KEEP-LOCAL / OVERRIDE / DEFER` ; +- matérialiser/adopter localement uniquement les règles, templates/configurations et audits réellement nécessaires ; +- ne pas recopier mécaniquement l'arborescence PGR lorsqu'un owner Knowledge plus adapté suffit. + +Le prompt `prompts/002-V0_0_2_START_PROMPT.md` reste historique et inchangé : sa consultation de PGR appartenait précisément à l'adoption explicitement engagée au démarrage de `0.0.2`. + +## Scope futur `alpha.4` + +`alpha.4` doit : + +- inventorier les owners/contrats PGR `v0.1.3` réellement retenus par Knowledge ; +- produire le mapping durable de leurs décisions et owners locaux ; +- vérifier que gouvernance, workflow, documentation, validation, Rust/Cargo et Web nécessaires sont compréhensibles depuis Knowledge seul ; +- adapter/matérialiser les règles, templates/configurations et audits manquants ; +- supprimer toute dépendance documentaire obligatoire vers PGR pour le développement courant ; +- auditer toutes les crates pour garder `lib.rs` comme façade/documentation/réexports et déplacer les définitions dans des modules possédant une responsabilité claire lorsque cela est justifié ; +- examiner en priorité `knowledge-git-api` et `knowledge-sync-api` ; +- ne pas imposer un générique `api.rs` si des modules `reference`, `revision`, `snapshot`, `repository`, `signal`, etc. expriment mieux l'ownership ; +- ne pas découper artificiellement une petite crate sans bénéfice réel. + +Cette tranche sera livrée séparément après `PASS` du présent fix. + +## Hors scope du fix + +`alpha.3.fix.1` ne doit pas : + +- créer `docs/rules/` ou copier des owners PGR détaillés ; +- refactorer maintenant `knowledge-git-api` ou `knowledge-sync-api` en modules supplémentaires ; +- modifier `crates/knowledge-git-api/src/`, `crates/knowledge-git-lib/src/` ou `crates/knowledge-sync-api/` ; +- modifier le comportement Git d'`alpha.3` ; +- introduire `knowledge-app-lib`, scheduler, PostgreSQL ou adapter de forge ; +- modifier `Web/` ; +- préparer `alpha.4` avant `PASS` opérateur du fix. + +## Gate opérateur + +Exécuter depuis la racine du workspace après application du delta : + +```bash +test "$(cat VERSION)" = '0.0.2-alpha.3.fix.1' +grep -F 'version = "0.0.2-alpha.3.fix.1"' Cargo.toml +grep -A2 '^## Statut$' history/0.0.2/alpha.3.md | grep -Fx 'FAIL' + +git diff --check + +python3 - <<'PY' +from pathlib import Path +import re +import tomllib + +root = tomllib.loads(Path("Cargo.toml").read_text(encoding="utf-8")) +assert len(root["workspace"]["members"]) == 8 + +plan_path = Path("docs/plans/002-V0_0_2_GIT_SYNC_PLAN.md") +plan = plan_path.read_text(encoding="utf-8") +plan_lines = plan.splitlines() +assert plan_lines[1] == "" + +trajectory_start = plan_lines.index("## Trajectoire prévisionnelle") +replan_start = plan_lines.index("## Déclencheurs de REPLAN") +trajectory = plan_lines[trajectory_start + 1:replan_start] + +for heading in ( + "### alpha.3 — refresh, résolution et snapshot réel", + "### alpha.4 — autonomie normative et structure interne des crates", + "### alpha.5 — cas d'usage de synchronisation", + "### beta.1 — réconciliation et revue d'horizon", + "### rc.1 — candidate stable", + "### rel.1 — fermeture stable", +): + assert heading in trajectory, heading + +for phrase in ( + "Statut opérateur initial : **FAIL**.", + "`v0.1.3` constitue une provenance d'adoption", + "une réévaluation PGR explicitement engagée", + "aucune consultation PGR automatique", +): + assert phrase in plan, phrase + +assert "une nouvelle stable PGR modifie un owner" not in plan + +rules = Path("RULES.md").read_text(encoding="utf-8") +for phrase in ( + "## Provenance PGR et autonomie normative", + "source d'adoption", + "n'est pas une dépendance normative vivante", + "ni un référentiel à charger automatiquement", + "Une future version de PGR n'a aucun effet automatique sur Knowledge", +): + assert phrase in rules, phrase +assert "baseline PGR courante" not in rules + +profile = Path("docs/architecture/001-PROJECT_PROFILE.md").read_text(encoding="utf-8") +assert "source d'adoption" in profile +assert "provenance d'adoption figée" in profile +assert "ne consulte pas automatiquement le PGR courant" in profile + +git_api_test = Path("crates/knowledge-git-api/unit_tests/lib.rs").read_text(encoding="utf-8") +assert 'assert_eq!(snapshot_result, Ok(crate::GitSnapshot::new(revision, std::path::PathBuf::from("/controlled/snapshot"))));' in git_api_test + +integration = Path("crates/knowledge-git-lib/tests/git_read_path.rs").read_text(encoding="utf-8") +assert "//! Integration tests for the real generic Git read path using local temporary repositories." in integration +for phrase in ( + "real_local_repository_refreshes_resolves_and_materializes_revision_snapshots", + "invalid_reference_and_dirty_existing_snapshot_are_rejected", +): + assert phrase in integration, phrase + +for path in Path(".").rglob("*.md"): + if any(part in {".git", "node_modules", "target", "builds"} for part in path.parts): + continue + lines = path.read_text(encoding="utf-8").splitlines() + assert lines[0] == f"", path + assert re.fullmatch(r"", lines[1]), path + +print("Knowledge 0.0.2-alpha.3.fix.1 structural/replan 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 > /tmp/sasedev-knowledge-0.0.2-alpha.3.fix.1-metadata.json +cargo check --workspace +cargo clippy --workspace --all-targets --all-features -- -D warnings +cargo test -p knowledge-git-api --all-targets --all-features +cargo test -p knowledge-git-lib --all-targets --all-features +cargo test -p knowledge-git-lib --test git_read_path +cargo test --workspace --all-targets --all-features + +python3 - <<'PY' +import json +from pathlib import Path + +metadata = json.loads(Path("/tmp/sasedev-knowledge-0.0.2-alpha.3.fix.1-metadata.json").read_text(encoding="utf-8")) +packages = {package["name"] for package in metadata["packages"]} +expected = { + "knowledge-domain-lib", + "knowledge-git-api", + "knowledge-git-lib", + "knowledge-sync-api", + "knowledge-web-lib", + "knowledge-pgr-server", + "knowledge-howtos-server", + "knowledge-snippets-server", +} +assert packages == expected, packages +assert len(metadata["workspace_members"]) == 8, metadata["workspace_members"] +print("Knowledge 0.0.2-alpha.3.fix.1 Cargo metadata audit: clean") +PY + +test -f Cargo.lock +git check-ignore -q Cargo.lock +if git ls-files --error-unmatch Cargo.lock >/dev/null 2>&1; then + echo 'Cargo.lock must remain untracked for Knowledge' >&2 + exit 1 +fi + +test -z "$(git diff --name-only -- Web)" +test -z "$(git diff --name-only -- crates/knowledge-sync-api)" +test -z "$(git diff --name-only -- crates/knowledge-git-api/src)" +test -z "$(git diff --name-only -- crates/knowledge-git-lib/src)" +test -z "$(git diff --name-only -- prompts)" +test ! -e docs/rules +test ! -e crates/knowledge-app-lib +test ! -e crates/knowledge-forge-gitea-lib +test ! -e crates/knowledge-store-postgres-lib + +git add -A +git diff --cached --check +git status --short +``` + +## Transition + +Si la gate est `PASS` : + +```text +history alpha.3.fix.1 = PASS +-> commit/push alpha.3.fix.1 +-> préparer alpha.4 uniquement ensuite +``` + +Si la gate est `FAIL`, produire un nouveau fix ciblé ou REPLAN uniquement si le résultat révèle un problème structurel nouveau. diff --git a/docs/architecture/001-PROJECT_PROFILE.md b/docs/architecture/001-PROJECT_PROFILE.md index 3ea8256..073281d 100644 --- a/docs/architecture/001-PROJECT_PROFILE.md +++ b/docs/architecture/001-PROJECT_PROFILE.md @@ -1,5 +1,5 @@ - + # Profil du projet Knowledge @@ -17,7 +17,7 @@ Knowledge start prompt prompts/002-V0_0_2_START_PROMPT.md La fondation `0.0.1` a été construite sous PGR `v0.1.1`. Cette identité reste historique dans les artefacts `0.0.1`. -Le démarrage de `0.0.2` vérifie puis adopte la stable PGR courante : +Le démarrage explicite de `0.0.2` a réévalué PGR et a retenu la stable suivante comme source d'adoption : ```text PGR stable tag v0.1.3 @@ -26,6 +26,10 @@ PGR archive SHA-256 f3a7dffd5fe0fd3542e6b5207fda0b94bca2bd05bd5a54542d0a08d635a5 PGR publish report pgr-0.1.3-publish.001-report.md = PASS ``` +Cette référence est une provenance d'adoption figée. Après matérialisation des contrats retenus, la baseline normative de Knowledge est constituée des artefacts locaux du dépôt Knowledge. Une version ou session future ne consulte pas automatiquement le PGR courant ; une nouvelle comparaison PGR exige une réévaluation explicitement engagée. + +`alpha.4` doit terminer cette matérialisation locale pour l'adoption `v0.1.3`, sans recopier mécaniquement la structure PGR et sans réécrire les artefacts historiques déjà publiés. + L'archive PGR `v0.1.3` vérifiée possède `VERSION = 0.1.3`, `332` entrées ZIP, `290` fichiers, `42` répertoires, une racine unique `pgr/`, aucun symlink et aucun `.git`. Son rapport post-tag indique `48/48` tests Python et les audits Markdown propres. Cette prévalidation ne remplace aucune gate opérateur Knowledge. 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 b5e5dfd..fd200b4 100644 --- a/docs/plans/002-V0_0_2_GIT_SYNC_PLAN.md +++ b/docs/plans/002-V0_0_2_GIT_SYNC_PLAN.md @@ -1,5 +1,5 @@ - + # Plan 0.0.2 — Git générique et synchronisation de lecture @@ -17,7 +17,7 @@ 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 réévaluée au démarrage de cette release est : +La source PGR explicitement réévaluée au démarrage de cette release est : ```text PGR stable tag v0.1.3 @@ -26,9 +26,9 @@ PGR archive SHA-256 f3a7dffd5fe0fd3542e6b5207fda0b94bca2bd05bd5a54542d0a0 PGR publish report pgr-0.1.3-publish.001-report.md = PASS ``` -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. +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. `v0.1.3` constitue une provenance d'adoption, pas une dépendance normative vivante : les futurs démarrages Knowledge doivent partir des règles locales et ne consultent PGR que lorsqu'une nouvelle adoption est explicitement engagée. -`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` a corrigé uniquement ce cadrage documentaire et sa gate opérateur est `PASS`. `alpha.2` peut donc matérialiser le premier backend Git réel. +`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` a corrigé uniquement ce cadrage documentaire et sa gate opérateur est `PASS`. `alpha.2` a été fermée par `alpha.2.fix.2` `PASS`. `alpha.3` démontre le chemin Git réel mais sa gate est `FAIL` sur hygiène/formatage/documentation de test ; `alpha.3.fix.1` corrige ces défauts et enregistre le REPLAN décrit ci-dessous. ## Mission @@ -43,13 +43,13 @@ source locale/remote -> résultat de synchronisation changed/unchanged ``` -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. +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. Elle doit également terminer l'adoption PGR engagée au démarrage en rendant Knowledge autonome : règles applicables adaptées/possédées localement, PGR conservé comme provenance et non chargé automatiquement à chaque reprise. ## État acquis et questions ouvertes Décisions déjà matérialisées par le cadrage `alpha.1` et non remises en cause par son `FAIL` documentaire : -- PGR `v0.1.3` est la baseline applicable au projet existant ; +- PGR `v0.1.3` est la source d'adoption explicitement retenue pour `0.0.2`, tandis que la baseline normative courante doit être possédée localement par Knowledge ; - 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 ; @@ -164,24 +164,51 @@ Si la surface « configuration + runner + mirror » ne peut plus être validée ### alpha.3 — refresh, résolution et snapshot réel -Statut opérateur : **à valider**. +Statut opérateur initial : **FAIL**. -La tranche complète le chemin de lecture Git sur de vrais repositories temporaires : +La tranche a matérialisé et prouvé sur de vrais repositories temporaires : -- enregistrer explicitement les configurations physiques des sources dans `GitBackend` afin d'implémenter réellement le contrat provider-neutral ; -- faire implémenter `knowledge-git-api::GitRepository` par `knowledge-git-lib` ; -- étendre le contrat uniquement avec `GitSnapshot` / `prepare_snapshot`, maintenant nécessaires à la matérialisation de lecture ; +- enregistrement explicite des configurations physiques dans `GitBackend` ; +- implémentation réelle de `knowledge-git-api::GitRepository` par `knowledge-git-lib` ; +- extension minimale du contrat avec `GitSnapshot` / `prepare_snapshot` ; - refresh idempotent du mirror via `remote update --prune` ; -- résolution typée d'une référence vers un commit avec `rev-parse --verify --end-of-options ...^{commit}` ; -- refus des références invalides ou non résolubles ; -- préparation d'un worktree/snapshot détaché adressé par révision ; -- validation du `HEAD` et de l'état propre 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. +- résolution typée avec `rev-parse --verify --end-of-options ...^{commit}` ; +- worktree/snapshot détaché adressé par révision ; +- validation du `HEAD` et de l'état propre avant réutilisation ; +- changement de révision après ajout d'un commit source ; +- rejet d'une référence invalide et d'un snapshot sale. -Les tests doivent exercer la frontière `GitRepository` et les effets Git réels. Une imitation complète de `git` par mocks ne constitue pas la preuve principale de cette tranche. Aucun `knowledge-app-lib`, scheduler ou état persistant n'entre dans `alpha.3`. +Les tests fonctionnels passent, mais la gate complète échoue sur trois défauts de conformité : ligne vide terminale dans la matrice, formatage rustfmt d'un test `knowledge-git-api` et documentation de crate manquante dans le test d'intégration `git_read_path`. -### alpha.4 — cas d'usage de synchronisation +`alpha.3.fix.1` corrige exclusivement ces défauts techniques et enregistre le présent REPLAN. Il ne modifie pas le comportement Git déjà prouvé. + +La revue de tranche a déclenché un REPLAN explicite : l'autonomie normative après adoption PGR et l'organisation interne des crates doivent être traitées avant l'orchestration de synchronisation. + +### alpha.4 — autonomie normative et structure interne des crates + +Finaliser l'adoption PGR `v0.1.3` comme migration ponctuelle, sans transformer PGR en dépendance documentaire permanente : + +- inventorier les owners/contrats PGR réellement retenus par Knowledge ; +- produire un mapping durable `ADOPT / KEEP-LOCAL / OVERRIDE / DEFER` fondé sur la baseline locale actuelle ; +- pour chaque `ADOPT`, identifier l'owner local qui possède effectivement le contrat ; +- adapter et matérialiser localement uniquement les règles, templates/configurations et audits nécessaires au développement de Knowledge ; +- ne pas recopier mécaniquement l'arborescence ou les textes PGR lorsque `RULES.md` ou un owner local plus adapté suffit ; +- faire de PGR `v0.1.3` une provenance d'adoption figée, et non une « baseline courante » à recharger ; +- établir que les futurs prompts de démarrage partent de la baseline Knowledge locale et ne demandent une consultation PGR que si une réévaluation PGR est explicitement dans leur scope ; +- vérifier que les règles de gouvernance, workflow, documentation, validation, Rust/Cargo et Web réellement nécessaires sont compréhensibles et applicables depuis le dépôt Knowledge seul. + +La même tranche audite l'organisation interne des crates : + +- `lib.rs` reste la façade publique/documentation de crate ; +- les types, traits et implémentations sont déplacés vers des modules nommés selon leur responsabilité lorsqu'ils forment une responsabilité distincte ; +- les crates `knowledge-git-api` et `knowledge-sync-api` sont examinées en priorité ; +- `api.rs` n'est pas imposé comme nom générique : préférer des modules tels que `reference`, `revision`, `snapshot`, `repository`, `signal` ou autre ownership réel ; +- les petites crates/fichiers ne sont pas découpés artificiellement uniquement pour satisfaire une forme ; +- les réexports publics restent centralisés à la crate root et les consommateurs externes continuent d'utiliser la façade stable. + +Cette tranche ne change pas la sémantique Git prouvée par `alpha.3` et ne matérialise pas encore le cas d'usage `Changed` / `Unchanged`. + +### alpha.5 — cas d'usage de synchronisation Composer les primitives Git en un cas d'usage réellement consommable : @@ -250,7 +277,7 @@ REPLAN obligatoire si : - 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 ; +- une réévaluation PGR explicitement engagée révèle un changement substantiel d'un contrat déjà adopté par Knowledge ; - 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. @@ -260,7 +287,7 @@ Un REPLAN modifie le présent plan de manière explicite ; il ne doit pas être - 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 ; +- prompt/handoff suivant : créé uniquement si une prochaine mission est réellement décidée et fondé sur la baseline normative locale Knowledge ; aucune consultation PGR automatique n'y est ajouté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`. diff --git a/docs/validation/001-VALIDATION_MATRIX.md b/docs/validation/001-VALIDATION_MATRIX.md index 94447e1..a492b7c 100644 --- a/docs/validation/001-VALIDATION_MATRIX.md +++ b/docs/validation/001-VALIDATION_MATRIX.md @@ -1,5 +1,5 @@ - + # Matrice de validation Knowledge @@ -635,5 +635,26 @@ La tranche de lecture Git réelle doit prouver : - `Cargo.lock` toujours ignoré/non suivi ; - `git diff --cached --check` propre avant commit. -Le `PASS` de `alpha.3` autorise uniquement la préparation de `0.0.2-alpha.4`, consacrée au cas d'usage de synchronisation `Changed` / `Unchanged`. +La gate opérateur réelle d'`alpha.3` est `FAIL` : les preuves Git fonctionnelles passent, mais `git diff --check`, `cargo fmt --check` et Clippy strict ne sont pas tous propres. La transition autorisée est uniquement `alpha.3.fix.1`. +## Gate de `0.0.2-alpha.3.fix.1` + +Le fix ferme les défauts techniques d'`alpha.3` et enregistre le REPLAN sans élargir son comportement Git. Il doit prouver : + +- `VERSION = 0.0.2-alpha.3.fix.1` et `[workspace.package].version` identique ; +- history `history/0.0.2/alpha.3.md` présent avec statut réel `FAIL` et committé avant application du fix ; +- delta historique `deltas/0.0.2/alpha.3.md` inchangé ; +- suppression du défaut `git diff --check` sur la matrice de validation ; +- formatage rustfmt propre du test `knowledge-git-api` signalé par la gate ; +- documentation de crate explicite dans `crates/knowledge-git-lib/tests/git_read_path.rs` afin de satisfaire `missing_docs` ; +- comportement Git d'`alpha.3` inchangé : refresh, résolution, snapshot et tests réels restent identiques ; +- plan `0.0.2` replanifié avec `alpha.4` dédiée à l'autonomie normative/structure interne des crates et ancien scope de synchronisation déplacé en `alpha.5` ; +- PGR `v0.1.3` documenté comme provenance d'adoption figée et non comme dépendance normative vivante ; +- règle locale interdisant la consultation automatique de PGR à chaque version/session/tranche, sauf réévaluation PGR explicitement engagée ; +- aucune matérialisation prématurée des règles PGR détaillées ni refactor massif de crates dans ce fix : ce travail appartient à `alpha.4` ; +- `cargo fmt --all -- --check`, audits Rust, `cargo metadata`, `cargo check`, Clippy strict, tests ciblés `knowledge-git-api`/`knowledge-git-lib`, test d'intégration `git_read_path` et tests workspace propres ; +- `Web/` et `knowledge-sync-api` sans diff ; +- `Cargo.lock` toujours ignoré/non suivi ; +- `git diff --cached --check` propre avant commit. + +Le `PASS` de `alpha.3.fix.1` ferme `alpha.3` et autorise uniquement la préparation de `0.0.2-alpha.4`. diff --git a/history/0.0.2/alpha.3.fix.1.md b/history/0.0.2/alpha.3.fix.1.md new file mode 100644 index 0000000..df31967 --- /dev/null +++ b/history/0.0.2/alpha.3.fix.1.md @@ -0,0 +1,173 @@ + + + +# History 0.0.2-alpha.3.fix.1 — clôture du chemin Git réel et REPLAN d'autonomie + +## Statut + +PASS + +La gate opérateur de `0.0.2-alpha.3.fix.1` exécutée le `2026-09-28` est propre. Elle ferme les défauts de conformité d'`alpha.3`, conserve son comportement Git réel et valide le REPLAN qui insère `alpha.4` avant le cas d'usage de synchronisation. + +## Baseline opérateur + +`alpha.3` `FAIL` a été historisé, committé et poussé avant application du fix : + +```text +history/0.0.2/alpha.3.md FAIL +commit 721e8a6 +message 0.0.2-alpha.3 +branch master +push origin/master PASS +workspace après push propre +``` + +Le push observé a avancé `origin/master` de `3802526` à `721e8a6`. + +## Version et gouvernance + +Les contrôles passent : + +```text +VERSION 0.0.2-alpha.3.fix.1 +Cargo workspace version 0.0.2-alpha.3.fix.1 +history alpha.3 FAIL +structural/replan audit clean +``` + +Le plan `0.0.2` contient désormais la trajectoire : + +```text +alpha.3 refresh / résolution / snapshot réel +alpha.4 autonomie normative + structure interne des crates +alpha.5 cas d'usage de synchronisation +beta.1 réconciliation + revue d'horizon +rc.1 candidate stable +rel.1 fermeture stable +``` + +PGR `v0.1.3` est enregistré comme provenance d'adoption figée. Une version, session ou tranche Knowledge ne doit pas consulter automatiquement une nouvelle stable PGR ; une comparaison future exige une réévaluation PGR explicitement engagée. + +## Audits structurels + +`git diff --check` passe. + +Les audits Rust structurels passent : + +```text +Rust test-layout audit: clean (8 crate(s)) +Rust blank-line audit: clean (23 file(s)) +Rust item-spacing audit: clean (23 file(s)) +Rust module-order audit: clean (23 file(s)) +Rust trait-import-block audit: clean (23 file(s)) +Rust re-export-block audit: clean (23 file(s)) +Rust export completeness audit: 0 candidate(s) across 8 package(s) +``` + +Les contrôles de scope confirment notamment : + +```text +Web/ sans diff +crates/knowledge-sync-api sans diff +crates/knowledge-git-api/src sans diff +crates/knowledge-git-lib/src sans diff +prompts/ sans diff +docs/rules/ absent avant alpha.4 +``` + +Le fix n'a donc pas absorbé prématurément le travail transversal réservé à `alpha.4`. + +## Formatage, compilation et Clippy + +Toutes les gates 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 +``` + +Les défauts initiaux d'`alpha.3` sont fermés : fin de fichier de la matrice propre, formatage du test `knowledge-git-api` conforme et documentation de crate du test d'intégration présente. + +## Tests Git ciblés + +Le contrat `knowledge-git-api` passe : + +```text +cargo test -p knowledge-git-api --all-targets --all-features +1 passed; 0 failed +``` + +`knowledge-git-lib` passe avec huit tests unitaires et deux tests d'intégration réels : + +```text +cargo test -p knowledge-git-lib --all-targets --all-features +8 unit passed; 0 failed +2 integration passed; 0 failed +``` + +Le test d'intégration ciblé passe également : + +```text +cargo test -p knowledge-git-lib --test git_read_path +2 passed; 0 failed +``` + +Les scénarios réels continuent de prouver refresh, résolution, snapshots par révision, second commit source, référence invalide et rejet d'un snapshot sale. + +## Tests workspace + +La suite workspace passe intégralement : + +```text +knowledge-domain-lib : 3 PASS +knowledge-git-api : 1 PASS +knowledge-git-lib : 8 unit PASS + 2 integration PASS +knowledge-sync-api : 1 PASS +knowledge-web-lib : 4 PASS +launchers : 0 test chacun +``` + +## Métadonnées et lockfile + +L'audit Cargo passe : + +```text +Knowledge 0.0.2-alpha.3.fix.1 Cargo metadata audit: clean +``` + +Les huit packages attendus sont présents. `Cargo.lock` est présent localement, ignoré et non suivi. + +Après staging, `git diff --cached --check` passe. Le staging observé avant ajout du présent history est : + +```text +M Cargo.toml +M README.md +M RULES.md +M VERSION +M crates/knowledge-git-api/unit_tests/lib.rs +M crates/knowledge-git-lib/tests/git_read_path.rs +A deltas/0.0.2/alpha.3.fix.1.md +M docs/architecture/001-PROJECT_PROFILE.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.3.fix.1` est `PASS`. + +La tranche `alpha.3` est fermée. La transition autorisée est : + +```text +appliquer ce history +-> git add / diff --cached --check / status +-> commit exact "0.0.2-alpha.3.fix.1" +-> push origin master +-> vérifier le workspace propre +-> appliquer seulement ensuite 0.0.2-alpha.4 +``` + +`alpha.4` peut maintenant terminer l'autonomie normative Knowledge et normaliser les crate-roots sans modifier la sémantique Git validée.