# Versioning & documentation

> Git est la **source unique de vérité**. Un artefact n'est "terminé" que s'il est
> **à la fois versionné ET documenté**. Règle non négociable (voir `CLAUDE.md`).

## Qu'est-ce qu'un "artefact" ?
Tout ce qui est créé ou modifié et qui a un effet : workflow n8n, stack/compose
Docker, code de l'orchestrateur, outil MCP, image Docker, doc d'asset.

## SemVer (`vMAJEUR.MINEUR.PATCH`)
- **MAJEUR** : changement incompatible (rupture d'API/contrat/comportement).
- **MINEUR** : ajout rétro-compatible (nouvel outil, nouvelle capacité).
- **PATCH** : correctif rétro-compatible, doc, durcissement sans rupture.
- Phase `0.x` : on tolère des ruptures sur le MINEUR (projet pré-1.0).

La version du dépôt est portée par `CHANGELOG.md` + un **tag git** `vX.Y.Z`.
Les assets individuels (workflow, stack, outil) portent **leur propre** version
dans leur en-tête de doc et dans la table assets (champ `version`).

## Règle "un artefact = un commit"
Chaque création/modification d'artefact = **un commit dédié** :
- message clair (Conventional Commits : `feat:`, `fix:`, `chore:`, `docs:`…),
- bump de version approprié + entrée `CHANGELOG.md`,
- la **doc** de l'artefact mise à jour dans le même commit.

Message type :
```
feat: <artefact> — <quoi> (vX.Y.Z)

<pourquoi / contexte>. Palier de risque : <réversible|privilégié>.
```

## Images Docker
- Tags **épinglés** et versionnés. **Jamais `:latest`**.
- Idéalement épingler aussi le **digest** (`image@sha256:…`) pour l'immuabilité.
- Tout bump d'image = commit + entrée CHANGELOG + note de rollback.

## Workflows n8n
- Exportés en **JSON** dans `workflows-n8n/` — **le dépôt fait foi**, pas l'instance.
- Convention de nommage : `workflows-n8n/<slug>.v<MAJEUR.MINEUR.PATCH>.json`.
- Chaque workflow a une doc d'asset (voir `asset-template.md`).

## Documentation d'un asset
Chaque artefact a une doc suivant `docs/asset-template.md` (rôle, entrées/sorties,
dépendances, **palier de risque**, **rollback**). Un asset non documenté est
**incomplet** et ne doit pas être considéré livré.

## Lien avec le cycle "need review" (Phase 2+)
En Phase 4, CHLOVA devra **committer + versionner + générer la doc** d'un asset
**avant** de le passer en "need review". La notification de review inclut la
**version** + le **lien commit** + le **lien doc** (champs `version`,
`lien_commit`, `lien_doc` de la table assets).