sasedev-knowledge/docs/plans/003-V0_0_3_GIT_WRITE_PLAN.md

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 :

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 et alpha.1.fix.1 sont conservées PARTIAL avec leurs preuves réelles. alpha.1.fix.2 a complété la gate documentaire et technique en PASS, ce qui ferme le cadrage et autorise alpha.2. alpha.2 matérialise maintenant uniquement le contrat d'écriture provider-neutral dans knowledge-git-api; le backend de worktree reste réservé à alpha.3.

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 :

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 :

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 :

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.