pgr/docs/rules/210-WORKFLOW.md

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.

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 :

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 :

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 :

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 :

alpha.3.md
alpha.3.fix.1.md
beta.1.md
rc.1.md
rel.1.md
rel.1.fix.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 :

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 :

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 :

<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 :

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.

Hygiène mécanique des artefacts texte

Les fichiers texte de gouvernance ajoutés ou remplacés MUST être livrés avec des fins de ligne LF, sans whitespace terminal et avec exactement une seule newline finale. Une ligne vide supplémentaire à EOF constitue un défaut de livraison même si le contenu sémantique du document est inchangé.

Avant remise d'un delta ou d'un history, le générateur MUST contrôler cette propriété sur les fichiers texte concernés. Le dépôt PGR fournit scripts/audit_text_hygiene.py comme audit read-only monotâche réutilisable ; il contrôle les CR, le whitespace terminal, l'absence de newline finale et les lignes vides terminales surnuméraires.

git diff --check et git diff --cached --check restent obligatoires lorsqu'ils sont sélectionnés par la gate Git applicable. Ils constituent un filet indépendant et ne remplacent pas l'audit d'hygiène lorsque celui-ci est disponible dans le projet.

Un générateur MUST corriger un défaut mécanique détectable avant livraison plutôt que compter sur la gate opérateur pour le découvrir. Si la gate opérateur détecte malgré tout ce défaut, le résultat réel reste FAIL et la correction suit le workflow .fix.N.

Commit de tranche

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

Avant ce commit :

current delta changes
+ current history

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

Pour une tranche alpha, beta, RC ou autre tranche qui n'établit pas la stable, le message de commit MAY suivre les conventions du projet tant que l'état et la tranche restent identifiables. PGR n'impose pas Conventional Commits, GitFlow ou une topologie universelle de branches.

La clôture stable rel.N[/fix.M] possède une règle plus stricte afin de distinguer une tentative de fermeture de l'identité stable réellement obtenue. En l'absence d'un mapping local explicitement documenté :

history rel.1 FAIL / PARTIAL / BLOCKED
    -> commit X.Y.Z-rel.1

history rel.1.fix.1 FAIL / PARTIAL / BLOCKED
    -> commit X.Y.Z-rel.1.fix.1

premier history rel.N[/fix.M] PASS qui établit réellement la stable
    -> commit X.Y.Z

Le suffixe opérationnel n'est donc conservé dans le message du commit que tant que la clôture n'a pas obtenu le PASS stable. Le commit X.Y.Z MUST contenir le delta de clôture concerné et son history PASS; il MUST précéder le tag canonique vX.Y.Z.

Un projet qui possède une convention de message différente MAY utiliser un mapping équivalent, mais il MUST conserver sans ambiguïté la distinction entre tentative de clôture échouée et commit stable final.

Le repository ne doit jamais mélanger deux tranches non clôturées dans un même commit.

Remise automatique des commandes opérateur

Après production d'un history destiné à être appliqué par l'opérateur, le générateur MUST remettre spontanément les commandes nécessaires pour fermer cette tranche. Il ne doit pas attendre une demande séparée du type « je commit avec quel message ? ».

Lorsque les valeurs Git sont établies par le projet ou par les sorties opérateur de la session, le bloc remis MUST utiliser les valeurs réelles : archive history, message de commit, remote et branche. Le générateur MUST NOT inventer un remote, une branche ou une politique de tag non établis. Une valeur encore inconnue doit être signalée explicitement ou résolue par une commande de découverte sûre avant la commande qui en dépend.

Pour une livraison ZIP et une tranche non stable, le handoff couvre normalement dans cet ordre :

apply history archive
    ↓
git add / staged whitespace check / status
    ↓
commit avec le message attendu
    ↓
push de la branche courante
    ↓
apply du delta suivant ou du fix déjà livré

Lorsqu'un history FAIL, PARTIAL ou BLOCKED conduit à un .fix.N, le bloc de commandes ferme d'abord la tranche constatée sous son identité propre puis autorise seulement l'application du correctif. Lorsqu'un history PASS conduit à la tranche planifiée suivante, le même ordre s'applique.

Pour la première clôture rel.N[/fix.M] qui établit réellement la stable, le bloc MUST utiliser le message de commit stable X.Y.Z, puis fournir séparément les commandes de tag et de vérification applicables. Le tag MUST NOT être créé avant le commit stable et son push lorsque le projet exige que la branche canonique distante porte d'abord ce commit.

Le handoff de publication MUST également indiquer exactement ce que l'opérateur doit remettre au générateur pour produire la preuve post-tag applicable. Pour une archive source générée par la forge à partir du tag, cela inclut normalement :

• le ZIP téléchargé depuis le tag canonique ;
• le SHA du commit stable local observé avant ou pendant le tag ;
• le commit déréférencé localement par le tag ;
• la référence distante du tag ;
• pour un tag annoté, le commit distant déréférencé refs/tags/vX.Y.Z^{} afin de ne pas confondre l'objet tag avec son commit ;
• toute autre preuve explicitement requise par la politique locale de publication.

Le rapport publish.* est produit seulement à partir des artefacts et preuves réellement disponibles après publication. Il MUST NOT être prérempli avec un PASS futur.

../templates/006-OPERATOR_COMMAND_HANDOFF.md fournit le pattern de rendu des blocs de commandes. Il complète le présent contrat sans devenir une seconde source normative.

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 :

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 :

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 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 :

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 :

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 :

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.1 ou publish.001 MAY être utilisé pour distinguer une clôture ou une vérification de publication sans devenir une nouvelle version SemVer produit. La famille rel.N utilise la représentation sans zéro de padding définie par la gouvernance ; les anciennes formes rel.001* déjà publiées restent historiques et immuables.

rel.1 est la première tranche de clôture stable pré-tag d'une nouvelle release utilisant cette convention. Si elle échoue, rel.1.fix.N corrige uniquement cette fermeture. La première de ces tranches qui obtient réellement PASS est incluse dans le commit stable X.Y.Z, puis seulement le tag vX.Y.Z est créé.

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. La présente règle ne renomme pas publish.001; son identité reste indépendante de la correction rel.001 -> rel.1.

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 :

history/
handoffs/
manifests/
prompts/
deltas/

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