sasedev-knowledge/RULES.md

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.

Provenance PGR et autonomie normative

La fondation stable 0.0.1 a été cadrée à partir de PGR v0.1.1. Cette référence reste historique et n'est pas réécrite rétroactivement.

Au démarrage explicite de 0.0.2, Knowledge a réévalué PGR et retenu v0.1.3 comme source d'adoption vérifiée par pgr-0.1.3-publish.001-report.md = PASS :

tag      v0.1.3
commit   fe80dbbb737390a7ea99df27d979bd59ccfb86e3
SHA-256  f3a7dffd5fe0fd3542e6b5207fda0b94bca2bd05bd5a54542d0a08d635a5d6ee

Cette identité documente la provenance de l'adoption ; elle n'est pas une dépendance normative vivante. Une migration réussie doit laisser Knowledge autonome : les règles réellement retenues sont sélectionnées, adaptées et possédées localement par Knowledge. PGR n'est ni une dépendance runtime/build, ni un référentiel à charger automatiquement au début d'une version, d'une session ou d'une tranche.

Le prompt prompts/002-V0_0_2_START_PROMPT.md reste historique : sa vérification de la stable PGR courante appartenait à l'adoption explicitement engagée au démarrage de 0.0.2. Ce comportement ne devient pas le modèle des futurs prompts Knowledge.

Une future version de PGR n'a aucun effet automatique sur Knowledge. Elle n'est consultée que lorsqu'une réévaluation/adoption PGR est explicitement inscrite au scope d'une tranche ou d'une release. Cette réévaluation doit alors comparer la baseline locale Knowledge avec la version PGR choisie, classifier les décisions ADOPT / KEEP-LOCAL / OVERRIDE / DEFER, puis matérialiser localement les décisions retenues avant de refermer l'adoption.

0.0.2-alpha.4 est la tranche de réconciliation qui doit terminer l'autonomie normative de l'adoption v0.1.3 : inventorier les owners réellement retenus, vérifier où chaque contrat nécessaire est possédé localement, adapter les règles/templates/audits manquants sans recopier mécaniquement l'arborescence PGR et supprimer les références externes nécessaires à la compréhension courante du projet.

Owners normatifs locaux

Le développement courant est gouverné par les owners Knowledge suivants :

• docs/rules/200-GOVERNANCE.md — baseline, autonomie et décisions ;
• docs/rules/210-WORKFLOW.md — plan/delta/history/fix/handoff ;
• docs/rules/300-DOCUMENTATION.md — structure documentaire, headers et prompts ;
• docs/rules/400-VALIDATION.md — preuves proportionnées et autorité opérateur ;
• docs/rules/510-RUST_CARGO.md — Rust/Cargo strict, façade crate-root et tests ;
• docs/rules/530-WEB_FRONTEND.md — TypeScript/npm/Vite/Sass/Bootstrap/Maud.

Le mapping complet de provenance et de décisions ADOPT / KEEP-LOCAL / OVERRIDE / DEFER est conservé dans docs/architecture/003-PGR_ADOPTION_MAP.md. Les owners PGR non matérialisés localement ne sont pas des dépendances documentaires du développement quotidien.

Priorité et décisions locales

Les contrats issus de PGR et explicitement adoptés par Knowledge deviennent des règles locales Knowledge après adaptation/matérialisation. C'est leur formulation locale qui gouverne ensuite le projet ; PGR conserve uniquement la provenance de la décision.

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 requis par l'adoption v0.1.3 de 0.0.2-alpha.1.

Les décisions différées sont explicites dans 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 possède localement le workflow suivant, issu de l'adoption PGR :

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 :

.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 :

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

Chaque package exécutable reste une couche de composition mince conformément au contrat Rust/Cargo retenu localement par Knowledge. 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.

Pour 0.0.2, la première implémentation générique retenue utilise un processus git contrôlé derrière knowledge-git-api. Cette décision est locale à Knowledge et reste remplaçable derrière le contrat.

La configuration physique des sources Git et la matérialisation locale appartiennent à knowledge-git-lib, matérialisée en 0.0.2-alpha.2. Les copies générées MUST résider sous une racine d'état explicitement fournie au backend, hors du dépôt applicatif et des dépôts éditoriaux. Ni une URL remote ni un SourceId brut ne doivent devenir directement un chemin de stockage.

knowledge-git-lib dérive une clé de stockage sûre à partir des octets UTF-8 du SourceId et ne réutilise jamais directement l'identifiant logique ou l'URL comme composant de chemin. Le backend MUST invoquer l'exécutable Git directement sans shell, avec arguments séparés et prompts interactifs désactivés. Les erreurs publiques du runner MUST NOT recopier les arguments de commande, l'URL source, stderr ou des credentials.

À partir de 0.0.2-alpha.3, le backend enregistre explicitement les configurations physiques associées aux SourceId puis implémente knowledge-git-api::GitRepository. Le refresh MUST converger par le remote du mirror avec pruning ; une référence MUST être résolue avec vérification vers un commit avant d'être utilisée comme identité autoritaire. Les snapshots MUST être adressés par la révision résolue et un snapshot existant MUST être vérifié sur son HEAD et son état propre avant réutilisation. Une divergence ou un worktree sale est une erreur récupérable et ne déclenche aucune suppression silencieuse.

La racine d'état Git n'est pas un stockage métier. En 0.0.2, elle est possédée exclusivement par une instance de backend/processus ; un partage concurrent inter-processus reste différé tant qu'un verrouillage dédié n'est pas matérialisé.

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 :

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 :

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 contrat Web courant est possédé par docs/rules/530-WEB_FRONTEND.md. Le frontend contrôlé utilise 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é depuis la fondation 0.0.1. 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

Knowledge possède localement la politique de lockfile suivante :

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.

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/<fichier>.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 :

#[cfg(test)]
#[path = "../unit_tests/bite.rs"]
mod tests;

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 contrat Rust strict est possédé par docs/rules/510-RUST_CARGO.md. Pour toutes les crates bibliothèque, src/lib.rs reste une façade de documentation, modules et réexports ; les définitions de production résident dans des modules nommés selon leur responsabilité. Les crates knowledge-git-api et knowledge-sync-api appliquent ce contrat à partir de 0.0.2-alpha.4 sans changer leur API crate-root.

Les audits Rust read-only possédés localement incluent 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, audit_rust_crate_root_facades.py et audit_rust_export_completeness.py. L'audit const n'est pas sélectionné globalement : il reste opt-in uniquement si un ordre mécanique de constantes devient 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.