174 lines
7.1 KiB
Markdown
174 lines
7.1 KiB
Markdown
<!-- file: deltas/0.0.5/alpha.3.md -->
|
|
<!-- version: 1 -->
|
|
|
|
# Delta 0.0.5-alpha.3 — pattern facultatif de contrats de fichiers ou familles
|
|
|
|
## Baseline et version
|
|
|
|
Baseline attendue : commit opérateur de `0.0.5-alpha.2`, réalisé après application de `history/0.0.5/alpha.2.md` avec statut `PASS`.
|
|
|
|
Le hash de ce commit n'est pas anticipé. Le history `alpha.2` 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.3` MUST NOT être appliqué avant le commit de `alpha.2`.
|
|
|
|
Version avant application :
|
|
|
|
```text
|
|
0.0.5-alpha.2
|
|
```
|
|
|
|
Version après application :
|
|
|
|
```text
|
|
0.0.5-alpha.3
|
|
```
|
|
|
|
## Objet
|
|
|
|
Exécuter la troisième tranche du plan `0.0.5` en généralisant un besoin observé indépendamment dans les deux corpus externes : expliciter, lorsque la complexité le justifie, la responsabilité et la règle de modification de certaines familles de fichiers locales.
|
|
|
|
La tranche normalise le pattern et non les catalogues KSP/Games. Elle n'impose ni le nom `FILE_CONTRACTS.md`, ni une table exhaustive, ni la reprise de leurs chemins, règles métier ou conventions de release.
|
|
|
|
## Scope
|
|
|
|
REPLACE :
|
|
|
|
```text
|
|
VERSION
|
|
docs/000-README.md
|
|
docs/rules/300-DOCUMENTATION.md
|
|
docs/skeletons/001-PROJECT_GOVERNANCE_FOUNDATION.md
|
|
```
|
|
|
|
ADD :
|
|
|
|
```text
|
|
docs/templates/004-FILE_FAMILY_CONTRACTS.md
|
|
deltas/0.0.5/alpha.3.md
|
|
```
|
|
|
|
DELETE : aucun.
|
|
|
|
L'archive delta contient uniquement ces six fichiers complets avec leurs chemins relatifs. Elle ne contient pas `history/0.0.5/alpha.2.md`, livré séparément pour clôturer la tranche précédente, ni `history/0.0.5/alpha.3.md`, qui sera produit après la gate opérateur.
|
|
|
|
## Contrat matérialisé
|
|
|
|
`docs/rules/300-DOCUMENTATION.md` possède désormais le pattern générique :
|
|
|
|
- un registre local est facultatif et ne doit exister que pour lever une ambiguïté réelle ;
|
|
- il décrit au minimum fichier/famille, responsabilité durable et règle de modification ;
|
|
- source de vérité, statut généré/versionné, owner ou validation restent des champs optionnels ;
|
|
- le registre ne doit ni recopier les owners existants ni devenir un miroir exhaustif de l'arborescence ;
|
|
- son nom, son emplacement et sa forme appartiennent au projet destinataire ;
|
|
- l'ajout d'un fichier déjà couvert par une famille ne force pas une entrée supplémentaire.
|
|
|
|
`docs/templates/004-FILE_FAMILY_CONTRACTS.md` fournit une forme d'adaptation courte avec critères d'usage, modèle minimal, règles d'instanciation et exemple abstrait.
|
|
|
|
La fondation `001-PROJECT_GOVERNANCE_FOUNDATION.md` référence ce pattern uniquement comme possibilité pour un projet dont plusieurs familles durables deviennent ambiguës. Elle confirme explicitement qu'un projet simple n'a rien à matérialiser.
|
|
|
|
## Validation opérateur
|
|
|
|
Après avoir appliqué `history/0.0.5/alpha.2.md`, committé `0.0.5-alpha.2`, puis appliqué le présent delta, depuis la racine du dépôt :
|
|
|
|
```bash
|
|
test "$(cat VERSION)" = '0.0.5-alpha.3'
|
|
test -f history/0.0.5/alpha.2.md
|
|
test -f deltas/0.0.5/alpha.3.md
|
|
test -f docs/templates/004-FILE_FAMILY_CONTRACTS.md
|
|
test ! -e history/0.0.5/alpha.3.md
|
|
|
|
grep -Fx '<!-- version: 11 -->' docs/000-README.md
|
|
grep -Fx '<!-- version: 3 -->' docs/rules/300-DOCUMENTATION.md
|
|
grep -Fx '<!-- version: 2 -->' docs/skeletons/001-PROJECT_GOVERNANCE_FOUNDATION.md
|
|
grep -Fx '<!-- version: 1 -->' docs/templates/004-FILE_FAMILY_CONTRACTS.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.2.md').read_text(encoding='utf-8')
|
|
assert re.search(r'## Statut\s+PASS\s', history)
|
|
|
|
doc = Path('docs/rules/300-DOCUMENTATION.md').read_text(encoding='utf-8')
|
|
template = Path('docs/templates/004-FILE_FAMILY_CONTRACTS.md').read_text(encoding='utf-8')
|
|
foundation = Path('docs/skeletons/001-PROJECT_GOVERNANCE_FOUNDATION.md').read_text(encoding='utf-8')
|
|
index = Path('docs/000-README.md').read_text(encoding='utf-8')
|
|
|
|
required_doc = (
|
|
'## Registre local de contrats de fichiers ou familles',
|
|
'outil de désambiguïsation, pas un inventaire exhaustif',
|
|
'le fichier, motif de chemin ou famille concernée',
|
|
'sa responsabilité durable',
|
|
'la règle ou le déclencheur pertinent de modification',
|
|
'PGR n\'impose ni `FILE_CONTRACTS.md`',
|
|
'l\'ajout d\'un fichier conforme à une famille déjà décrite ne force pas une nouvelle entrée',
|
|
)
|
|
for phrase in required_doc:
|
|
assert phrase in doc, phrase
|
|
|
|
required_template = (
|
|
'# Pattern — contrats locaux de fichiers ou familles',
|
|
'Quand l\'utiliser',
|
|
'Forme minimale',
|
|
'Règles d\'adaptation',
|
|
'Critère de sortie',
|
|
'`docs/rules/FILE_CONTRACTS.md` est un nom possible, pas une convention PGR obligatoire',
|
|
)
|
|
for phrase in required_template:
|
|
assert phrase in template, phrase
|
|
|
|
assert '004-FILE_FAMILY_CONTRACTS.md' in foundation
|
|
assert 'Ce registre reste facultatif' in foundation
|
|
assert '004-FILE_FAMILY_CONTRACTS.md' in index
|
|
|
|
for text in (doc, template, foundation):
|
|
for forbidden in ('tokio-postgres', 'WebTransport', 'Uroburas'):
|
|
assert forbidden not in text, forbidden
|
|
|
|
print('0.0.5 alpha.3 file-family contract audit: clean (optional registry, short reusable pattern, no project-specific contract imported)')
|
|
PY
|
|
|
|
git diff --check
|
|
git add VERSION docs/000-README.md docs/rules/300-DOCUMENTATION.md \
|
|
docs/skeletons/001-PROJECT_GOVERNANCE_FOUNDATION.md \
|
|
docs/templates/004-FILE_FAMILY_CONTRACTS.md deltas/0.0.5/alpha.3.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.3.md
|
|
M docs/000-README.md
|
|
M docs/rules/300-DOCUMENTATION.md
|
|
M docs/skeletons/001-PROJECT_GOVERNANCE_FOUNDATION.md
|
|
A docs/templates/004-FILE_FAMILY_CONTRACTS.md
|
|
```
|
|
|
|
La revue opérateur doit en outre confirmer que :
|
|
|
|
- le pattern réduit une ambiguïté réelle au lieu d'imposer une nouvelle cérémonie ;
|
|
- `FILE_CONTRACTS.md` reste un exemple de nom, jamais une obligation ;
|
|
- le registre ne devient pas un catalogue exhaustif de chaque fichier du dépôt ;
|
|
- une règle détaillée déjà possédée ailleurs est référencée plutôt que dupliquée ;
|
|
- la fondation n'impose aucun nouveau document aux petits projets ou aux projets dont les responsabilités sont déjà claires.
|
|
|
|
## Transition
|
|
|
|
### PASS
|
|
|
|
Rédiger et livrer séparément `history/0.0.5/alpha.3.md` avec les résultats réellement observés ; l'appliquer et committer la tranche. Préparer seulement ensuite `0.0.5-alpha.4` pour l'audit Rust facultatif de façade/export completeness.
|
|
|
|
### FAIL
|
|
|
|
Consigner le résultat réel dans le history de `alpha.3`, puis corriger le pattern dans `0.0.5-alpha.3.fix.1` ou produire un REPLAN motivé. Aucun contenu de l'audit Rust `alpha.4` ne doit être absorbé silencieusement dans un fix.
|