From d7282dc33b059221f1fcf32640700e681e3b6afd Mon Sep 17 00:00:00 2001 From: SinuS Von SifriduS Date: Thu, 24 Sep 2026 21:21:44 +0200 Subject: [PATCH] 0.0.5-alpha.2 --- VERSION | 2 +- deltas/0.0.5/alpha.2.md | 179 +++++++++++++++++++++++++++++++++++++ docs/rules/000-README.md | 4 +- docs/rules/210-WORKFLOW.md | 50 +++++++++-- history/0.0.5/alpha.2.md | 100 +++++++++++++++++++++ 5 files changed, 323 insertions(+), 12 deletions(-) create mode 100644 deltas/0.0.5/alpha.2.md create mode 100644 history/0.0.5/alpha.2.md diff --git a/VERSION b/VERSION index 2995b01..e86f37c 100644 --- a/VERSION +++ b/VERSION @@ -1 +1 @@ -0.0.5-alpha.1 +0.0.5-alpha.2 diff --git a/deltas/0.0.5/alpha.2.md b/deltas/0.0.5/alpha.2.md new file mode 100644 index 0000000..1566f35 --- /dev/null +++ b/deltas/0.0.5/alpha.2.md @@ -0,0 +1,179 @@ + + + +# 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 '' docs/rules/000-README.md +grep -Fx '' 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 '' 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. diff --git a/docs/rules/000-README.md b/docs/rules/000-README.md index dd3bb53..d33cb24 100644 --- a/docs/rules/000-README.md +++ b/docs/rules/000-README.md @@ -1,5 +1,5 @@ - + # 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. diff --git a/docs/rules/210-WORKFLOW.md b/docs/rules/210-WORKFLOW.md index 2030f45..f43844b 100644 --- a/docs/rules/210-WORKFLOW.md +++ b/docs/rules/210-WORKFLOW.md @@ -1,5 +1,5 @@ - + # 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 diff --git a/history/0.0.5/alpha.2.md b/history/0.0.5/alpha.2.md new file mode 100644 index 0000000..2e8949e --- /dev/null +++ b/history/0.0.5/alpha.2.md @@ -0,0 +1,100 @@ + + + +# 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.