Sasedev/pgr
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

0.1.0-alpha.3

Browse Source
This commit is contained in:
SinuS von SifriduS
2026-09-26 19:06:59 +02:00
parent 3230356cd6
commit f37481627a
7 changed files with 472 additions and 11 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
VERSION
View File

@@ -1 +1 @@
0.1.0-alpha.2.fix.1
0.1.0-alpha.3

185
deltas/0.1.0/alpha.3.md Normal file
View File

@@ -0,0 +1,185 @@
<!-- file: deltas/0.1.0/alpha.3.md -->
<!-- version: 1 -->
# Delta 0.1.0-alpha.3 — handoff automatique des commandes opérateur
## Baseline et version
Baseline attendue : commit opérateur de `0.1.0-alpha.2.fix.1`, réalisé après application de `history/0.1.0/alpha.2.fix.1.md` avec statut `PASS`.
Le hash de ce commit n'est pas anticipé.
Version avant application :
```text
0.1.0-alpha.2.fix.1
```
Version après application :
```text
0.1.0-alpha.3
```
## Objet
Rendre normative la remise automatique des commandes opérateur après chaque history et pendant la publication stable.
La tranche doit supprimer le besoin récurrent de demander séparément :
```text
quel message de commit utiliser ?
quand pousser ?
quand appliquer le prochain delta ?
quelles commandes exécuter pour le tag ?
quelles preuves fournir pour produire publish.* ?
```
Le workflow reste l'owner normatif. Un nouveau pattern documentaire fournit uniquement une forme de rendu réutilisable.
## Scope
REPLACE :
```text
VERSION
docs/000-README.md
docs/plans/006-V0_1_0_REUSABLE_BASELINE_PLAN.md
docs/rules/210-WORKFLOW.md
```
ADD :
```text
docs/templates/006-OPERATOR_COMMAND_HANDOFF.md
deltas/0.1.0/alpha.3.md
```
DELETE : aucun.
## Changements normatifs
`210-WORKFLOW.md` impose désormais qu'après production d'un history destiné à l'opérateur, le générateur fournisse spontanément le bloc de fermeture correspondant. Le rendu doit utiliser les valeurs Git réelles lorsqu'elles sont établies et ne doit jamais inventer branche, remote ou politique de tag.
Le contrat distingue explicitement :
- fermeture ordinaire `history -> commit/push -> delta suivant` ;
- fermeture `FAIL/PARTIAL/BLOCKED -> commit de la tranche -> fix` ;
- première clôture `rel.N[/fix.M] PASS -> commit X.Y.Z -> tag` ;
- vérification d'un tag annoté avec distinction objet tag / commit déréférencé ;
- artefacts et preuves que l'opérateur doit fournir pour produire `publish.*` ;
- message manuel de reprise après `publish.* PASS` déjà possédé par `003-NEW_SESSION_PROMPT.md`.
## Nouveau pattern documentaire
`docs/templates/006-OPERATOR_COMMAND_HANDOFF.md` fournit les blocs adaptables pour :
```text
history ZIP
commit / push
fix ou delta suivant
tag stable
preuves post-tag
transition après publish.*
```
Il ne fixe pas `origin`, `master` ou une forge particulière comme valeurs universelles. Une commande concrète livrée à l'opérateur doit employer les valeurs déjà établies pour le projet.
## Validation opérateur
Exécuter depuis la racine du workspace après application du delta :
```bash
test "$(cat VERSION)" = '0.1.0-alpha.3'
test -f history/0.1.0/alpha.2.fix.1.md
test -f deltas/0.1.0/alpha.3.md
test -f docs/templates/006-OPERATOR_COMMAND_HANDOFF.md
test ! -e history/0.1.0/alpha.3.md
grep -Fx '<!-- version: 7 -->' docs/rules/210-WORKFLOW.md
grep -Fx '<!-- version: 19 -->' docs/000-README.md
grep -Fx '<!-- version: 4 -->' docs/plans/006-V0_1_0_REUSABLE_BASELINE_PLAN.md
python3 -B - <<'PYGATE'
from pathlib import Path
import re
history = Path('history/0.1.0/alpha.2.fix.1.md').read_text(encoding='utf-8')
assert re.search(r'## Statut\s+PASS\s', history)
workflow = Path('docs/rules/210-WORKFLOW.md').read_text(encoding='utf-8')
template = Path('docs/templates/006-OPERATOR_COMMAND_HANDOFF.md').read_text(encoding='utf-8')
plan = Path('docs/plans/006-V0_1_0_REUSABLE_BASELINE_PLAN.md').read_text(encoding='utf-8')
index = Path('docs/000-README.md').read_text(encoding='utf-8')
for phrase in (
'## Remise automatique des commandes opérateur',
"le générateur MUST remettre spontanément les commandes nécessaires pour fermer cette tranche",
'Le générateur MUST NOT inventer un remote, une branche ou une politique de tag non établis.',
'première clôture `rel.N[/fix.M]` qui établit réellement la stable',
'refs/tags/vX.Y.Z^{}',
'Le rapport `publish.*` est produit seulement à partir des artefacts et preuves réellement disponibles après publication.',
'../templates/006-OPERATOR_COMMAND_HANDOFF.md',
):
assert phrase in workflow, phrase
for phrase in (
'## Fermeture d'une tranche non stable',
'git diff --cached --check',
'git push <remote> <branche>',
'## Tranche échouée suivie d'un fix',
'## Première clôture qui établit réellement la stable',
'git tag -a vX.Y.Z -m "vX.Y.Z"',
"git ls-remote <remote> 'refs/tags/vX.Y.Z^{}'",
'## Remise nécessaire pour `publish.*`',
'## Après `publish.* PASS`',
):
assert phrase in template, phrase
assert '006-OPERATOR_COMMAND_HANDOFF.md' in index
assert 'Statut opérateur : **PASS**.' in plan
assert '### alpha.3 — handoff automatique des commandes opérateur' in plan
print('0.1.0 alpha.3 operator handoff audit: clean (history-to-commit, stable tag and publish evidence rendered explicitly)')
PYGATE
python3 -B -m unittest discover -s tests -v
python3 -B scripts/audit_markdown_headers.py \
README.md RULES.md ROADMAP.md CHANGELOG.md docs deltas history prompts
python3 -B scripts/audit_markdown_tables.py \
README.md RULES.md ROADMAP.md CHANGELOG.md docs deltas history prompts
python3 -B scripts/audit_markdown_links.py \
README.md RULES.md ROADMAP.md CHANGELOG.md docs deltas history prompts
git diff --check
git add VERSION docs/000-README.md \
docs/plans/006-V0_1_0_REUSABLE_BASELINE_PLAN.md \
docs/rules/210-WORKFLOW.md \
docs/templates/006-OPERATOR_COMMAND_HANDOFF.md \
deltas/0.1.0/alpha.3.md
git diff --cached --check
git status --short
```
## Résultat attendu
La gate est `PASS` si :
- le history `alpha.2.fix.1` est présent et `PASS` ;
- le workflow impose la remise spontanée des commandes et interdit d'inventer les paramètres Git ;
- le pattern couvre tranche ordinaire, échec + fix, stable/tag et preuves `publish.*` ;
- la vérification d'un tag annoté distingue objet tag et commit déréférencé ;
- les `48` tests existants restent propres ;
- les trois audits Markdown restent propres ;
- le scope Git correspond exactement aux six fichiers de `alpha.3`.
## Transition
Si `PASS` :
1. produire `history/0.1.0/alpha.3.md` ;
2. remettre automatiquement le bloc opérateur conforme au nouveau pattern pour committer/pousser `0.1.0-alpha.3` ;
3. préparer `0.1.0-alpha.4`, consacré à l'adoption proportionnée de PGR par un projet existant.
Si `FAIL` : conserver le history réel et corriger uniquement la cause dans `alpha.3.fix.N`, sauf preuve imposant un REPLAN.

3
docs/000-README.md
View File

@@ -1,5 +1,5 @@
<!-- file: docs/000-README.md -->
<!-- version: 18 -->
<!-- version: 19 -->
# Documentation PGR
@@ -23,6 +23,7 @@ Les templates techniques copiables sous `templates/` restent séparés des instr
## Points d'entrée de 0.1.0
- [`plans/006-V0_1_0_REUSABLE_BASELINE_PLAN.md`](plans/006-V0_1_0_REUSABLE_BASELINE_PLAN.md) — audit de la stable `v0.0.5`, cadrage du workflow de clôture/publication et préparation de la première baseline PGR réellement réutilisable.
- [`templates/006-OPERATOR_COMMAND_HANDOFF.md`](templates/006-OPERATOR_COMMAND_HANDOFF.md) — pattern de remise automatique des commandes entre history, commit/push, delta suivant, tag et vérification post-tag.
## Points d'entrée de 0.0.5

13
docs/plans/006-V0_1_0_REUSABLE_BASELINE_PLAN.md
View File

@@ -1,5 +1,5 @@
<!-- file: docs/plans/006-V0_1_0_REUSABLE_BASELINE_PLAN.md -->
<!-- version: 3 -->
<!-- version: 4 -->
# Plan 0.1.0 — première baseline PGR réutilisable
@@ -181,20 +181,17 @@ Le défaut appartient à la gate opérateur, pas aux owners `200-GOVERNANCE` / `
### alpha.2.fix.1 — correction de la gate `rel.N`
Corriger uniquement la validation de `alpha.2` :
Statut opérateur : **PASS**.
- conserver `200-GOVERNANCE.md` et `210-WORKFLOW.md` inchangés ;
- remplacer les assertions shell fragiles par une vérification Python syntaxiquement sûre ;
- rejouer la suite Python complète, les audits Markdown et la preuve structurelle ;
- conserver le `FAIL` de `alpha.2` avant toute progression.
Le fix a conservé `200-GOVERNANCE.md`, `210-WORKFLOW.md` et le delta historique `alpha.2.md` inchangés. La preuve Python corrigée a reconfirmé la convention `rel.N`, le `FAIL` historique de `alpha.2`, les anciens artefacts `rel.001*` et l'indépendance de `publish.001`.
Après PASS de ce fix, reprendre la trajectoire normale à `alpha.3`.
La validation a exécuté `48/48` tests et les trois audits Markdown sans diagnostic. Aucun nouveau fix ni REPLAN n'est requis.
### alpha.3 — handoff automatique des commandes opérateur
Formaliser le bloc de commandes remis après chaque history, l'ordre commit/push avant application du delta suivant, les commandes supplémentaires de tag pour une stable validée et la liste des preuves à fournir pour produire le rapport post-tag.
Créer ou adapter un template documentaire uniquement si cela évite de dupliquer ces commandes dans chaque delta.
La tranche introduit un pattern documentaire dédié afin de ne pas recopier ces règles dans chaque delta. Le workflow reste owner de la sémantique ; le template possède seulement la forme de rendu et les variantes tranche normale / échec + fix / clôture stable / post-tag.
### alpha.4 — adoption d'un projet existant

39
docs/rules/210-WORKFLOW.md
View File

@@ -1,5 +1,5 @@
<!-- file: docs/rules/210-WORKFLOW.md -->
<!-- version: 6 -->
<!-- version: 7 -->
# Workflow artifact rules
@@ -197,6 +197,43 @@ Un projet qui possède une convention de message différente MAY utiliser un map
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 :
```text
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`](../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.

126
docs/templates/006-OPERATOR_COMMAND_HANDOFF.md vendored Normal file
View File

@@ -0,0 +1,126 @@
<!-- file: docs/templates/006-OPERATOR_COMMAND_HANDOFF.md -->
<!-- version: 1 -->
# Pattern — handoff des commandes opérateur
## Usage
Ce pattern matérialise la sortie opérateur exigée par [`210-WORKFLOW.md`](../rules/210-WORKFLOW.md) après production d'un history et pendant une clôture stable. Son objectif est d'éviter que l'opérateur doive demander séparément quelles commandes exécuter entre le history reçu, son commit, le delta suivant et, pour une stable, le tag puis la vérification post-tag.
Le pattern est un guide de rendu : `210-WORKFLOW.md` reste l'owner normatif.
## Informations à résoudre avant le rendu
Le générateur doit déterminer depuis les preuves disponibles :
```text
project
X.Y.Z
tranche courante
statut du history
archive history réellement livrée
message de commit attendu
remote Git établi
branche Git établie
delta/fix suivant déjà livré ou non
stable obtenue ou non
tag canonique attendu
forge/archive post-tag applicable
preuve publish.* attendue ou non
```
Une valeur non établie ne doit pas être inventée. Si le remote ou la branche manque, le rendu peut d'abord fournir une commande de découverte telle que `git remote -v` ou `git branch --show-current`, puis demander d'utiliser la valeur réellement observée ; il ne doit pas transformer silencieusement un exemple `origin/master` en règle universelle.
## Fermeture d'une tranche non stable
Lorsque le history est livré sous forme de ZIP et que remote/branche sont établis, le bloc remis suit cette forme :
```bash
unzip -o <project>-<X.Y.Z>-<tranche>.history.zip -d .
git add -A
git diff --cached --check
git status --short
git commit -m "<message attendu>"
git push <remote> <branche>
```
Si le delta suivant ou le fix est déjà livré dans la même réponse, son application est affichée **après** le bloc de commit/push :
```bash
unzip -o <archive delta suivante>.delta.zip -d .
```
L'ordre visuel du rendu doit refléter l'ordre autorisé : history → commit/push → delta suivant.
## Tranche échouée suivie d'un fix
Un `FAIL`, `PARTIAL` ou `BLOCKED` est d'abord committé avec l'identité de la tranche observée, puis le fix est appliqué. Exemple générique :
```bash
unzip -o <project>-<X.Y.Z>-alpha.2.history.zip -d .
git add -A
git diff --cached --check
git status --short
git commit -m "X.Y.Z-alpha.2"
git push <remote> <branche>
unzip -o <project>-<X.Y.Z>-alpha.2.fix.1.delta.zip -d .
```
Le history `FAIL` n'est jamais remplacé par le futur `PASS` du fix.
## Première clôture qui établit réellement la stable
Quand `rel.N[/fix.M]` obtient le premier `PASS` stable, le commit porte l'identité produit :
```bash
unzip -o <project>-<X.Y.Z>-<rel.N[/fix.M]>.history.zip -d .
git add -A
git diff --cached --check
git status --short
git commit -m "X.Y.Z"
git push <remote> <branche>
```
Le tag vient ensuite. Si la politique locale utilise un tag annoté, le bloc type est :
```bash
git status --short
git rev-parse HEAD
git tag -a vX.Y.Z -m "vX.Y.Z"
git push <remote> vX.Y.Z
git rev-list -n 1 vX.Y.Z
git ls-remote --exit-code --tags <remote> refs/tags/vX.Y.Z
git ls-remote <remote> 'refs/tags/vX.Y.Z^{}'
```
Pour un tag annoté, `refs/tags/vX.Y.Z` peut identifier l'objet tag et différer du SHA du commit. La référence déréférencée `refs/tags/vX.Y.Z^{}` est celle qui doit être comparée au commit stable.
Si le projet utilise volontairement une autre forme de tag, le bloc est adapté à cette politique au lieu d'imposer `git tag -a`.
## Remise nécessaire pour `publish.*`
Après création/push du tag et génération de l'archive par la forge, le générateur indique explicitement ce qu'il attend. Pour le cas source-archive usuel :
```text
1. télécharger depuis la forge le ZIP correspondant exactement au tag vX.Y.Z ;
2. fournir ce ZIP au générateur ;
3. fournir les sorties Git du commit/tag local et distant exécutées ci-dessus ;
4. fournir toute preuve de publication supplémentaire exigée localement.
```
Le générateur vérifie alors l'archive publiée, calcule son empreinte dans son propre environnement lorsque possible et produit le rapport `publish.*` à partir des observations réelles. Le rapport reste extérieur au tag qu'il vérifie.
## Après `publish.* PASS`
Si une version suivante est déjà décidée et son prompt existe dans la stable, le générateur remet automatiquement la phrase de nouvelle session définie par [`003-NEW_SESSION_PROMPT.md`](003-NEW_SESSION_PROMPT.md), avec les noms réels du ZIP taggé, du rapport post-tag et du prompt versionné.
Si l'horizon reste ouvert, il remet à la place le handoff ou la consigne de revue d'horizon applicable sans inventer de prochaine version.
## Critère de qualité
Le handoff est correct lorsque l'opérateur peut passer du history reçu au commit, au delta suivant ou à la publication sans devoir deviner une commande, un message de commit, un ordre d'application ou un artefact à fournir, tout en conservant explicites les valeurs Git qui ne sont pas encore établies.

115
history/0.1.0/alpha.3.md Normal file
View File

@@ -0,0 +1,115 @@
<!-- file: history/0.1.0/alpha.3.md -->
<!-- version: 1 -->
# History 0.1.0-alpha.3 — handoff automatique des commandes opérateur
## Statut
FAIL
La gate opérateur de `0.1.0-alpha.3` exécutée le `2026-09-26` n'a pas atteint un PASS complet. Le contenu de workflow et le nouveau pattern de handoff ont été appliqués, les `48` tests ont réussi et les trois audits Markdown sont propres, mais le contrôle Python obligatoire livré par le delta contient une chaîne littérale invalide : l'apostrophe de `d'une` ferme prématurément une chaîne entourée de quotes simples.
Le défaut appartient donc à la gate de validation de `alpha.3`. Aucun défaut normatif de `210-WORKFLOW.md` ni de `006-OPERATOR_COMMAND_HANDOFF.md` n'est établi par les preuves opérateur disponibles.
## Baseline opérateur
La tranche précédente `0.1.0-alpha.2.fix.1` a été clôturée avec son history `PASS`, puis committée et poussée avant application de `alpha.3` :
```text
commit 3230356
message 0.1.0-alpha.2.fix.1
push origin/master PASS
```
Après application de `alpha.3`, les contrôles initiaux ont confirmé :
```text
VERSION 0.1.0-alpha.3
history/0.1.0/alpha.2.fix.1.md présent
deltas/0.1.0/alpha.3.md présent
docs/templates/006-OPERATOR_COMMAND_HANDOFF.md présent
history/0.1.0/alpha.3.md absent pendant la gate
docs/rules/210-WORKFLOW.md version 7
docs/000-README.md version 19
docs/plans/006-V0_1_0_REUSABLE_BASELINE_PLAN.md version 4
```
## Défaut exact de la gate
Le delta contenait dans son bloc Python :
```python
for phrase in (
'## Fermeture d'une tranche non stable',
...
):
assert phrase in template, phrase
```
L'apostrophe de `d'une` termine la chaîne Python avant `une tranche non stable`. L'interpréteur a donc arrêté le contrôle spécifique avec :
```text
File "<stdin>", line 24
'## Fermeture d'une tranche non stable',
^
SyntaxError: unterminated string literal (detected at line 24)
```
La gate spécifique n'a donc pas pu produire son message final `clean`. Ce défaut est analogue à celui déjà rencontré sur `alpha.2`, mais il se situe cette fois dans une chaîne Python et non dans le quoting shell d'un `grep`.
## Preuves réussies malgré le défaut
La suite Python globale a exécuté `48` tests et tous ont réussi :
```text
Ran 48 tests in 0.698s
OK
```
Les audits Markdown ont affiché :
```text
Markdown header audit: clean (180 file(s))
Markdown table audit: clean (8 table(s), 180 file(s))
Markdown link audit: clean (167 local link(s), 180 file(s))
```
Le scope Git observé avant ajout du présent history est exactement :
```text
M VERSION
A deltas/0.1.0/alpha.3.md
M docs/000-README.md
M docs/plans/006-V0_1_0_REUSABLE_BASELINE_PLAN.md
M docs/rules/210-WORKFLOW.md
A docs/templates/006-OPERATOR_COMMAND_HANDOFF.md
```
Ce scope correspond aux six fichiers annoncés par `alpha.3`.
## Décision
Aucun REPLAN n'est requis. Le correctif doit rester strictement limité à la gate de `alpha.3` :
```text
0.1.0-alpha.3.fix.1
```
Le fix doit :
- conserver intégralement le delta historique `alpha.3.md` ;
- conserver `docs/rules/210-WORKFLOW.md`, `docs/templates/006-OPERATOR_COMMAND_HANDOFF.md` et `docs/000-README.md` inchangés ;
- remplacer uniquement les littéraux Python fragiles de la validation par une forme syntaxiquement sûre ;
- reconfirmer le history `alpha.3` en `FAIL`, le contenu du workflow et du template, les `48` tests et les trois audits Markdown ;
- vérifier que le scope du fix reste borné à `VERSION`, au plan actif et au nouveau delta de correction.
## Résultat
`0.1.0-alpha.3` est enregistré `FAIL` pour défaut de syntaxe dans sa gate opérateur, sans défaut normatif établi sur le handoff automatique des commandes.
La seule transition autorisée est :
```text
0.1.0-alpha.3.fix.1
```