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

0.0.5-alpha.2

Browse Source
This commit is contained in:
SinuS von SifriduS
2026-09-24 21:21:44 +02:00
parent 3ca2518c5c
commit d7282dc33b
5 changed files with 323 additions and 12 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
VERSION
View File

@@ -1 +1 @@
0.0.5-alpha.1
0.0.5-alpha.2

179
deltas/0.0.5/alpha.2.md Normal file
View File

@@ -0,0 +1,179 @@
<!-- file: deltas/0.0.5/alpha.2.md -->
<!-- version: 1 -->
# Delta 0.0.5-alpha.2 — contrat générique des prompts de démarrage
## Baseline et version
Baseline attendue : commit opérateur de `0.0.5-alpha.1`, réalisé après application de `history/0.0.5/alpha.1.md` avec statut `PASS`.
Le hash de ce commit n'est volontairement pas anticipé : le history `alpha.1` et le présent delta peuvent être livrés dans le même échange, mais restent deux archives séparées et le delta `alpha.2` MUST NOT être appliqué avant le commit de `alpha.1`.
Version avant application :
```text
0.0.5-alpha.1
```
Version après application :
```text
0.0.5-alpha.2
```
## Objet
Exécuter la deuxième tranche du plan `0.0.5` en renforçant l'owner `docs/rules/210-WORKFLOW.md` pour les prompts de démarrage versionnés.
Les prompts PGR récents et les baselines KSP/Games montrent qu'un bon prompt de reprise ne se limite pas à nommer une baseline et une mission : il doit permettre de reconstruire explicitement l'état utile, les sources à lire, les décisions déjà acquises, les limites de scope, la première gate et la trajectoire de validation sans réimporter toute la documentation du projet.
La tranche généralise ce contrat sémantique sans copier la structure exhaustive des prompts KSP/Games. Elle ne crée ni nouveau template manuel ni nouveau type d'artefact.
## Scope
REPLACE :
```text
VERSION
docs/rules/000-README.md
docs/rules/210-WORKFLOW.md
```
ADD :
```text
deltas/0.0.5/alpha.2.md
```
DELETE : aucun.
L'archive delta contient uniquement ces quatre fichiers complets avec leurs chemins relatifs. Elle ne contient pas `history/0.0.5/alpha.1.md`, livré séparément pour clôturer la tranche précédente, ni `history/0.0.5/alpha.2.md`, qui sera produit après la gate opérateur.
Le plan `docs/plans/005-V0_0_5_RECONCILIATION_PLAN.md`, l'étude `docs/studies/001-KSP_GAMES_RECONCILIATION.md` et `docs/templates/003-NEW_SESSION_PROMPT.md` restent inchangés : cette tranche exécute leur trajectoire et préserve explicitement la séparation entre prompt versionné et message manuel de nouvelle session.
## Contrat matérialisé
`docs/rules/210-WORKFLOW.md` porte désormais un contrat réutilisable des prompts de démarrage versionnés couvrant :
- baseline autoritaire, cible et première tranche ;
- ordre de lecture nécessaire à une reprise fiable ;
- état déjà acquis et traçabilité des décisions conservées ;
- mission et résultat attendu ;
- scope et hors-scope ;
- décisions gelées et questions ouvertes ;
- première gate et travaux éventuellement interdits avant sa fermeture ;
- trajectoire prévisionnelle explicitement non contraignante ;
- validation et responsabilité de la preuve ;
- comportement fail-closed lorsqu'une source externe requise manque.
Le contrat reste sémantique : il n'impose pas neuf titres littéraux ni une longueur uniforme. Les projets importants peuvent détailler leur ordre de lecture et leurs questions de cadrage ; les projets simples conservent une forme courte dès lors que les mêmes responsabilités sont couvertes.
Les règles locales de langage, plateforme, framework, architecture ou métier ne deviennent pas des règles PGR parce qu'elles apparaissent dans un prompt. Le prompt doit renvoyer vers les owners existants au lieu de les dupliquer.
`docs/templates/003-NEW_SESSION_PROMPT.md` conserve son rôle distinct : produire la courte phrase manuelle de reprise après une stable publiée. Il ne remplace pas le prompt versionné et n'est pas dupliqué par cette tranche.
## Validation opérateur
Après avoir appliqué `history/0.0.5/alpha.1.md`, committé `0.0.5-alpha.1`, puis appliqué le présent delta, depuis la racine du dépôt :
```bash
test "$(cat VERSION)" = '0.0.5-alpha.2'
test -f history/0.0.5/alpha.1.md
test -f deltas/0.0.5/alpha.2.md
test ! -e history/0.0.5/alpha.2.md
grep -Fx '<!-- version: 12 -->' docs/rules/000-README.md
grep -Fx '<!-- version: 4 -->' docs/rules/210-WORKFLOW.md
grep -F 'prompts versionnés' docs/rules/000-README.md
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
python3 -B - <<'PY'
from pathlib import Path
import re
history = Path('history/0.0.5/alpha.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')
required = (
'## Prompt de démarrage versionné',
'### Contrat minimal',
'baseline autoritaire et cible',
'ordre de lecture',
'état déjà acquis',
'mission et résultat attendu',
'scope et hors-scope',
'décisions gelées et questions ouvertes',
'première gate',
'trajectoire prévisionnelle',
'validation et responsabilité',
'### Sources externes et données manquantes',
'### Décisions acquises et détails locaux',
'### Création et clôture',
'003-NEW_SESSION_PROMPT.md',
)
for phrase in required:
assert phrase in workflow, phrase
for forbidden in (
'prompts/036-V0_3_17_START_PROMPT.md',
'prompts/007-V0_3_6_START_PROMPT.md',
'tokio-postgres',
'WebTransport',
'Uroburas',
):
assert forbidden not in workflow, forbidden
assert 'MUST NOT les recopier exhaustivement' in workflow
assert 'Le prompt n\'a pas à reproduire littéralement cette numérotation.' in workflow
assert 'MUST NOT autoriser à reconstituer silencieusement' in workflow
assert 'Les contraintes locales de langage, plateforme, framework, architecture ou métier restent chez leurs owners respectifs.' in workflow
manual = Path('docs/templates/003-NEW_SESSION_PROMPT.md').read_text(encoding='utf-8')
assert '<!-- version: 1 -->' in manual
assert 'une seule phrase' in manual
print('0.0.5 alpha.2 prompt contract audit: clean (versioned prompt strengthened, manual restart template unchanged)')
PY
git diff --check
git add VERSION docs/rules/000-README.md docs/rules/210-WORKFLOW.md \
deltas/0.0.5/alpha.2.md
git diff --cached --check
git status --short
```
Le scope indexé attendu avant ajout du history est :
```text
M VERSION
A deltas/0.0.5/alpha.2.md
M docs/rules/000-README.md
M docs/rules/210-WORKFLOW.md
```
La revue opérateur doit en outre confirmer que :
- le nouveau contrat décrit des responsabilités de reprise et non une liste obligatoire de titres ;
- la baseline et les sources manquantes restent fail-closed : aucun état externe n'est reconstruit depuis un souvenir ou un workspace non fourni ;
- les décisions acquises sont résumées seulement lorsqu'elles empêchent une régression utile et restent traçables vers leur owner ;
- les contraintes KSP/Games spécifiques ne sont pas aspirées dans la règle générale ;
- le template `003-NEW_SESSION_PROMPT.md` reste la forme courte post-publication et n'est ni remplacé ni dupliqué.
## Transition
### PASS
Rédiger et livrer séparément `history/0.0.5/alpha.2.md` avec les résultats réellement observés ; l'appliquer et committer la tranche. Préparer seulement ensuite `0.0.5-alpha.3` pour le pattern facultatif de contrats de fichiers/familles.
### FAIL
Consigner le résultat réel dans le history de `alpha.2`, puis corriger le contrat dans `0.0.5-alpha.2.fix.1` ou produire un REPLAN motivé. Aucun contenu de `alpha.3` ne doit être absorbé silencieusement dans un fix.

4
docs/rules/000-README.md
View File

@@ -1,5 +1,5 @@
<!-- file: docs/rules/000-README.md -->
<!-- version: 11 -->
<!-- version: 12 -->
# Index des règles PGR
@@ -12,7 +12,7 @@ Les règles générales actuellement nécessaires restent dans `RULES.md`. La fa
## Familles actives
- [`200-GOVERNANCE.md`](200-GOVERNANCE.md) — versioning, lifecycle des releases, fixes, cadrage, replan et abandon/supersession.
- [`210-WORKFLOW.md`](210-WORKFLOW.md) — contrats des artefacts workflow, ordre delta/history/commit, reprise et baselines de release.
- [`210-WORKFLOW.md`](210-WORKFLOW.md) — contrats des artefacts workflow, ordre delta/history/commit, prompts versionnés, reprise et baselines de release.
- [`220-SKELETONS.md`](220-SKELETONS.md) — contrat commun des skeleton specifications, sélection des profils/templates, décisions, overrides et validation.
- [`300-DOCUMENTATION.md`](300-DOCUMENTATION.md) — rôles des documents, taxonomie, révisions internes, documents vivants et snapshots historiques.
- [`400-VALIDATION.md`](400-VALIDATION.md) — matrice de validation, preuves proportionnelles, tests/audits/diagnostics, doubles de test et autorité du gate opérateur.

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

@@ -1,5 +1,5 @@
<!-- file: docs/rules/210-WORKFLOW.md -->
<!-- version: 3 -->
<!-- version: 4 -->
# Workflow artifact rules
@@ -173,9 +173,9 @@ S'il existe :
Un manifest ne doit pas exister vide uniquement pour satisfaire une structure théorique.
## Prompt de démarrage
## Prompt de démarrage versionné
Un prompt de démarrage transmet la mission et le contexte nécessaires à une nouvelle version ou à une reprise explicitement prévue.
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 :
@@ -185,15 +185,47 @@ prompts/NNN-VX_Y_Z_START_PROMPT.md
`NNN` est monotone à l'échelle du dépôt.
Le prompt :
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.
- 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.
### Contrat minimal
Une interruption au milieu d'une version MUST NOT produire artificiellement le prompt de la version suivante.
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 :
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`](../templates/003-NEW_SESSION_PROMPT.md) décrit une forme réutilisable ; elle ne remplace ni le prompt versionné ni la preuve de publication.
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`](../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

100
history/0.0.5/alpha.2.md Normal file
View File

@@ -0,0 +1,100 @@
<!-- file: history/0.0.5/alpha.2.md -->
<!-- version: 1 -->
# History 0.0.5-alpha.2 — contrat générique des prompts de démarrage
## Statut
PASS
La gate de `0.0.5-alpha.2` exécutée par l'opérateur le `2026-09-24` valide le renforcement du contrat générique des prompts de démarrage versionnés. Les tests, audits Markdown, contrôle structurel ciblé et contrôles Git demandés sont propres ; le scope indexé correspond exactement au delta.
## Baseline et version
La tranche part du commit opérateur de `0.0.5-alpha.1` créé après ajout de son history `PASS`. La sortie Git fournie identifie ce commit sous la forme abrégée :
```text
3ca2518 0.0.5-alpha.1
```
Le push vers `origin/master` a réussi avant l'application de `alpha.2`.
La version contrôlée après application du delta est :
```text
0.0.5-alpha.2
```
`history/0.0.5/alpha.1.md` et `deltas/0.0.5/alpha.2.md` sont présents. `history/0.0.5/alpha.2.md` était absent pendant la gate, conformément au workflow.
## Validation opérateur observée
L'opérateur a fourni les sorties du `2026-09-24` depuis `~/Projects/pgr`, à `20:44:04`–`20:44:48`.
Les contrôles de présence et de version ont réussi sans diagnostic :
```text
VERSION 0.0.5-alpha.2
history/0.0.5/alpha.1.md présent
deltas/0.0.5/alpha.2.md présent
history/0.0.5/alpha.2.md absent pendant la gate
docs/rules/000-README.md version 12
docs/rules/210-WORKFLOW.md version 4
```
L'index des règles contient bien la mention des `prompts versionnés` pour `210-WORKFLOW.md`.
La suite Python globale a exécuté `15` tests, tous réussis :
```text
Ran 15 tests in 0.239s
OK
```
Les trois audits documentaires affichent :
```text
Markdown header audit: clean (129 file(s))
Markdown table audit: clean (4 table(s), 129 file(s))
Markdown link audit: clean (123 local link(s), 129 file(s))
```
Le contrôle structurel spécifique affiche :
```text
0.0.5 alpha.2 prompt contract audit: clean (versioned prompt strengthened, manual restart template unchanged)
```
Il confirme notamment :
- le statut `PASS` du history `alpha.1` ;
- la présence, dans `210-WORKFLOW.md`, du contrat minimal couvrant baseline autoritaire et cible, ordre de lecture, état acquis, mission/résultat, scope/hors-scope, décisions gelées/ouvertes, première gate, trajectoire prévisionnelle et responsabilité de validation ;
- le comportement fail-closed lorsqu'une source externe requise manque ;
- l'absence de détails locaux KSP/Games tels que `tokio-postgres`, `WebTransport` ou `Uroburas` dans la règle générale ;
- le maintien de `docs/templates/003-NEW_SESSION_PROMPT.md` en version `1` et de son rôle distinct de message manuel court.
`git diff --check` et `git diff --cached --check` n'ont produit aucun diagnostic. Après ajout des fichiers du delta, le statut indexé transmis est exactement :
```text
M VERSION
A deltas/0.0.5/alpha.2.md
M docs/rules/000-README.md
M docs/rules/210-WORKFLOW.md
```
La transcription du terminal intercale quelques fragments du heredoc de contrôle avec la sortie de `unittest`. Les quinze tests individuels, le résumé `OK`, les trois audits Markdown, le contrôle structurel final et le scope Git restent identifiables et ne signalent aucun échec.
## Résultat
Le contrat des prompts versionnés est renforcé sans imposer une liste rigide de titres, sans dupliquer le template manuel de reprise et sans aspirer les règles propres aux deux corpus externes.
La baseline et les sources externes manquantes restent fail-closed. Les décisions acquises peuvent être résumées pour empêcher une régression utile, mais restent reliées à leurs owners au lieu d'être recopiées exhaustivement dans le prompt.
Aucun fix ni REPLAN n'est requis.
## Transition
Appliquer le présent history puis committer `0.0.5-alpha.2` avant d'appliquer le delta `0.0.5-alpha.3`.
La tranche suivante est `0.0.5-alpha.3` et doit rester limitée au pattern documentaire facultatif de contrats de fichiers ou familles : owner `docs/rules/300-DOCUMENTATION.md`, guide court réutilisable et intégration minimale à la fondation `001` uniquement lorsque la complexité du projet justifie ce registre.