# 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` a produit une gate technique propre jusqu'aux tests workspace mais reste `PARTIAL` : la fin de gate n'a pas été fournie et la revue opérateur a détecté un mauvais cycle de rédaction du changelog, du prompt suivant et de la roadmap. `0.0.3-alpha.1.fix.1` corrige uniquement ce workflow documentaire avant l'implémentation fonctionnelle. ## 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` et établir un premier horizon au-delà d'elle ; - mettre à jour les owners/architecture vivants nécessaires ; - établir le présent plan ; - créer exceptionnellement `prompts/003-V0_0_3_START_PROMPT.md` comme rattrapage, puisque `0.0.2` avait été fermée sans prochaine mission décidée ; - ne modifier aucun code sous `crates/` ni `Web/`. ### alpha.1.fix.1 — correction du cycle documentaire - conserver `alpha.1` comme `PARTIAL` sans réécrire ses preuves ; - retirer du changelog l'entrée candidate écrite prématurément ; - faire de la roadmap une vue de la release en cours plus un horizon prévisionnel borné ; - codifier que le changelog est rédigé vers la stabilisation à partir des changements réellement acquis ; - codifier que le prompt de `N+1` est normalement préparé pendant les dernières phases de `N`, après revue d'horizon ; - garder `prompts/003-V0_0_3_START_PROMPT.md` comme rattrapage historique valide ; - ne modifier aucun code sous `crates/` ni `Web/`. ### alpha.1.fix.2 — complétion de la preuve opérateur - conserver `alpha.1.fix.1` comme `PARTIAL` sans réécrire les preuves observées ; - ne modifier aucune décision fonctionnelle du cadrage ; - rejouer la gate utile et terminer explicitement les assertions documentaires, l'hygiène texte, l'invariance `crates/` / `Web/`, la politique `Cargo.lock` et le staging ; - ne modifier aucun code sous `crates/` ni `Web/` ; - autoriser `alpha.2` uniquement après un `PASS` complet. ### 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 ; - réévaluer `0.0.4` comme prochaine mission potentielle et l'horizon `0.0.5` / `0.0.6` / `0.0.7` ; - réordonner, scinder ou dénuméroter ces horizons si les preuves de `0.0.3` le justifient ; - si `0.0.4` est suffisamment décidée, préparer son prompt de démarrage avant la clôture stable de `0.0.3`. ### 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` ; - finaliser le changelog à partir du scope réellement acquis ; - fermer roadmap/plan sans nouveau scope et vérifier que le handoff de la prochaine release décidée est déjà présent ; - 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. Le `PARTIAL` de `alpha.1` a autorisé `0.0.3-alpha.1.fix.1`. Le retour opérateur de ce premier fix reste `PARTIAL` parce que son transcript s'arrête avant les assertions finales imposées par le delta ; il autorise donc uniquement `0.0.3-alpha.1.fix.2`. Un `PASS` complet de `alpha.1.fix.2` autorise `0.0.3-alpha.2`. Tout autre statut produit d'abord son history puis un nouveau fix ou REPLAN selon le diagnostic. ## Revue d'horizon `alpha.1.fix.1` établit un horizon prévisionnel afin que `0.0.3` ne soit pas développée isolément : ```text 0.0.4 PostgreSQL partagé et migrations 0.0.5 contenu structuré et lecture publique 0.0.6 identité / autorisation / administration locale 0.0.7 propositions / revue / publication ``` Ces numéros sont des horizons, pas encore des missions engagées. `beta.1` doit les réévaluer à la lumière de l'implémentation réelle de `0.0.3`, confirmer ou modifier la prochaine mission et préparer le prompt de cette mission pendant la fin de `0.0.3` si elle est suffisamment définie. Recherche avancée, adapters de forge, scheduler, administration transverse, opérations multi-domaines et autres `DEFER` restent reclassables ultérieurement.