pgr/docs/rules/210-WORKFLOW.md

<!-- file: docs/rules/210-WORKFLOW.md -->
<!-- version: 5 -->

# Workflow artifact rules

## Scope

Ce document définit les contrats communs des artefacts de workflow gouvernés par PGR et leur ordre d'application.

Il couvre les plans, deltas, histories, prompts, handoffs, manifests de suppression, commits de tranche, reprise de session et baselines stables.

Les règles détaillées de validation et la taxonomie des preuves appartiennent à [`400-VALIDATION.md`](400-VALIDATION.md).

## Principe général

Le workflow MUST préserver une frontière nette entre l'intention d'une tranche, sa validation réelle et l'état Git qui en résulte.

La séquence canonique d'une tranche est :

```text
delta N
    ↓
apply
    ↓
validate
    ↓
history N
    ↓
apply history
    ↓
commit N
    ↓
delta N+1
```

Le delta suivant MUST NOT être appliqué avant le commit de la tranche courante, sauf opération explicite de récupération documentée après erreur de manipulation.

Un résultat `FAIL`, `PARTIAL` ou `BLOCKED` n'interdit pas le commit de la tranche constatée. Le history enregistre l'état réel et la tranche corrective suivante part de ce commit.

## Plan de release

Un plan décrit la trajectoire active d'une release lorsque cette trajectoire mérite un document dédié.

Les plans vivent sous :

```text
docs/plans/
```

Un plan :

- SHOULD être créé ou consolidé pendant `alpha.1` lorsque plusieurs tranches ou décisions doivent être coordonnées ;
- MAY évoluer lorsque la réalité invalide le forecast ;
- SHOULD NOT être modifié à chaque tranche uniquement pour recopier l'avancement ;
- MUST distinguer prévision et état réellement observé ;
- MUST NOT remplacer ROADMAP, delta ou history.

Lorsqu'un plan existe pour une release gouvernée par le workflow PGR, il MUST aussi rendre explicites, de manière proportionnée :

- la mission, le scope et le hors-scope actuellement applicables ;
- la stratégie de validation et les gates qui conditionnent réellement la fermeture ;
- la trajectoire prévisionnelle des responsabilités, sans transformer le forecast en promesse immuable ;
- une section ou un bloc **clôture et transition** indiquant où seront traités la réconciliation documentaire durable, le `CHANGELOG`, la mise à jour de `ROADMAP`, le prompt ou handoff de reprise, la fermeture du plan et la promotion/publication ;
- l'état de la **revue d'horizon** : soit elle n'est pas nécessaire parce que la roadmap possède déjà un horizon suffisant, soit son déclencheur et le moment où elle sera instruite sont identifiés.

Le plan MUST NOT inventer une version future uniquement pour remplir la rubrique de transition. Lorsque la cible suivante n'est pas suffisamment décidée, il l'indique explicitement et planifie une revue d'horizon ou un handoff approprié plutôt que de fabriquer un numéro, une mission ou un prompt.

Un changement substantiel du plan MAY être porté par une tranche REPLAN conformément aux règles de gouvernance. Le corps du plan reste l'état de pilotage actuellement applicable ; les deltas et histories conservent le détail historique des changements. PGR n'impose pas un journal `Revisions` alimenté à chaque tranche.

À la clôture `completed`, `abandoned` ou `superseded`, le plan devient principalement historique. Il ne doit plus être réécrit pour refléter silencieusement la connaissance acquise dans des releases ultérieures.

## Delta

Un delta est un artefact prospectif : il décrit exactement le changement à appliquer pour une tranche avant sa validation opérateur.

Le chemin canonique est :

```text
deltas/X.Y.Z/<tranche>.md
```

Le nom `<tranche>` reprend l'identité de prerelease ou de tranche sans répéter `X.Y.Z`, par exemple :

```text
alpha.3.md
alpha.3.fix.1.md
beta.1.md
rc.1.md
```

Un delta MUST :

- déclarer la baseline attendue et la version après application lorsque la tranche change `VERSION` ;
- déclarer son scope avec uniquement les opérations `ADD`, `REPLACE` et `DELETE` ;
- fournir les fichiers complets à ajouter ou remplacer dans son archive de livraison ;
- documenter les suppressions exactes ;
- fournir les commandes de validation opérateur applicables à la tranche ;
- définir la transition PASS/FAIL attendue.

Un delta MUST NOT demander des patchs manuels ligne par ligne lorsqu'un fichier complet peut être livré.

Après livraison au destinataire, le delta est un snapshot historique et MUST NOT être réécrit silencieusement. Une correction passe par une tranche `.fix.N` ou un REPLAN selon le problème.

## History

Un history est un artefact rétrospectif : il enregistre ce qui a réellement été observé lors de la validation d'une tranche.

Le chemin canonique est :

```text
history/X.Y.Z/<tranche>.md
```

Son identité MUST correspondre à celle du delta qu'il constate.

Le statut est l'un des états suivants selon ce qui a réellement été obtenu :

```text
PASS
FAIL
PARTIAL
BLOCKED
```

Un history SHOULD contenir au minimum :

- le statut ;
- la baseline/version validée ;
- les commandes ou preuves opérateur réellement observées ;
- les diagnostics utiles lorsqu'une validation échoue ou reste partielle ;
- la décision de transition vers la tranche suivante, un fix, un REPLAN ou un arrêt.

Le history MUST être appliqué avant le commit de la tranche qu'il constate.

Une fois committé, un history est historique et MUST NOT être réécrit pour présenter rétroactivement un meilleur résultat. Une erreur factuelle importante découverte ensuite doit être corrigée par un nouvel artefact explicite.

## Archives de livraison delta et history

Lorsqu'un échange se fait par archive ZIP, les noms canoniques sont :

```text
<project>-<X.Y.Z>-<tranche>.delta.zip
<project>-<X.Y.Z>-<tranche>.history.zip
```

L'archive delta contient uniquement les fichiers à ajouter ou remplacer pour la tranche, plus les artefacts de workflow qui appartiennent à cette tranche.

L'archive history contient uniquement le ou les fichiers history à appliquer pour clôturer l'état validé, sauf besoin explicitement documenté.

Delta et history MUST rester des livraisons séparées afin que la preuve observée ne soit pas confondue avec l'intention prospective.

Lorsque la gate courante est `PASS` et que la tranche suivante est déjà déterminée par le plan sans décision ouverte, le générateur SHOULD préparer et remettre dans la même réponse :

```text
archive history de la tranche courante
+
archive delta de la tranche suivante
```

Les deux archives restent séparées. Cette optimisation de flux n'autorise jamais l'application du delta suivant avant l'application du history courant et le commit complet de la tranche.

Le delta suivant SHOULD NOT être anticipé lorsqu'une décision opérateur, un REPLAN non résolu, un abandon/supersession, une preuve externe post-tag ou toute autre dépendance peut encore modifier sa baseline ou son scope.

## Commit de tranche

Le commit d'une tranche doit représenter l'état complet de cette tranche, y compris son history.

Avant ce commit :

```text
current delta changes
+ current history
```

doivent être présents, alors que le delta suivant MUST rester absent.

Le message de commit MAY suivre les conventions du projet. PGR n'impose pas Conventional Commits, GitFlow ou une topologie universelle de branches.

L'important est que l'état et la tranche restent identifiables et que le repository ne mélange pas deux tranches non clôturées.

## Manifest de suppression

Lorsqu'un delta supprime des chemins, un manifest de suppression MAY être utilisé pour permettre une application fiable de l'archive.

Le chemin canonique est :

```text
manifests/X.Y.Z/<tranche>.delete.txt
```

S'il existe :

- chaque ligne significative MUST identifier exactement un chemin à supprimer ;
- l'ensemble des chemins MUST être exactement égal aux suppressions déclarées dans le delta ;
- aucun chemin supplémentaire ne peut être supprimé implicitement ;
- le manifest n'est créé que lorsqu'une suppression réelle le justifie.

Un manifest ne doit pas exister vide uniquement pour satisfaire une structure théorique.

## Prompt de démarrage versionné

Un prompt de démarrage versionné transmet le contrat de reprise nécessaire pour ouvrir une nouvelle version depuis une baseline autoritaire sans reconstruire implicitement l'état du projet depuis une conversation antérieure, un workspace non fourni ou une mémoire informelle.

Le chemin canonique est :

```text
prompts/NNN-VX_Y_Z_START_PROMPT.md
```

`NNN` est monotone à l'échelle du dépôt.

Le prompt MUST rester un artefact de reprise et de cadrage. Il référence les règles, plans, histories, handoffs ou documents techniques qui possèdent déjà le détail ; il MUST NOT les recopier exhaustivement ni devenir une seconde source normative concurrente.

### Contrat minimal

Le prompt MUST couvrir, sous des titres adaptés au projet plutôt que selon une forme imposée, les éléments suivants lorsqu'ils sont applicables :

1. **baseline autoritaire et cible** — identifier la source exacte depuis laquelle la version doit être ouverte, la version cible et la première tranche attendue ; préciser les limites matérielles de cette source, par exemple l'absence normale de `.git` dans une archive de tag ;
2. **ordre de lecture** — nommer les points d'entrée normatifs, plans, histories, handoffs ou documents de subsystem qui doivent être lus avant de modifier le projet lorsqu'un ordre est nécessaire pour reconstruire correctement le contexte ;
3. **état déjà acquis** — résumer uniquement les résultats stables nécessaires à la reprise et les décisions qui ne doivent pas être redébattues sans preuve nouvelle ; cet état MUST rester traçable à la baseline ou aux artefacts cités ;
4. **mission et résultat attendu** — décrire ce que la version doit rendre vrai ou livrer, sans substituer un catalogue de tâches à l'objectif ;
5. **scope et hors-scope** — borner les changements autorisés et les sujets explicitement différés afin d'éviter qu'une reprise étende silencieusement la release ;
6. **décisions gelées et questions ouvertes** — distinguer les choix déjà établis des décisions que la première tranche doit encore instruire ; une valeur non prouvée MUST rester ouverte plutôt qu'être figée arbitrairement ;
7. **première gate** — définir l'objectif de la première tranche, les lectures/audits ou preuves préalables attendus et, lorsque nécessaire, les travaux interdits avant fermeture de ce gate ;
8. **trajectoire prévisionnelle** — fournir uniquement le forecast nécessaire pour dimensionner la release et ordonner les responsabilités ; il reste non contraignant et peut être scindé, fusionné ou replanifié selon les preuves ;
9. **validation et responsabilité** — rappeler les familles de gates pertinentes, les validations déjà imposées par les règles applicables et toute séparation importante entre préparation, exécution opérateur et preuve observée, sans déclarer réussie une commande qui n'a pas été exécutée.

Un projet MAY regrouper plusieurs de ces éléments dans une même section lorsque le résultat reste explicite et non ambigu. Le prompt n'a pas à reproduire littéralement cette numérotation.

### Sources externes et données manquantes

Lorsqu'une release dépend de snapshots, corpus, rapports ou autres sources externes, le prompt MUST identifier celles qui sont réellement autoritaires pour la reprise et définir le comportement lorsque l'une d'elles manque.

L'absence d'une source attendue MUST être signalée. Le travail doit alors être borné à ce que les preuves disponibles permettent réellement de conclure ; le prompt MUST NOT autoriser à reconstituer silencieusement une version, un commit, un contenu ou un résultat depuis une conversation antérieure ou un workspace non fourni.

Une preuve externe complète la baseline seulement pour les propriétés qu'elle établit. Elle ne remplace pas l'audit de la source effectivement fournie à la nouvelle session.

### Décisions acquises et détails locaux

Le prompt SHOULD citer les décisions acquises qui empêchent une régression ou une réouverture inutile, mais il SHOULD pointer vers leur owner documentaire lorsque leur explication détaillée existe déjà.

Les contraintes locales de langage, plateforme, framework, architecture ou métier restent chez leurs owners respectifs. Leur présence dans un prompt de projet ne les élève pas au rang de règle générale PGR.

Le prompt MAY imposer un ordre de lecture détaillé ou une matrice de questions lorsque la taille du projet le justifie. Un petit projet SHOULD conserver une forme plus courte si elle couvre le même contrat de reprise.

### Création et clôture

Lorsque la version suivante est suffisamment connue, son prompt SHOULD être amorcé pendant la consolidation finale, vérifié pendant la RC et finalisé pendant la promotion stable. Il MUST être présent dans la stable taggée qui prépare cette reprise.

Lorsque la cible suivante n'est pas suffisamment connue, PGR MUST NOT fabriquer un prompt de version, un numéro ou une mission pour respecter une cérémonie. Le plan et la roadmap indiquent alors que l'horizon reste ouvert et un handoff `NEXT` ou une revue d'horizon porte la continuité nécessaire.

Une interruption au milieu d'une version MUST NOT produire artificiellement le prompt de la version suivante. La reprise de la tranche courante utilise son état committé et, si nécessaire, un handoff conforme au présent document.

Lorsqu'une stable publiée possède une cible suivante connue, le générateur MUST remettre spontanément à l'opérateur, après la vérification post-tag applicable, une courte consigne manuelle identifiant l'archive du tag, le rapport post-tag lorsqu'il existe réellement, le prompt versionné à lire et la première gate. [`../templates/003-NEW_SESSION_PROMPT.md`](../templates/003-NEW_SESSION_PROMPT.md) décrit cette forme courte ; elle reste distincte du prompt versionné et ne remplace ni son contrat détaillé ni la preuve de publication.

Si une preuve post-tag externe est requise pour la prochaine reprise, le prompt versionné MAY annoncer à l'avance son nom attendu mais MUST la décrire comme une preuve future extérieure au tag. La consigne manuelle finale ne la présente comme `PASS` qu'après sa production et sa vérification réelles.

## Handoff

Un handoff est un snapshot de continuité utilisé lorsqu'un travail doit être repris à une frontière de session ou de responsabilité sans changer artificiellement de version ou de tranche. Un REPLAN traité entièrement dans la même session n'a pas besoin d'un handoff uniquement pour laisser une trace : delta, history et plan possèdent déjà cette trace.

Le chemin canonique est :

```text
handoffs/X.Y.Z/NNN-TYPE-<description>.md
```

Le dossier `X.Y.Z` est celui de la version source du handoff.

Les types usuels sont :

```text
CONTINUE
REPLAN
ABANDON
SUPERSEDE
NEXT
```

Selon le besoin réel, un handoff SHOULD permettre de retrouver sans mémoire conversationnelle :

- son type, la version source et une cible éventuelle ;
- la baseline autoritaire et le dernier état opérateur validé ;
- le dernier delta validé et tout delta livré mais encore en attente ;
- l'état du plan, le travail terminé et le travail restant ;
- les décisions acquises, les questions ouvertes et les validations restantes ;
- le prompt applicable lorsqu'il existe ;
- l'instruction exacte de reprise et, lorsque cela aide l'opérateur, un court texte copiable vers la nouvelle session.

Un petit handoff n'a pas à répéter les champs sans valeur pour son cas. Il référence les owners existants plutôt que recopier leurs règles.

Un `NEXT` après stable peut transmettre une version suivante connue. Si l'horizon est volontairement ouvert, il peut au contraire transmettre explicitement le besoin de revue d'horizon sans inventer une release.

Une fois livré comme snapshot de reprise, un handoff SHOULD être traité comme historique plutôt que réécrit continuellement.

Un changement de conversation ou de session n'est jamais, à lui seul, une raison de changer `VERSION`.

## Baseline stable et archive taggée

Après validation et commit de la stable, le tag canonique `vX.Y.Z` identifie la source stable.

Pour une reprise ou une nouvelle session après release, l'archive source générée depuis ce tag par le forge canonique du projet SHOULD être la baseline autoritaire lorsque ce mode de distribution est utilisé.

L'absence de `.git` dans une archive source taggée est normale. Une vérification de cette archive MUST porter sur sa cohérence interne et MUST NOT exiger une preuve Git que l'archive ne peut matériellement contenir.

Un projet MAY conserver une autre baseline de distribution si son écosystème l'exige, mais cette exception doit être explicite.

## Clôture stable et vérification post-tag

La validation pré-tag et la vérification de l'archive réellement publiée sont deux preuves distinctes.

La séquence recommandée est :

```text
stable delta
    ↓
stable validation
    ↓
stable history / release closure
    ↓
commit
    ↓
tag vX.Y.Z
    ↓
published source archive
    ↓
post-tag verification
```

Un identifiant opérationnel tel que `rel.001` ou `publish.001` MAY être utilisé pour distinguer une clôture ou une vérification de publication sans devenir une nouvelle version SemVer produit.

`rel.001` prouve l'état stable avant création du tag. Une preuve `publish.001`, lorsqu'elle existe, porte sur l'artefact réellement publié après le tag et reste donc extérieure au tag qu'elle vérifie. Elle ne revalide pas fonctionnellement la release.

Lorsqu'un rapport `publish.001` est un prérequis de la session suivante, la clôture post-tag MUST indiquer explicitement à l'opérateur qu'il doit fournir ce rapport avec l'archive taggée. Le démarrage suivant effectue toujours son propre audit d'intake de la baseline ; il ne traite pas pour autant la stable précédente comme une release encore en attente de validation.

## Conservation et immutabilité

Deltas, histories, handoffs, plans historiques, études et autres preuves utiles SHOULD être conservés lorsqu'ils expliquent une décision ou permettent une reprise fiable.

Les documents vivants peuvent évoluer selon leur rôle. Les snapshots historiques déjà consommés par le workflow ne doivent pas être retouchés silencieusement.

Une suppression historique est réservée aux contenus réellement nuisibles, secrets, juridiquement problématiques ou devenus dangereusement trompeurs ; la raison et le remplacement SHOULD alors être documentés.

## Répertoires à la demande

PGR MUST NOT imposer la création de répertoires workflow vides.

Des répertoires comme :

```text
history/
handoffs/
manifests/
prompts/
deltas/
```

sont créés lorsqu'ils reçoivent leur premier artefact réel dans le projet concerné.