diff --git a/presets/ekologgia/README.md b/presets/ekologgia/README.md new file mode 100644 index 0000000000..33fe7c80b1 --- /dev/null +++ b/presets/ekologgia/README.md @@ -0,0 +1,65 @@ +# Ekologgia Engineering Standards + +Preset Spec Kit encodant les standards d'ingénierie Ekologgia, dérivés des +conventions réelles du monorepo NotaImmo/Notamap (`notaimmo-backend`). + +## Ce que le preset impose + +| Règle | Où elle s'applique | +| --- | --- | +| Documentation FR canonique, miroir EN régénéré | `spec`, `tasks`, `implement` | +| ADR daté pour toute décision technique non triviale | `plan`, `tasks`, `implement` | +| Intégrations externes fail-closed — aucune donnée inventée | `spec`, `plan`, `implement` | +| Périmètre monorepo explicite (workspaces touchés, contrat entre eux) | `spec` | +| Modèle de données partagé dans `packages/core`, jamais dupliqué | `spec`, `plan`, `implement` | +| Guard et rôles déclarés pour chaque route | `plan` | +| Vérification explicite (lint, types, tests) — la CI ne teste pas | `plan`, `tasks`, `implement` | + +## Composition + +Le preset n'écrase aucun template du coeur. Il utilise la stratégie `append` sur +quatre points d'extension, ce qui le rend cumulable avec d'autres presets : + +| Cible | Fichier | Stratégie | +| --- | --- | --- | +| `spec-template` | `templates/spec-addendum.md` | `append` | +| `plan-template` | `templates/plan-addendum.md` | `append` | +| `tasks-template` | `templates/tasks-addendum.md` | `append` | +| `speckit.implement` | `commands/implement-addendum.md` | `append` | + +## Installation + +Depuis une copie locale du dépôt `spec-kit` : + +```bash +specify preset add --dev /chemin/vers/spec-kit/presets/ekologgia +``` + +Vérifier l'installation : + +```bash +specify preset list +``` + +## Adapter à un autre projet Ekologgia + +Les sections « Workspaces touchés » (`spec-addendum.md`) et « Modèle de données +partagé » (`plan-addendum.md`) nomment explicitement les workspaces de +`notaimmo-backend`. Pour un autre dépôt, ajuster ces deux listes ; le reste des +règles est indépendant du projet. + +## Origine des règles + +Les règles proviennent de sources vérifiables du dépôt `notaimmo-backend` : + +- `CLAUDE.md` — obligation documentaire, format ADR, français canonique, miroir EN +- `docs/architecture.md` — rôle de `packages/core` comme modèle unique, pattern + adaptateur fournisseurs +- `docs/workflows.md` — politique fail-closed sur Property Intelligence, guards + et rôles, absence de tests en CI +- `docs/decisions/2026-07-10-property-intelligence-stub-fail-closed.md` — la + règle fail-closed déjà formalisée en ADR + +## Licence + +MIT. diff --git a/presets/ekologgia/commands/implement-addendum.md b/presets/ekologgia/commands/implement-addendum.md new file mode 100644 index 0000000000..bfd961aed4 --- /dev/null +++ b/presets/ekologgia/commands/implement-addendum.md @@ -0,0 +1,59 @@ +--- + +## Définition de terminé — Ekologgia + +> Section ajoutée par le preset `ekologgia`. Elle complète la section +> « Done When » du coeur : les deux s'appliquent. + +Ces conditions ne sont pas des suggestions de fin de course. Une tâche +d'implémentation qui modifie le comportement du système n'est pas terminée tant +que la documentation correspondante n'est pas à jour. + +### Règles d'exécution + +1. **Documentation avant clôture.** Après toute modification significative — + nouvelle feature, refacto, changement d'architecture, nouvelle dépendance, + nouvel endpoint, changement de schéma de données — mettre à jour les fichiers + concernés dans `docs/` **avant** de considérer la tâche terminée. + +2. **ADR pour les décisions non triviales.** Si l'implémentation impose une + décision technique qui n'était pas dans le plan (choix de bibliothèque, + pattern, compromis de performance ou de sécurité), rédiger un ADR daté dans + `docs/decisions/` au format contexte / décision / alternatives écartées / + conséquences. Ne pas attendre la relecture. + +3. **Français canonique, anglais régénéré.** Écrire la documentation en français, + de façon concise et factuelle. Régénérer ensuite les fichiers correspondants + dans `docs/en/` — ne jamais éditer le miroir anglais directement. + +4. **Documenter le pourquoi, pas la ligne.** Le code documente le détail. `docs/` + documente le pourquoi et le comment global. Quelqu'un qui rejoint le projet + doit comprendre le système en quinze minutes de lecture. + +5. **Signaler les écarts.** En cas de divergence entre la documentation existante + et le code réel, corriger la documentation et le signaler explicitement dans + le rapport de complétion. + +6. **Fail-closed.** Ne jamais livrer un chemin de code qui invente une donnée + métier quand un service externe est absent. Stub explicite activé par variable + d'environnement et porteur d'un `disclaimer`, ou échec explicite — rien d'autre. + +7. **Modèle unique.** Les entités Mongoose et schémas Zod partagés vivent dans + `packages/core`. Ne pas dupliquer une définition de type dans un app parce que + c'était plus rapide. + +8. **Rapporter la vérification honnêtement.** Exécuter `pnpm lint`, + `pnpm check-types` et les tests des workspaces touchés. Reporter le résultat + réel, y compris les échecs et les zones sans couverture de test. Le dépôt + n'exécute pas les tests en CI : ce rapport est la seule vérification. + +### Done When — Ekologgia + +- [ ] `docs/architecture.md` et `docs/workflows.md` reflètent le code livré +- [ ] Un ADR daté existe pour chaque décision technique non triviale +- [ ] `docs/setup.md` liste toute nouvelle variable d'environnement ou commande +- [ ] `docs/changelog.md` porte une entrée datée de 2 à 3 lignes +- [ ] Les fichiers modifiés de `docs/` ont leur miroir régénéré dans `docs/en/` +- [ ] `pnpm lint` et `pnpm check-types` passent sur les workspaces touchés +- [ ] Le résultat réel des tests est reporté, échecs et lacunes compris +- [ ] Tout écart doc ↔ code découvert en chemin est corrigé et signalé diff --git a/presets/ekologgia/preset.yml b/presets/ekologgia/preset.yml new file mode 100644 index 0000000000..daa46fe2ab --- /dev/null +++ b/presets/ekologgia/preset.yml @@ -0,0 +1,46 @@ +schema_version: "1.0" + +preset: + id: "ekologgia" + name: "Ekologgia Engineering Standards" + version: "1.0.0" + description: "Standards d'ingénierie Ekologgia — documentation FR canonique + miroir EN, ADR obligatoires, intégrations fail-closed, périmètre monorepo explicite." + author: "Ekologgia" + repository: "https://github.com/ehoudet/spec-kit" + license: "MIT" + +requires: + speckit_version: ">=0.14.0" + +provides: + templates: + - type: "template" + name: "spec-template" + file: "templates/spec-addendum.md" + description: "Ajoute le périmètre monorepo et les impacts documentaires à la spec" + strategy: "append" + + - type: "template" + name: "plan-template" + file: "templates/plan-addendum.md" + description: "Ajoute la revue ADR, fail-closed, modèle partagé et sécurité au plan" + strategy: "append" + + - type: "template" + name: "tasks-template" + file: "templates/tasks-addendum.md" + description: "Ajoute la phase de clôture documentaire obligatoire aux tâches" + strategy: "append" + + - type: "command" + name: "speckit.implement" + file: "commands/implement-addendum.md" + description: "Ajoute la définition de terminé Ekologgia à l'exécution" + strategy: "append" + +tags: + - "ekologgia" + - "documentation" + - "adr" + - "monorepo" + - "french" diff --git a/presets/ekologgia/templates/plan-addendum.md b/presets/ekologgia/templates/plan-addendum.md new file mode 100644 index 0000000000..b5593f48ef --- /dev/null +++ b/presets/ekologgia/templates/plan-addendum.md @@ -0,0 +1,76 @@ +--- + +## Revue Ekologgia *(obligatoire)* + +> Section ajoutée par le preset `ekologgia`. À remplir avant de générer les tâches. + +### Décisions d'architecture (ADR) + +Liste chaque décision technique non triviale prise dans ce plan : choix de +bibliothèque, pattern, compromis de performance ou de sécurité, ajout d'une +dépendance, changement de schéma de données, nouvelle intégration externe. + +| Décision | Non triviale ? | ADR | +| --- | --- | --- | +| [Décision] | [Oui/Non] | [`docs/decisions/AAAA-MM-JJ-titre-court.md` ou « sans objet »] | + +Chaque ADR suit le format maison : **contexte**, **décision**, +**alternatives écartées**, **conséquences**. Le nom de fichier est daté +(`AAAA-MM-JJ-titre-court.md`). Écrire l'ADR fait partie du plan, pas de la +relecture : la tâche correspondante doit apparaître dans `tasks.md`. + +Si aucune décision non triviale n'est prise, l'écrire explicitement — un plan +sans ADR est un signal, pas un oubli toléré par défaut. + +### Modèle de données partagé + +- Les entités Mongoose et schémas Zod vivent dans `packages/core` et sont + consommés par `apps/api`, `apps/cli` et les scripts de seed via `workspace:*`. +- **Vérification** : ce plan introduit-il une définition de type ou de schéma + qui existe déjà, ou qui devrait vivre dans `packages/core` ? + [Réponse — si oui, corriger le plan avant de continuer.] +- Un changement de `packages/core` impacte **tous** ses consommateurs. Lister + ceux qui devront être rebuild ou adaptés : [liste ou « aucun »] + +### Intégrations externes et fail-closed + +Pour chaque appel sortant introduit ou modifié : + +- **Service** : [nom] +- **Configuration** : [variables d'environnement requises] +- **Chemin nominal** : [comportement quand le service répond] +- **Chemin dégradé** : [stub explicite activé par variable d'environnement, avec + `disclaimer` dans la réponse — ou échec explicite] +- **Production sans configuration** : doit échouer explicitement. Aucune valeur + plausible inventée. [Confirmer que le plan respecte ce point.] + +### Sécurité et autorisations + +Pour chaque route ou commande ajoutée : + +| Route / commande | Guard | Rôles autorisés | +| --- | --- | --- | +| [`METHOD /chemin`] | [`JwtAuthGuard` / public / …] | [`@Roles(...)` ou « public »] | + +`RolesGuard` s'applique **après** `JwtAuthGuard`. Une route sans ligne dans ce +tableau est une route non revue, pas une route publique. + +- **Secrets** : ce plan introduit-il une nouvelle variable d'environnement + sensible ? [Oui/Non — si oui, elle est documentée dans `docs/setup.md` et + jamais commitée.] +- **Données personnelles** : cette feature manipule-t-elle des données de + vendeurs, acheteurs ou notaires ? [Oui/Non — si oui, préciser la rétention et + qui y accède.] + +### Vérification + +Le dépôt n'exécute **pas** les tests en CI aujourd'hui (les workflows GitHub +Actions ne couvrent que le déploiement). La vérification est donc à la charge du +plan, explicitement. + +- **Commandes de vérification** : [`pnpm lint`, `pnpm check-types`, et les tests + du ou des workspaces touchés — préciser les commandes exactes] +- **Couverture de test attendue** : [quels comportements sont couverts par un + test automatisé, et lesquels sont vérifiés manuellement et pourquoi] +- **Vérification manuelle** : [étapes reproductibles, ou `scripts/demo-local.sh` + si le flux complet est concerné] diff --git a/presets/ekologgia/templates/spec-addendum.md b/presets/ekologgia/templates/spec-addendum.md new file mode 100644 index 0000000000..3059835aa6 --- /dev/null +++ b/presets/ekologgia/templates/spec-addendum.md @@ -0,0 +1,59 @@ +--- + +## Périmètre Ekologgia *(obligatoire)* + +> Section ajoutée par le preset `ekologgia`. Rédigée en français — le français est +> la langue canonique des artefacts projet. + +### Workspaces touchés + +Coche les workspaces du monorepo que cette feature modifie. Une feature qui +touche plusieurs workspaces doit expliciter le contrat entre eux. + +- [ ] `apps/api` — API HTTP (NestJS + Mongoose) +- [ ] `apps/web` — front public et espaces notaire/négociateur/staff (Next.js) +- [ ] `apps/backoffice` — back-office interne (Vite + React-admin) +- [ ] `apps/cli` — synchronisation nocturne (AWS Batch) +- [ ] `apps/cdk` — infrastructure (AWS CDK) +- [ ] `packages/core` — entités Mongoose, schémas Zod, services partagés +- [ ] Autre : [PRÉCISER] + +**Contrat inter-workspaces** : [Si plusieurs workspaces sont cochés, décrire ce +qui circule entre eux — endpoint, type partagé, événement. Sinon : « sans objet ».] + +### Modèle de données + +- **Entités touchées** : [`listing`, `contact`, `estimation`, … ou « aucune »] +- **Nouveau champ / nouvelle entité ?** [Oui/Non — si oui, il est défini dans + `packages/core` et **jamais** dupliqué dans un app. Voir la règle de modèle + unique dans la constitution.] +- **Migration nécessaire ?** [Oui/Non — si oui, décrire l'état des documents + existants et la stratégie de rétrocompatibilité.] + +### Intégrations externes + +Pour chaque service tiers appelé (Property Intelligence, PERVAL, SendGrid, +OpenAI, ADNOV, Noty Broadcast, BAN/adresse.data.gouv.fr, Stripe…) : + +| Service | Usage | Comportement si indisponible ou non configuré | +| --- | --- | --- | +| [Nom] | [Ce qu'on lui demande] | [Fail-closed attendu — voir ci-dessous] | + +**Règle fail-closed** : aucune donnée métier ne doit être inventée quand un +service externe est absent. Soit un stub explicite activé par variable +d'environnement et porteur d'un `disclaimer`, soit un échec explicite. Un +comportement dégradé silencieux est un défaut de spécification, pas un choix +d'implémentation. + +### Impact documentaire + +Cette feature imposera une mise à jour de (cocher ce qui s'applique) : + +- [ ] `docs/architecture.md` — nouveau composant, flux, ou choix technique +- [ ] `docs/workflows.md` — workflow métier ou technique modifié +- [ ] `docs/decisions/` — ADR requis (décision technique non triviale) +- [ ] `docs/setup.md` — nouvelle variable d'environnement ou commande +- [ ] `docs/changelog.md` — toujours coché pour une feature livrée + +> Le miroir anglais `docs/en/` est **régénéré** depuis le français, jamais édité +> à la main. Il n'a donc pas à être listé ici. diff --git a/presets/ekologgia/templates/tasks-addendum.md b/presets/ekologgia/templates/tasks-addendum.md new file mode 100644 index 0000000000..450c62207c --- /dev/null +++ b/presets/ekologgia/templates/tasks-addendum.md @@ -0,0 +1,47 @@ +--- + +## Phase de clôture Ekologgia *(obligatoire)* + +> Section ajoutée par le preset `ekologgia`. Ces tâches sont **toujours** +> générées, en dernière phase, et ne sont jamais marquées optionnelles. + +Une feature n'est pas terminée quand le code marche : elle est terminée quand la +documentation reflète le code. Ces tâches ferment cet écart. + +### Vérification + +- [ ] `T[N]` Exécuter `pnpm lint` sur les workspaces touchés — zéro erreur +- [ ] `T[N]` Exécuter `pnpm check-types` sur les workspaces touchés — zéro erreur +- [ ] `T[N]` Exécuter les tests des workspaces touchés et reporter le résultat réel + (si aucun test n'existe pour la zone modifiée, l'écrire explicitement dans + le rapport de complétion plutôt que de passer la tâche sous silence) + +### Documentation (français — source canonique) + +Générer une tâche par fichier réellement impacté, en s'appuyant sur la section +« Impact documentaire » de `spec.md`. Ne pas générer de tâche pour un fichier non +impacté. + +- [ ] `T[N]` Mettre à jour `docs/architecture.md` — [composant, flux ou choix + technique introduit, avec sa justification] +- [ ] `T[N]` Mettre à jour `docs/workflows.md` — [workflow métier ou technique + modifié] +- [ ] `T[N]` Rédiger `docs/decisions/AAAA-MM-JJ-titre-court.md` — [une tâche par + ADR identifié dans le plan : contexte, décision, alternatives écartées, + conséquences] +- [ ] `T[N]` Mettre à jour `docs/setup.md` — [nouvelles variables + d'environnement, prérequis ou commandes] +- [ ] `T[N]` Ajouter une entrée datée à `docs/changelog.md` — 2 à 3 lignes, + factuelles + +### Miroir anglais + +- [ ] `T[N]` Régénérer les fichiers correspondants dans `docs/en/` depuis leur + version française. Le miroir est **régénéré**, jamais édité à la main : ne + régénérer que les fichiers dont la version FR a changé dans cette feature. + +### Cohérence doc ↔ code + +- [ ] `T[N]` Relire les fichiers `docs/` touchés à la recherche d'un écart avec le + code réel. Corriger la documentation et signaler l'écart dans le rapport de + complétion — un écart découvert est une information, pas une nuisance.