Formats de fichiers

Les fichiers de codev sont du Markdown et du YAML destinés à être rédigés par des personnes et des agents, puis analysés par codev. Ce chapitre en donne les règles exactes, avec les mots-clés anglais. codev lit aussi leurs équivalents français (### Exigence :, ## Exigences AJOUTÉES, DOIT…), présentés dans Langue des artefacts.

Tout ce qui figure dans des blocs de code délimités et dans des commentaires HTML est ignoré par les analyseurs : les templates peuvent donc contenir des consignes dans des commentaires <!-- … -->.

Spec principale

Chemin : _codev/specs/<capability>/spec.md, où <capability> est formé d’un ou plusieurs segments en kebab-case (ui/theme). Seul un fichier nommé exactement spec.md est une spec principale : les autres fichiers de _codev/specs/, comme un README.md, sont ignorés par codev list --specs et codev validate.

# Theme Specification

## Purpose

Permettre aux utilisateurs de choisir le thème de couleurs de l'interface.

## Requirements

### Requirement: Le thème suit par défaut la préférence du système

L'application SHALL s'afficher avec le jeu de couleurs du système d'exploitation tant que l'utilisateur n'a pas choisi de thème.

#### Scenario: Aucun thème encore choisi

- **GIVEN** un utilisateur qui n'a jamais modifié le réglage du thème
- **WHEN** son système d'exploitation est en mode sombre
- **THEN** l'application s'affiche avec le thème sombre

• ## Purpose est obligatoire.
• Les exigences sont des titres ### Requirement: <name> placés dans ## Requirements. Le nom identifie l’exigence dans les deltas : veillez à ce qu’il soit unique au sein de la spec.
• La description d’une exigence contient un mot-clé normatif en majuscules : SHALL ou MUST, ou DOIT ou DOIVENT.
• Chaque exigence comporte au moins un #### Scenario: <name>, avec exactement quatre caractères #. Les étapes d’un scénario sont des lignes à puces utilisant **GIVEN**, **WHEN**, **THEN** et **AND**.
• Les autres sections ## sont autorisées et préservées lors des fusions.
• Les titres de delta (## ADDED Requirements…) sont interdits dans une spec principale.

Lorsque l’archivage crée la spec principale d’une nouvelle capacité, il la titre d’après le dernier segment du chemin de la capacité (# Theme Specification) et recopie la section ## Purpose du delta.

Delta de spec

Chemin : _codev/changes/<name>/specs/<capability>/spec.md, avec le même chemin de capacité que la spec principale qu’il modifie.

## ADDED Requirements

### Requirement: Le thème choisi est mémorisé

L'application SHALL restaurer le dernier thème choisi par l'utilisateur, sur chacun des appareils depuis lesquels il se connecte.

#### Scenario: Utilisateur de retour

- **GIVEN** un utilisateur qui a choisi le thème sombre sur son ordinateur portable
- **WHEN** il se connecte depuis son téléphone
- **THEN** l'application s'affiche avec le thème sombre

## MODIFIED Requirements

### Requirement: Le thème suit par défaut la préférence du système

<l'exigence complète, scénarios compris, telle qu'elle doit se lire après le change>

## REMOVED Requirements

### Requirement: Ancien sélecteur de couleurs

**Reason**: Remplacé par le réglage du thème.
**Migration**: Les couleurs personnalisées des utilisateurs sont abandonnées ; le thème par défaut s'applique.

## RENAMED Requirements

- FROM: Le thème suit par défaut la préférence du système
- TO: Le thème suit la préférence du système jusqu'au choix de l'utilisateur

Dans RENAMED, écrivez après FROM: et TO: soit le nom seul de l’exigence, comme ci-dessus, soit le titre complet entre accents graves, comme le fait le template : - FROM: `### Requirement: <old name>`.

Règles vérifiées par la validation :

• Une exigence figure dans une seule section au plus parmi ADDED, MODIFIED et REMOVED (cross_section_conflict), et au plus une fois par section (duplicate_requirement).
• Dans une section de delta, chaque titre ### est un ### Requirement: (delta_unexpected_heading) ; une section sans aucune entrée fait l’objet d’un avertissement (delta_section_empty).
• La source d’un RENAMED doit exister dans la spec principale (rename_source_missing, sauf si le renommage a déjà été appliqué par une synchronisation antérieure) ; la cible d’un RENAMED ne peut pas figurer aussi dans ADDED (rename_target_collision) ; et MODIFIED emploie le nouveau nom d’une exigence renommée, et non l’ancien (modified_uses_old_name).
• Les noms cités dans MODIFIED et REMOVED doivent exister dans la spec principale ; cette vérification a lieu lors de la fusion du delta (modified_target_missing).
• Nouvelle capacité : commencez le delta par ## Purpose. Pour une capacité existante, omettez cette section : le Purpose de la spec principale est conservé.
• Un delta REMOVED qui laisserait une spec sans aucune exigence est refusé (would_leave_spec_without_requirement), sauf si le change déclare retire_capabilities: true ; la spec principale est alors supprimée.

proposal.md

Le template du schéma spec-driven :

# Proposal: <change title>

## Why

## What Changes

## Capabilities

### New Capabilities

### Modified Capabilities

### Removed Capabilities

## Impact

## Domains

## Release note

Chaque capacité listée sous New Capabilities ou Modified Capabilities reçoit son propre fichier de delta dans specs/<capability>/spec.md. Les changements incompatibles sont signalés par BREAKING dans What Changes. Une capacité listée sous Removed Capabilities exige retire_capabilities: true.

Release note

Ce que les utilisateurs liront dans le changelog, construit par codev changelog. Soit un ou plusieurs éléments :

## Release note

- Added: `--format json` pour `codev export`.
- Changed: **BREAKING** `codev export` écrit sur stdout par défaut ; passez
  `--output <PATH>` pour écrire un fichier.

soit, pour un change que les utilisateurs ne remarqueront pas, la seule ligne :

## Release note

None

Chaque élément s’écrit - <Category>: <texte>, la catégorie étant l’une de Added, Changed, Deprecated, Removed, Fixed et Security — les catégories de Keep a Changelog. Un élément peut s’étendre sur plusieurs lignes. Un élément incompatible commence son texte par **BREAKING**. Le texte suit la langue des artefacts du projet. codev validate signale une section absente par un avertissement, et une catégorie inconnue, un élément sans texte ou une section vide par une erreur, sur les changes actifs uniquement.

Domains

Les domaines que touche le change, qui activent leurs experts. Le modèle liste les six domaines non cochés ; cochez ceux que touche le change :

## Domains

- [x] security
- [ ] personal-data
- [ ] user-interface
- [ ] performance
- [x] operations — un nouveau worker en arrière-plan
- [ ] migration

ou, lorsqu’il n’en touche aucun, écrivez la seule ligne None.

- [x] <domaine> ou - <domaine> coche un domaine, - [ ] <domaine> le laisse non coché, et le texte qui suit le nom du domaine est un commentaire libre. Les domaines sont security, personal-data, user-interface, performance, operations et migration. codev validate signale, sur les changes actifs uniquement, un domaine inconnu (unknown_domain) et une ligne qui n’est ni un élément ni None, ou None à côté d’un domaine coché (domains_invalid), par une erreur, et une section absente (domains_missing) par un avertissement.

Ce commentaire est aussi la façon de répondre à un domaine suggéré que le change ne touche pas : un domaine non coché suivi d’une raison est justified — - [ ] security — only renames a variable. Les tirets, deux-points et espaces de tête ne font pas partie de la raison ; None ne justifie rien. codev validate signale chaque domaine suggéré ni coché ni justifié par domain_suggested, un avertissement à la ligne du domaine.

design.md

# Design: <change title>

## Context

## Goals / Non-Goals

## Decisions

### Decision: <the choice>

**Alternatives considered**:

## Risks / Trade-offs

## Migration Plan

## Open Questions

Chaque bloc ### Decision: <title> peut être promu en ADR avec codev decision promote <change> "<title>". Risks / Trade-offs suit la forme [Risk] → Mitigation. Migration Plan et Open Questions sont supprimées lorsqu’elles ne s’appliquent pas.

tasks.md

# Tasks

## 1. Jetons de thème

- [ ] 1.1 Déplacer chaque couleur dans une propriété CSS personnalisée, vérifié par un diff visuel de la page des réglages
- [ ] 1.2 Ajouter le jeu de jetons sombres, vérifié par `npm test -- theme`

Les tâches sont regroupées sous des titres ## numérotés et s’écrivent - [ ] X.Y <task> ; /codev-apply les coche sous la forme - [x]. Chaque tâche indique comment la vérifier.

change.yaml

Chemin : _codev/changes/<name>/change.yaml. Écrit par codev new change. <name> n’est jamais archive, le dossier des changes archivés.

schema: spec-driven
created: 2026-09-30
goal: Let users switch the UI to a dark theme

Les clés inconnues sont rejetées — dans review aussi. Un codev antérieur à review refuse un change.yaml qui la définit : relevez le codev_version du projet jusqu’à la version qui l’a introduite avant de l’utiliser. Un dossier de change dépourvu de change.yaml utilise le schéma du projet. Une entrée invalide de roles est signalée par codev validate comme une erreur du change (unknown_role, invalid_role_activation, role_not_disableable).

Les artefacts d’un schema.yaml peuvent déclarer leur rôle comme une donnée, sous role: — voir Schémas personnalisés.

review.md

Chemin : _codev/changes/<name>/review.md. Le compte rendu de revue du change, écrit par /codev-propose (plan.challenge) et /codev-apply (code.review), ou à la main. Ce n’est pas un artefact de planification : codev status l’ignore, codev sync le laisse en place, codev archive le déplace avec le change.

# Review record: add-sessions

<!-- codev-review: 1 -->

## plan.challenge

### skeptic

No finding.

### security

#### R-security-1 Session tokens are stored in clear

```yaml
severity: high
confidence: high
location: "design.md#Decision: Sessions live in the database"
evidence: |
  The session token is stored in the `sessions` table.
recommendation: Store a SHA-256 of the token and compare digests.
history:
  - status: open
    by: security
  - status: fixed
    by: architect
    ref: design.md, the decision now stores a digest
  - status: fixed
    by: security
    note: verified
```

## code.review

### newcomer

Disabled by configuration.

Les titres et les lignes No finding. et Disabled by configuration. restent en anglais : codev les lit.

Un champ que ce codev ne connaît pas est un avertissement, review_unknown_field, et il est ignoré : un codev ultérieur peut ajouter des champs facultatifs sans changer de format. Un nouveau statut, une nouvelle étape ou un nouveau champ obligatoire relève au contraire le marqueur de format, qu’un codev plus ancien refuse de vérifier. Les transitions et les contrôles sont dans Compte rendu de revue.

Décision (ADR)

Chemin : _codev/decisions/NNNN-<slug>.md. Chaque fichier .md de ce dossier est analysé comme une décision.

---
id: "0003"
title: "Use SQLite for persistence"
status: accepted
date: 2026-09-30
tags: [storage]
supersedes: ["0001"]
---

## Context

## Decision

## Consequences

## Alternatives considered

Le frontmatter est délimité par des lignes --- placées tout au début du fichier. Le contenu est découpé en sections ## ; les quatre sections du template relèvent de la convention, et non de l’obligation. Seules les décisions accepted qui ne sont ni remplacées ni l’objet d’un écart sont en vigueur, et supersedes comme deviates_from ne prennent effet que sur une décision accepted : un remplacement ou un écart proposed ne change rien avant codev decision accept.

Les fichiers enregistrés avec des fins de ligne Windows (CRLF) sont lus comme les autres. Lorsque codev réécrit le statut d’une décision — codev decision accept, ou un prédécesseur passé en superseded —, il conserve les fins de ligne du fichier et laisse le corps identique à l’octet près : le sceau reste valide.

seal.yaml

Chemin : _codev/decisions/seal.yaml. Maintenu par codev ; ne le modifiez pas à la main.

version: 1
seals:
- id: '0001'
  bodySha256: sha256:fad1f272bf13eb44f97aba1bc22f36f294503d1a2471bf12ab4bfc6ee7b4d7f6
  sealedAt: 2026-09-30

Chaque entrée enregistre l’empreinte SHA-256 du contenu d’une décision — tout ce qui suit le --- fermant du frontmatter, octet pour octet — et la date de son scellement. Commitez ce fichier avec vos décisions.

codev.lock

Chemin : _codev/codev.lock. Écrit uniquement par codev sources update, au format TOML.

version = 1

[[source]]
git = "git@github.com:acme/codev-standards.git"
ref = "main"
commit = "12958274cbed0eb66985f57d3272c6d3134b672d"
resolved_at = "2026-09-30"

Une entrée [[source]] par source git:, avec la ref qu’elle suit, le commit sur lequel elle est épinglée et, le cas échéant, son subpath. Commitez ce fichier.

SKILL.md

Chemin : .claude/skills/codev-<workflow>/SKILL.md. Généré par codev init et codev update :

---
name: codev-explore
description: "Explore an idea, investigate a problem or clarify a need before creating a codev change. …"
allowed-tools: "Bash(codev:*), Read, Glob, Grep"
license: MIT
metadata:
  generator: codev
  version: "0.6.1"
  checksum: "8d676b09…"
---

<workflow instructions>

metadata.checksum est l’empreinte SHA-256 de toute la skill, hors de cette ligne. Avec metadata.version, c’est ce qui permet à codev update de distinguer les rendus de codev de vos modifications. codev update réécrit une skill marquée d’une autre version ; parmi les skills marquées de sa propre version, il réécrit celle dont le contenu correspond encore à son checksum — un rendu de codev, d’une compilation antérieure ou pour l’autre mode de revue — et préserve celle qui n’y correspond plus, modifiée à la main, sauf si vous passez --force. Une skill sans checksum, rendue avant leur existence, est préservée quand elle porte la marque de cette version et diffère du rendu par plus que le mode de revue : lancez une fois codev update --force pour la doter d’un checksum — il écrase aussi une skill que vous avez réellement modifiée : vérifiez d’abord git diff, puis réappliquez vos modifications ; une modification faite ensuite est préservée, puisqu’elle ne correspond plus au checksum.

Codes de validation

Chaque constat signalé par codev validate porte un code stable. Les messages peuvent être reformulés d’une version à l’autre ; les codes, non.