sasedev-knowledge/docs/plans/001-V0_0_1_FOUNDATION_PLAN.md

Plan 0.0.1 — fondation SaseDev Knowledge

Statut et sources

Plan historique de la stable de fondation 0.0.1, préparé après vérification de la stable PGR v0.1.1 et de pgr-0.1.1-publish.001-report.md PASS.

Sources de cadrage :

PGR v0.1.1 archive SHA-256
caaf8f456f7f8520172ea7705fd0cf5c5bf0e942dc4a773410bcbe7fe4ce243a

Knowledge start prompt
prompts/001-V0_0_1_START_PROMPT.md

Mission

0.0.1 doit rendre le nouveau dépôt suffisamment gouverné, reproductible et architecturalement découplé pour commencer ensuite l'implémentation de Knowledge sans coupler le domaine à Gitea, PostgreSQL, Actix ou une représentation éditoriale prématurée.

La release doit établir :

• la gouvernance PGR locale ;
• la composition des owners/skeletons réellement applicables ;
• la topologie du workspace à trois applications Actix Web distinctes ;
• les frontières Git générique / forge optionnelle / PostgreSQL ;
• les frontières PGR / HOWTO / snippet / project-local ;
• un workspace Rust minimal strict et reproductible ;
• une baseline frontend indépendante du backend selon les owners Web PGR ;
• de premiers contrats ciblés sans implémentation disproportionnée ;
• une validation suffisante pour promouvoir une stable 0.0.1.

État acquis et questions ouvertes

Acquis par le cadrage alpha.1.fix.1 :

• dépôt applicatif/workspace sasedev-knowledge, nom court knowledge ;
• trois launchers publics retenus : knowledge-pgr-server, knowledge-howtos-server, knowledge-snippets-server ;
• au moins trois sources Git indépendantes : pgr, howtos, snippets ;
• Git autoritaire pour le contenu ;
• forge facultative derrière adapter ;
• une base PostgreSQL logique partagée pour l'état transversal et les projections ;
• crates communes privilégiées à la duplication entre launchers ;
• Rust stable/édition 2024 ;
• Actix Web, Maud, Vite, TypeScript, Sass, Bootstrap et PostgreSQL retenus comme intentions locales conformes aux owners applicables ;
• préférence Eclipse UTF-8 versionnée conformément à la politique PGR ;
• aucun override PGR nécessaire.

Restent volontairement ouverts jusqu'à la tranche qui les consomme :

• package manager et lockfile frontend ;
• modèle détaillé des rôles/capabilities ;
• racine(s) et partage concret du frontend entre les trois applications ;
• driver/ORM et migrations PostgreSQL ;
• éventuel découpage en schémas PostgreSQL ;
• moteur de recherche ;
• fournisseur d'identité ;
• adapter forge réel ;
• formats finaux HOWTO/snippet ;
• URL et routage exacts des surfaces d'administration/login ;
• décision d'une éventuelle quatrième application d'administration transverse ;
• liste définitive des crates de bibliothèque.

Scope

0.0.1 inclut :

• documentation de gouvernance et architecture ;
• workspace Rust/Cargo minimal ;
• configuration de toolchain/lints proportionnée ;
• trois packages serveur distincts uniquement lorsque leur composition devient utile ;
• premiers types/traits de boundary lorsque leur responsabilité est claire ;
• baseline Web minimale et reproductible ;
• validation indépendante backend/frontend ;
• documentation de fermeture et handoff de la stable.

Hors scope

0.0.1 n'implémente pas :

• moteur de recherche complet ;
• UI d'administration complète ;
• workflow complet de contribution ;
• adapter multi-forge complet ;
• intégration Gitea obligatoire ;
• schéma PostgreSQL métier complet ;
• authentification complète ;
• production multi-domaines ;
• moteur de rendu final de tous les formats ;
• architecture de microservices distribués ;
• quatrième application d'administration sans besoin démontré.

Stratégie de validation

Les gates suivent ../validation/001-VALIDATION_MATRIX.md.

Principes :

• gate documentaire pour alpha.1 et ses fixes ;
• politique Eclipse explicitement contrôlée ;
• Cargo officiel dès matérialisation Rust ;
• audits Rust structurels PGR seulement s'ils apportent une preuve distincte ;
• package manager/TypeScript/Vite/Sass officiels dès matérialisation Web ;
• backend et frontend validables séparément ;
• chaque launcher serveur reçoit un smoke seulement lorsqu'une propriété runtime réelle est introduite ;
• aucune prévalidation assistant ne vaut PASS opérateur.

Trajectoire prévisionnelle

alpha.1 — cadrage et gouvernance

Matérialiser la fondation locale : version, règles, objectifs, profil PGR, architecture, plan, validation, roadmap/changelog et prompt de démarrage.

Le résultat opérateur initial est FAIL. Le fix alpha.1.fix.1 corrige la politique Eclipse, la gate de fichiers et la topologie produit à trois applications. Sa gate opérateur est PASS.

Aucun code fonctionnel n'est ajouté dans alpha.1 ou son fix.

alpha.2 — workspace Rust/Cargo minimal

Statut opérateur : PASS.

Le skeleton 002-RUST_CARGO_WORKSPACE est matérialisé avec knowledge-domain-lib, Cargo.lock versionné, artefacts Cargo hors dépôt et étude auth/admin séparant fonctionnalités réelles et intentions historiques. Les gates metadata, fmt, check, Clippy et tests workspace sont propres.

alpha.3 — contrats domaine/Git/synchronisation

Statut opérateur initial : FAIL.

La gate valide la structure et les audits puis échoue dans knowledge-domain-lib : SourceId::new tente de construire le tuple struct privé via le re-export crate-root depuis son sous-module. Le même défaut bloque cargo check, Clippy et les trois suites ciblées.

alpha.3.fix.1 corrige ce défaut Rust, ajoute une régression directe de construction SourceId et précise la trajectoire Web/Maud fournie avant clôture de la tranche ; il ne démarre aucune implémentation frontend ou serveur. Sa gate opérateur reste toutefois FAIL : cargo check et les tests passent, mais Clippy strict rejette les quatre variantes publiques de ContentFamily non documentées sous missing_docs.

alpha.3.fix.2 corrige exclusivement cette dette de documentation publique et rejoue la gate Rust complète sans modifier les contrats domaine/Git/synchronisation ni le cadrage Web/Maud. Sa gate opérateur reste toutefois FAIL malgré le passage de cargo check, Clippy strict et des trois suites ciblées : git diff --check détecte une ligne vide supplémentaire en fin de docs/validation/001-VALIDATION_MATRIX.md.

alpha.3.fix.3 corrige exclusivement cette anomalie documentaire de fin de fichier, conserve les corrections Rust déjà validées et rejoue la gate complète avant clôture d'alpha.3. Sa gate opérateur est PASS.

Le scope fonctionnel de alpha.3 reste : introduire uniquement les premiers contrats/types nécessaires aux frontières GitRepository, source/famille de contenu et synchronisation, avec tests ciblés. Le modèle doit supporter au moins les trois sources initiales sans coder une limite à trois.

Matérialiser knowledge-git-api et knowledge-sync-api parce que ces frontières ont des implémentations réellement remplaçables/multiples. Garder ces crates passives ; ne pas créer knowledge-git-lib, worker, Gitea ou persistence par anticipation.

Adopter les audits Rust PGR de structure/façade désormais utiles avec les premiers items publics partagés. Ne pas activer globalement l'audit const, qui reste sélection explicite par fichier.

Ne pas ajouter d'API Gitea ni de persistance PostgreSQL par anticipation.

alpha.4 — baseline Web indépendante et templates de référence

Instancier obligatoirement le skeleton 003-WEB_FRONTEND avec les décisions désormais résolues :

package              Web/knowledge-template-lab/
package manager      npm
lockfile             package-lock.json versionné
TypeScript           strict
Vite                 build + dev server + manifest
styles               Sass
framework CSS        Bootstrap

Le package reste partagé entre les trois façades tant qu'aucune divergence réelle ne justifie une séparation. Il sert d’abord de laboratoire de templates statiques : développer et valider indépendamment le markup de référence, les comportements TypeScript, le responsive Bootstrap et les styles Sass avant adaptation du markup runtime en Maud. Les pages statiques ne deviennent pas une seconde UI de production.

Le build Vite active le manifest et matérialise une entrée stable src/main.ts. Cette entrée importe la chaîne Sass afin que le manifest relie l'entrée logique aux sorties JavaScript/CSS hashées consommables plus tard par Maud.

Les outputs et caches restent sous ../builds/sasedev-knowledge/ et hors Git. La gate doit prouver une restauration reproductible depuis package-lock.json, un typecheck séparé, le build Vite, un manifest parsable et la présence des assets attendus.

La preuve contre la dérive statique/Maud reste volontairement limitée à cette tranche : le package de référence documente les invariants de classes/attributs/assets, tandis que la comparaison runtime réelle n'existe qu'après matérialisation Maud en alpha.5.

La gate opérateur d'alpha.4 reste FAIL malgré le passage de Cargo, Clippy, des tests Rust, de npm ci, du build Vite et de l'audit du manifest :

• npm run typecheck échoue sur l'import side-effect ./styles/main.scss faute de types client Vite déclarés ;
• git diff --check détecte une ligne vide supplémentaire en fin de docs/validation/001-VALIDATION_MATRIX.md.

alpha.4.fix.1 corrige exclusivement ces deux défauts : ajout de vite/client aux types TypeScript du package et hygiène EOF de la matrice. Les warnings Sass provenant de Bootstrap restent des diagnostics de dépendance tierce non bloquants. La politique npm allowScripts reste observée sans approbation automatique.

La gate opérateur d'alpha.4.fix.1 reste FAIL. L'hygiène Git est corrigée et le build/manifest restent propres, mais le typecheck expose deux besoins supplémentaires de la toolchain :

• les déclarations Vite et sass-embedded utilisent les types Node (Buffer, NodeJS, node:*) ;
• Rolldown utilise Symbol.asyncDispose, qui nécessite la bibliothèque TypeScript ESNext.Disposable lorsque le target reste ES2022.

L'audit structurel du fix contenait également une vérification trop large de tous les *.d.ts sous Web/, incluant node_modules; il doit être limité aux déclarations appartenant au source du projet.

alpha.4.fix.2 ajoute donc @types/node sur la branche Node 24, expose les types node, ajoute ESNext.Disposable et corrige uniquement la gate structurelle associée. Aucun scope runtime n'est ajouté. Sa gate opérateur est PASS : typecheck et build Vite passent, le manifest est valide, les gates Rust restent propres et le warning @parcel/watcher demeure seulement observable sans approbation automatique.

alpha.5 — composition Actix/Maud et manifest Vite

Matérialiser knowledge-web-lib comme owner partagé de la composition Actix/Maud et trois launchers minces :

knowledge-pgr-server
knowledge-howtos-server
knowledge-snippets-server

Les launchers ne possèdent que la sélection de façade et du nom de variable de bind. knowledge-web-lib possède les routes publiques minimales / et /healthz, le rendu Maud et l'intégration Vite.

En développement, KNOWLEDGE_VITE_DEV_ORIGIN fournit l'origin et la page charge @vite/client puis src/main.ts. En production, KNOWLEDGE_VITE_MANIFEST_PATH fournit le manifest ; l'entrée stable src/main.ts est résolue vers ses assets hashés et le répertoire assets/ est servi par Actix Files. KNOWLEDGE_ASSET_BASE_PATH garde le préfixe de production configurable. Configurer simultanément dev-origin et manifest est une erreur récupérable.

Les binds sont exclusivement configurés par KNOWLEDGE_PGR_BIND_ADDRESS, KNOWLEDGE_HOWTOS_BIND_ADDRESS et KNOWLEDGE_SNIPPETS_BIND_ADDRESS. Aucun port de déploiement n'est codé en dur.

La gate doit couvrir les tests knowledge-web-lib, la compilation/Clippy des quatre nouvelles crates, le build Vite et un smoke HTTP production des trois launchers vérifiant /healthz, le rendu Maud et le service réel des assets hashés.

La tranche ne doit pas introduire admin complète, auth complète, persistance métier complète, logging transverse artificiel ni forge obligatoire.

La gate technique d'alpha.5 est verte : structure, Web, Cargo, Clippy, tests et smokes HTTP passent. La tranche reste néanmoins FAIL après revue opérateur de gouvernance : les tests unitaires sont encore implémentés sous src/unit_tests.rs, alors que Knowledge sélectionne désormais la convention PGR optionnelle unit_tests/ séparée et miroir de src/.

Le défaut existait déjà dans les trois crates antérieures et est également introduit par knowledge-web-lib; il doit donc être corrigé globalement et non seulement dans la nouvelle crate.

alpha.5.fix.1 :

• formalise cette convention locale comme MUST dans RULES.md ;
• déplace les tests unitaires des quatre crates concernées sous unit_tests/ ;
• rattache les tests avec #[cfg(test)] + #[path = "..."] ;
• conserve tests/ pour les tests d'intégration Cargo uniquement ;
• ajoute un audit monotâche empêchant le retour de #[test] ou de fichiers unit_tests.rs sous src/.

La gate opérateur d'alpha.5.fix.1 reste FAIL : le premier git diff --check détecte une ligne vide supplémentaire en fin de crates/knowledge-domain-lib/src/lib.rs et de crates/knowledge-web-lib/src/lib.rs. cargo fmt normalise ensuite ces deux fichiers et la totalité des audits/tests Rust ainsi que la baseline Web passent. Le smoke HTTP demandé n'est pas rejoué dans le transcript du fix.

Le snapshot alpha.5.fix.1 committé après history contient donc déjà la normalisation rustfmt observée. alpha.5.fix.2 ne réécrit pas artificiellement les deux lib.rs : il avance la tranche, documente le défaut et rejoue la gate sans exécuter de formatage mutateur avant cargo fmt --check. Les trois smokes HTTP sont de nouveau obligatoires.

beta.1 — réconciliation de fondation

Réconcilier la fondation réellement matérialisée sans expansion fonctionnelle.

La tranche doit :

• confirmer les sept packages Rust et le package Web de référence ;
• corriger les formulations documentaires devenues obsolètes après alpha.4/alpha.5 ;
• confirmer que knowledge-git-api et knowledge-sync-api restent passifs ;
• confirmer le layout unit_tests/ comme convention locale ;
• confirmer que PostgreSQL, forge, auth/admin complète, formats finaux et workflow d'écriture restent différés ;
• réaliser la revue d'horizon ;
• préparer un handoff uniquement si une prochaine mission est suffisamment décidée.

La revue d'horizon engage uniquement :

0.0.2 — Git générique et synchronisation de lecture

Aucun numéro ultérieur n'est réservé.

La mission et ses non-objectifs sont possédés par ../studies/003-V0_0_1_FOUNDATION_RECONCILIATION.md.

Le prompt ../../prompts/002-V0_0_2_START_PROMPT.md est préparé mais reste bloqué jusqu'à publication stable et rapport post-tag PASS de 0.0.1.

Aucun nouveau crate runtime, contrat métier, dépendance, route, schéma SQL ou comportement Git n'entre dans beta.1.

rc.1 — candidate stable

Geler le scope fonctionnel de 0.0.1 et exécuter la gate complète de release candidate.

La RC ne modifie aucun code Rust, package Web, dépendance, roadmap, changelog candidat, étude de fondation ou prompt de reprise. Elle doit uniquement :

• porter VERSION = 0.0.1-rc.1 et la version workspace identique ;
• vérifier les quatorze histories antérieurs et leurs statuts réels ;
• vérifier que rc.1 est la seule tranche possédant un delta sans history pendant sa gate ;
• confirmer le changelog 0.0.1 (candidate) sans détails de fixes internes ;
• confirmer la roadmap avec 0.0.1 encore planifié, 0.0.2 engagé et aucun 0.0.3 réservé ;
• confirmer le handoff 002 bloqué jusqu'à la stable taggée et au rapport post-tag PASS ;
• confirmer les DEFER de fondation ;
• rejouer audits Markdown, audits Rust, Cargo/Clippy/tests, baseline Web, manifest Vite et les trois smokes HTTP ;
• vérifier l'hygiène texte et Git.

Un défaut fonctionnel important découvert en RC impose un retour de phase ou un REPLAN ; il ne doit pas être absorbé silencieusement dans la promotion stable.

La gate opérateur de rc.1 reste FAIL à cause d'une assertion de gate incorrecte : git diff --name-only ne liste pas le delta rc.1.md encore non suivi, bien qu'il soit présent et ensuite correctement stage.

Avant la stable, une décision locale supplémentaire est prise : Cargo.lock ne sera plus versionné. rc.1.fix.1 corrige donc la gate, ajoute /Cargo.lock au .gitignore, retire le lockfile de l'index sans supprimer sa copie locale et réconcilie les documents vivants. Les anciennes tranches continuent de documenter fidèlement la politique appliquée au moment où elles ont été exécutées.

La gate opérateur de rc.1.fix.1 est PASS : Cargo.lock reste local/ignoré/non suivi, package-lock.json reste versionné et l'ensemble des audits Rust/Web/HTTP passe.

rc.2 — candidate finale sur politique stabilisée

Rejouer une release candidate complète après le changement de politique Cargo.lock.

rc.2 ne modifie aucun code Rust, frontend, règle de produit, dépendance, roadmap, changelog candidat, étude ou prompt. Elle doit uniquement :

• porter VERSION = 0.0.1-rc.2 et la version workspace identique ;
• confirmer que Cargo.lock reste présent localement, ignoré et absent de Git ;
• confirmer que package-lock.json reste suivi ;
• vérifier les seize histories antérieurs avec leurs statuts réels ;
• confirmer que rc.2 est le seul delta courant sans history pendant sa gate ;
• rejouer la gate RC complète sur le scope final ;
• autoriser rel.1 uniquement après PASS.

Statut opérateur : PASS.

La candidate finale a été validée après récupération d'un commit local erroné non publié. La récupération n'a modifié ni le contenu rc.2 ni origin/master, et l'intégralité de la gate RC a ensuite été confirmée.

rel.1 — fermeture stable

Promotion mécanique pré-tag de la candidate validée vers 0.0.1.

La tranche :

• porte VERSION = 0.0.1 et la version workspace Cargo identique ;
• marque 0.0.1 terminée dans ROADMAP.md ;
• retire le marqueur candidate du CHANGELOG.md ;
• présente README.md, l'index documentaire et le présent plan comme état stable/historique ;
• conserve 0.0.2 comme seule prochaine release engagée ;
• conserve le prompt 002 conditionnel à la publication réelle de v0.0.1 et au rapport post-tag PASS ;
• ne modifie aucun fichier sous crates/ ou Web/, aucune dépendance et aucun contrat technique.

Le résultat opérateur appartient à history/0.0.1/rel.1.md, créé uniquement après la gate.

Si rel.1 est PASS, son history est appliqué puis le commit produit porte le message exact 0.0.1. Le tag stable v0.0.1 n'est créé et poussé qu'après ce commit et son push sur la branche canonique.

La vérification post-tag est séparée et doit produire sasedev-knowledge-0.0.1-publish.001-report.md à partir de l'archive réellement téléchargée depuis le tag et des preuves Git observées. Le prompt 002 reste bloqué jusqu'à un publish.001 PASS réel.

Déclencheurs de REPLAN

REPLAN obligatoire si :

• une tranche nécessite plusieurs responsabilités non prévues qui ne peuvent plus être validées proprement ensemble ;
• un choix de crate impose un couplage du domaine à Actix/Gitea/PostgreSQL ;
• les trois launchers entraînent une duplication de logique qui devrait être possédée par une crate commune ;
• une future administration transverse tente de contourner ou remplacer les contrôles d'autorisation propres aux trois applications ;
• le frontend ne peut pas être validé indépendamment du host sans raison architecturale réelle ;
• le choix Git impose une API de forge pour une opération fondamentale ;
• la base PostgreSQL partagée impose un couplage de contenu qui contredit l'autorité Git ;
• le format de contenu doit être figé sans corpus représentatif ;
• trois fixes ou plus apparaissent sur une même tranche ;
• un prérequis externe invalide la mission de fondation.

Clôture et transition

• documentation durable : réconciliée à chaque tranche qui change son contrat, puis revue en beta.1 ;
• CHANGELOG.md : entrée candidate tenue à jour puis finalisée en rel.1 ;
• ROADMAP.md : revue d'horizon en beta.1, sans création automatique d'une prochaine version ;
• prompt/handoff suivant : préparé avant la clôture une fois la prochaine mission réellement décidée ;
• fermeture du plan : rel.1 ou son fix qui établit la stable ;
• publication : commit produit 0.0.1, tag stable puis rapport post-tag séparé.

Revue d'horizon

État après gate opérateur beta.1 : PASS.

Décision matérialisée :

• engager 0.0.2 pour l'implémentation Git générique et la synchronisation réelle de lecture ;
• ne réserver aucun numéro après 0.0.2 ;
• conserver PostgreSQL, parsing/index, propositions/admin/auth, forge et publication en domaines futurs non numérotés ;
• préparer le prompt 002-V0_0_2_START_PROMPT.md, exécutable seulement après publication vérifiée de 0.0.1.

La revue complète et les critères de reprise sont possédés par ../studies/003-V0_0_1_FOUNDATION_RECONCILIATION.md.