Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
66 changes: 29 additions & 37 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,28 +9,22 @@ travail à plusieurs postes. Licence **GPL-3.0-only** (`LICENSE`) ; démonstrati
<https://demo.scribae.eu>.

Ce fichier s'adresse à un agent (Claude Code, Mistral Vibe…) qui reprend le dépôt. Le
**même dépôt est aussi édité dans un atelier** (Perchance) : le dépôt est la référence
**publiée**, l'atelier la copie de travail. Ne renommez donc pas les fichiers sans raison.

> **Si vous travaillez dans l'atelier, lisez `src/docs/ATELIER.md` AVANT d'écrire une ligne.**
> C'est le document écrit pour être suffisant à lui seul quand on n'a pas de terminal : la
> méthode en six gestes, les dix garde-fous, le harnais qui fait tourner la syntaxe, le style,
> les épreuves et les générateurs **sans Node**, l'éprouvette du service de l'aperçu, les
> parcours du navigateur, et la liste de ce qu'on vérifie avant de dire « terminé » (§ 9).
**dépôt est la seule source de vérité** : on y travaille directement, sur la branche `dev`,
et la branche `main` ne reçoit que ce qui a été revu (voir « Comment on livre » ci-dessous).
Ne renommez donc pas les fichiers sans raison.

## Par où commencer

| Fichier | Ce qu'il contient |
|---|---|
| `src/docs/ATELIER.md` | **à lire si vous travaillez dans l'atelier** : la méthode, les garde-fous, comment vérifier sans terminal, et ce qui est « terminé » |
| `src/README.md` | **à lire en premier** : architecture, conventions de code, pièges connus, et le flux de travail atelier ↔ dépôt |
| `src/README.md` | **à lire en premier** : architecture, conventions de code, pièges connus, et le flux de travail |
| `src/SPEC.md` | la spécification fonctionnelle complète |
| `src/TODO.md` | les chantiers ouverts (et ceux faits) |
| `src/CHANGELOG.md` | le journal des versions — son premier titre daté donne `APP_VERSION` |
| `src/docs/REPRISE.md` | le kit de reprise : points d'entrée, « un seul point de vérité par règle », recettes de livraison |
| `src/audit/REGISTRE-NON-CONFORMITES.md` | les non-conformités connues, avec statut et preuves — **à lire avant de promettre** |
| `tests/README.md` | ce que tient chaque épreuve |
| `src/docs/` | atelier (la méthode), administration, Docker, API, variables, industrialisation, performance |
| `src/docs/` | administration, Docker, API, variables, industrialisation, performance |

## Comment c'est rangé

Expand All @@ -40,14 +34,12 @@ Ce fichier s'adresse à un agent (Claude Code, Mistral Vibe…) qui reprend le d
/ README.md, AGENTS.md, CLAUDE.md, package.json, LICENSE, CNAME, .nojekyll
index.html, main.pjs la page publiée (GitHub Pages) et son code
compose-exemple/ L'EXEMPLE DE PREMIER DÉPLOIEMENT : MariaDB + l'image publiée, deux services
scripts/ L'OUTILLAGE : vérifications, analyse statique, générateurs de documents,
harnais de l'atelier (harnais-atelier.mjs)
scripts/ L'OUTILLAGE : vérifications, analyse statique, générateurs de documents
tests/ LES ÉPREUVES transverses (le service éprouve, lui, à côté de son code)
src/ LE CODE, servi tel quel par le navigateur
lib/ ui/ css/ pages/ métier pur · écrans · feuilles de style · édition statique
server/ service auto-hébergé (docker-compose, MySQL, nginx) — voir son README
docs/ audit/ pdfa/ wiki.js documentation, cadre d'audit, polices du PDF/A, guide intégré
(docs/ATELIER.md = la méthode de travail et les garde-fous)
CHANGELOG.md SPEC.md TODO.md README.md les documents de travail
server/mysql/*.test.mjs les épreuves du service, à côté de ce qu'elles éprouvent
```
Expand All @@ -57,11 +49,20 @@ src/ LE CODE, servi tel quel par le navigateur
> `src/docs/GITHUB.md`, `src/AGENTS.md` ou `src/CLAUDE.md` **sous** `src/`, ce sont des doublons
> d'une version précédente (l'outillage et l'exemple de déploiement vivent à la racine) :
> `git rm -r …`. Un doublon fait corriger le fichier que personne ne lit.
>
> **Dans l'atelier, c'est l'inverse : ne supprimez RIEN de ce qui est sous `src/`.** L'atelier ne
> conserve qu'un seul arbre (`src/`), et l'export y prend ces fichiers pour les remonter à la
> racine du dépôt : `src/AGENTS.md`, `src/CLAUDE.md`, `src/scripts/**`, `src/tests/**`,
> `src/package.json`, `src/github/**` et `src/compose-exemple/**` y sont donc **à leur place**.

## Comment on livre — le dépôt est la source de vérité

Le développement se fait **ici**, sur la branche `dev` :

1. **Une branche par sujet**, partagée de `dev` (`vibe/<sujet>` ou le nom du chantier) —
jamais de commit direct sur `main`, qui ne reçoit que des fusions relues ;
2. **un changement, un sujet** : pas de renommage ni de réorganisation « au passage » ;
3. **vérifier en local avant d'envoyer** : `npm run verifier` (syntaxe + style strict +
épreuves) — c'est ce que la CI rejoue ;
4. **une pull request vers `dev`**, la CI verte avant toute demande de relecture ;
5. **la trace** : une entrée datée dans `src/CHANGELOG.md` (rubrique `Ajouté` / `Modifié` /
`Corrigé` / `Retiré`), `APP_VERSION` (`src/lib/version.js`) au même numéro, et les
documents que le changement rend faux.

## Vérifier — c'est tout ce qui compte

Expand All @@ -75,12 +76,6 @@ npm run style # le style seul, en strict : un avertissement fait écho
npm test # les épreuves (tests/ + le domaine du service)
```

> **Sans terminal (atelier).** Ces commandes demandent un processus, que l'atelier n'a pas : le
> harnais **`scripts/harnais-atelier.mjs`** les rejoue — les scripts livrés **tels quels** — et
> rend un verdict en quelques lignes (`h.texte(await h.verifier({ fs }))`). La recette exacte, les
> chiffres attendus et les dix-neuf écarts connus (tous dus à l'absence de Node) sont dans
> `src/docs/ATELIER.md` § 3.

Le **contrôle de style est écrit maison** (`scripts/verifier-style.mjs`, sans dépendance) : il
refuse `debugger`, signale `var` et les `console.log` du code client, et refuse les **imports
jamais employés** — un import que plus personne n'utilise trompe la lecture et survit à toutes
Expand All @@ -91,22 +86,19 @@ dans la console de la page de l'application (voir `src/docs/INDUSTRIALISATION.md

## Les garde-fous, en une ligne chacun

Le détail, et le **pourquoi** de chacun, sont dans `src/docs/ATELIER.md` § 1.
Ce sont des règles **du projet**, pas des préférences. Chacune a été payée par un incident.

1. **Ne rien publier ni enregistrer sans demande explicite** (l'atelier porte une version non
enregistrée : l'enregistrer fige un nom, et un nom ne se défait pas).
1. **Ne rien publier ni enregistrer sans demande explicite.**
2. **Ne jamais écrire à la main un document engendré** (`VARIABLES.md`, `API.md`,
`logiciel-engendre.mjs`) : corriger la source, puis régénérer.
3. **Une règle, une seule implémentation** — et quand deux existent (les deux services), le jeu
de conformité les tient ensemble.
4. **Aucune dépendance nouvelle** ; le métier (`src/lib/`) ne touche ni au DOM ni au réseau.
5. **Tout est en français**, commentaires compris ; un commentaire dit le **pourquoi**.
6. **Après une série d'écritures : recharger l'aperçu** — les fichiers n'y sont pas appliqués
avant, et l'on croirait regarder la nouvelle version.
7. **Toute variable de déploiement a sa ligne dans les deux `env.example`.**
8. **Une livraison laisse une trace** : changelog daté, `APP_VERSION` accordé, documents corrigés.
9. **Un changement, un sujet** : pas de renommage ni de réorganisation « au passage ».
10. **Ne jamais dire « terminé » sans preuve**, ni annoncer un chiffre qu'on n'a pas mesuré.
6. **Toute variable de déploiement a sa ligne dans les deux `env.example`.**
7. **Une livraison laisse une trace** : changelog daté, `APP_VERSION` accordé, documents corrigés.
8. **Un changement, un sujet** : pas de renommage ni de réorganisation « au passage ».
9. **Ne jamais dire « terminé » sans preuve**, ni annoncer un chiffre qu'on n'a pas mesuré.

## Les règles du projet

Expand Down Expand Up @@ -169,10 +161,10 @@ Le détail, et le **pourquoi** de chacun, sont dans `src/docs/ATELIER.md` § 1.
## Avant de dire « terminé »

On ne rend la main que lorsque ces lignes sont vraies — chacune avec une **preuve**, pas une
intention. La liste complète est dans `src/docs/ATELIER.md` § 9.
intention.

- `npm run verifier` (ou, dans l'atelier, `h.verifier({ fs })`) : **syntaxe 0 faute, style code 0**,
et **aucun fichier autrefois vert n'est rouge** ;
- `npm run verifier` : **syntaxe 0 faute, style code 0**, et **aucun fichier autrefois vert
n'est rouge** ;
- si le **service** a changé : les **deux** implémentations, et le jeu de conformité ;
- si un **écran** a changé : il a été **regardé** (390 px **et** grand) ;
- les **documents engendrés** sont régénérés si leur source a bougé ;
Expand Down
5 changes: 0 additions & 5 deletions CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,9 +6,4 @@ code : il dit où chaque chose vit, comment vérifier (`npm run verifier`), les
(l'outillage ne vit qu'à la racine, la CI est stricte, un correctif du client demande de
reconstruire l'image `web`).

**Si vous travaillez dans l'atelier (Perchance), lisez d'abord `docs/ATELIER.md`** : c'est là que
sont la méthode, les dix garde-fous, le harnais qui rejoue syntaxe, style, épreuves et générateurs
**sans terminal** (`scripts/harnais-atelier.mjs`), et la liste de ce qu'on vérifie avant de dire
« terminé ».

@AGENTS.md
14 changes: 4 additions & 10 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -375,19 +375,13 @@ npm test # node --test tests/ et le domaine du service
dépôt — commence par **`AGENTS.md`** : il tient l'arborescence, les commandes, les
règles du projet (aucune dépendance, métier sans DOM ni réseau, documents engendrés
à ne pas modifier à la main), les pièges et la licence. **`CLAUDE.md`** y renvoie.
S'il travaille dans **l'atelier** (l'édition en ligne, où il n'y a ni terminal ni
processus), il lit en plus **`src/docs/ATELIER.md`** : la méthode, les dix
garde-fous, le harnais `scripts/harnais-atelier.mjs` — qui rejoue la syntaxe, le
style, les épreuves et les générateurs **sans Node** — et ce qui compte comme
« terminé ». Le fond vit sous `src/` : `src/README.md` (mode d'emploi du code,
Le fond vit sous `src/` : `src/README.md` (mode d'emploi du code,
doctrine, recettes d'exploitation et de livraison), `src/SPEC.md` (spécification),
`src/docs/` (service, administration, industrialisation, atelier), `src/audit/`
`src/docs/` (service, administration, industrialisation), `src/audit/`
(registre).

Un fichier ne vit qu'à **un seul endroit** : la table de l'export
(`src/README.md` § « Exporter le dépôt GitHub ») dit lequel. Le même outillage, dans
l'atelier de travail, sert à faire tourner l'aperçu — d'où des chemins qui restent
relatifs dans les deux dispositions.
Un fichier ne vit qu'à **un seul endroit** : `src/README.md`, § « Disposition des
fichiers », dit lequel vit où et pourquoi.

## Version

Expand Down
18 changes: 18 additions & 0 deletions src/CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -23,6 +23,24 @@ numéros `MAJEUR.MINEUR.CORRECTIF` ([semver](https://semver.org/lang/fr/)).
- On décrit le **changement visible** (ce que l'utilisateur constate, ou ce que
l'exploitant doit savoir), pas la liste des fichiers touchés.

## [1.6.3v] — 2026-10-24 — La doc agent dit le nouveau monde : le dépôt est la source unique

**Modifié**

- **Les consignes aux agents disent le dépôt, et seulement le dépôt.** Le flux de
travail « Perchance ↔ GitHub », les recettes d'export et la double disposition
des fichiers disparaissent : on développe dans le dépôt sur `dev`, une branche
par sujet, une PR par sujet vers `dev` avec la chaîne verte avant relecture, et
chaque livraison laisse une trace — une entrée datée au changelog et
`APP_VERSION` à jour.

**Retiré**

- **L'atelier en ligne (Perchance) et son harnais de vérification sans Node ne
figurent plus dans la doc agent.** Le mot « atelier » reste pour l'écran interne
de l'application, inchangé.


## [1.6.3u] — 2026-10-01 — L'acte modificatif se referme comme l'acte modifié

Demande : « quand un acte a été modifié, la vue en version consolidée est complètement cassée
Expand Down
Loading
Loading