Conventions editoriales — ulk

Reconstitue depuis agents/_shared/base-rules.md, agents-authoring.md et les pratiques observees dans le codebase.

1. Nommage des fichiers

1.1 Agents

Type	Pattern	Exemple
Agent racine	`NN-agent-name.md`	`25-bruce.md`
Agent sous-dossier	`NN-agent-name.md`	`frontend/01-brique.md`
Protocole partage	`nom-descriptif.md`	`_shared/context-protocol.md`
Checklist	`nom-checklist.md`	`frontend/checklists/ux-checklist.md`

La numerotation est globale et preservee (prochain : 51). Les trous historiques ne sont pas reutilises (02-03, 13-14, 19-20, 22-23, 28-30, 33, 37).

1.2 Documents generes

Type	Pattern	Emplacement
Audit	`audit-[TYPE]-YYYYMMDD.md`	`docs/audits/`
Rapport	`[type]-YYYYMMDD.md`	`docs/reports/`
Import Notion	`spec_notion.md`, `todo_notion.md`	`docs/imports/`
Communication	`update-YYYYMMDD.md`	`docs/communications/`
API	`*.md`	`docs/api/`
Metadonnees	`*.json`	`.claude/`
Entree memoire	`slug-en-kebab-case.md`	`docs/_memory/<categorie>/`

1.3 Documents manuels

Type	Pattern	Emplacement
Specification	`spec.md`	`docs/`
Kanban	`todo.md`	`docs/`
Guide	`guide.md`	`docs/`
Reference	`reference.md`	`docs/`
ADR	`adr.md`	`docs/`
Glossaire	`glossaire.md`	`docs/`
Index	`index.md`	`docs/00-meta/`
Conventions	`conventions.md`	`docs/00-meta/`

1.4 Regles generales de nommage

kebab-case pour tous les fichiers Markdown
Pas d’espaces dans les noms de fichiers
Max 60 caracteres pour les noms de fichiers de memoire (slugification automatique)
Suffixe date (-YYYYMMDD) pour les rapports et audits

2. Frontmatter YAML

2.1 Frontmatter standard pour documents

---
title: "Titre du document"
type: spec | audit | guide | report | adr | task | context
category: "Categorie libre"
date: YYYY-MM-DD
updated: YYYY-MM-DD
status: draft | active | deprecated | archived
author: nom-agent | nom-humain
tags:
  - tag1
  - tag2
---

Champs obligatoires : title, type, date, status.

Champs recommandes : category, author, tags.

Champs optionnels : updated, version.

2.2 Frontmatter agent

---
name: agent-name
description: |
  Description multi-lignes de l'agent.
  Quand l'invoquer et mots-cles de detection.
tools: Read, Glob, Grep, Bash, Write, Task, AskUserQuestionTool
model: opus | sonnet
phase: define | plan | build | verify | review | ship | orchestrator
invocation: /ulk:name or "name" or "trigger"
extends:
  - _shared/base-rules.md
  - _shared/update-protocol.md
---

2.3 Frontmatter Monoboard (todo.md)

---
kanban-plugin: board
project: Nom du Projet
version: "1.0.0"
updated: YYYY-MM-DD
---

2.4 Frontmatter entree memoire (vault)

---
title: "Titre de l'entree"
category: lesson | pattern | mistake | insight | rule | research
subcategory: architecture | debugging | workflow | typescript
project: nom-projet
severity: critical | major | minor
tags: [tag1, tag2]
date: YYYY-MM-DD
captured_from: MEMORY.md
status: active
---

3. Conventions Markdown

3.1 Structure des documents

h1 (#) : titre unique du document, correspond au title du frontmatter
h2 (##) : sections principales (numerotees ## 1. Titre, ## 2. Titre)
h3 (###) : sous-sections
h4 (####) : findings dans les rapports d’audit (avec prefixe [PREFIX-NNN])

3.2 Tableaux

Privilegier les tableaux Markdown pour les donnees structurees :

| Colonne 1 | Colonne 2 | Colonne 3 |
|-----------|-----------|-----------|
| Valeur | Valeur | Valeur |

3.3 Blocs de code

Toujours specifier le langage : ```yaml, ```bash, ```typescript
Pour les commandes, utiliser ```bash
Pour les structures de donnees, utiliser le langage adapte

3.4 Liens

Liens relatifs entre documents du meme depot : [Titre](./chemin-relatif.md)
Pas de wikilinks ([[...]]) dans la documentation principale (reservees au vault Obsidian docs/_memory/)
Liens absolus uniquement pour les ressources externes

3.5 Emojis et indicateurs

Contexte	Convention
Priorites	P0, P1, P2, P3
Scores	/10 (ex: 7/10)
Statuts dans les tableaux	`draft`, `active`, `deprecated`, `archived`
Findings	Prefixes `#A001`, `#A11Y-001`, `#PERF-001`

4. Format des findings (audits)

#### [PREFIX-NNN] Titre du finding
- **Fichier** : `path/to/file.ts:42`
- **Probleme** : Description factuelle
- **Impact** : Consequence mesurable
- **Recommandation** : Action concrete
- **Effort** : Estimation realiste

Prefixes par source :

Source	Prefixe
Code audit	`A`
A11y audit	`A11Y-`
Perf audit	`PERF-`
API design	`API-`
SEO audit	`SEO-`

5. Format des taches (todo.md)

5.1 Carte courte

- [ ] #PREFIX-NNN [PX] Description #zone #effort-S

5.2 Carte detaillee

### #PREFIX-NNN · Titre
> Contexte — Severite

- **Critere de done** : Definition precise
- **Estimation** : Xh
- **Dependances** : aucune | #XXX
- **Fichiers concernes** : liste

**Sous-taches :**
- [ ] Sous-tache 1
- [ ] Sous-tache 2

5.3 Niveaux de priorite

Priorite	Criteres
P0	Bloquant : securite, bugs critiques, data loss
P1	Haute : perf majeure, archi cassee, DX degradee
P2	Moyenne : qualite, dette tech, tests manquants
P3	Basse : style, doc, nice-to-have

5.4 Niveaux d’effort

Effort	Duree
XS	< 30 min
S	1-2h
M	2-4h
L	4-8h
XL	1-2 jours
XXL	3-5 jours

6. Conventions git

6.1 Format de commit

[prefix]([scope]): description (#ID)

6.2 Prefixes

Categorie	Prefixe
Nouvelle fonctionnalite	`feat`
Correction de bug	`fix`
Refactoring	`refactor`
Documentation	`docs`
Tests	`test`
Maintenance	`chore`
Performance	`perf`
Securite	`security`

7. Conventions pour les agents docs

7.1 Regles absolues

Exhaustif : couvrir l’integralite du perimetre demande
Factuel : chaque finding avec fichier:ligne quand applicable
Actionnable : chaque issue = une recommandation concrete
Prioritise : Securite > Performance > Qualite > Style
Non destructif : ne pas supprimer sans archiver ou documenter
Reproductible : documenter les commandes et conditions utilisees
Idempotent : relancer l’agent produit le meme resultat
Incremental : mettre a jour les sections existantes plutot que reecrire

7.2 Langue

Tout en francais : rapports, messages, commentaires dans les documents generes.

7.3 Scoring standard

Score	Niveau
8-10	Bon
5-7	Moyen
0-4	Critique