sasedev-knowledge/docs/studies/007-V0_0_3_GIT_WRITE_RECONCILIATION.md

Réconciliation 0.0.3 — écriture Git et horizon produit

Objet

Cette étude de 0.0.3-beta.1 réconcilie la mission d'écriture Git avec ce qui est réellement matérialisé par les alphas, puis réévalue l'horizon produit de SaseDev Knowledge avant la release candidate.

Elle n'ajoute aucune fonctionnalité. Elle sert de baseline durable pour stabiliser 0.0.3 et préparer la prochaine release sans consulter ni réadopter automatiquement une nouvelle version de PGR.

Chemin Git réellement obtenu

La lecture et l'écriture restent deux capacités provider-neutral distinctes :

GitRepository
  refresh
  resolve_revision
  prepare_snapshot

GitRepositoryWriter
  create_candidate
  push_candidate

Le chemin d'écriture réellement validé est :

GitRevision de base explicite
-> worktree d'écriture isolé
-> mutations create/update/delete confinées
-> commit avec identité explicite et hooks/config ambiante neutralisés
-> vérification du parent exact
-> référence interne refs/knowledge/candidates/<revision>
-> observation distante de refs/heads/...
-> push --force-with-lease contre l'état attendu
-> Updated(candidate) ou Conflict { actual }

Aucun adapter de forge, rebase/merge automatique ou force-push non gardé n'est nécessaire pour cette primitive.

Invariants acquis

0.0.3 acquiert les propriétés suivantes :

• chemins de mutation relatifs et normalisés, avec .git, traversées et doublons refusés ;
• vérification filesystem empêchant une traversée par symlink hors du worktree contrôlé ;
• auteur et committer fournis explicitement ;
• hooks Git désactivés pour le commit candidat ;
• configuration Git système/globale pertinente neutralisée ;
• candidat enfant direct de la base demandée ;
• candidat retenu par une ref backend interne avant nettoyage du worktree ;
• branche distante limitée à refs/heads/... ;
• création de branche uniquement lorsque son absence est attendue ;
• mise à jour d'une branche existante uniquement contre sa révision attendue ;
• --force-with-lease comme garde autoritaire contre la course concurrente ;
• divergence représentée comme conflit récupérable sans écrasement.

Ces invariants sont démontrés par des tests d'intégration utilisant uniquement des repositories et remotes bare locaux.

DEFER reclassés

Reclassé comme prochaine mission

La persistance PostgreSQL partagée est désormais le prochain axe structurant. Le chemin Git de lecture et d'écriture étant disponible, les futures façades ont besoin d'un état durable commun pour la configuration logique, la dernière révision synchronisée/indexée, les projections et les futurs workflows transversaux.

0.0.4 est donc retenue comme prochaine mission :

fondation PostgreSQL partagée + premier schéma + migrations

Cette décision n'impose pas encore :

• un driver/ORM particulier ;
• un pool particulier ;
• une stratégie Docker/service système particulière pour les tests ;
• un schéma de contenu final PGR/HOWTO/snippet ;
• auth, propositions ou moteur de recherche complet.

Ces points appartiennent à l'étude de démarrage de 0.0.4.

Toujours différés

Restent DEFER ou hors horizon numéroté tant que leur déclencheur n'est pas réel :

• rebase/merge automatique ;
• adapter Gitea ou autre forge et webhooks forge-only ;
• scheduler/jobs concrets ;
• moteur de recherche avancé au-delà des besoins de projection réellement observés ;
• quatrième application d'administration transverse ;
• partage simultané d'une même racine Git par plusieurs processus ;
• Git LFS/submodules ;
• politique avancée de rétention/cleanup ;
• observabilité ou service supplémentaire sans owner démontré.

Horizon produit des trois sites

L'objectif produit n'est pas une succession de seules briques backend. Knowledge vise trois façades distinctes utilisant le même socle Git/PostgreSQL :

pgr.sasedev.com       affichage et gestion de PGR
howtos.sasedev.com    affichage et gestion des HOWTOs
snippets.sasedev.com  affichage et gestion des snippets

La revue beta distingue donc les phases suivantes.

0.0.4 — PostgreSQL partagé

Matérialiser la base logique commune, ses migrations et l'état minimal transversal/reconstructible sans déplacer l'autorité éditoriale hors de Git.

0.0.5 — modèles de contenu et projections

Travailler sur des corpus réels PGR/HOWTO/snippet, définir parsing/validation, métadonnées et relations nécessaires, puis produire les projections locales consommables par les façades.

0.0.6 — templates publics

Développer dans Web/knowledge-template-lab les références visuelles des trois sites : pages de garde, navigation, listes, détails, composants communs et états de recherche/filtrage visibles.

Cette phase valide le design et les contrats de markup/assets indépendamment du runtime Rust.

0.0.7 — templates d'administration

Développer les surfaces de gestion propres aux trois sites : dashboards, formulaires d'édition, listes d'objets, états de proposition/revue et retours d'erreur utiles.

Ces templates restent une référence de conception ; ils ne constituent pas encore une UI runtime complète.

0.0.8 — Actix Web / Maud public

Matérialiser les routes publiques réelles dans les trois launchers et adapter en Maud les templates publics validés. Les pages sont alimentées par les sources Git/projections locales et conservent le pipeline Vite/assets commun.

0.0.9 — Actix Web / Maud admin et autorisation

Matérialiser les besoins réels d'identité/session/capabilities, protéger les routes d'administration par façade et adapter en Maud les templates admin validés.

0.0.10 — gestion, proposition, revue et publication

Relier les interfaces d'administration aux cas d'usage applicatifs : édition/proposition basée sur une révision Git connue, revue, conflit explicite, création/push de la révision Git autoritaire, puis réconciliation PostgreSQL.

Pourquoi séparer templates et Maud

Le laboratoire Web existe précisément pour concevoir et valider les références statiques sans lier chaque décision visuelle au cycle de compilation serveur.

La trajectoire retenue est donc :

conception/validation template
-> contrat de composants/classes/assets utile
-> adaptation Maud
-> routes et données runtime

Cela évite deux écueils :

• concevoir l'interface directement dans le code Maud avant validation visuelle ;
• maintenir durablement deux produits UI indépendants, l'un statique et l'autre runtime.

La future phase d'intégration doit définir des invariants ciblés permettant de détecter une dérive significative entre les références validées et leur adaptation Maud, sans imposer une duplication exhaustive.

Changelog et handoff

beta.1 est la première phase où l'implémentation de 0.0.3 est suffisamment acquise pour préparer une entrée ## 0.0.3 (candidate) décrivant les capacités réelles plutôt que les intentions alpha.

La mission 0.0.4 est également suffisamment définie pour préparer maintenant :

prompts/004-V0_0_4_START_PROMPT.md

Le prompt ne contient pas de commit stable, SHA-256 d'archive ou résultat post-tag inventé pour v0.0.3. Ces preuves devront être fournies et vérifiées après publication réelle de la stable.

Conclusion

Le scope fonctionnel de 0.0.3 est cohérent avec sa mission et peut entrer en stabilisation sans nouveau code produit. La release candidate doit geler ce résultat et rejouer la preuve complète applicable.

La trajectoire suivante est désormais lisible à l'échelle du produit : Git lecture/écriture acquis, PostgreSQL ensuite, puis contenu/projections, conception des interfaces publiques et admin, adaptation Actix/Maud et enfin workflows de gestion/publication.