0.0.3-alpha.1

2026-09-29 09:58:22 +02:00
parent 183d354a67
commit a74a19838f
15 changed files with 1052 additions and 27 deletions
--- a/docs/000-README.md
+++ b/docs/000-README.md
@@ -1,5 +1,5 @@
 <!-- file: docs/000-README.md -->
-<!-- version: 9 -->
+<!-- version: 10 -->

 # 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.
--- a/docs/architecture/001-PROJECT_PROFILE.md
+++ b/docs/architecture/001-PROJECT_PROFILE.md
@@ -1,18 +1,18 @@
 <!-- file: docs/architecture/001-PROJECT_PROFILE.md -->
-<!-- version: 16 -->
+<!-- version: 17 -->

 # 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.
--- a/docs/architecture/002-KNOWLEDGE_ARCHITECTURE.md
+++ b/docs/architecture/002-KNOWLEDGE_ARCHITECTURE.md
@@ -1,5 +1,5 @@
 <!-- file: docs/architecture/002-KNOWLEDGE_ARCHITECTURE.md -->
-<!-- version: 14 -->
+<!-- version: 15 -->

 # 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é.
--- a/docs/plans/003-V0_0_3_GIT_WRITE_PLAN.md
+++ b/docs/plans/003-V0_0_3_GIT_WRITE_PLAN.md
@@ -0,0 +1,223 @@
+<!-- file: docs/plans/003-V0_0_3_GIT_WRITE_PLAN.md -->
+<!-- version: 1 -->
+
+# 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.
--- a/docs/studies/006-V0_0_3_GIT_WRITE_STUDY.md
+++ b/docs/studies/006-V0_0_3_GIT_WRITE_STUDY.md
@@ -0,0 +1,217 @@
+<!-- file: docs/studies/006-V0_0_3_GIT_WRITE_STUDY.md -->
+<!-- version: 1 -->
+
+# É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.
--- a/docs/validation/001-VALIDATION_MATRIX.md
+++ b/docs/validation/001-VALIDATION_MATRIX.md
@@ -1,5 +1,5 @@
 <!-- file: docs/validation/001-VALIDATION_MATRIX.md -->
-<!-- version: 32 -->
+<!-- version: 33 -->

 # 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.