0.0.3-alpha.1

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.