From a74a19838fa81584189ac4dfb8496e72e9aa1f77 Mon Sep 17 00:00:00 2001 From: SinuS Von SifriduS Date: Tue, 29 Sep 2026 09:58:22 +0200 Subject: [PATCH] 0.0.3-alpha.1 --- CHANGELOG.md | 10 +- Cargo.toml | 4 +- README.md | 9 +- ROADMAP.md | 9 +- RULES.md | 14 +- VERSION | 2 +- deltas/0.0.3/alpha.1.md | 288 ++++++++++++++++++ docs/000-README.md | 5 +- docs/architecture/001-PROJECT_PROFILE.md | 22 +- .../002-KNOWLEDGE_ARCHITECTURE.md | 30 +- docs/plans/003-V0_0_3_GIT_WRITE_PLAN.md | 223 ++++++++++++++ docs/studies/006-V0_0_3_GIT_WRITE_STUDY.md | 217 +++++++++++++ docs/validation/001-VALIDATION_MATRIX.md | 29 +- history/0.0.3/alpha.1.md | 84 +++++ prompts/003-V0_0_3_START_PROMPT.md | 133 ++++++++ 15 files changed, 1052 insertions(+), 27 deletions(-) create mode 100644 deltas/0.0.3/alpha.1.md create mode 100644 docs/plans/003-V0_0_3_GIT_WRITE_PLAN.md create mode 100644 docs/studies/006-V0_0_3_GIT_WRITE_STUDY.md create mode 100644 history/0.0.3/alpha.1.md create mode 100644 prompts/003-V0_0_3_START_PROMPT.md diff --git a/CHANGELOG.md b/CHANGELOG.md index 75ccdfa..a3dc53e 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,10 +1,18 @@ - + # Changelog SaseDev Knowledge Ce fichier décrit les changements utiles des releases publiées. Les détails de tranches et preuves opérateur appartiennent aux plans, deltas et histories. +## 0.0.3 (candidate) + +- engage l'écriture Git générique contrôlée comme prochaine capacité après la stable de lecture `0.0.2` ; +- retient un worktree d'écriture isolé sous la racine d'état contrôlée et un contrat d'écriture distinct du contrat `GitRepository` de lecture ; +- exige des mutations de fichiers confinées, une identité de commit explicite, des hooks neutralisés et des erreurs publiques redacted ; +- prévoit un push vers `refs/heads/...` avec attente explicite sur l'état distant afin qu'une divergence devienne un conflit au lieu d'un écrasement ; +- conserve rebase/merge automatique, workflow complet de proposition, PostgreSQL, forge et auth/admin hors scope. + ## 0.0.2 - matérialise un backend Git générique de lecture derrière `knowledge-git-api`, sans dépendance obligatoire à une forge ; diff --git a/Cargo.toml b/Cargo.toml index 495a0a2..e2bbe4f 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -1,5 +1,5 @@ # file: Cargo.toml -# version: 30 +# version: 31 [workspace] resolver = "3" @@ -16,7 +16,7 @@ members = [ ] [workspace.package] -version = "0.0.2" +version = "0.0.3-alpha.1" edition = "2024" publish = false repository = "https://git.sasedev.com/Sasedev/sasedev-knowledge" diff --git a/README.md b/README.md index bf5e90b..b7a97cc 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,5 @@ - + # SaseDev Knowledge @@ -11,7 +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` est la stable du chemin Git générique de lecture, de l'autonomie normative locale et du cas d'usage partagé de synchronisation `Changed` / `Unchanged`. La release conserve les intégrations forge, PostgreSQL, écriture Git, auth/admin complète et formats éditoriaux finaux hors scope tant qu'une mission ultérieure ne les engage pas explicitement. +`0.0.1` est la première stable de fondation de SaseDev Knowledge. `0.0.2` est la stable du chemin Git générique de lecture, de l'autonomie normative locale et du cas d'usage partagé de synchronisation `Changed` / `Unchanged`. + +`0.0.3-alpha.1` ouvre la release d'écriture Git contrôlée et de push gardé. Cette première tranche est exclusivement un cadrage : elle sélectionne un worktree d'écriture isolé, un contrat d'écriture distinct de la lecture et une mise à jour distante avec attente explicite sur l'état précédent. Aucun code produit n'est encore modifié. PostgreSQL, forge, workflow complet de proposition, rebase/merge automatique et auth/admin restent hors scope. `knowledge-git-lib` implémente `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. `alpha.4` ne change pas cette sémantique. Les règles nécessaires au développement courant sont désormais possédées localement sous `docs/rules/`, et les futurs prompts Knowledge ne chargent pas PGR sauf réévaluation explicitement engagée. `knowledge-app-lib` compose maintenant refresh, résolution, comparaison avec la révision précédente et préparation de snapshot en un résultat explicite `Changed` / `Unchanged`, sans persister la dernière révision ni matérialiser de scheduler. @@ -76,11 +78,14 @@ Le runtime exige un bind configuré par launcher et l'une des deux sources d'ass - [`docs/studies/002-ACTIX_MAUD_VITE_CORPUS_STUDY.md`](docs/studies/002-ACTIX_MAUD_VITE_CORPUS_STUDY.md) — étude ciblée du pattern Vite manifest / Actix / Maud à adapter pour Knowledge ; - [`docs/studies/003-V0_0_1_FOUNDATION_RECONCILIATION.md`](docs/studies/003-V0_0_1_FOUNDATION_RECONCILIATION.md) — réconciliation `beta.1`, état matérialisé, DEFER conservés et revue d'horizon ; - [`docs/studies/004-V0_0_2_GIT_IMPLEMENTATION_STUDY.md`](docs/studies/004-V0_0_2_GIT_IMPLEMENTATION_STUDY.md) — comparaison processus Git / `gix` / `git2` et décision d'implémentation de lecture ; +- [`docs/studies/006-V0_0_3_GIT_WRITE_STUDY.md`](docs/studies/006-V0_0_3_GIT_WRITE_STUDY.md) — choix de la prochaine mission, stratégie de worktree d'écriture et invariants de push gardé ; - [`docs/plans/001-V0_0_1_FOUNDATION_PLAN.md`](docs/plans/001-V0_0_1_FOUNDATION_PLAN.md) — plan historique de la fondation stable `0.0.1` ; - [`docs/plans/002-V0_0_2_GIT_SYNC_PLAN.md`](docs/plans/002-V0_0_2_GIT_SYNC_PLAN.md) — plan historique de la stable `0.0.2`, gates et décisions de fermeture ; +- [`docs/plans/003-V0_0_3_GIT_WRITE_PLAN.md`](docs/plans/003-V0_0_3_GIT_WRITE_PLAN.md) — plan actif de l'écriture Git contrôlée et du push gardé ; - [`docs/validation/001-VALIDATION_MATRIX.md`](docs/validation/001-VALIDATION_MATRIX.md) — matrice de validation ; - [`prompts/001-V0_0_1_START_PROMPT.md`](prompts/001-V0_0_1_START_PROMPT.md) — prompt de démarrage autoritaire de la release. - [`prompts/002-V0_0_2_START_PROMPT.md`](prompts/002-V0_0_2_START_PROMPT.md) — handoff historique exécuté pour ouvrir `0.0.2` depuis la stable `v0.0.1` vérifiée. +- [`prompts/003-V0_0_3_START_PROMPT.md`](prompts/003-V0_0_3_START_PROMPT.md) — prompt local de reprise de `0.0.3` depuis la stable `v0.0.2` publiée et vérifiée. ## Langue et nomenclature diff --git a/ROADMAP.md b/ROADMAP.md index 49c96be..bdc45d0 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -1,5 +1,5 @@ - + # Roadmap SaseDev Knowledge @@ -15,11 +15,14 @@ Statuts : `( )` planifié, `(x)` terminé, `(d)` différé, `(c)` annulé. - `(x) 0.0.2` — implémentation Git générique et synchronisation de lecture : backend provider-neutral derrière `knowledge-git-api`, configuration de sources locales/remotes, matérialisation locale reproductible, refresh/résolution de révision, snapshot/worktree de lecture et convergence des déclencheurs explicite/périodique vers un même cas d'usage, sans API de forge obligatoire, écriture/publication Git, PostgreSQL ni format final HOWTO/snippet. +## Release engagée + +- `( ) 0.0.3` — écriture Git contrôlée et push gardé : contrat d'écriture provider-neutral distinct de la lecture, worktree d'écriture isolé, mutations de fichiers confinées, commit avec identité explicite et mise à jour d'une branche `refs/heads/...` uniquement lorsque son état distant correspond à l'attente fournie ; sans forge obligatoire, rebase/merge automatique, PostgreSQL ni workflow complet de proposition. + ## Domaines futurs non numérotés Les thèmes suivants sont candidats à des releases ultérieures mais ne reçoivent pas encore de numéro : -- écriture Git contrôlée, branches/propositions/rebase/push et workflow de publication ; - état PostgreSQL partagé et migrations applicatives ; - contribution/revue et administration ; - publication/rendu des trois façades ; @@ -28,4 +31,4 @@ Les thèmes suivants sont candidats à des releases ultérieures mais ne reçoiv - authentification/autorisation complète ; - déploiement et opérations multi-domaines. -La revue d'horizon `0.0.2-beta.1` est réalisée et la stable `0.0.2` est fermée : aucune release postérieure à `0.0.2` n'est engagée ni numérotée. Les thèmes futurs restent volontairement non numérotés jusqu'à ce qu'un scope et un ordre réellement utiles soient décidés. +La revue d'horizon `0.0.2-beta.1` avait laissé la suite ouverte. L'ouverture explicite de `0.0.3-alpha.1` engage désormais uniquement la mission d'écriture Git contrôlée décrite ci-dessus ; aucun numéro ultérieur n'est réservé. diff --git a/RULES.md b/RULES.md index 2624c72..3ae42a9 100644 --- a/RULES.md +++ b/RULES.md @@ -1,5 +1,5 @@ - + # Règles SaseDev Knowledge @@ -27,7 +27,7 @@ Le prompt `prompts/002-V0_0_2_START_PROMPT.md` reste historique : sa vérificati 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. +`0.0.2-alpha.4` a terminé l'autonomie normative de l'adoption `v0.1.3` : les owners nécessaires sont possédés localement et les futures releases normales repartent de Knowledge seul. ## Owners normatifs locaux @@ -124,6 +124,16 @@ La configuration physique des sources Git et la matérialisation locale appartie La racine d'état Git n'est pas un stockage métier. En `0.0.2`, elle est possédée exclusivement par une instance de backend/processus ; un partage concurrent inter-processus reste différé tant qu'un verrouillage dédié n'est pas matérialisé. +### Écriture Git contrôlée + +`0.0.3` engage une capacité d'écriture Git générique derrière un contrat distinct du contrat de lecture. Elle reste indépendante d'une forge et ne transforme pas une proposition externe en publication directe. + +Toute écriture MUST partir d'une révision de base explicite et utiliser un worktree contrôlé distinct des snapshots de lecture. Les chemins de mutation MUST rester relatifs au worktree ; les chemins absolus, composants `..`, accès `.git` et échappements hors racine sont interdits. + +Les commits créés par le backend MUST utiliser une identité auteur/committer explicitement fournie et MUST neutraliser les hooks et prompts interactifs possédés par l'opération. La configuration Git globale de la machine ne constitue pas une source d'identité autoritaire. + +Une mise à jour distante de `0.0.3` MUST viser une branche `refs/heads/...` et MUST être gardée par l'état distant attendu. Une divergence produit un conflit récupérable ; le backend MUST NOT effectuer un `push --force` non gardé, un rebase automatique ou un merge automatique pour masquer cette divergence. + ## PostgreSQL PostgreSQL est destiné à l'état applicatif : comptes, sessions, propositions, revues, audit applicatif, index, recherche, synchronisation et jobs. diff --git a/VERSION b/VERSION index 4e379d2..223b8c4 100644 --- a/VERSION +++ b/VERSION @@ -1 +1 @@ -0.0.2 +0.0.3-alpha.1 diff --git a/deltas/0.0.3/alpha.1.md b/deltas/0.0.3/alpha.1.md new file mode 100644 index 0000000..e50f1c4 --- /dev/null +++ b/deltas/0.0.3/alpha.1.md @@ -0,0 +1,288 @@ + + + +# Delta 0.0.3-alpha.1 — cadrage de l'écriture Git contrôlée + +## Baseline requise + +Partir de la stable autoritaire : + +```text +tag Knowledge v0.0.2 +commit Knowledge 183d354a67bec6d2d512c4898f5189759a6120b0 +archive SHA-256 0e518c7eaad115811cccc8fb2b38a1e68150ec985c2ca72ec08a9ca5bbb202ce +publish report sasedev-knowledge-0.0.2-publish.001-report.md = PASS +``` + +La stable `0.0.2` ne contenait volontairement aucun prompt `0.0.3`, car sa revue d'horizon n'avait engagé aucune prochaine mission. La présente session a ouvert explicitement une nouvelle mission depuis cette baseline ; le prompt versionné correspondant est donc matérialisé par cette tranche : + +```text +prompts/003-V0_0_3_START_PROMPT.md +``` + +PGR `v0.1.3` reste une provenance historique. Aucune version PGR ultérieure n'est consultée ou adoptée. + +La version devient : + +```text +0.0.3-alpha.1 +``` + +## Objet + +Fermer le cadrage de la prochaine release avant toute modification fonctionnelle : + +- vérifier la stable `v0.0.2`, ses règles/owners, architecture, deltas/histories et `DEFER` ; +- sélectionner l'écriture Git générique contrôlée comme mission `0.0.3` ; +- conserver le processus `git` contrôlé déjà validé en `0.0.2` ; +- choisir un worktree d'écriture isolé pour créer une révision candidate ; +- décider que le contrat d'écriture restera distinct du contrat `GitRepository` de lecture ; +- borner la mise à jour distante aux branches `refs/heads/...` avec attente explicite sur leur état précédent ; +- garder une divergence comme conflit récupérable sans rebase/merge automatique ; +- établir l'étude, le plan, le prompt local et la gate de release. + +Aucun code produit, aucune crate, aucune dépendance Cargo/npm et aucun fichier Web ne sont ajoutés ou modifiés dans cette tranche. + +## Décision d'horizon + +La prochaine release engagée est : + +```text +0.0.3 — écriture Git contrôlée et push gardé +``` + +Les domaines PostgreSQL, proposition/revue, rendu/publication produit, recherche, Gitea, auth/admin et opérations restent non numérotés. + +`0.0.3` ne ferme pas le workflow de proposition complet. Elle fournit la primitive Git générique dont ce workflow aura besoin : base explicite, mutations confinées, commit candidat et mise à jour distante gardée. + +## Contrats retenus + +L'étude : + +```text +docs/studies/006-V0_0_3_GIT_WRITE_STUDY.md +``` + +retient : + +- un worktree d'écriture isolé sous la racine d'état contrôlée ; +- des mutations de fichiers par chemins relatifs validés ; +- une identité auteur/committer explicite ; +- hooks et prompts neutralisés ; +- une nouvelle révision candidate avant tout push ; +- un push de branche avec comparaison de l'état distant attendu ; +- conflit explicite si la branche a divergé ; +- aucun `push --force` non gardé ; +- aucun rebase/merge automatique ; +- aucune forge obligatoire. + +Le plan actif est : + +```text +docs/plans/003-V0_0_3_GIT_WRITE_PLAN.md +``` + +avec trajectoire prévisionnelle `alpha.1` à `alpha.4`, puis `beta.1`, `rc.1` et `rel.1`. + +## Scope des fichiers + +REPLACE : + +```text +VERSION +Cargo.toml +README.md +RULES.md +ROADMAP.md +CHANGELOG.md +docs/000-README.md +docs/architecture/001-PROJECT_PROFILE.md +docs/architecture/002-KNOWLEDGE_ARCHITECTURE.md +docs/validation/001-VALIDATION_MATRIX.md +``` + +ADD : + +```text +docs/studies/006-V0_0_3_GIT_WRITE_STUDY.md +docs/plans/003-V0_0_3_GIT_WRITE_PLAN.md +prompts/003-V0_0_3_START_PROMPT.md +deltas/0.0.3/alpha.1.md +``` + +DELETE : aucun. + +Aucun fichier sous `crates/` ou `Web/` n'est modifié. + +Aucun history `0.0.3-alpha.1` n'est inclus : il doit refléter la gate opérateur réelle. + +## Gate opérateur + +Exécuter depuis la racine du dépôt après application du delta : + +```bash +test "$(cat VERSION)" = '0.0.3-alpha.1' +grep -F 'version = "0.0.3-alpha.1"' Cargo.toml + +git diff --check + +python3 -B scripts/audit_markdown_headers.py README.md RULES.md ROADMAP.md CHANGELOG.md docs prompts deltas history +python3 -B scripts/audit_markdown_links.py README.md RULES.md ROADMAP.md CHANGELOG.md docs prompts deltas history +python3 -B scripts/audit_markdown_tables.py README.md RULES.md ROADMAP.md CHANGELOG.md docs prompts deltas history + +cargo fmt --all +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_crate_root_facades.py crates +python3 -B scripts/audit_rust_export_completeness.py --root . --summary-only + +cargo metadata --format-version 1 --no-deps > /tmp/sasedev-knowledge-0.0.3-alpha.1-metadata.json +cargo check --workspace +cargo clippy --workspace --all-targets --all-features -- -D warnings +cargo test -p knowledge-git-lib --test git_read_path +cargo test --workspace --all-targets --all-features + +python3 - <<'PYGATE' +import json +from pathlib import Path + +assert Path('docs/studies/006-V0_0_3_GIT_WRITE_STUDY.md').is_file() +assert Path('docs/plans/003-V0_0_3_GIT_WRITE_PLAN.md').is_file() +assert Path('prompts/003-V0_0_3_START_PROMPT.md').is_file() +assert Path('deltas/0.0.3/alpha.1.md').is_file() +assert not Path('history/0.0.3/alpha.1.md').exists() + +roadmap = Path('ROADMAP.md').read_text(encoding='utf-8') +assert '- `( ) 0.0.3`' in roadmap +assert '0.0.4' not in roadmap + +rules = Path('RULES.md').read_text(encoding='utf-8') +for phrase in ( + 'Écriture Git contrôlée', + 'MUST viser une branche `refs/heads/...`', + 'MUST NOT effectuer un `push --force` non gardé', +): + assert phrase in rules, phrase + +study = Path('docs/studies/006-V0_0_3_GIT_WRITE_STUDY.md').read_text(encoding='utf-8') +for phrase in ( + 'worktree d\'écriture isolé', + 'comparaison-et-échange', + 'aucun rebase ou merge automatique', + 'PGR `v0.1.3` reste une provenance historique', +): + assert phrase in study, phrase + +plan = Path('docs/plans/003-V0_0_3_GIT_WRITE_PLAN.md').read_text(encoding='utf-8') +headings = ( + '## 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 = [plan.index(value) for value in headings] +assert positions == sorted(positions) +for tranche in ('alpha.1', 'alpha.2', 'alpha.3', 'alpha.4', 'beta.1', 'rc.1', 'rel.1'): + assert f'### {tranche} —' in plan, tranche + +prompt = Path('prompts/003-V0_0_3_START_PROMPT.md').read_text(encoding='utf-8') +assert 'Ne pas rechercher, charger ni adopter automatiquement une nouvelle version de PGR.' in prompt +assert '0e518c7eaad115811cccc8fb2b38a1e68150ec985c2ca72ec08a9ca5bbb202ce' in prompt + +metadata = json.loads(Path('/tmp/sasedev-knowledge-0.0.3-alpha.1-metadata.json').read_text(encoding='utf-8')) +expected = { + 'knowledge-app-lib', + '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 {package['name'] for package in metadata['packages']} == expected +assert len(metadata['workspace_members']) == 9 + +assert not Path('crates/knowledge-forge-gitea-lib').exists() +assert not Path('crates/knowledge-store-postgres-lib').exists() +assert not Path('migrations').exists() + +print('Knowledge 0.0.3-alpha.1 framing audit: clean') +PYGATE + +python3 - <<'PYTEXT' +from pathlib import Path + +roots = [Path('README.md'), Path('RULES.md'), Path('ROADMAP.md'), Path('CHANGELOG.md'), Path('docs'), Path('prompts'), Path('deltas'), Path('history')] +paths = [] +for root in roots: + if root.is_file(): + paths.append(root) + elif root.is_dir(): + paths.extend(path for path in root.rglob('*') if path.is_file()) +for path in paths: + data = path.read_bytes() + assert b'\r' not in data, path + assert data.endswith(b'\n'), path + assert not data.endswith(b'\n\n'), path + text = data.decode('utf-8') + for number, line in enumerate(text.splitlines(), start=1): + assert line == line.rstrip(' \t'), (path, number) +print(f'Knowledge 0.0.3-alpha.1 text hygiene: clean ({len(paths)} file(s))') +PYTEXT + +test -z "$(git diff --name-only -- crates Web)" +test ! -e history/0.0.3/alpha.1.md + +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 -f Web/knowledge-template-lab/package-lock.json + +git add -A +git diff --cached --check +git status --short +``` + +La gate ne rejoue pas npm/Vite/HTTP dans `alpha.1` : aucun contrat Web ni fichier `Web/` n'est modifié, et la stable `0.0.2` a déjà acquis une gate Web/runtime complète. Cette omission est conforme à la validation proportionnée locale. + +## Transition + +### PASS + +Produire séparément : + +```text +history/0.0.3/alpha.1.md +``` + +avec les résultats réellement observés. Après application du history, commit/push `0.0.3-alpha.1`, puis seulement préparer `0.0.3-alpha.2`. + +### FAIL / PARTIAL / BLOCKED + +Produire le history réel avec son statut, l'appliquer et le committer avant toute correction. + +Une correction bornée à ce cadrage utilise : + +```text +0.0.3-alpha.1.fix.1 +``` + +Si le diagnostic invalide la mission, l'ownership ou la stratégie d'écriture, exécuter un REPLAN plutôt que d'absorber une nouvelle responsabilité dans un fix. diff --git a/docs/000-README.md b/docs/000-README.md index b412a42..77cec7f 100644 --- a/docs/000-README.md +++ b/docs/000-README.md @@ -1,5 +1,5 @@ - + # Documentation SaseDev Knowledge @@ -31,11 +31,13 @@ - [`studies/003-V0_0_1_FOUNDATION_RECONCILIATION.md`](studies/003-V0_0_1_FOUNDATION_RECONCILIATION.md) — réconciliation beta de la fondation, DEFER conservés et revue d'horizon engageant uniquement `0.0.2`. - [`studies/004-V0_0_2_GIT_IMPLEMENTATION_STUDY.md`](studies/004-V0_0_2_GIT_IMPLEMENTATION_STUDY.md) — étude comparative Git de démarrage `0.0.2`, décision process et ownership du backend. - [`studies/005-V0_0_2_GIT_SYNC_RECONCILIATION.md`](studies/005-V0_0_2_GIT_SYNC_RECONCILIATION.md) — réconciliation beta du chemin Git/synchronisation, `DEFER` conservés et revue d'horizon sans prochaine release réservée. +- [`studies/006-V0_0_3_GIT_WRITE_STUDY.md`](studies/006-V0_0_3_GIT_WRITE_STUDY.md) — décision d'engager l'écriture Git contrôlée, stratégie de worktree et invariants de concurrence. ## Plans - [`plans/001-V0_0_1_FOUNDATION_PLAN.md`](plans/001-V0_0_1_FOUNDATION_PLAN.md) — plan historique de la stable de fondation `0.0.1`. - [`plans/002-V0_0_2_GIT_SYNC_PLAN.md`](plans/002-V0_0_2_GIT_SYNC_PLAN.md) — plan historique de la stable Git générique et synchronisation de lecture `0.0.2`. +- [`plans/003-V0_0_3_GIT_WRITE_PLAN.md`](plans/003-V0_0_3_GIT_WRITE_PLAN.md) — plan actif de `0.0.3`, écriture Git contrôlée et push gardé. ## Validation @@ -46,3 +48,4 @@ Les deltas et histories sont des artefacts de workflow, pas des substituts à ce ## Handoff - [`../prompts/002-V0_0_2_START_PROMPT.md`](../prompts/002-V0_0_2_START_PROMPT.md) — handoff historique exécuté pour ouvrir `0.0.2` depuis `v0.0.1` publiée et vérifiée. +- [`../prompts/003-V0_0_3_START_PROMPT.md`](../prompts/003-V0_0_3_START_PROMPT.md) — prompt local de reprise de `0.0.3` depuis `v0.0.2` publiée et vérifiée. diff --git a/docs/architecture/001-PROJECT_PROFILE.md b/docs/architecture/001-PROJECT_PROFILE.md index 4cd538a..b8b67b6 100644 --- a/docs/architecture/001-PROJECT_PROFILE.md +++ b/docs/architecture/001-PROJECT_PROFILE.md @@ -1,18 +1,18 @@ - + # Profil du projet Knowledge ## Baseline autoritaire -La stable produit depuis laquelle `0.0.2` est ouverte est : +La stable produit depuis laquelle `0.0.3` est ouverte est : ```text -Knowledge stable tag v0.0.1 -Knowledge stable commit 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 +Knowledge stable tag v0.0.2 +Knowledge stable commit 183d354a67bec6d2d512c4898f5189759a6120b0 +Knowledge archive SHA-256 0e518c7eaad115811cccc8fb2b38a1e68150ec985c2ca72ec08a9ca5bbb202ce +Knowledge publish report sasedev-knowledge-0.0.2-publish.001-report.md = PASS +Knowledge start prompt prompts/003-V0_0_3_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`. @@ -34,7 +34,7 @@ L'archive PGR `v0.1.3` vérifiée possède `VERSION = 0.1.3`, `332` entrées ZIP Cette prévalidation ne remplace aucune gate opérateur Knowledge. -## Nature de l'adoption +## Historique de l'adoption Knowledge n'est plus un nouveau dépôt à instancier : `0.0.2-alpha.1` migre un projet existant de la baseline PGR `v0.1.1` vers `v0.1.3`. @@ -83,6 +83,8 @@ Le détail de la migration depuis les owners PGR `v0.1.3`, y compris les décisi | Implémentation Git de `0.0.2` | `KEEP-LOCAL` | processus `git` contrôlé derrière `knowledge-git-api` ; décision réévaluable derrière le contrat | | Configuration physique Git | `KEEP-LOCAL` | `knowledge-git-lib` matérialisée en `0.0.2-alpha.2` ; source locale/remote + racine d'état ; pas dans le domaine | | Copies Git générées | `KEEP-LOCAL` | racine d'état explicite hors dépôt source, mirrors et snapshots adressés par clé sûre/révision | +| Écriture Git contrôlée `0.0.3` | `KEEP-LOCAL` | contrat distinct de la lecture, worktree isolé, commit explicite et push de branche gardé par état attendu | +| Rebase/merge automatique | `DEFER` | reprendre avec un workflow de proposition réellement matérialisé ; divergence = conflit en `0.0.3` | | Partage du cache Git entre processus | `DEFER` | état root exclusif à une instance backend en `0.0.2` ; reprendre avec verrouillage inter-processus réel | | Forge | `KEEP-LOCAL` | capacité optionnelle derrière adapter ; aucune API de forge dans le domaine | | Gitea | `DEFER` | premier adapter candidat ; reprendre lorsque des capacités forge-only sont implémentées | @@ -170,6 +172,6 @@ Elles justifient de conserver séparées l'identité/authentification partagée, `0.0.2-beta.1` confirme que le scope alpha est matérialisé par neuf packages Cargo : contrats domaine/Git/synchronisation, backend Git générique, orchestration application partagée, composition Web et trois launchers. Aucune responsabilité supplémentaire n'est nécessaire pour fermer la mission de lecture/synchronisation de `0.0.2`. -Restent différés : adapter Gitea, PostgreSQL/migrations, moteur de recherche, auth/admin complète, quatrième application d'administration, modèle détaillé rôles/capabilities, formats finaux HOWTO/snippet, écriture/publication Git, scheduler concret, support explicite submodules/LFS, politique de nettoyage/rétention des snapshots et partage concurrent de la même racine Git entre plusieurs processus. +Restent différés après `0.0.2` : adapter Gitea, PostgreSQL/migrations, moteur de recherche, auth/admin complète, quatrième application d'administration, modèle détaillé rôles/capabilities, formats finaux HOWTO/snippet, scheduler concret, support explicite submodules/LFS, politique de nettoyage/rétention des snapshots et partage concurrent de la même racine Git entre plusieurs processus. -La revue d'horizon beta ne réserve aucune release suivante. Un changement de scope produit, un besoin mesuré ou une contrainte d'exploitation pourra engager ultérieurement une nouvelle mission ; il ne justifie pas un choix anticipé. +La revue d'horizon beta n'avait réservé aucune release suivante. L'ouverture explicite de `0.0.3` consomme uniquement le `DEFER` d'écriture Git contrôlée : worktree d'écriture isolé, commit candidat et push de branche gardé. Rebase/merge automatique et workflow complet de proposition restent différés. diff --git a/docs/architecture/002-KNOWLEDGE_ARCHITECTURE.md b/docs/architecture/002-KNOWLEDGE_ARCHITECTURE.md index e879683..13b51b4 100644 --- a/docs/architecture/002-KNOWLEDGE_ARCHITECTURE.md +++ b/docs/architecture/002-KNOWLEDGE_ARCHITECTURE.md @@ -1,5 +1,5 @@ - + # Architecture de fondation Knowledge @@ -177,9 +177,23 @@ Le snapshot de lecture est ensuite créé comme worktree détaché adressé par Les hooks Git sont désactivés pour les opérations de checkout/worktree appartenant au backend. Les commandes sont exécutées directement sans shell, avec prompts interactifs désactivés et sans journaliser de credential. -### Scope futur du contrat Git +### Écriture Git engagée en `0.0.3` -`alpha.3` étend `GitRepository` uniquement avec `prepare_snapshot`, parce que la matérialisation locale devient effectivement nécessaire au cas d'usage de lecture. Les opérations génériques à plus long terme peuvent inclure `status/diff`, branch, commit, merge/rebase et push. Elles ne sont pas ajoutées en `0.0.2`. +`0.0.3` ajoute une frontière d'écriture distincte du `GitRepository` de lecture. Le backend conserve le processus `git` contrôlé et matérialise un worktree d'écriture isolé sous la racine d'état, sans modifier les snapshots de lecture. + +Le chemin cible est : + +```text +base GitRevision explicite +-> worktree d'écriture contrôlé +-> mutations de fichiers confinées +-> commit avec identité explicite +-> révision candidate +-> push vers refs/heads/... gardé par l'état distant attendu +-> succès ou conflit explicite +``` + +Une divergence ne déclenche ni rebase, ni merge, ni force-push non gardé. Ces décisions appartiennent à un futur workflow de proposition/publication. Les capacités forge-specific restent séparées. La baseline conserve au moins trois sources indépendantes (`pgr`, `howtos`, `snippets`) mais le mapping reste configurable et extensible ; aucun `match` codé en dur n'impose exactement trois repositories. @@ -348,7 +362,7 @@ La fondation matérialisée est cohérente avec les objectifs `0.0.1` : - frontend de référence indépendant et rendu runtime Maud effectivement relié au manifest Vite ; - aucune persistance PostgreSQL, auth complète, UI admin complète, forge spécifique ou format final HOWTO/snippet introduit par anticipation. -`0.0.2-alpha.1` conserve cette réconciliation comme baseline : la release courante ouvre uniquement le chemin Git générique de lecture et la synchronisation réelle ; les autres axes restent différés. +`0.0.2-alpha.1` a conservé cette réconciliation comme baseline et la stable `0.0.2` a fermé le chemin Git générique de lecture et la synchronisation réelle. ## Réconciliation `0.0.2-beta.1` @@ -365,6 +379,14 @@ La mission Git/synchronisation est réconciliée avec l'implémentation réellem Les besoins de rétention de snapshots, submodules/LFS, partage multi-processus de la racine Git et scheduler concret restent différés jusqu'à preuve d'un besoin réel. Aucune prochaine release n'est numérotée par cette réconciliation. +## Ouverture `0.0.3` — écriture Git contrôlée + +Après publication vérifiée de `v0.0.2`, la prochaine mission explicitement engagée est l'écriture Git générique contrôlée. Elle réutilise le backend process existant, introduit un contrat d'écriture distinct de la lecture et garde la forge optionnelle. + +`0.0.3` borne la mise à jour distante à des branches `refs/heads/...` et exige un état distant attendu. Un push n'est accepté que lorsque cette attente reste vraie ; sinon le résultat est un conflit récupérable. Le backend ne résout pas ce conflit par rebase/merge automatique. + +PostgreSQL, workflow complet de proposition, auth/admin, parsing final et adapter Gitea restent des missions distinctes. + ## 10. Administration L'administration Web est une interface vers les mêmes cas d'usage que l'édition locale Git, pas une deuxième source de vérité. diff --git a/docs/plans/003-V0_0_3_GIT_WRITE_PLAN.md b/docs/plans/003-V0_0_3_GIT_WRITE_PLAN.md new file mode 100644 index 0000000..c4b0aa8 --- /dev/null +++ b/docs/plans/003-V0_0_3_GIT_WRITE_PLAN.md @@ -0,0 +1,223 @@ + + + +# Plan 0.0.3 — écriture Git contrôlée et push gardé + +## Statut et sources + +Plan actif de `0.0.3`, ouvert depuis la stable Knowledge `v0.0.2` publiée et vérifiée. + +Sources autoritaires de reprise : + +```text +Knowledge tag stable v0.0.2 +Knowledge commit stable 183d354a67bec6d2d512c4898f5189759a6120b0 +Knowledge archive SHA-256 0e518c7eaad115811cccc8fb2b38a1e68150ec985c2ca72ec08a9ca5bbb202ce +Knowledge publish report sasedev-knowledge-0.0.2-publish.001-report.md = PASS +Knowledge start prompt prompts/003-V0_0_3_START_PROMPT.md +``` + +PGR `v0.1.3` reste une provenance historique de l'adoption fermée pendant `0.0.2`. Aucune version PGR plus récente n'est une source de cette release et aucune réévaluation PGR n'est engagée. + +`0.0.3-alpha.1` est la tranche courante de cadrage. Aucun history n'existe avant la gate opérateur. + +## Mission + +`0.0.3` doit étendre le backend Git générique de Knowledge avec une capacité d'écriture contrôlée, indépendante d'une forge, capable de produire une révision candidate puis de mettre à jour une branche distante uniquement si son état précédent correspond encore à l'attente de l'appelant. + +Le chemin cible est : + +```text +source Git configurée + -> base commit explicite + -> worktree d'écriture isolé + -> mutations de fichiers confinées + -> commit avec identité explicite + -> révision candidate + -> push gardé vers refs/heads/... + -> succès ou conflit explicite +``` + +La release fournit une primitive Git réutilisable aux futurs workflows de proposition/publication ; elle n'implémente pas encore ces workflows produit. + +## État acquis et questions ouvertes + +Acquis par `0.0.2` : + +- Git reste la source autoritaire du contenu publié ; +- `knowledge-git-api::GitRepository` possède le contrat provider-neutral de lecture ; +- `knowledge-git-lib` possède la configuration physique, les mirrors, refresh, résolution et snapshots ; +- les opérations Git sont lancées sans shell, avec prompts interactifs désactivés et erreurs publiques redacted ; +- les snapshots de lecture sont adressés par révision et vérifiés avant réutilisation ; +- `knowledge-app-lib` possède uniquement le cas d'usage de synchronisation `Changed` / `Unchanged` ; +- Gitea, PostgreSQL, auth/admin et workflow complet de proposition restent différés. + +Décisions prises par l'étude `006` : + +- conserver le processus `git` contrôlé ; +- utiliser un worktree d'écriture isolé plutôt qu'une nouvelle implémentation Git ou un moteur plumbing complet ; +- introduire un contrat d'écriture distinct de `GitRepository` afin de préserver les consommateurs lecture seule ; +- limiter `0.0.3` aux branches `refs/heads/...` ; +- utiliser une attente explicite sur l'état distant pour empêcher l'écrasement concurrent ; +- traiter une divergence comme conflit récupérable, sans rebase/merge automatique ; +- ne créer aucune nouvelle crate tant qu'un owner distinct n'est pas démontré. + +Questions laissées à l'implémentation sans modifier la mission : + +- forme exacte des types de mutation publique dans `knowledge-git-api` ; +- stratégie interne de nommage/cleanup des worktrees d'écriture ; +- découpage exact des erreurs de conflit versus erreurs process ; +- détail de la commande Git utilisée pour la garde distante, sous réserve de la sémantique décidée. + +## Scope + +La release couvre : + +- contrat passif d'écriture Git dans `knowledge-git-api`, séparé du contrat de lecture ; +- création/modification/suppression de fichiers par chemins relatifs validés ; +- worktree d'écriture sous la racine d'état contrôlée, séparé des snapshots de lecture ; +- commit à partir d'une base `GitRevision` explicite ; +- identité auteur/committer et message fournis explicitement ; +- neutralisation des hooks et de la configuration Git ambiante pertinente ; +- résultat de révision candidate explicite ; +- push vers une branche générique avec garde sur l'état distant attendu ; +- conflit explicite et non destructif en cas de divergence ; +- tests unitaires et d'intégration locaux couvrant sécurité de chemin, commit, push et concurrence ; +- documentation durable des invariants réellement matérialisés. + +## Hors scope + +`0.0.3` n'introduit pas : + +- API Gitea/GitHub/GitLab, webhook, pull/merge request ou release de forge ; +- rebase/merge automatique ; +- workflow complet de proposition/revue, commentaires ou audit applicatif ; +- PostgreSQL, migrations ou persistance de dernière révision ; +- auth/admin ou modèle rôles/capabilities ; +- route HTTP d'écriture ou UI d'administration ; +- modification du rendu public ou du package Web ; +- signature de commits ; +- Git LFS/submodules ; +- partage concurrent de la racine d'état Git entre plusieurs processus ; +- formats finaux HOWTO/snippet ; +- scheduler/job de publication. + +## Stratégie de validation + +Les alphas fonctionnelles privilégient les preuves Git locales et ciblées : + +```text +cargo fmt --all +cargo fmt --all -- --check +-> audits Rust structurels applicables +-> cargo metadata / cargo check +-> clippy strict +-> tests ciblés knowledge-git-api / knowledge-git-lib +-> tests d'intégration avec repositories temporaires locaux/bare +-> tests workspace lorsque la frontière publique ou le workspace change +``` + +Les tests d'écriture ne nécessitent ni Internet ni forge. Ils créent leur propre repository source/remote temporaire et fournissent explicitement l'identité de commit. + +`Web/` reste hors scope alpha ; npm/Vite ne sont pas rejoués par défaut sans diff Web. La phase beta/RC pourra imposer la non-régression runtime globale conformément à l'owner de validation. + +La gate de `alpha.1` reste une gate de cadrage : elle valide baseline, documentation, version, audits et non-régression du workspace existant, sans prétendre tester une implémentation d'écriture encore absente. + +## Trajectoire prévisionnelle + +### alpha.1 — baseline, étude et cadrage + +- vérifier la stable `v0.0.2` et son rapport post-tag ; +- confirmer l'autonomie normative Knowledge sans nouvelle consultation PGR ; +- réconcilier les `DEFER` avec la prochaine mission ; +- produire l'étude `006` ; +- engager `0.0.3` dans la roadmap ; +- mettre à jour les owners/architecture vivants nécessaires ; +- établir le présent plan ; +- ne modifier aucun code sous `crates/` ni `Web/`. + +### alpha.2 — contrat d'écriture provider-neutral + +- étendre `knowledge-git-api` avec un contrat distinct du `GitRepository` de lecture ; +- matérialiser uniquement les types nécessaires aux mutations, identité de commit, branche cible, état attendu et résultat ; +- valider strictement les chemins relatifs et les branches `refs/heads/...` ; +- préserver les implémentations/fakes lecture seule sans leur imposer des méthodes d'écriture ; +- ne pas effectuer encore de push distant réel si le découpage de la tranche devient disproportionné. + +### alpha.3 — worktree d'écriture et commit candidat + +- matérialiser dans `knowledge-git-lib` un worktree d'écriture isolé dérivé d'une base résolue ; +- appliquer create/update/delete sous confinement ; +- neutraliser hooks/configuration ambiante pertinente ; +- créer un commit avec identité explicite ; +- retourner une révision candidate vérifiée ; +- nettoyer l'état temporaire de manière déterministe sans masquer un état inattendu. + +### alpha.4 — push gardé et concurrence + +- observer l'état de la branche distante ; +- pousser la révision candidate uniquement si la cible correspond à l'attente explicite ; +- gérer création de branche lorsque l'absence est attendue ; +- produire un conflit récupérable en cas de divergence ; +- prouver l'absence d'écrasement par tests d'intégration avec remote bare local ; +- fermer le scope fonctionnel alpha sans ajouter workflow de proposition ou forge. + +### beta.1 — réconciliation et revue d'horizon + +- réconcilier contrats, implémentation et documentation durable ; +- vérifier les `DEFER` encore valides ; +- rejouer la non-régression utile, y compris runtime global si nécessaire à la stabilisation ; +- décider explicitement si une mission suivante est suffisamment définie pour être engagée ; +- ne pas numéroter automatiquement une version ultérieure. + +### rc.1 — candidate stable + +- geler le scope ; +- rejouer la gate complète applicable à la release ; +- vérifier reproductibilité des tests Git d'écriture locaux, intégrité des deltas/histories, Cargo/Clippy/tests et non-régression Web/runtime prévue par la phase ; +- n'introduire aucune nouvelle fonctionnalité. + +### rel.1 — promotion stable pré-tag + +- promouvoir mécaniquement `VERSION` et le workspace vers `0.0.3` ; +- fermer changelog/roadmap/plan sans nouveau scope ; +- rejouer la gate stable prévue ; +- produire le history observé avant commit produit/tag ; +- ne fabriquer aucun rapport post-tag avant publication réelle. + +## Déclencheurs de REPLAN + +REPLAN avant de poursuivre si : + +- le contrat d'écriture exige de casser le contrat de lecture existant au lieu de rester séparé ; +- le push gardé ne peut pas garantir l'absence d'écrasement avec une attente explicite ; +- l'implémentation nécessite une forge spécifique ; +- un besoin de rebase/merge automatique devient nécessaire pour fermer la mission ; +- l'écriture révèle une responsabilité de persistance PostgreSQL indispensable à la correction du backend lui-même ; +- le cycle de vie des worktrees exige un owner/processus distinct ; +- le partage multi-processus de la racine d'état devient nécessaire ; +- la stratégie process Git actuelle devient inadéquate pour une raison mesurée ; +- une tranche atteint `.fix.3`, conformément à la gouvernance locale. + +La conclusion du REPLAN doit utiliser `CONTINUE`, `SPLIT`, `CONTINUE-NEXT-SESSION` ou `ABANDON`. + +## Clôture et transition + +La release est fermable lorsque : + +- l'écriture produit une révision candidate à partir d'une base explicite ; +- les mutations restent confinées au worktree contrôlé ; +- le commit n'utilise ni hooks ni identité Git ambiante ; +- la mise à jour distante est gardée contre une révision attendue ou une absence attendue ; +- une divergence produit un conflit sans écrasement ; +- les tests locaux réels couvrent les chemins critiques ; +- les règles/architecture décrivent l'état effectivement obtenu ; +- beta et RC ont fermé les non-régressions prévues. + +Un `PASS` de `alpha.1` autorise uniquement `0.0.3-alpha.2`. Tout autre statut produit d'abord son history puis un fix ou REPLAN selon le diagnostic. + +## Revue d'horizon + +La revue d'horizon n'est pas réalisée en `alpha.1`. + +Les thèmes PostgreSQL, proposition/revue, rendu/publication produit, recherche, forge, auth/admin et opérations restent non numérotés. `beta.1` décidera, à partir du retour réel de l'écriture Git, si l'un d'eux devient la prochaine mission. diff --git a/docs/studies/006-V0_0_3_GIT_WRITE_STUDY.md b/docs/studies/006-V0_0_3_GIT_WRITE_STUDY.md new file mode 100644 index 0000000..fcae226 --- /dev/null +++ b/docs/studies/006-V0_0_3_GIT_WRITE_STUDY.md @@ -0,0 +1,217 @@ + + + +# Étude 0.0.3 — écriture Git contrôlée + +## Objet + +Cette étude ouvre `0.0.3` depuis la stable autoritaire `v0.0.2` et détermine le prochain incrément utile après le chemin Git générique de lecture matérialisé en `0.0.2`. + +Elle s'appuie uniquement sur les règles, l'architecture, la roadmap, les décisions différées et les preuves locales Knowledge. PGR `v0.1.3` reste une provenance historique d'adoption et aucune version PGR plus récente n'est consultée ou adoptée pour cette décision. + +## Baseline observée + +La stable de départ est : + +```text +Knowledge tag stable v0.0.2 +Knowledge commit stable 183d354a67bec6d2d512c4898f5189759a6120b0 +Knowledge archive SHA-256 0e518c7eaad115811cccc8fb2b38a1e68150ec985c2ca72ec08a9ca5bbb202ce +Knowledge publish report sasedev-knowledge-0.0.2-publish.001-report.md = PASS +``` + +`0.0.2` fournit déjà : + +```text +source locale/remote + -> mirror contrôlé + -> refresh avec pruning + -> résolution vers commit + -> snapshot/worktree de lecture + -> synchronisation Changed / Unchanged +``` + +Le backend process Git contrôlé et les contrats provider-neutral sont donc acquis avant toute nouvelle capacité d'écriture. + +## Revue des axes différés + +La revue d'horizon `0.0.2-beta.1` laisse notamment ouverts : + +- écriture Git contrôlée et publication ; +- PostgreSQL et migrations ; +- workflow complet de proposition/revue ; +- parsing final HOWTO/snippet ; +- recherche/indexation ; +- adapter Gitea ; +- auth/admin complète ; +- scheduler concret ; +- rétention de snapshots et partage multi-processus. + +Le prochain axe doit apporter une capacité réellement réutilisable sans forcer plusieurs de ces décisions à la fois. + +## Choix de la prochaine mission + +La mission retenue est l'**écriture Git générique contrôlée avec mise à jour distante gardée**. + +Ce choix est retenu parce qu'il : + +- prolonge directement les responsabilités déjà matérialisées dans `knowledge-git-api` et `knowledge-git-lib` ; +- reste testable avec des repositories locaux et remotes bare temporaires, sans service externe ; +- conserve la forge optionnelle ; +- fournit la primitive nécessaire aux futurs workflows de proposition/publication sans implémenter prématurément leur état PostgreSQL, leurs rôles ou leur UI ; +- évite de sélectionner maintenant un driver/ORM PostgreSQL alors que l'écriture Git peut être fermée indépendamment ; +- transforme un `DEFER` explicitement identifié en une mission bornée sans absorber rebase/merge automatique ni publication produit complète. + +`0.0.3` est donc le prochain incrément SemVer engagé. + +## Stratégies d'écriture considérées + +### A — worktree d'écriture isolé + commandes Git usuelles + +Séquence conceptuelle : + +```text +base commit explicite +-> worktree d'écriture isolé sous la racine d'état +-> mutations de fichiers validées +-> git add +-> commit avec identité explicite et hooks neutralisés +-> révision candidate +-> push gardé vers une branche autorisée +-> suppression contrôlée du worktree temporaire +``` + +Avantages : + +- comportement proche de Git utilisé manuellement et facile à diagnostiquer ; +- réutilise le backend process déjà choisi et validé ; +- permet des tests locaux réalistes ; +- rend les mutations de fichiers et leur diff inspectables ; +- n'introduit pas de nouvelle bibliothèque Git. + +Risques : + +- cycle de vie d'un worktree temporaire à posséder explicitement ; +- validation stricte des chemins de mutation nécessaire ; +- nettoyage après erreur à traiter sans suppression destructive ambiguë. + +### B — construction de commits par commandes Git plumbing + +Une implémentation fondée sur `hash-object`, index temporaire, `write-tree` et `commit-tree` éviterait un worktree d'écriture classique. + +Avantages : + +- état filesystem potentiellement plus réduit ; +- contrôle fin de la construction du commit. + +Inconvénients : + +- complexité sensiblement supérieure pour les mutations multi-fichiers, suppressions et futurs cas de validation ; +- risque d'introduire une mini-couche Git plumbing difficile à maintenir alors que le projet possède déjà un modèle worktree pour la lecture ; +- bénéfice non démontré à ce stade. + +### C — réouverture du choix `gix`/`git2` + +Changer de backend uniquement pour l'écriture n'est pas retenu. `0.0.2` a déjà validé le processus `git` contrôlé comme implémentation locale remplaçable derrière le contrat. Une seconde implémentation demanderait une preuve de besoin distincte. + +## Décision technique + +`0.0.3` retient la stratégie A : **worktree d'écriture isolé piloté par le processus `git` existant**. + +La capacité d'écriture reste séparée de la lecture dans l'API publique : `GitRepository` n'est pas transformé en interface obligatoire d'écriture pour tous ses implémenteurs. `knowledge-git-api` introduira un contrat d'écriture distinct uniquement lorsque `alpha.2` matérialisera les types nécessaires. + +Aucune nouvelle crate n'est justifiée par le cadrage. L'implémentation appartient à `knowledge-git-lib` et l'orchestration métier future reste dans `knowledge-app-lib` lorsqu'un vrai cas d'usage de proposition/publication sera engagé. + +## Invariants de sécurité et de cohérence + +L'implémentation doit respecter les invariants suivants : + +- aucune commande Git via shell ; +- prompts interactifs désactivés ; +- hooks neutralisés pour les opérations possédées par le backend ; +- identité auteur/committer fournie explicitement, sans dépendre de la configuration Git globale de la machine ; +- base d'écriture obligatoirement une `GitRevision` déjà résolue ; +- chemins de mutation obligatoirement relatifs, normalisés et confinés au worktree ; +- chemins absolus, composants `..`, accès `.git` et échappement par symlink refusés ; +- aucune mutation du snapshot de lecture stable ; +- aucune suppression/réinitialisation silencieuse d'un état inattendu ; +- le résultat d'écriture est une nouvelle révision Git explicite avant toute mise à jour distante ; +- la mise à jour distante porte uniquement sur une branche `refs/heads/...` dans `0.0.3` ; +- la branche distante est mise à jour avec une attente explicite sur son état précédent ; une divergence devient un conflit récupérable ; +- aucun `push --force` non gardé ; +- aucun rebase ou merge automatique pour masquer une divergence ; +- les erreurs publiques ne divulguent ni URL remote, ni credentials, ni arguments sensibles, ni stderr brut. + +## Modèle de concurrence retenu + +Le push doit utiliser une sémantique de comparaison-et-échange : + +```text +expected remote revision + candidate revision + target branch +-> refresh/observation +-> push gardé +-> succès seulement si la cible possède encore l'état attendu +``` + +Pour une nouvelle branche, l'état attendu est l'absence de branche. Pour une branche existante, l'état attendu est une révision explicite. + +Une divergence n'entraîne ni rebase ni écrasement automatique. Le futur workflow de proposition décidera comment présenter et résoudre ce conflit. + +## Scope fonctionnel proposé pour 0.0.3 + +La release doit fournir : + +- un contrat d'écriture Git distinct et provider-neutral ; +- des types de mutation de fichiers suffisamment bornés pour créer/modifier/supprimer un contenu ; +- un worktree d'écriture isolé dérivé d'une révision de base ; +- un commit avec message et identité explicites ; +- une révision candidate vérifiée ; +- un push vers une branche Git générique avec garde sur l'état distant attendu ; +- un résultat de conflit explicite lorsque la branche distante a divergé ; +- des tests d'intégration sur repositories locaux/bare temporaires couvrant succès, création de branche, modification, suppression, conflit et redaction. + +## Hors scope confirmé + +Restent différés : + +- workflow complet de proposition/revue ; +- publication directe déclenchée par une requête utilisateur ; +- rebase/merge automatique ; +- pull/merge request de forge ; +- adapter Gitea ; +- PostgreSQL, migrations et persistance des propositions ; +- auth/admin complète ; +- signature GPG/SSH des commits ; +- Git LFS/submodules ; +- partage concurrent d'une même racine d'état entre plusieurs processus ; +- scheduler et jobs de publication ; +- formats finaux HOWTO/snippet. + +## Ownership + +```text +knowledge-git-api contrat passif d'écriture Git distinct du contrat de lecture +knowledge-git-lib worktree d'écriture, mutations, commit, push gardé et erreurs redacted +knowledge-app-lib inchangée tant qu'aucun cas d'usage produit de proposition/publication n'est matérialisé +``` + +Aucune `knowledge-forge-gitea-lib`, `knowledge-store-postgres-lib` ou autre crate candidate n'est créée par cette release uniquement pour préparer l'avenir. + +## Validation attendue + +Les preuves fonctionnelles doivent utiliser des repositories Git temporaires locaux et un remote bare local. Elles ne doivent dépendre ni d'Internet, ni de Gitea, ni d'un compte utilisateur Git préconfiguré. + +La validation devra notamment démontrer : + +- qu'un commit candidat est descendant de la base attendue ; +- qu'un fichier hors worktree ne peut pas être modifié ; +- qu'une branche absente peut être créée seulement lorsque l'appelant attend explicitement son absence ; +- qu'une branche existante peut avancer lorsque sa révision correspond à l'attente ; +- qu'une divergence concurrente produit un conflit sans écrasement ; +- que l'identité de commit ne provient pas de la configuration globale ; +- que les hooks ne s'exécutent pas ; +- que les erreurs restent expurgées. + +## Conclusion + +`0.0.3` est engagée comme release d'écriture Git contrôlée et push gardé. Le cadrage ne justifie aucun changement de forge, de base de données, d'authentification ou de rendu Web. diff --git a/docs/validation/001-VALIDATION_MATRIX.md b/docs/validation/001-VALIDATION_MATRIX.md index 4fb9ffd..976660c 100644 --- a/docs/validation/001-VALIDATION_MATRIX.md +++ b/docs/validation/001-VALIDATION_MATRIX.md @@ -1,5 +1,5 @@ - + # Matrice de validation Knowledge @@ -840,3 +840,30 @@ La fermeture stable pré-tag doit prouver : - fichiers texte gouvernés terminés par exactement un LF ; - `git diff --check` et `git diff --cached --check` propres ; - aucun tag stable ou rapport post-tag déclaré comme existant avant le history `rel.1` `PASS` et le commit stable. + +## Gate de `0.0.3-alpha.1` + +La première tranche de `0.0.3` est une gate de cadrage sans code produit. Elle doit prouver : + +- `VERSION = 0.0.3-alpha.1` et `[workspace.package].version` identique ; +- baseline Knowledge `v0.0.2` identifiée par commit `183d354a67bec6d2d512c4898f5189759a6120b0`, SHA-256 `0e518c7eaad115811cccc8fb2b38a1e68150ec985c2ca72ec08a9ca5bbb202ce` et rapport `publish.001 PASS` ; +- aucun chargement/adoption PGR nouveau et PGR `v0.1.3` conservé uniquement comme provenance historique ; +- `ROADMAP.md` engage uniquement `0.0.3` après les stables existantes et ne réserve aucune version ultérieure ; +- étude `006` et plan `003` présents ; +- mission bornée à l'écriture Git contrôlée et au push gardé ; +- contrat d'écriture prévu distinct de `GitRepository` afin de préserver les consommateurs lecture seule ; +- rebase/merge automatique, PostgreSQL, forge, auth/admin et workflow complet de proposition encore hors scope ; +- aucun diff sous `crates/` ou `Web/` ; +- aucun history `history/0.0.3/alpha.1.md` présent avant la gate ; +- aucun nouveau package Cargo ou npm et aucune nouvelle dépendance ; +- audits Markdown et hygiène texte propres ; +- `cargo fmt --all` puis `cargo fmt --all -- --check` exécutés avant les audits Rust ; +- audits Rust locaux propres ; +- `cargo metadata`, `cargo check --workspace`, Clippy strict, test d'intégration Git de lecture et tests workspace propres ; +- `Cargo.lock` généré localement si Cargo l'exige, mais ignoré/non suivi ; +- `package-lock.json` inchangé et versionné ; +- `git diff --cached --check` propre avant commit. + +La baseline Web n'est pas rejouée automatiquement dans cette tranche, car aucun fichier sous `Web/` ni contrat runtime Web n'est modifié et la stable `0.0.2` a déjà acquis sa gate complète. + +Un `PASS` de `0.0.3-alpha.1` autorise uniquement la préparation de `0.0.3-alpha.2`. Un autre statut doit d'abord être conservé dans son history puis conduire à un fix borné ou à un REPLAN. diff --git a/history/0.0.3/alpha.1.md b/history/0.0.3/alpha.1.md new file mode 100644 index 0000000..138ce56 --- /dev/null +++ b/history/0.0.3/alpha.1.md @@ -0,0 +1,84 @@ + + + +# History 0.0.3-alpha.1 — cadrage de l'écriture Git contrôlée + +## Statut + +`PARTIAL` + +## Baseline observée + +La tranche a été appliquée sur la stable autoritaire `v0.0.2` puis a porté `VERSION` et le workspace Cargo à : + +```text +0.0.3-alpha.1 +``` + +## Preuves opérateur reçues + +Les preuves transmises le `2026-09-29` montrent : + +- contrôle `VERSION` / `workspace.package.version` conforme ; +- `git diff --check` propre ; +- audits Markdown headers/liens/tables propres ; +- `cargo fmt --all` puis `cargo fmt --all -- --check` PASS ; +- audits Rust structurels propres sur les neuf crates / trente-deux fichiers concernés ; +- `cargo metadata --format-version 1 --no-deps` exécuté ; +- `cargo check --workspace` PASS ; +- `cargo clippy --workspace --all-targets --all-features -- -D warnings` PASS ; +- `cargo test -p knowledge-git-lib --test git_read_path` : `2 passed` ; +- `cargo test --workspace --all-targets --all-features` : tous les tests observés PASS. + +Les comptes observés dans la gate workspace restent cohérents avec la stable : + +```text +knowledge-app-lib 3 PASS +knowledge-domain-lib 3 PASS +knowledge-git-api 1 PASS +knowledge-git-lib 8 unit + 2 integration PASS +knowledge-sync-api 1 PASS +knowledge-web-lib 4 PASS +launchers 0 test chacun, compilation PASS +``` + +## Limites de la gate reçue + +Le retour fourni s'arrête après `cargo test --workspace --all-targets --all-features`. + +Les commandes de fin annoncées dans le delta `alpha.1` ne sont donc pas présentées comme exécutées : + +- audit Python spécifique de cadrage `alpha.1` ; +- audit d'hygiène texte ; +- vérifications finales `crates/` / `Web/`, lockfiles et absence de history prématuré ; +- `git add -A`, `git diff --cached --check` et `git status --short`. + +Cette absence suffit à empêcher un statut `PASS` intégral de la gate telle qu'elle était spécifiée. + +## Revue opérateur du cycle documentaire + +La revue manuelle a en outre identifié trois corrections de gouvernance/documentation à matérialiser avant de poursuivre le développement fonctionnel : + +1. `CHANGELOG.md` ne doit pas être rédigé au démarrage d'une release ; il doit synthétiser les changements réellement acquis vers les phases de stabilisation/fin de release ; +2. le prompt de démarrage de la release suivante doit normalement être préparé pendant les dernières phases de la release en cours, après revue d'horizon ; l'ajout de `prompts/003-V0_0_3_START_PROMPT.md` pendant `0.0.3-alpha.1` est accepté uniquement comme rattrapage parce que `0.0.2` avait été fermée sans ce handoff ; +3. `ROADMAP.md` doit montrer à la fois la release en cours et un horizon borné des releases suivantes, en distinguant clairement l'engagement courant des versions d'horizon encore révisables. + +Ces défauts ne remettent pas en cause la mission Git choisie pour `0.0.3`, mais rendent le cadrage documentaire incomplet. + +## Décision + +`0.0.3-alpha.1` est conservée avec le statut `PARTIAL`. + +La correction reste bornée au workflow documentaire et utilise : + +```text +0.0.3-alpha.1.fix.1 +``` + +Le fix doit : + +- retirer la section candidate `0.0.3` prématurée du changelog ; +- transformer la roadmap en roadmap courante + horizon prévisionnel ; +- rendre explicite chez les owners locaux le moment de rédaction du changelog et du prompt de release suivante ; +- mettre à jour le plan `0.0.3` pour refléter cette correction sans modifier la mission Git ; +- ne modifier aucun code sous `crates/` ni aucun fichier sous `Web/`. diff --git a/prompts/003-V0_0_3_START_PROMPT.md b/prompts/003-V0_0_3_START_PROMPT.md new file mode 100644 index 0000000..1c60289 --- /dev/null +++ b/prompts/003-V0_0_3_START_PROMPT.md @@ -0,0 +1,133 @@ + + + +# Knowledge 0.0.3 — prompt de démarrage + +## Condition d'utilisation + +Ce prompt est matérialisé lors de l'ouverture explicite de `0.0.3`, après fermeture et publication complète de `0.0.2`. + +La reprise n'est valide que si les preuves suivantes sont disponibles : + +```text +history rel.1 de 0.0.2 PASS +commit produit 0.0.2 183d354a67bec6d2d512c4898f5189759a6120b0 +tag stable v0.0.2 publié +archive sasedev-knowledge-v0.0.2.zip vérifiée +rapport post-tag publish.001 PASS +``` + +## Baseline autoritaire + +Partir de : + +```text +tag Knowledge v0.0.2 +commit Knowledge 183d354a67bec6d2d512c4898f5189759a6120b0 +archive SHA-256 0e518c7eaad115811cccc8fb2b38a1e68150ec985c2ca72ec08a9ca5bbb202ce +publish report sasedev-knowledge-0.0.2-publish.001-report.md = PASS +``` + +L'archive taggée est la baseline produit. L'absence de `.git` dans cette archive est normale. + +Ne pas reconstruire l'état depuis une conversation, un workspace local ou une version ultérieure non vérifiée. + +## Autonomie normative + +Knowledge est autonome après l'adoption fermée en `0.0.2`. + +Ne pas rechercher, charger ni adopter automatiquement une nouvelle version de PGR. PGR `v0.1.3` reste uniquement une provenance historique locale. Une réévaluation PGR n'est autorisée que si elle est explicitement ajoutée au scope par un REPLAN ou une release future. + +Relire les owners Knowledge : + +```text +RULES.md +docs/rules/200-GOVERNANCE.md +docs/rules/210-WORKFLOW.md +docs/rules/300-DOCUMENTATION.md +docs/rules/400-VALIDATION.md +docs/rules/510-RUST_CARGO.md +docs/rules/530-WEB_FRONTEND.md +``` + +## Mission + +`0.0.3` matérialise l'écriture Git générique contrôlée et un push gardé indépendant d'une forge. + +La release doit pouvoir : + +- partir d'une `GitRevision` de base explicite ; +- créer un worktree d'écriture isolé sous la racine d'état contrôlée ; +- appliquer des mutations de fichiers confinées ; +- créer un commit avec identité explicite et hooks neutralisés ; +- produire une révision candidate ; +- mettre à jour une branche `refs/heads/...` uniquement si son état distant correspond à l'attente fournie ; +- signaler un conflit sans écraser une divergence concurrente. + +## Contrats à préserver + +Réutiliser la séparation actuelle : + +```text +knowledge-git-api contrats passifs provider-neutral +knowledge-git-lib implémentation process Git contrôlée +knowledge-app-lib orchestration application existante, sans backend Git/DB/forge +``` + +Ne pas transformer le contrat de lecture existant en interface d'écriture obligatoire. Introduire un contrat distinct seulement lorsque les types d'écriture sont matérialisés. + +## Étude obligatoire de cadrage + +Avant toute implémentation fonctionnelle, vérifier : + +- pourquoi l'écriture Git est le prochain axe utile parmi les `DEFER` ; +- worktree d'écriture isolé versus plumbing Git ; +- confinement des chemins et risques `.git`/`..`/symlinks ; +- identité auteur/committer explicite ; +- neutralisation des hooks et prompts ; +- sémantique d'attente distante/compare-and-exchange ; +- création d'une branche absente ; +- conflit sur branche divergente ; +- cleanup après succès/échec ; +- redaction des erreurs ; +- tests reproductibles avec remote bare local. + +Le résultat est documenté dans : + +```text +docs/studies/006-V0_0_3_GIT_WRITE_STUDY.md +``` + +## Non-objectifs + +Ne pas absorber par anticipation : + +- rebase/merge automatique ; +- workflow complet de proposition/revue ; +- PostgreSQL/migrations ; +- Gitea ou autre API de forge ; +- auth/admin ; +- routes HTTP d'écriture ; +- UI de contribution ; +- signature de commits ; +- scheduler/jobs ; +- formats finaux HOWTO/snippet ; +- Git LFS/submodules ; +- partage multi-processus de la racine Git. + +## Première tranche + +`0.0.3-alpha.1` doit : + +1. vérifier intégralement la stable `v0.0.2` et son rapport post-tag ; +2. relire les règles/owners locaux, architecture, roadmap, deltas/histories et `DEFER` ; +3. confirmer qu'aucune adoption PGR n'est engagée ; +4. déterminer et documenter l'écriture Git contrôlée comme mission `0.0.3` ; +5. produire l'étude `006` et le plan `003` ; +6. mettre à jour les documents vivants nécessaires ; +7. ne modifier aucun fichier produit sous `crates/` ou `Web/` ; +8. préparer la gate de cadrage puis attendre le résultat opérateur avant tout history. + +## Sortie attendue + +À la fin de `0.0.3`, Knowledge doit posséder une primitive d'écriture Git générique, sûre et testable permettant de produire puis pousser une révision candidate sans dépendre d'une forge et sans écraser silencieusement une branche ayant divergé.