sasedev-knowledge/docs/architecture/001-PROJECT_PROFILE.md

Profil du projet Knowledge

Baseline autoritaire

La stable produit depuis laquelle 0.0.4 est ouverte est :

Knowledge stable tag       v0.0.3
Knowledge stable commit    b3823972449150b72905930b806d4d15471cddce
Knowledge archive SHA-256  82407dc2a83be878daa65692f975681428d0adc721ff249c3c9020e3a9d1f29d
Knowledge publish report   sasedev-knowledge-0.0.3-publish.001-report.md = PASS
Knowledge start prompt      prompts/004-V0_0_4_START_PROMPT.md

L'archive taggée v0.0.3 a été vérifiée avant le cadrage 0.0.4-alpha.1 : VERSION et le workspace Cargo valent 0.0.3, les douze deltas et douze histories 0.0.3 sont appariés, rel.1.fix.1 = PASS clôt la release et le commentaire ZIP contient le commit stable ci-dessus.

La fondation 0.0.1 a été construite sous PGR v0.1.1. Cette identité reste historique dans les artefacts 0.0.1.

Le démarrage explicite de 0.0.2 a réévalué PGR et a retenu la stable suivante comme source d'adoption :

PGR stable tag      v0.1.3
PGR stable commit   fe80dbbb737390a7ea99df27d979bd59ccfb86e3
PGR archive SHA-256 f3a7dffd5fe0fd3542e6b5207fda0b94bca2bd05bd5a54542d0a08d635a5d6ee
PGR publish report  pgr-0.1.3-publish.001-report.md = PASS

Cette référence est une provenance d'adoption figée. Après matérialisation des contrats retenus, la baseline normative de Knowledge est constituée des artefacts locaux du dépôt Knowledge. Une version ou session future ne consulte pas automatiquement le PGR courant ; une nouvelle comparaison PGR exige une réévaluation explicitement engagée.

0.0.2-alpha.4 matérialise les owners locaux nécessaires et ferme cette adoption comme migration ponctuelle. Le mapping durable est 003-PGR_ADOPTION_MAP.md.

L'archive PGR v0.1.3 vérifiée possède VERSION = 0.1.3, 332 entrées ZIP, 290 fichiers, 42 répertoires, une racine unique pgr/, aucun symlink et aucun .git. Son rapport post-tag indique 48/48 tests Python et les audits Markdown propres.

Cette prévalidation ne remplace aucune gate opérateur Knowledge.

Historique de l'adoption

Knowledge n'est plus un nouveau dépôt à instancier : 0.0.2-alpha.1 migre un projet existant de la baseline PGR v0.1.1 vers v0.1.3.

L'owner PGR 230-ADOPTION devient applicable à cette migration ; son contrat est instancié localement par les décisions suivantes :

• partir d'une baseline autoritaire observée ;
• sélectionner uniquement les owners réellement applicables ;
• classifier ADOPT / KEEP-LOCAL / OVERRIDE / DEFER ;
• préserver les décisions locales compatibles ;
• ne pas réécrire les commits, deltas, histories ou documents historiques pour simuler une conformité rétroactive ;
• valider proportionnellement la migration.

Les classifications locales restent :

• ADOPT — contrat PGR applicable retenu ;
• KEEP-LOCAL — choix propre à Knowledge, compatible et non possédé par un owner PGR plus spécifique ;
• OVERRIDE — règle PGR applicable remplacée ou raffinée localement avec justification ;
• DEFER — choix volontairement reporté avec condition de reprise.

Owners locaux après adoption

Les responsabilités quotidiennes sont désormais possédées par :

docs/rules/200-GOVERNANCE.md
docs/rules/210-WORKFLOW.md
docs/rules/300-DOCUMENTATION.md
docs/rules/400-VALIDATION.md
docs/rules/510-RUST_CARGO.md
docs/rules/530-WEB_FRONTEND.md

Le détail de la migration depuis les owners PGR v0.1.3, y compris les décisions KEEP-LOCAL, les éléments non applicables et les skeletons uniquement historiques, est conservé dans 003-PGR_ADOPTION_MAP.md. Aucun de ces owners locaux ne nécessite de consulter PGR pour être interprété.

Matrice des décisions importantes

Décision	Classification	Contrat retenu / condition de reprise
Dépôt applicatif	KEEP-LOCAL	sasedev-knowledge ; workspace unique de la plateforme
Nom court / préfixe crates	KEEP-LOCAL	knowledge / knowledge-
Dépôt normatif	KEEP-LOCAL	dépôt existant pgr, jamais fusionné dans le dépôt applicatif
Dépôt HOWTO	KEEP-LOCAL	dépôt séparé howtos
Dépôt snippets	KEEP-LOCAL	dépôt séparé snippets
Nombre de sources Git	KEEP-LOCAL	au moins trois sources initiales, sans limite codée à trois
Git comme backend du contenu	KEEP-LOCAL	invariant d'architecture Knowledge
Implémentation Git de 0.0.2	KEEP-LOCAL	processus git contrôlé derrière knowledge-git-api ; décision réévaluable derrière le contrat
Configuration physique Git	KEEP-LOCAL	knowledge-git-lib matérialisée en 0.0.2-alpha.2 ; source locale/remote + racine d'état ; pas dans le domaine
Copies Git générées	KEEP-LOCAL	racine d'état explicite hors dépôt source, mirrors et snapshots adressés par clé sûre/révision
Écriture Git contrôlée 0.0.3	KEEP-LOCAL	contrat distinct de la lecture, worktree isolé, commit explicite et push de branche gardé par état attendu
Rebase/merge automatique	DEFER	reprendre avec un workflow de proposition réellement matérialisé ; divergence = conflit en 0.0.3
Partage du cache Git entre processus	DEFER	état root exclusif à une instance backend en 0.0.2 ; reprendre avec verrouillage inter-processus réel
Forge	KEEP-LOCAL	capacité optionnelle derrière adapter ; aucune API de forge dans le domaine
Gitea	DEFER	premier adapter candidat ; reprendre lorsque des capacités forge-only sont implémentées
Synchronisation sans webhook	KEEP-LOCAL	explicite/périodique convergent vers le même cas d'usage ; hooks/webhooks restent accélérateurs
Scheduler périodique concret	DEFER	créer seulement lorsque son owner runtime/lifecycle est démontré
Dernière révision observée en 0.0.2	KEEP-LOCAL	fournie par l'appelant et retournée par le cas d'usage ; pas de pseudo-persistance locale
PostgreSQL	KEEP-LOCAL	une base logique partagée ; 0.0.4 matérialise sa première fondation sans déplacer la vérité éditoriale de Git
Rust stable / édition 2024	ADOPT	owner local docs/rules/510-RUST_CARGO.md
Workspace Cargo	ADOPT	configuration locale + owner 510-RUST_CARGO.md
Cargo.lock	KEEP-LOCAL	généré localement et ignoré ; manifests Cargo versionnés
Actix Web	KEEP-LOCAL	trois launchers existants et composition partagée dans knowledge-web-lib
Maud	KEEP-LOCAL	rendu SSR commun dans knowledge-web-lib
TypeScript	ADOPT	owner local docs/rules/530-WEB_FRONTEND.md
Package manager frontend	KEEP-LOCAL	npm ; package-lock.json versionné
Vite	KEEP-LOCAL + contrat adopté	owner local Web ; build/preview de références et manifest consommé par Maud
Sass	KEEP-LOCAL + contrat adopté	owner local Web ; styles source et assets réellement servis
Bootstrap	KEEP-LOCAL	framework CSS local Knowledge, jamais règle PGR universelle
Racine frontend	KEEP-LOCAL	package partagé Web/knowledge-template-lab/
Templates statiques Web	KEEP-LOCAL	harness de conception/validation ; rendu runtime Maud
Intégration manifest Vite / Maud	KEEP-LOCAL	matérialisée dans knowledge-web-lib
Toolkit PostgreSQL	KEEP-LOCAL	tokio-postgres + deadpool-postgres, async/Tokio et SQL explicite ; aucun ORM sélectionné
Migrations PostgreSQL	KEEP-LOCAL	SQL versionné possédé par knowledge-store-postgres-lib, appliqué explicitement via Refinery
Moteur de recherche	DEFER	commencer par capacités PostgreSQL/index applicatif lorsque ce scope sera engagé
Fournisseur d'auth externe	DEFER	reprendre lorsque le workflow utilisateur l'exige
Surface admin par application	KEEP-LOCAL	chaque serveur protège ses opérations privilégiées ; URL exacte différée
Quatrième application d'administration	DEFER	agréger seulement si une responsabilité transverse apparaît
Modèle rôles/capabilities	DEFER	reprendre avec les cas d'usage d'autorisation réels
Formats finaux HOWTO/snippet	DEFER	définir avec corpus réel
Autres noms de crates	DEFER	créer uniquement lorsque l'ownership est démontré

Nomenclature de crates

Les packages matérialisés sont :

knowledge-domain-lib       types métier stables de famille/source
knowledge-app-lib          cas d'usage applicatifs partagés, dont synchronisation de lecture
knowledge-git-api          contrat passif GitRepository provider-neutral
knowledge-git-lib          implémentation Git générique + mirror/refresh/resolve/snapshot + état local contrôlé
knowledge-sync-api         contrat passif RepositoryEventSource
knowledge-web-lib          composition Actix/Maud/Vite partagée
knowledge-pgr-server       launcher PGR mince
knowledge-howtos-server    launcher HOWTOs mince
knowledge-snippets-server  launcher snippets mince

knowledge-git-lib devient réelle en 0.0.2-alpha.2 puis implémente le chemin de lecture Git dans alpha.3. knowledge-app-lib devient réelle en 0.0.2-alpha.5 : l'orchestration refresh / résolution / comparaison / snapshot confirme une responsabilité application partagée distincte du backend Git et des launchers.

0.0.4-alpha.1 retient comme prochaine responsabilité réelle, sans encore la matérialiser dans cette tranche :

knowledge-store-postgres-lib  pool, migrations et état applicatif PostgreSQL partagé

Les responsabilités suivantes restent candidates et non matérialisées :

knowledge-forge-gitea-lib  adapter Gitea optionnel
knowledge-logging-lib      diagnostics partagés, seulement sur besoin multi-runtime réel

Règles de création :

• ne pas créer une crate uniquement pour refléter un diagramme ;
• ne pas utiliser -api sans frontière de contrat indépendante réellement nécessaire ;
• garder le domaine indépendant d'Actix, Gitea, Git process et PostgreSQL ;
• garder les adapters/implémentations dépendants des contrats, jamais l'inverse ;
• ne pas dupliquer dans les trois serveurs une logique qui possède clairement un owner commun ;
• ne pas créer un service réseau supplémentaire lorsqu'une crate partagée suffit.

Corpus auth/admin étudié en 0.0.1

Les archives historiques actix-auth-app-master.zip et amahil-project-master.zip restent des sources d'inspiration non autoritaires. Leur analyse est conservée dans ../studies/001-AUTH_ADMIN_CORPUS_STUDY.md.

Elles justifient de conserver séparées l'identité/authentification partagée, l'autorisation privilégiée propre à chaque application et une éventuelle façade transverse ultérieure. Elles ne justifient toujours pas de créer une crate auth, de figer /admin ou /login, ni d'adopter OAuth2/OIDC/MFA pendant 0.0.2.

Résultat de l'adoption PGR 0.1.3

0.0.2-alpha.4 ferme l'adoption comme migration ponctuelle :

• les owners nécessaires sont adaptés et possédés localement ;
• les règles Web externes applicables sont consolidées en un owner Knowledge plutôt que copiées en quatre documents ;
• les skeletons restent une provenance d'instanciation, pas des dépendances normatives ;
• les scripts génériques utiles sont sélectionnés localement et les variantes locales restent autoritaires ;
• les futurs prompts de session repartent de Knowledge seul ;
• une nouvelle stable PGR n'a aucun effet tant qu'une réévaluation n'est pas explicitement planifiée ;
• les artefacts historiques 0.0.1 et les tranches antérieures de 0.0.2 restent inchangés.

Réconciliation beta et décisions différées

0.0.2-beta.1 confirme que le scope alpha est matérialisé par neuf packages Cargo : contrats domaine/Git/synchronisation, backend Git générique, orchestration application partagée, composition Web et trois launchers. Aucune responsabilité supplémentaire n'est nécessaire pour fermer la mission de lecture/synchronisation de 0.0.2.

Restent différés après 0.0.2 : adapter Gitea, PostgreSQL/migrations, moteur de recherche, auth/admin complète, quatrième application d'administration, modèle détaillé rôles/capabilities, formats finaux HOWTO/snippet, scheduler concret, support explicite submodules/LFS, politique de nettoyage/rétention des snapshots et partage concurrent de la même racine Git entre plusieurs processus.

La revue d'horizon 0.0.2-beta.1 n'avait réservé aucune release suivante. L'ouverture explicite de 0.0.3 a consommé uniquement le DEFER d'écriture Git contrôlée : worktree d'écriture isolé, commit candidat et push de branche gardé. Rebase/merge automatique et workflow complet de proposition restent différés.

La revue 0.0.3-beta.1 sélectionne désormais la fondation PostgreSQL partagée comme prochaine mission 0.0.4, sans préchoisir son driver/ORM avant l'étude de démarrage. Elle réordonne ensuite l'horizon produit pour rendre visibles les phases de modèles/projections, templates publics, templates admin, intégration Actix/Maud puis workflow de gestion/publication. Gitea, scheduler, recherche avancée, quatrième application admin et partage multi-processus restent différés tant que leurs déclencheurs ne sont pas matérialisés.

Ouverture 0.0.4 — fondation PostgreSQL partagée

Après publication vérifiée de v0.0.3, 0.0.4-alpha.1 consomme les DEFER portant sur le toolkit PostgreSQL et les migrations.

La décision locale est :

owner prévu       knowledge-store-postgres-lib
driver             tokio-postgres 0.7
modèle             SQL explicite, sans ORM
pool               deadpool-postgres 0.14
migrations         SQL versionné + Refinery 0.9
premier état       source logique + dernière révision synchronisée
autorité contenu   Git

Aucune crate n'est créée pendant alpha.1. La tranche établit seulement l'étude et le plan qui autoriseront alpha.2 après gate opérateur PASS.

La configuration physique Git reste possédée par knowledge-git-lib. Le premier schéma PostgreSQL ne stocke pas de credentials Git et ne transforme pas les URLs/paths physiques en vérité métier. La configuration de connexion PostgreSQL est injectée par la composition, non lue implicitement par la future crate de stockage.

Les DEFER Gitea/forge, scheduler, recherche avancée, auth/capabilities, formats finaux de contenu, quatrième application admin, partage multi-processus de racine Git, LFS/submodules et rétention avancée restent inchangés. L'horizon 0.0.5 à 0.0.10 reste cohérent et n'est pas replanifié par cette étude.