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

29
.gitignore vendored Normal file
View File

@@ -0,0 +1,29 @@
# IDE and local editor state
.project
.classpath
.settings/
.idea/
.vscode/
# Local environment and secrets
.env
.env.*
!.env.example
# Rust/Cargo outputs
/target/
# JavaScript/frontend dependencies and transient outputs
/node_modules/
/frontend/node_modules/
/frontend/.vite/
/frontend/dist/
# Project build outputs kept outside source when configured
/builds/
# OS/transient files
.DS_Store
Thumbs.db
*.swp
*~

13
CHANGELOG.md Normal file
View File

@@ -0,0 +1,13 @@
<!-- file: CHANGELOG.md -->
<!-- version: 1 -->
# Changelog SaseDev Knowledge
Ce fichier décrit les changements utiles des releases publiées. Les détails de tranches et preuves opérateur appartiennent aux plans, deltas et histories.
## 0.0.1 (candidate)
- établit la gouvernance locale Knowledge à partir de PGR `v0.1.1` vérifiée ;
- cadre la séparation Git / forge optionnelle / PostgreSQL ;
- fixe les frontières PGR / HOWTO / snippet / project-local ;
- prépare un workspace Rust et une baseline Web composables sans construire prématurément la plateforme complète.

40
README.md Normal file
View File

@@ -0,0 +1,40 @@
<!-- file: README.md -->
<!-- version: 1 -->
# SaseDev Knowledge
SaseDev Knowledge est la plateforme applicative destinée à publier et administrer plusieurs familles de connaissance SaseDev sans transformer PGR en encyclopédie technique.
Le dépôt applicatif retenu est `sasedev-knowledge`. Le nom court du produit et le préfixe de crates sont `knowledge`.
## Statut
La version courante est définie par [`VERSION`](VERSION).
`0.0.1` est une release de fondation. Elle établit la gouvernance, les frontières d'architecture, le workspace minimal, les premiers contrats et les validations nécessaires avant toute implémentation fonctionnelle importante.
## Invariants de fondation
- Git est la source autoritaire du contenu versionné.
- Une forge est une intégration optionnelle et ne constitue pas une dépendance du domaine.
- PostgreSQL conserve l'état applicatif ; il ne remplace pas Git comme vérité du contenu publié.
- La lecture publique doit pouvoir fonctionner depuis des copies Git locales et un index/cache applicatif sans appel à une forge pour chaque requête.
- PGR, HOWTOs, snippets et décisions `project-local` conservent des forces et responsabilités documentaires distinctes.
- Une proposition externe ne publie jamais directement du contenu et conserve la révision Git de base utilisée pour sa création.
## Entrées principales
- [`RULES.md`](RULES.md) — point d'entrée normatif local ;
- [`ROADMAP.md`](ROADMAP.md) — trajectoire macro engagée ;
- [`CHANGELOG.md`](CHANGELOG.md) — changements utiles par release ;
- [`docs/000-README.md`](docs/000-README.md) — index documentaire ;
- [`docs/objectives/001-PROJECT_OBJECTIVES.md`](docs/objectives/001-PROJECT_OBJECTIVES.md) — objectifs et non-objectifs ;
- [`docs/architecture/001-PROJECT_PROFILE.md`](docs/architecture/001-PROJECT_PROFILE.md) — baseline PGR, profils/skeletons et matrice de décisions ;
- [`docs/architecture/002-KNOWLEDGE_ARCHITECTURE.md`](docs/architecture/002-KNOWLEDGE_ARCHITECTURE.md) — architecture de fondation Git/forge/PostgreSQL et frontières de contenu ;
- [`docs/plans/001-V0_0_1_FOUNDATION_PLAN.md`](docs/plans/001-V0_0_1_FOUNDATION_PLAN.md) — plan vivant de `0.0.1` ;
- [`docs/validation/001-VALIDATION_MATRIX.md`](docs/validation/001-VALIDATION_MATRIX.md) — matrice de validation ;
- [`prompts/001-V0_0_1_START_PROMPT.md`](prompts/001-V0_0_1_START_PROMPT.md) — prompt de démarrage autoritaire de la release.
## Langue et nomenclature
Les noms de fichiers, crates, identifiants et code sont en anglais. La documentation normative et explicative principale est en français.

27
ROADMAP.md Normal file
View File

@@ -0,0 +1,27 @@
<!-- file: ROADMAP.md -->
<!-- version: 1 -->
# Roadmap SaseDev Knowledge
Le roadmap ne réserve que les releases dont la mission est réellement engagée.
Statuts : `( )` planifié, `(x)` terminé, `(d)` différé, `(c)` annulé.
## Fondation
- `( ) 0.0.1` — fondation Knowledge : gouvernance PGR, architecture Git/forge/PostgreSQL, frontières PGR/HOWTO/snippet, workspace Rust minimal, premiers contrats et baseline Web reproductible sans implémentation fonctionnelle disproportionnée.
## Domaines futurs non numérotés
Les thèmes suivants sont candidats à des releases ultérieures mais ne reçoivent pas encore de numéro :
- implémentation Git générique et synchronisation réelle ;
- état PostgreSQL et migrations applicatives ;
- contribution/revue et administration ;
- publication/rendu multi-familles ;
- recherche et indexation avancées ;
- adapter Gitea puis autres forges selon besoin réel ;
- authentification/autorisation complète ;
- déploiement et opérations multi-domaines.
Une revue d'horizon pendant `0.0.1` décidera si une prochaine version doit être engagée. Aucun numéro n'est inventé uniquement pour prolonger la roadmap.

140
RULES.md Normal file
View File

@@ -0,0 +1,140 @@
<!-- file: RULES.md -->
<!-- version: 1 -->
# Règles SaseDev Knowledge
## Scope
Ce document gouverne le dépôt 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 et de la topologie des dépôts de contenu.
Aucun `OVERRIDE` PGR n'est établi par `0.0.1-alpha.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.
## 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.
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.
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 ;
- Actix Web pour HTTP ;
- Maud pour le SSR lorsque pertinent ;
- Vite + TypeScript pour les assets et interactions frontend ;
- Sass ;
- Bootstrap ;
- PostgreSQL.
Ces choix ne sont pas présentés comme des règles PGR universelles.
## Rust et crates
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 pas utilisé par anticipation.
Le profil Rust strict PGR s'appliquera aux crates matérialisées, notamment Rust 2024, `unsafe` interdit par défaut, lints stricts, exports publics maîtrisés et chemins explicites.
## 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.

1
VERSION Normal file
View File

@@ -0,0 +1 @@
0.0.1-alpha.1

201
deltas/0.0.1/alpha.1.md Normal file
View File

@@ -0,0 +1,201 @@
<!-- file: deltas/0.0.1/alpha.1.md -->
<!-- version: 1 -->
# Delta 0.0.1-alpha.1 — cadrage et gouvernance Knowledge
## Base requise
Nouveau dépôt applicatif `sasedev-knowledge` avant sa première tranche gouvernée.
Aucune release Knowledge antérieure n'existe. L'absence initiale de `VERSION`, rules, plan, delta/history ou code applicatif est normale.
Le cadrage de cette tranche a été préparé à partir des artefacts externes autoritaires suivants :
```text
PGR tag stable v0.1.1
pgr-v0.1.1.zip SHA-256 caaf8f456f7f8520172ea7705fd0cf5c5bf0e942dc4a773410bcbe7fe4ce243a
PGR publish report pgr-0.1.1-publish.001-report.md = PASS
Knowledge start prompt prompts/001-V0_0_1_START_PROMPT.md
```
L'absence de `.git` dans l'archive taggée PGR est normale et a été vérifiée comme telle.
## Objet
Établir le gate de framing `0.0.1-alpha.1` avant toute implémentation fonctionnelle : gouvernance locale, owners/skeletons PGR applicables, architecture Git/forge/PostgreSQL, frontières PGR/HOWTO/snippet, plan de release et validation proportionnée.
La version devient :
```text
0.0.1-alpha.1
```
Cette tranche n'ajoute aucun serveur Actix, frontend Vite, schéma PostgreSQL, adapter Gitea ou implémentation Git.
## Fichiers ajoutés
```text
.gitignore
VERSION
README.md
RULES.md
ROADMAP.md
CHANGELOG.md
docs/000-README.md
docs/objectives/001-PROJECT_OBJECTIVES.md
docs/architecture/001-PROJECT_PROFILE.md
docs/architecture/002-KNOWLEDGE_ARCHITECTURE.md
docs/plans/001-V0_0_1_FOUNDATION_PLAN.md
docs/validation/001-VALIDATION_MATRIX.md
deltas/0.0.1/alpha.1.md
prompts/001-V0_0_1_START_PROMPT.md
```
Aucun fichier n'est remplacé ou supprimé.
Aucun manifest de suppression n'est nécessaire.
## Décisions de cadrage
La tranche fixe notamment :
- `sasedev-knowledge` comme nom du dépôt applicatif ;
- `knowledge` comme nom court et préfixe de crates ;
- la composition PGR réellement applicable sans activer Java/Android/Tauri ;
- les skeletons `001`, `002` et `003` comme trajectoire de composition, avec matérialisation progressive ;
- l'absence d'override PGR identifié ;
- Git comme backend autoritaire du contenu ;
- une forge comme adapter optionnel distinct des opérations Git ;
- une synchronisation fonctionnant sans webhook ;
- PostgreSQL comme état applicatif et projection reconstructible ;
- le monolithe modulaire comme baseline de départ ;
- la séparation des dépôts `pgr`, `howtos` et `snippets` ;
- les frontières de force normative entre PGR, HOWTO, snippet et project-local ;
- la trajectoire prévisionnelle de `0.0.1` et ses décisions explicitement différées.
## Prévalidation assistant effectuée
Avant livraison du delta, la stable PGR source a été vérifiée et rejouée :
```text
archive SHA-256 PASS
archive CRC PASS
292 entries / 256 files / 36 directories
root pgr/ PASS
symlinks 0
.git absent
VERSION 0.1.1
Python tests 48/48 PASS
Markdown headers clean, 231 files
Markdown tables clean, 9 tables / 231 files
Markdown links clean, 267 links / 231 files
0.1.1 deltas/histories 11 / 11, statuts conformes au publish report
```
Cette prévalidation ne constitue pas le résultat de la gate opérateur Knowledge.
## Validation attendue
Depuis la racine du nouveau dépôt après extraction du delta :
```bash
test "$(cat VERSION)" = "0.0.1-alpha.1"
git diff --check
python3 - <<'PY'
from pathlib import Path
import re
expected = {
".gitignore",
"VERSION",
"README.md",
"RULES.md",
"ROADMAP.md",
"CHANGELOG.md",
"docs/000-README.md",
"docs/objectives/001-PROJECT_OBJECTIVES.md",
"docs/architecture/001-PROJECT_PROFILE.md",
"docs/architecture/002-KNOWLEDGE_ARCHITECTURE.md",
"docs/plans/001-V0_0_1_FOUNDATION_PLAN.md",
"docs/validation/001-VALIDATION_MATRIX.md",
"deltas/0.0.1/alpha.1.md",
"prompts/001-V0_0_1_START_PROMPT.md",
}
actual = {
path.as_posix()
for path in Path(".").rglob("*")
if path.is_file() and ".git" not in path.parts
}
assert actual == expected, (sorted(actual - expected), sorted(expected - actual))
for path_string in sorted(expected):
path = Path(path_string)
if path.suffix != ".md":
continue
lines = path.read_text(encoding="utf-8").splitlines()
assert lines[0] == f"<!-- file: {path.as_posix()} -->", path
assert re.fullmatch(r"<!-- version: [1-9][0-9]* -->", lines[1]), path
rules = Path("RULES.md").read_text(encoding="utf-8")
profile = Path("docs/architecture/001-PROJECT_PROFILE.md").read_text(encoding="utf-8")
architecture = Path("docs/architecture/002-KNOWLEDGE_ARCHITECTURE.md").read_text(encoding="utf-8")
plan = Path("docs/plans/001-V0_0_1_FOUNDATION_PLAN.md").read_text(encoding="utf-8")
for phrase in (
"caaf8f456f7f8520172ea7705fd0cf5c5bf0e942dc4a773410bcbe7fe4ce243a",
"Aucun `OVERRIDE` PGR n'est établi",
"Git est la source autoritaire du contenu versionné publié",
):
assert phrase in rules, phrase
for phrase in ("ADOPT", "KEEP-LOCAL", "OVERRIDE", "DEFER", "003-WEB_FRONTEND"):
assert phrase in profile, phrase
for phrase in (
"Git est le backend du contenu ; une forge est une capacité optionnelle.",
"RepositoryEventSource",
"PGR / HOWTO / snippet / project-local",
"Git versus PostgreSQL",
):
assert phrase in architecture, phrase
assert "### alpha.2 — workspace Rust/Cargo minimal" in plan
assert "### rel.1 — fermeture stable" in plan
for forbidden in ("src/main.rs", "src/lib.rs", "package.json", "vite.config.ts", "migrations/"):
assert not Path(forbidden).exists(), forbidden
print("Knowledge 0.0.1-alpha.1 framing audit: clean")
PY
git add -A
git diff --cached --check
git status --short
```
Revue opérateur complémentaire :
- vérifier qu'aucun fichier fonctionnel non listé n'a été introduit ;
- vérifier que le dépôt est réellement nouveau ou que tout fichier local préexistant non livré a été identifié avant `git add -A` ;
- vérifier la cohérence des décisions locales et des `DEFER` ;
- vérifier l'absence de secret, credential, URL privée sensible ou chemin machine absolu ;
- vérifier que les fichiers Eclipse/IDE locaux restent ignorés.
## Transition
### PASS
Transmettre les sorties complètes de la gate opérateur.
L'assistant produit ensuite une archive history séparée pour `history/0.0.1/alpha.1.md`, puis prépare `0.0.1-alpha.2` consacré au workspace Rust/Cargo minimal conformément au plan.
Le commit de `alpha.1` intervient uniquement après application du history observé et avant application du delta suivant.
### FAIL / PARTIAL / BLOCKED
Conserver le résultat réel dans le history correspondant.
Rester dans le scope `alpha.1` et produire `0.0.1-alpha.1.fix.1` si le défaut relève de cette tranche. Aucun scope `alpha.2` ne doit être introduit dans le fix.

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.

104
history/0.0.1/alpha.1.md Normal file
View File

@@ -0,0 +1,104 @@
<!-- file: history/0.0.1/alpha.1.md -->
<!-- version: 1 -->
# History 0.0.1-alpha.1 — cadrage et gouvernance Knowledge
## Statut
FAIL
## Baseline validée
```text
Knowledge version 0.0.1-alpha.1
Delta deltas/0.0.1/alpha.1.md
Workspace ~/Projects/sasedev-knowledge
```
## Preuves opérateur observées
### Version
Commande :
```bash
test "$(cat VERSION)" = "0.0.1-alpha.1"
```
Résultat : PASS, aucune sortie.
### Whitespace avant staging complémentaire
Commande :
```bash
git diff --check
```
Résultat : PASS, aucune sortie.
### Audit de framing fourni par le delta
L'audit Python a échoué sur la comparaison stricte de tous les fichiers physiquement présents dans le workspace :
```text
Traceback (most recent call last):
File "<stdin>", line 26, in <module>
AssertionError: (['.project', '.settings/org.eclipse.core.resources.prefs'], [])
```
Le résultat de la tranche est donc `FAIL`.
### Whitespace du staging
Commande :
```bash
git diff --cached --check
```
Résultat : PASS, aucune sortie.
### État Git observé
```text
A .gitignore
A CHANGELOG.md
A README.md
A ROADMAP.md
A RULES.md
A VERSION
A deltas/0.0.1/alpha.1.md
A docs/000-README.md
A docs/architecture/001-PROJECT_PROFILE.md
A docs/architecture/002-KNOWLEDGE_ARCHITECTURE.md
A docs/objectives/001-PROJECT_OBJECTIVES.md
A docs/plans/001-V0_0_1_FOUNDATION_PLAN.md
A docs/validation/001-VALIDATION_MATRIX.md
A prompts/001-V0_0_1_START_PROMPT.md
```
`.project` et `.settings/org.eclipse.core.resources.prefs` existaient dans le workspace mais n'apparaissaient pas dans le staging de `alpha.1`.
## Diagnostic
Le `FAIL` révèle plusieurs défauts appartenant tous au scope de framing `alpha.1` :
1. la gate comparait les fichiers **physiquement présents** à la distribution attendue et considérait donc `.project` comme erreur alors que ce fichier Eclipse machine-local doit rester ignoré ;
2. `.settings/org.eclipse.core.resources.prefs` était également ignoré par le `.gitignore` initial alors que la politique PGR `v0.1.1` prévoit explicitement de le versionner pour conserver `encoding/<project>=UTF-8` ;
3. le `.gitignore` Knowledge ne portait pas le header texte `file/version` attendu par la convention documentaire adoptée ;
4. la décision produit « une même application MAY servir plusieurs hostnames » ne représente pas la topologie voulue : PGR, HOWTOs et snippets doivent être trois applications Actix Web distinctes dans un workspace commun ;
5. la fondation doit expliciter qu'au moins trois sources Git distinctes existent initialement et que PostgreSQL peut être partagé entre les trois applications pour l'état transversal sans remplacer Git comme source autoritaire du contenu.
Le contenu historique de `deltas/0.0.1/alpha.1.md` n'est pas réécrit. Ces corrections appartiennent à une tranche distincte.
## Transition
Produire et appliquer `0.0.1-alpha.1.fix.1` après :
1. application du présent history ;
2. commit de l'état complet `0.0.1-alpha.1` avec son résultat `FAIL` ;
3. push de ce commit selon la branche/remote réellement configurés ;
4. application seulement ensuite du delta `alpha.1.fix.1`.
Le fix reste strictement dans le scope `alpha.1` et n'introduit aucun code fonctionnel ni workspace Cargo.

265
prompts/001-V0_0_1_START_PROMPT.md Normal file
View File

@@ -0,0 +1,265 @@
<!-- file: prompts/001-V0_0_1_START_PROMPT.md -->
<!-- version: 1 -->
# Knowledge 0.0.1 — prompt de démarrage
## Mission
Initialiser le nouveau projet SaseDev Knowledge en conformité avec la stable PGR fournie.
Cette première version ne doit pas chercher à implémenter toute la plateforme. Elle doit établir une fondation de gouvernance, une architecture suffisamment précise pour éviter les mauvais couplages, un workspace minimal reproductible et un plan versionné pour les prochaines tranches.
La première tranche à préparer après audit est `0.0.1-alpha.1`.
## Baselines autoritaires
Utiliser comme autorité PGR :
- l'archive téléchargée depuis le tag Gitea stable `v0.1.1`, attendue sous un nom du type `pgr-v0.1.1.zip` ;
- le rapport post-tag `pgr-0.1.1-publish.001-report.md`, qui doit être `PASS`.
Vérifier les hashes fournis avec les artefacts de session. Ne pas inventer un hash si l'archive ou le rapport réellement fournis diffèrent d'un nom ou d'une copie antérieure.
L'absence de `.git` dans une archive de tag est normale.
Ne pas utiliser une conversation précédente comme autorité lorsque l'information peut être vérifiée dans l'archive PGR ou les artefacts fournis.
## Produit à construire
Le projet doit préparer une plateforme SaseDev Knowledge permettant à terme de publier et administrer :
- PGR ;
- des HOWTOs ;
- des snippets.
Les façades publiques envisagées sont notamment :
- `pgr.sasedev.com` ;
- `howtos.sasedev.com` ;
- `snippets.sasedev.com`.
Ces hostnames sont des intentions produit. Leur déploiement effectif ne fait pas partie de `0.0.1` sauf nécessité architecturale démontrée.
L'application doit être développée en interne et ne doit pas dépendre d'un CMS existant.
## Principe fondamental de stockage
Concevoir la plateforme avec la règle suivante :
> Git est le backend de contenu ; une forge est une capacité optionnelle.
Le cœur doit fonctionner avec :
- un dépôt Git local ;
- un remote Git générique ;
- éventuellement une forge telle que Gitea.
Gitea ne doit pas être introduit comme dépendance du domaine.
Les capacités forge-only — webhooks, pull requests, issues, releases, permissions — doivent être séparées des opérations Git fondamentales.
La lecture publique doit pouvoir continuer à partir d'une copie Git locale/index/cache lorsque la forge distante est temporairement indisponible.
## Source de vérité et PostgreSQL
Git est la source autoritaire du contenu versionné.
PostgreSQL est destiné à l'état applicatif, par exemple :
- utilisateurs et sessions ;
- propositions ;
- révisions et commentaires ;
- revue/modération ;
- audit applicatif ;
- index de contenu ;
- tags/relations calculés ;
- recherche ;
- état de synchronisation ;
- jobs de publication.
Ne pas faire de PostgreSQL la source autoritaire du contenu publié lorsque ce contenu existe dans Git.
## Synchronisation générique
Le système doit pouvoir détecter les changements sans dépendre des webhooks.
Étudier et cadrer :
- synchronisation explicite ;
- polling ;
- hook Git local/serveur ;
- webhook de forge.
Tous doivent converger vers un même cas d'usage interne de synchronisation.
Un watcher filesystem peut être un accélérateur, mais ne doit pas remplacer Git comme source de vérité sur la révision courante.
## Contributions externes
Le système doit permettre à un utilisateur externe de proposer :
- une correction ;
- un nouveau HOWTO ;
- un nouveau snippet ;
- éventuellement une amélioration de documentation PGR, sans contourner le workflow propre à PGR.
Une proposition ne doit jamais écrire directement dans le contenu publié.
Elle doit conserver la révision Git de base afin de détecter les conflits et besoins de rebase.
Le workflow d'administration doit pouvoir fonctionner même sans pull request fournie par une forge.
Lorsqu'une forge compatible est disponible, une branche/PR peut être utilisée comme intégration optionnelle.
## Frontières documentaires
Étudier et formaliser la distinction :
- `normative` : PGR ;
- `guidance/howto` : procédure, explication, diagnostic, anti-pattern ;
- `snippet` : exemple court/configuration/commande contextualisée ;
- `project-local` : décision concrète d'un projet.
Le système de métadonnées doit pouvoir relier ces contenus sans leur donner la même force normative.
Prévoir qu'un HOWTO/snippet puisse référencer des owners/règles PGR et que PGR puisse référencer facultativement une guidance externe sans en dépendre pour être intelligible.
## Stack technique initialement souhaitée
Évaluer cette stack par rapport à PGR et la retenir sauf raison documentée de déroger :
- Rust stable ;
- workspace Cargo ;
- Actix Web pour HTTP ;
- Maud pour le rendu HTML SSR ;
- Vite + TypeScript pour les assets et interactions frontend ;
- Sass ;
- Bootstrap ;
- PostgreSQL.
Ne pas figer prématurément :
- l'ORM/driver PostgreSQL ;
- le moteur de recherche ;
- la topologie de déploiement ;
- les noms définitifs des crates ;
- un découpage microservices ;
- le fournisseur Git/forge ;
- l'authentification externe ;
- les formats finaux HOWTO/snippet.
Ces points doivent être étudiés au moment où ils deviennent nécessaires.
## Travail PGR obligatoire avant implémentation
Lire dans la stable PGR au minimum :
- règles générales et workflow ;
- modèle de profils ;
- profil Rust/Cargo ;
- profil TypeScript ;
- profil JavaScript package ecosystem ;
- profil Vite ;
- profil CSS/Sass ;
- profils/éléments Tauri uniquement pour comprendre les frontières, sans les adopter automatiquement ;
- skeleton de fondation projet ;
- skeleton workspace Rust ;
- skeleton Web frontend ;
- validations associées ;
- templates Web TypeScript/package ;
- études pertinentes ;
- règles de documentation, versions, deltas/histories et handoff opérateur.
Ne pas recopier mécaniquement toute la structure PGR. Appliquer uniquement les owners/skeletons nécessaires et documenter les décisions locales.
## Architecture à étudier en 0.0.1
La première version doit aboutir à une décision claire sur au moins les frontières suivantes :
1. application/domain ;
2. Git générique ;
3. adapter forge ;
4. synchronisation événementielle/polling ;
5. workflow de propositions ;
6. parsing et validation des contenus ;
7. index/recherche/cache ;
8. rendu/publication ;
9. administration ;
10. authentification/autorisation au niveau conceptuel ;
11. séparation PGR/HOWTO/snippet ;
12. séparation contenu Git / état PostgreSQL.
Éviter de multiplier les crates sans ownership réel.
## Dépôts
Étudier explicitement au moins les options suivantes :
- un dépôt applicatif Knowledge ;
- le dépôt PGR existant comme source de contenu normative ;
- un dépôt HOWTOs séparé ;
- un dépôt snippets séparé.
Ne pas fusionner ces contenus dans PGR uniquement pour simplifier l'implémentation.
Le nom final du dépôt applicatif doit être proposé et justifié. `sasedev-knowledge` est un candidat, pas une obligation.
## Première version 0.0.1
`0.0.1` doit rester une version de fondation.
Objectifs candidats :
- gouvernance du nouveau dépôt ;
- sélection des profils/skeletons PGR applicables ;
- workspace Rust minimal ;
- architecture/ADR ou étude fondatrice ;
- configuration minimale reproductible ;
- premiers contrats/interfaces sans implémentation disproportionnée ;
- plan vivant des tranches suivantes ;
- validations/audits adaptés.
Ne pas construire en `0.0.1` :
- moteur de recherche complet ;
- UI d'administration complète ;
- workflow de contribution complet ;
- support complet Gitea/GitHub/GitLab ;
- publication multi-domaines en production ;
- moteur de rendu final de tous les formats ;
- système d'authentification complet.
## Étude avant `alpha.1`
Avant de produire le premier delta :
1. vérifier intégralement l'archive PGR et son rapport post-tag ;
2. relever les règles réellement applicables ;
3. établir une matrice `ADOPT / KEEP-LOCAL / OVERRIDE / DEFER` pour les décisions importantes ;
4. proposer l'architecture minimale ;
5. proposer la nomenclature du dépôt et des premières crates ;
6. identifier les décisions qui doivent rester différées ;
7. vérifier que le scope `0.0.1` est suffisamment petit ;
8. préparer un plan versionné ;
9. seulement ensuite produire `0.0.1-alpha.1`.
## Livrables attendus de l'assistant
Pour chaque tranche :
- analyse fondée sur les artefacts réels ;
- delta ZIP applicable à la racine du dépôt ;
- delta Markdown ;
- commandes opérateur exactes ;
- après retour opérateur : history observé ;
- tranche suivante ou `.fix.N` selon le résultat réel.
Ne jamais produire un history `PASS` avant réception des preuves opérateur correspondantes.
Lorsqu'un FAIL provient uniquement d'une gate ou d'un défaut de validation, conserver le contenu livré, historiser le FAIL et produire un fix limité au défaut réel.
## Condition de fin de session
Une session de version se termine uniquement selon le workflow PGR applicable : tranche de release, history observé, commit stable, tag stable et rapport post-tag lorsque la release l'exige.
Préparer avant la clôture le prompt de démarrage de la version suivante et le texte introductif correspondant.