# 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éé 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 : ```text deltas/X.Y.Z/.md ``` Le nom `` 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/.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 --.delta.zip --.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 : ```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/.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 Un prompt de démarrage transmet la mission et le contexte nécessaires à une nouvelle version ou à une reprise explicitement prévue. Le chemin canonique est : ```text prompts/NNN-VX_Y_Z_START_PROMPT.md ``` `NNN` est monotone à l'échelle du dépôt. Le prompt : - doit transmettre la mission, la baseline et les règles de reprise utiles ; - MUST NOT devenir une copie exhaustive du plan ou de l'historique ; - SHOULD être finalisé à la clôture stable de la version précédente lorsqu'il prépare la version suivante. Une interruption au milieu d'une version MUST NOT produire artificiellement le prompt de la version suivante. ## 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 : ```text handoffs/X.Y.Z/NNN-TYPE-.md ``` Le dossier `X.Y.Z` est celui de la version source du handoff. Les types usuels sont : ```text 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 : ```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. ## 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é.