Sasedev/sasedev-knowledge
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

0.0.1-alpha.1

Browse Source
This commit is contained in:
SinuS von SifriduS
2026-09-27 21:04:10 +02:00
commit 116219f860
15 changed files with 1505 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

23
docs/000-README.md Normal file
View File

@@ -0,0 +1,23 @@
<!-- file: docs/000-README.md -->
<!-- version: 1 -->
# Documentation SaseDev Knowledge
## Objectifs
- [`objectives/001-PROJECT_OBJECTIVES.md`](objectives/001-PROJECT_OBJECTIVES.md) — mission durable, objectifs et hors-scope.
## Architecture
- [`architecture/001-PROJECT_PROFILE.md`](architecture/001-PROJECT_PROFILE.md) — baseline PGR, owners/skeletons applicables, décisions `ADOPT / KEEP-LOCAL / OVERRIDE / DEFER` et nomenclature ;
- [`architecture/002-KNOWLEDGE_ARCHITECTURE.md`](architecture/002-KNOWLEDGE_ARCHITECTURE.md) — frontières application/domain, Git, forge, synchronisation, PostgreSQL, contenu et publication.
## Plans
- [`plans/001-V0_0_1_FOUNDATION_PLAN.md`](plans/001-V0_0_1_FOUNDATION_PLAN.md) — plan vivant de la release de fondation `0.0.1`.
## Validation
- [`validation/001-VALIDATION_MATRIX.md`](validation/001-VALIDATION_MATRIX.md) — preuves proportionnées par scope.
Les deltas et histories sont des artefacts de workflow, pas des substituts à cette documentation durable.

112
docs/architecture/001-PROJECT_PROFILE.md Normal file
View File

@@ -0,0 +1,112 @@
<!-- file: docs/architecture/001-PROJECT_PROFILE.md -->
<!-- version: 1 -->
# Profil du projet Knowledge
## Baseline autoritaire
Le cadrage initial repose sur :
```text
PGR stable tag v0.1.1
PGR archive SHA-256 caaf8f456f7f8520172ea7705fd0cf5c5bf0e942dc4a773410bcbe7fe4ce243a
PGR publish report pgr-0.1.1-publish.001-report.md = PASS
Knowledge prompt prompts/001-V0_0_1_START_PROMPT.md
```
L'archive PGR observée possède `VERSION = 0.1.1`, `292` entrées ZIP, `256` fichiers, `36` répertoires, une racine unique `pgr/`, aucun symlink et aucun `.git`. Les `48` tests Python et les audits Markdown headers/tables/links de la stable ont été rejoués avant préparation de cette tranche et sont propres.
Cette constatation de prévalidation ne remplace aucune gate opérateur Knowledge.
## Nature de l'instanciation
Knowledge est un nouveau projet. La procédure normative d'adoption d'un dépôt existant `230-ADOPTION.md` n'est donc pas activée comme owner de migration.
Le prompt de démarrage exige néanmoins une matrice `ADOPT / KEEP-LOCAL / OVERRIDE / DEFER`. Les mêmes libellés sont utilisés ci-dessous pour rendre explicite la relation entre PGR et les décisions fondatrices Knowledge :
- `ADOPT` — contrat PGR applicable retenu ;
- `KEEP-LOCAL` — choix propre à Knowledge, non possédé par un owner PGR plus spécifique et compatible avec les contrats adoptés ;
- `OVERRIDE` — règle PGR applicable remplacée localement ;
- `DEFER` — choix volontairement reporté avec condition de reprise.
## Owners et skeletons applicables
| Élément | Décision | Matérialisation | Motif |
|----------------------------------------------|---------------------------------|-----------------|----------------------------------------------|
| `200-GOVERNANCE` | `ADOPT` | `alpha.1` | lifecycle/version locale |
| `210-WORKFLOW` | `ADOPT` | `alpha.1` | plan/delta/history/handoff |
| `220-SKELETONS` | `ADOPT` pour l'instanciation | `alpha.1` | composition explicite sans copie mécanique |
| `300-DOCUMENTATION` | `ADOPT` | `alpha.1` | rôles documentaires et taxonomie utile |
| `400-VALIDATION` | `ADOPT` | `alpha.1` | preuves proportionnées et autorité opérateur |
| `500-LANGUAGES` + `510-RUST_CARGO` | `ADOPT` | `alpha.2` | backend Rust/workspace Cargo contrôlé |
| `530-TYPESCRIPT` | `ADOPT` | tranche Web | frontend durable TypeScript |
| `540-JAVASCRIPT_PACKAGE_ECOSYSTEM` | `ADOPT` | tranche Web | package manager/lockfile/scripts explicites |
| `550-VITE` | `ADOPT` puisque Vite est retenu | tranche Web | dev server/build/cache/outputs |
| `560-CSS_SASS` | `ADOPT` | tranche Web | CSS/Sass et outputs |
| `700-FRAMEWORKS` | `ADOPT` | avec Actix/Maud | cadre générique des frameworks |
| `710-TAURI` | `DEFER` / non applicable | hors `0.0.1` | aucun host desktop/mobile Tauri |
| skeleton `001-PROJECT_GOVERNANCE_FOUNDATION` | `ADOPT` | `alpha.1` | fondation locale PGR |
| skeleton `002-RUST_CARGO_WORKSPACE` | `ADOPT` | `alpha.2` | workspace Rust contrôlé |
| skeleton `003-WEB_FRONTEND` | `ADOPT` | tranche Web | frontend indépendant du host |
| validation `005-WEB_FRONTEND_VALIDATION` | `ADOPT` | tranche Web | restore/typecheck/build/smoke proportionnés |
Les profils Java/Maven/Gradle, Android et autres technologies absentes ne sont pas sélectionnés.
## Matrice des décisions importantes
| Décision | Classification | Contrat retenu / condition de reprise |
|--------------------------------------|-----------------------------------|-------------------------------------------------------------------------------------------------------|
| Dépôt applicatif | `KEEP-LOCAL` | `sasedev-knowledge` ; explicite le produit et évite un nom générique `knowledge` au niveau forge |
| 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` |
| Git comme backend du contenu | `KEEP-LOCAL` | invariant d'architecture Knowledge |
| 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/polling constituent le socle ; hooks/webhooks sont des accélérateurs |
| PostgreSQL | `KEEP-LOCAL` | état applicatif et projections ; jamais vérité du contenu Git publié |
| Rust stable / édition 2024 | `ADOPT` | profil Rust/Cargo PGR |
| Workspace Cargo | `ADOPT` | skeleton Rust/Cargo ; matérialisation `alpha.2` |
| `Cargo.lock` | `DEFER` | décider lors de la matérialisation selon le rôle application/workspace et `510` |
| Actix Web | `KEEP-LOCAL` | framework HTTP initial ; PGR ne possède pas de profil Actix dédié |
| Maud | `KEEP-LOCAL` | rendu SSR initial lorsque pertinent |
| TypeScript | `ADOPT` | conforme au owner `530` et à l'intention locale |
| Package manager frontend | `DEFER` | choisir dans la tranche Web avant création du manifest/lockfile |
| Vite | `KEEP-LOCAL` + owner `550` adopté | choix local cohérent avec la recommandation PGR ; configuration à décider dans la tranche Web |
| Sass | `KEEP-LOCAL` + owner `560` adopté | choix local ; compilation intégrée à la chaîne Web si elle apporte la valeur attendue |
| Bootstrap | `KEEP-LOCAL` | framework CSS local, jamais règle PGR/Tauri/Web universelle |
| Racine frontend | `DEFER` | décider dans la tranche Web ; `frontend/` reste candidat mais non figé par PGR |
| Driver/ORM PostgreSQL | `DEFER` | reprendre à la première implémentation persistante réelle |
| Migrations PostgreSQL | `DEFER` | reprendre avec le choix de driver/tooling et le premier schéma réel |
| Moteur de recherche | `DEFER` | commencer par capacités PostgreSQL/index applicatif ; réévaluer sur besoin mesuré |
| Fournisseur d'auth externe | `DEFER` | reprendre lorsque le workflow utilisateur l'exige |
| Topologie de déploiement | `DEFER` | monolithe modulaire par défaut ; séparer seulement sur contrainte observée |
| Formats finaux HOWTO/snippet | `DEFER` | définir avec corpus réel ; ne pas figer un schéma sans contenu représentatif |
| Noms définitifs de toutes les crates | `DEFER` | seules les responsabilités et le préfixe sont cadrés ; créer une crate uniquement avec ownership réel |
Aucun `OVERRIDE` n'est requis à ce stade.
## Nomenclature de crates candidate
Le projet n'instancie pas toutes les crates suivantes en `alpha.1`. Elles décrivent des boundaries candidats et ne deviennent des packages que lorsque leur responsabilité est matérialisée :
```text
knowledge-domain-lib contrats et types métier stables
knowledge-app-lib orchestration des use cases, si une séparation dédiée devient utile
knowledge-git-lib implémentation Git générique
knowledge-store-postgres-lib état applicatif PostgreSQL
knowledge-forge-gitea-lib adapter Gitea optionnel
knowledge-server composition HTTP/SSR et point d'entrée exécutable
```
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 et PostgreSQL ;
- garder les adapters dépendants des contrats, jamais l'inverse.
## Décisions à rouvrir
Les `DEFER` sont réexaminés dans la tranche qui consomme réellement la décision. Un changement de scope produit, l'ajout d'un host natif ou une contrainte externe peut déclencher un REPLAN ; il ne justifie pas un choix anticipé dans `alpha.1`.

237
docs/architecture/002-KNOWLEDGE_ARCHITECTURE.md Normal file
View File

@@ -0,0 +1,237 @@
<!-- file: docs/architecture/002-KNOWLEDGE_ARCHITECTURE.md -->
<!-- version: 1 -->
# Architecture de fondation Knowledge
## Décision structurante
Knowledge part d'un **monolithe modulaire**. Les frontières décrites ici sont des responsabilités et ports logiques, pas une obligation de créer un service ou une crate par boîte.
Le principe directeur est :
> Git est le backend du contenu ; une forge est une capacité optionnelle.
## Vue de responsabilités
```text
HTTP / SSR / admin
|
v
application use cases
|
+---------------------> content/domain contracts
| |
| +---- parsing / validation
| +---- proposal / review rules
| +---- publication selection
|
+---- GitRepository ----------> Git local / remote générique
|
+---- GitForge ---------------> Gitea ou autre forge, optionnel
|
+---- RepositoryEventSource --> sync explicite / polling / hook / webhook
|
+---- application state ------> PostgreSQL
|
+---- local index/cache ------> lecture publique / recherche / rendu
```
La dépendance pointe vers les contrats métier. Les détails Actix, processus Git, API Gitea ou SQL ne remontent pas dans le domaine.
## 1. Application et domaine
Le domaine porte les concepts durables : source de contenu, révision, proposition, validation, publication, type documentaire et références entre contenus.
La couche application orchestre les cas d'usage tels que synchroniser un dépôt, indexer une révision, ouvrir/revoir une proposition et publier une révision autorisée.
Les modèles HTTP, SQL et payloads Gitea ne sont pas des modèles domaine par défaut.
## 2. Git générique
Le contrat conceptuel `GitRepository` couvre uniquement les opérations Git nécessaires :
```text
refs / resolve revision
fetch
checkout ou worktree local
status/diff
branch
commit
merge/rebase contrôlé lorsque le workflow l'exige
push lorsque autorisé
```
L'implémentation doit fonctionner sans connaître Gitea, GitHub ou GitLab.
Le serveur préfère des mirrors/clones et worktrees locaux. Une requête publique ne doit pas déclencher un appel réseau vers la forge.
## 3. Forge optionnelle
Le contrat conceptuel `GitForge` porte uniquement les capacités qui ne sont pas des opérations Git fondamentales :
```text
pull/merge requests
issues
permissions forge
releases forge
webhooks et métadonnées spécifiques
```
L'absence d'un adapter forge ne doit pas empêcher la synchronisation d'un dépôt local/générique, la lecture publique ou le workflow interne de proposition.
Gitea est le premier candidat d'intégration mais n'est pas figé comme dépendance du domaine.
## 4. Événements et synchronisation
Le contrat conceptuel `RepositoryEventSource` produit un **signal de synchronisation**, pas une vérité de contenu.
Sources prévues :
```text
sync explicite
polling
hook Git local/serveur
webhook de forge
watcher filesystem éventuel
```
Toutes convergent vers le même cas d'usage interne :
```text
signal
-> fetch/refresh si nécessaire
-> résolution de la révision cible Git
-> comparaison avec la dernière révision indexée
-> checkout/worktree de la révision
-> parsing + validation
-> construction d'une projection/index
-> publication atomique de l'état dérivé
```
Un webhook peut être perdu ou dupliqué. Le commit Git résolu reste l'identité autoritaire de la révision.
## 5. Propositions et revues
Le workflow exact reste à formaliser avant implémentation, mais le contrat minimal conserve :
```text
auteur
cible
révision Git de base
patch ou contenu proposé
statut
historique de revue
résultat de validation
révision/branche résultante si acceptée
```
Une proposition ne modifie jamais directement la révision publiée.
Si la base n'est plus courante, le workflow doit pouvoir signaler un conflit/rebase plutôt que forcer un écrasement.
Une pull request de forge MAY refléter ou accélérer ce workflow ; elle n'en est pas le modèle autoritaire obligatoire.
## 6. Parsing et validation des contenus
Le contrat conceptuel `ContentRepository` expose du contenu normalisé au métier sans révéler le provider Git ou forge.
Le format final des HOWTOs/snippets reste `DEFER`. Le parseur devra néanmoins pouvoir produire au minimum :
```text
identité logique
famille de contenu
révision source
métadonnées normalisées
corps rendu/parsé
références sortantes
résultat de validation
```
Les validations normatives PGR restent propres au corpus PGR. Knowledge ne doit pas inventer une règle PGR pour simplifier son parseur.
## 7. Index, recherche et cache
L'index/cache est une projection reconstructible du contenu Git.
PostgreSQL MAY contenir des documents/index/métadonnées dérivés et assurer une première capacité de recherche. Aucun moteur de recherche externe n'est sélectionné en `0.0.1`.
Une projection doit garder la révision Git source afin de savoir exactement quel contenu elle représente.
## 8. Rendu et publication
La publication sélectionne une révision autorisée, la valide/indexe puis la rend disponible localement.
Pour PGR :
- le canal stable provient d'un tag stable vérifié par le workflow PGR ;
- un canal `dev` MAY exister mais doit être visuellement et sémantiquement distinct.
Pour HOWTOs/snippets :
- la cadence MAY être continue et plus légère ;
- le workflow SemVer/delta/history PGR n'est pas imposé artificiellement.
Actix Web et Maud sont des choix de composition/rendu locaux. Vite gère les assets/interactions frontend lorsqu'il est matérialisé.
## 9. Administration
L'administration Web est une interface vers les mêmes cas d'usage que l'édition locale Git, pas une deuxième source de vérité.
Elle pourra gérer propositions, revues, synchronisation, validation et publication. Une UI complète est hors scope `0.0.1`.
## 10. Authentification et autorisation
Le domaine doit distinguer identité, rôle/capacité et action autorisée, mais le fournisseur d'identité et le mécanisme complet restent différés.
Les permissions forge ne sont pas supposées équivalentes aux permissions applicatives.
## 11. Frontières PGR / HOWTO / snippet / project-local
Les quatre familles gardent une sémantique propre :
| Famille | Rôle | Force |
|---------------|--------------------------------------------------|--------------------------|
| PGR | règle/contrat de gouvernance | normative dans son scope |
| HOWTO | procédure, diagnostic, explication, anti-pattern | guidance |
| snippet | exemple court, commande, configuration, fragment | contextualisée |
| project-local | décision concrètement instanciée | locale au projet |
Les métadonnées peuvent relier ces familles sans promotion automatique de force normative.
Une pratique répétée dans HOWTO/snippet peut devenir un candidat d'étude PGR ; elle n'est normative qu'après le workflow PGR correspondant.
## 12. Git versus PostgreSQL
### Autoritaire dans Git
- corps du contenu publié ;
- métadonnées éditoriales versionnées avec ce contenu ;
- historique de révisions Git ;
- refs/tags/branches autorisées par la politique de chaque dépôt.
### État applicatif PostgreSQL
- utilisateurs/sessions ;
- propositions et revue ;
- commentaires/audit applicatif ;
- configuration logique des sources ;
- dernière révision synchronisée/indexée ;
- index et recherche dérivés ;
- relations calculées ;
- jobs de synchronisation/publication ;
- cache/projections reconstructibles.
### Interdit comme raccourci architectural
Une modification du contenu publié ne doit pas exister uniquement dans PostgreSQL après acceptation. L'acceptation doit produire une révision Git avant qu'elle devienne contenu publié.
## Topologie de dépôts retenue
```text
sasedev-knowledge application et gouvernance de la plateforme
pgr contenu normatif PGR existant
howtos contenu procédural séparé
snippets contenu court/contextualisé séparé
```
Les dépôts de contenu ne sont pas fusionnés dans PGR et ne sont pas requis comme submodules Git du dépôt applicatif. Leur localisation et leurs credentials sont de la configuration de déploiement.

51
docs/objectives/001-PROJECT_OBJECTIVES.md Normal file
View File

@@ -0,0 +1,51 @@
<!-- file: docs/objectives/001-PROJECT_OBJECTIVES.md -->
<!-- version: 1 -->
# Objectifs SaseDev Knowledge
## Mission
SaseDev Knowledge fournit une plateforme contrôlée permettant de publier, relier, rechercher et administrer des contenus de connaissance SaseDev tout en conservant Git comme vérité versionnée et PGR comme référentiel normatif indépendant.
## Façades produit visées
Les hostnames suivants sont des intentions produit, pas des obligations de déploiement de `0.0.1` :
```text
pgr.sasedev.com
howtos.sasedev.com
snippets.sasedev.com
```
Une même application MAY servir plusieurs hostnames tant que les frontières de contenu restent explicites.
## Objectifs durables
Knowledge doit permettre à terme :
- de publier une stable PGR issue d'un tag vérifié, avec un éventuel canal `dev` distinct ;
- de publier des HOWTOs procéduraux sans leur attribuer une force normative PGR ;
- de publier des snippets courts et contextualisés ;
- d'administrer des dépôts publics ou privés ;
- d'accepter des propositions externes sans écriture directe dans le contenu publié ;
- de conserver une révision Git de base pour détecter les conflits ;
- d'utiliser une forge lorsqu'elle apporte des capacités supplémentaires sans la rendre obligatoire ;
- de servir les lectures publiques depuis des données locales/indexées lorsque la forge distante est indisponible ;
- de garder les contenus récupérables et intelligibles par un clone Git indépendant du site.
## Non-objectifs de la fondation 0.0.1
`0.0.1` ne cherche pas à livrer :
- un moteur de recherche complet ;
- une UI d'administration complète ;
- un workflow de contribution complet ;
- un support complet Gitea/GitHub/GitLab ;
- un déploiement multi-domaines de production ;
- un moteur de rendu final pour tous les formats ;
- un système d'authentification complet ;
- une architecture microservices.
## Principe de simplicité
Le monolithe modulaire est la baseline architecturale de départ. Une séparation en services n'est introduite que lorsqu'une contrainte observée justifie un nouveau boundary de déploiement.

174
docs/plans/001-V0_0_1_FOUNDATION_PLAN.md Normal file
View File

@@ -0,0 +1,174 @@
<!-- file: docs/plans/001-V0_0_1_FOUNDATION_PLAN.md -->
<!-- version: 1 -->
# Plan 0.0.1 — fondation SaseDev Knowledge
## Statut et sources
Plan actif 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 :
```text
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 ;
- 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` :
- dépôt applicatif `sasedev-knowledge`, nom court `knowledge` ;
- Git autoritaire pour le contenu ;
- forge facultative derrière adapter ;
- PostgreSQL pour l'état applicatif/projections ;
- monolithe modulaire comme baseline de déploiement ;
- PGR, HOWTOs et snippets dans des dépôts séparés ;
- Rust stable/édition 2024 ;
- Actix Web, Maud, Vite, TypeScript, Sass, Bootstrap et PostgreSQL retenus comme intentions locales conformes aux owners applicables ;
- aucun override PGR nécessaire.
Restent volontairement ouverts jusqu'à la tranche qui les consomme :
- package manager et lockfile frontend ;
- `Cargo.lock` ;
- racine/configuration concrète du frontend ;
- driver/ORM et migrations PostgreSQL ;
- moteur de recherche ;
- fournisseur d'identité ;
- adapter forge réel ;
- formats finaux HOWTO/snippet ;
- liste définitive des crates.
## Scope
`0.0.1` inclut :
- documentation de gouvernance et architecture ;
- workspace Rust/Cargo minimal ;
- configuration de toolchain/lints proportionnée ;
- 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 microservices.
## Stratégie de validation
Les gates suivent [`../validation/001-VALIDATION_MATRIX.md`](../validation/001-VALIDATION_MATRIX.md).
Principes :
- gate documentaire pour `alpha.1` ;
- 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 ;
- smoke seulement pour une propriété runtime réellement 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.
Aucun code fonctionnel n'est ajouté.
### alpha.2 — workspace Rust/Cargo minimal
Instancier le skeleton `002-RUST_CARGO_WORKSPACE` sur la fondation : manifest workspace, toolchain/configuration durable réellement nécessaire, premier package possédant une responsabilité claire et gates Cargo officielles.
Décider explicitement `Cargo.lock`, outputs de build et premier sous-ensemble de crates réellement matérialisé.
### alpha.3 — contrats domaine/Git/synchronisation
Introduire uniquement les premiers contrats/types nécessaires aux frontières `GitRepository`, contenu et synchronisation, avec tests ciblés. Ne pas ajouter d'API Gitea ni de persistance PostgreSQL par anticipation.
Les noms conceptuels du cadrage peuvent être adaptés si l'implémentation montre un meilleur owner ; toute modification du plan est tracée dans le delta correspondant.
### alpha.4 — baseline Web indépendante
Instancier le skeleton `003-WEB_FRONTEND` : choisir package manager et lockfile, TypeScript strict, Vite, Sass et Bootstrap réellement nécessaires, avec typecheck/build indépendants du backend.
Ne pas faire de la présence d'Actix/Maud une excuse pour coupler la gate frontend au serveur.
### alpha.5 — composition serveur minimale
Matérialiser le minimum Actix Web/Maud nécessaire pour prouver la composition avec les contrats et assets de fondation, sans admin complète, auth complète, persistence métier complète ni forge.
Cette tranche peut être réduite ou reportée si `alpha.2` à `alpha.4` montrent qu'une stable de fondation plus petite est suffisante.
### beta.1 — réconciliation de fondation
Rejouer les gates pertinentes, réconcilier docs/architecture avec ce qui existe réellement, traiter les décisions devenues nécessaires et effectuer la revue d'horizon.
Aucune nouvelle grande fonctionnalité ne doit être introduite en beta par défaut.
### rc.1 — candidate stable
Clôturer les défauts de cohérence, préparer la présentation stable, le handoff suivant et vérifier l'absence de scope futur introduit par anticipation.
### rel.1 — fermeture stable
Exécuter la gate de release, produire le premier history `rel.N[/fix.M]` réellement `PASS`, matérialiser le commit produit `0.0.1`, publier le tag stable selon la politique Git retenue et effectuer la vérification post-tag requise.
## 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 ;
- 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 ;
- 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 : requise en `beta.1` ;
- raison : aucune version après `0.0.1` n'est suffisamment cadrée pour être réservée aujourd'hui ;
- sorties autorisées : engager une prochaine version avec mission réelle, laisser l'horizon ouvert ou différer la suite ;
- interdiction : fabriquer un numéro uniquement pour satisfaire une cadence documentaire.

88
docs/validation/001-VALIDATION_MATRIX.md Normal file
View File

@@ -0,0 +1,88 @@
<!-- file: docs/validation/001-VALIDATION_MATRIX.md -->
<!-- version: 1 -->
# Matrice de validation Knowledge
## Principe
La gate opérateur sélectionne les preuves nécessaires au scope réellement modifié. Une commande n'est pas exécutée uniquement pour augmenter le nombre de checks.
La prévalidation de génération ne vaut pas preuve opérateur.
## Fondation documentaire
Pour une tranche limitée à gouvernance/documentation :
```text
CHECK VERSION attendue
CHECK git diff --check
AUDIT liste des fichiers ajoutés/remplacés/supprimés conforme au delta
AUDIT headers file/version des Markdown gouvernés
AUDIT liens Markdown locaux principaux
REVIEW owners PGR / décisions locales / DEFER explicites
REVIEW absence de secret, chemin machine absolu et placeholder non résolu
```
## Rust/Cargo
Dès qu'un workspace Rust est matérialisé, sélectionner selon le scope :
```text
CHECK cargo metadata --no-deps
FORMAT cargo fmt --all -- --check
CHECK cargo check --workspace
LINT cargo clippy --workspace --all-targets --all-features -- -D warnings
TEST cargo test ciblé ou workspace selon le changement
AUDIT règles structurelles PGR seulement si la preuve n'est pas déjà possédée par Cargo/Rustfmt/Clippy
```
Le profil strict et les éventuelles exceptions doivent être visibles dans les manifests/règles locales.
## Frontend Web
Dès que le frontend est matérialisé :
```text
RESTORE mode reproductible du package manager sélectionné
TYPECHECK script typecheck TypeScript
BUILD production Vite lorsque ses entrées/configuration/outputs changent
STYLES preuve séparée uniquement si le build ne prouve pas déjà la compilation requise
SMOKE navigateur seulement lorsqu'une propriété runtime le justifie
```
La gate frontend reste exécutable indépendamment du backend autant que la topologie réelle le permet.
## Serveur et intégration
Actix Web/Maud reçoivent une gate backend Rust ciblée. Un smoke HTTP est ajouté uniquement lorsqu'une route/runtime réelle est introduite et que compilation/tests ne prouvent pas la propriété visée.
Une gate d'intégration ne remplace pas silencieusement les preuves frontend indépendantes.
## Git et forge
Les contrats Git génériques sont testés sans dépendance à une forge lorsque cela suffit.
Un test live de remote ou de forge doit être explicitement classé comme externe, séparé des tests unitaires et ne doit pas devenir une condition cachée pour les opérations locales.
## PostgreSQL
Aucune gate PostgreSQL n'est créée avant matérialisation d'une dépendance ou d'un schéma réel.
Lorsqu'elle devient nécessaire, la validation doit distinguer :
- parsing/compilation des migrations ou schémas ;
- tests avec base éphémère/localement contrôlée ;
- éventuels smokes externes ;
- reconstruction d'une projection dérivée à partir d'une révision Git connue.
## Gate de `0.0.1-alpha.1`
La première tranche est documentaire. Sa gate doit prouver :
- `VERSION = 0.0.1-alpha.1` ;
- les fichiers exacts du delta ;
- l'absence de code fonctionnel ;
- les headers et liens locaux ;
- la présence de la baseline PGR vérifiée et de la matrice de décisions ;
- l'absence d'override PGR non documenté ;
- la cohérence du plan et de la transition PASS/FAIL.