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éé pendant le cadrage lorsque plusieurs tranches ou décisions doivent être coordonnées ;
• MAY évoluer lorsque le plan change réellement ;
• 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.

Un changement substantiel du plan MAY être porté par une tranche REPLAN conformément aux règles de gouvernance.

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

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.

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.

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 :

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

Le prompt SHOULD être finalisé à la clôture stable de la version précédente lorsqu'il prépare la version suivante et que sa mission est suffisamment connue.

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.

Lors d'une nouvelle session ouverte depuis une stable publiée, une courte consigne manuelle MAY identifier 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.

Handoff

Un handoff est un snapshot de continuité utilisé lorsqu'un travail doit être repris sans changer artificiellement de version ou de tranche.

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

Le handoff SHOULD enregistrer uniquement les informations nécessaires à une reprise fiable : état de version/tranche, résultat déjà acquis, travail restant, risques ou décisions ouvertes et commandes pertinentes.

Une fois livré comme snapshot de reprise, il 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.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.

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é.