# Règles SaseDev Knowledge ## Scope Ce document gouverne le workspace applicatif `sasedev-knowledge` et sert de point d'entrée normatif local. Le contenu éditorial publié par PGR, HOWTOs et snippets vit dans des dépôts Git distincts et conserve sa propre gouvernance. Les règles de ce dépôt ne transforment pas ces contenus en sous-modules normatifs de l'application. ## Baseline PGR La fondation `0.0.1` est cadrée à partir de la stable PGR `v0.1.1`, vérifiée par son rapport post-tag `publish.001` `PASS`. Empreinte de l'archive PGR autoritaire utilisée pour ce cadrage : ```text SHA-256 caaf8f456f7f8520172ea7705fd0cf5c5bf0e942dc4a773410bcbe7fe4ce243a ``` Les contrats PGR adoptés sont instanciés localement dans ce dépôt. PGR n'est pas une dépendance runtime ou build de Knowledge. ## Owners PGR applicables La fondation retient les owners suivants dans leur scope réel : ```text 200 gouvernance et lifecycle 210 workflow plan/delta/history/handoff 220 composition des skeletons pendant l'instanciation 300 documentation 400 validation proportionnée 500 famille langage/écosystème 510 Rust/Cargo 530 TypeScript 540 écosystème de packages JavaScript 550 Vite lorsque Vite est sélectionné 560 CSS/Sass 700 famille framework pour les frameworks réellement utilisés ``` Les skeletons `001-PROJECT_GOVERNANCE_FOUNDATION`, `002-RUST_CARGO_WORKSPACE` et `003-WEB_FRONTEND` sont les spécialisations retenues pour `0.0.1`, avec matérialisation progressive selon le plan. Le profil `710-TAURI` n'est pas applicable au produit Web actuel. Aucun skeleton Tauri n'est adopté. Les profils Java/Maven/Gradle, Android et les autres technologies absentes du projet restent hors scope. ## Priorité et décisions locales Les obligations PGR réellement adoptées priment sur une préférence locale de Knowledge dans le même scope. Les choix propres au produit restent locaux lorsqu'aucun owner PGR plus spécifique ne les impose. C'est notamment le cas de l'architecture Git/forge/PostgreSQL, du choix Actix Web/Maud, de Bootstrap, de la topologie à trois applications Web et de la topologie des dépôts de contenu. Aucun `OVERRIDE` PGR n'est établi par `0.0.1-alpha.1.fix.1`. Les décisions différées sont explicites dans [`docs/architecture/001-PROJECT_PROFILE.md`](docs/architecture/001-PROJECT_PROFILE.md). Une valeur différée ne doit pas être remplacée par un choix arbitraire provenant d'un autre projet. ## Version et workflow `VERSION` est le repère canonique simple de la release unit applicative. Knowledge adopte le workflow PGR : ```text delta -> application -> gate opérateur -> history observé -> application du history -> commit/push -> delta suivant ``` Une prévalidation par l'assistant ne constitue jamais un `PASS` opérateur. Les `FAIL`, `PARTIAL` et `BLOCKED` observés sont conservés. Une correction limitée à la tranche courante utilise `.fix.N`. Aucun history n'est créé avant réception de preuves opérateur réelles. ## Politique Eclipse et fichiers locaux Les métadonnées Eclipse propres à une machine restent ignorées, notamment `.project`, `.classpath` et les préférences non partagées. L'exception versionnée est : ```text .settings/org.eclipse.core.resources.prefs ``` Elle fixe l'encodage UTF-8 du projet et doit rester traquée par Git. Le `.gitignore` doit donc ignorer `.settings/*` puis réautoriser explicitement ce fichier. ## Topologie applicative Le workspace possède trois applications serveur distinctes : ```text knowledge-pgr-server knowledge-howtos-server knowledge-snippets-server ``` Chaque package exécutable reste une couche de composition mince conformément au profil Rust/Cargo PGR. La logique partagée appartient aux crates `-lib` appropriées et ne doit pas être dupliquée entre les trois `main.rs`. Les trois applications peuvent être déployées, redémarrées et dimensionnées séparément. Cette séparation de launchers ne constitue pas une autorisation à fragmenter arbitrairement le domaine en microservices. Chaque application serveur MUST pouvoir protéger une surface d'administration propre à son domaine. Cette exigence porte sur la frontière d'autorisation et non sur un chemin HTTP particulier : les routes telles que `/admin`, `/login`, `/adminapi` ou toute alternative restent `DEFER` tant que le routage Web n'est pas matérialisé. Une éventuelle quatrième application d'administration MAY agréger plus tard des fonctions transversales. Elle MUST NOT devenir l'unique point de contrôle des opérations privilégiées : les trois applications conservent l'autorisation côté serveur de leurs propres cas d'usage d'administration. Le modèle détaillé des rôles, permissions, scopes ou capabilities reste `DEFER`. L'interface cliente ou la visibilité d'un lien d'administration ne constitue jamais à elle seule une preuve d'autorisation. ## Git, forge et contenu Git est la source autoritaire du contenu versionné publié. Le domaine MUST pouvoir fonctionner avec un dépôt Git local ou un remote Git générique sans API de forge. La baseline prévoit au minimum trois sources de contenu indépendantes : `pgr`, `howtos` et `snippets`. Une famille MAY ultérieurement agréger plusieurs repositories ; le nombre trois n'est donc pas codé comme limite du domaine. Les capacités spécifiques d'une forge — webhooks, pull/merge requests, issues, releases, permissions et métadonnées similaires — MUST rester derrière des adapters optionnels. Une proposition externe MUST conserver la révision Git de base et MUST NOT écrire directement dans le contenu publié. La synchronisation générique MUST disposer d'une voie indépendante des webhooks. Les hooks et webhooks MAY accélérer une synchronisation qui converge vers le même cas d'usage interne. ## PostgreSQL PostgreSQL est destiné à l'état applicatif : comptes, sessions, propositions, revues, audit applicatif, index, recherche, synchronisation et jobs. La baseline de fondation retient une base PostgreSQL logique partagée par les trois applications afin de conserver un état transversal cohérent et de permettre les relations entre PGR, HOWTOs et snippets. Une séparation physique ultérieure reste possible seulement si une contrainte observée la justifie. Le texte et les métadonnées éditoriales qui constituent le contenu publié restent autoritaires dans Git. Une copie ou projection PostgreSQL de ces données est dérivée et reconstructible. Le choix du driver, de l'ORM ou de la stratégie de migration reste différé jusqu'à une tranche qui en a réellement besoin. ## Frontières documentaires Knowledge distingue au minimum : ```text PGR connaissance normative HOWTO guidance procédurale et explicative snippet exemple court et contextualisé project-local décision instanciée dans un projet précis ``` Une référence entre ces familles ne change pas leur force normative. Un HOWTO ou snippet MAY référencer une règle/owner PGR. Une règle PGR MAY référencer une guidance externe uniquement comme ressource facultative ; PGR doit rester intelligible sans elle. ## Stack locale de départ Sous réserve des décisions différées et de la matérialisation par tranche, Knowledge retient comme intentions locales : - Rust stable, édition 2024 et workspace Cargo ; - trois launchers Actix Web distincts pour PGR, HOWTOs et snippets ; - Maud pour le SSR lorsque pertinent ; - Vite + TypeScript pour les assets et interactions frontend ; - Sass ; - Bootstrap ; - PostgreSQL partagé pour l'état applicatif transversal. Ces choix ne sont pas présentés comme des règles PGR universelles. ## Contrat frontend statique / Maud La baseline Web de `0.0.1` est matérialisée sous : ```text Web/knowledge-template-lab/ ``` Le package manager sélectionné est npm. Le fichier `package-lock.json` produit par npm est versionné dès la première restauration de dépendances. `node_modules/`, le cache Vite et les outputs de build restent générés/hors Git. Le package utilise TypeScript strict, Vite, Sass et Bootstrap. Bootstrap est un choix local Knowledge ; il ne devient pas une règle PGR universelle. Le skeleton Web PGR `003-WEB_FRONTEND` et sa validation associée sont obligatoires pour `0.0.1`. Le frontend contrôlé doit utiliser la chaîne réellement sélectionnée TypeScript + Vite + Sass + Bootstrap pour valider indépendamment du backend les assets, comportements client et templates statiques de référence. Les templates statiques servent de support de conception, prévisualisation et validation navigateur. Ils MUST NOT devenir silencieusement une seconde implémentation runtime divergente : le HTML servi en production par les applications Actix est rendu avec Maud, et toute adaptation depuis le template de référence doit préserver explicitement les contrats utiles de structure, classes, attributs et assets. Le build Vite de production MUST produire un mapping machine-readable des entrées hashées, typiquement le manifest Vite. L’intégration Actix/Maud MUST résoudre ses URLs d’assets depuis ce mapping plutôt que coder les noms hashés. En mode développement, un dev server Vite MAY fournir les entrées directement. Les origins, ports, préfixes de ressources et chemins de manifest MUST être configurables ou possédés explicitement par la configuration réelle ; ils ne doivent pas être copiés comme constantes depuis un corpus historique. Le pattern de loader observé dans `actix-auth-app` est un corpus d’inspiration. Sa reprise doit être réévaluée selon les règles Rust Knowledge : pas de `panic!`/`unwrap`/`expect`, erreurs récupérables, API minimale, tests ciblés et séparation claire entre debug/dev et production. `knowledge-web-lib` possède ce contrat partagé à partir d'`alpha.5`. En développement, `KNOWLEDGE_VITE_DEV_ORIGIN` MUST fournir l'origin du dev server et le renderer charge `@vite/client` puis `src/main.ts`. En production, `KNOWLEDGE_VITE_MANIFEST_PATH` MUST désigner le manifest généré et les noms hashés sont résolus depuis l'entrée stable `src/main.ts`. `KNOWLEDGE_ASSET_BASE_PATH` MAY remplacer le préfixe de production `/`. Les trois launchers MUST recevoir leur socket de bind par configuration (`KNOWLEDGE_PGR_BIND_ADDRESS`, `KNOWLEDGE_HOWTOS_BIND_ADDRESS`, `KNOWLEDGE_SNIPPETS_BIND_ADDRESS`). Aucun port de déploiement n'est choisi par le code. Les seules routes matérialisées par la fondation sont `/` et `/healthz`; cela ne fixe aucune convention future pour l'authentification ou l'administration. ## Rust et crates ### Politique `Cargo.lock` PGR `v0.1.1` exige une décision explicite de lockfile selon le type de produit et le besoin de reproductibilité ; il n'impose pas universellement le versionnement de `Cargo.lock`. Knowledge sélectionne localement la politique suivante : ```text Cargo.lock généré localement par Cargo Cargo.lock ignoré par Git Cargo.lock non versionné ``` Le fichier racine `Cargo.lock` MUST être ignoré et MUST NOT être suivi par Git. Les manifests Cargo et la documentation normative restent le contrat versionné des dépendances Rust. Cette décision ne s'applique pas au frontend npm : `Web/knowledge-template-lab/package-lock.json` reste versionné et `npm ci` demeure la preuve de restauration Web reproductible. ### Layout des tests Knowledge sélectionne localement la convention `unit_tests/` séparée que PGR `0.1.1` autorise sans l'imposer globalement. Pour toutes les crates Rust de ce workspace : - les tests d'intégration Cargo MUST résider sous `tests/` et consommer l'API publique de la crate ; - les tests unitaires MUST résider sous `unit_tests/` à la racine de la crate, en miroir logique de `src/` ; - `src/` MUST NOT contenir de fichier d'implémentation de tests unitaires ni d'attribut `#[test]` ; - un module source rattache son fichier de tests avec `#[cfg(test)]` et `#[path = "../unit_tests/.rs"]` ou le chemin miroir équivalent ; - les tests unitaires d'un item partagé continuent d'utiliser son identité crate-root conformément à PGR ; - `tests/` MUST NOT être utilisé pour contourner la visibilité interne ou héberger des tests unitaires qui dépendent d'éléments privés. Exemple : ```rust #[cfg(test)] #[path = "../unit_tests/bite.rs"] mod tests; ``` Cette convention locale est plus stricte que le `MAY` générique de PGR, mais reste conforme à celui-ci. Si PGR doit l'imposer à tous les futurs workspaces, cette évolution appartient à une version ultérieure du référentiel PGR et non à Knowledge. Le préfixe de crate retenu est `knowledge-`. Les responsabilités candidates sont documentées dans l'architecture. Une crate n'est matérialisée que lorsqu'elle possède une responsabilité réelle. Le suffixe `-api` n'est utilisé que pour une frontière passive dont des implémentations distinctes/remplaçables sont réellement prévues. `alpha.3` matérialise ainsi `knowledge-git-api` pour la frontière `GitRepository` et `knowledge-sync-api` pour la frontière `RepositoryEventSource`. Ces crates restent passives, sans runtime ni logging propre, et dépendent seulement des types de domaine nécessaires. Les implémentations Git, hooks, polling, webhooks ou forge restent hors de ces crates de contrat. Le profil Rust strict PGR s'applique aux crates matérialisées, notamment Rust 2024, `unsafe` interdit par défaut, lints stricts, exports publics maîtrisés et chemins intra-crate explicites via la façade crate-root. Les audits read-only PGR sélectionnés avec les premiers contrats publics sont `audit_rust_blank_lines.py`, `audit_rust_item_spacing.py`, `audit_rust_module_order.py`, `audit_rust_trait_import_blocks.py`, `audit_rust_reexport_blocks.py` et `audit_rust_export_completeness.py`. L'audit `const` n'est pas sélectionné globalement : il reste opt-in par fichier lorsqu'un ordre mécanique de constantes est réellement approprié. ## Secrets et configuration locale Les secrets, tokens, mots de passe, clés privées et credentials Git/forge/database ne doivent pas être versionnés ni journalisés. Une configuration locale sensible doit être ignorée ; un fichier `.example` MAY documenter uniquement des valeurs factices lorsqu'il devient utile. ## Langue Les noms techniques, chemins, crates, identifiants et code sont en anglais. La documentation normative et explicative principale est en français.