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 :

0.0.5-alpha.2

Version après application :

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 :

VERSION
docs/000-README.md
docs/rules/300-DOCUMENTATION.md
docs/skeletons/001-PROJECT_GOVERNANCE_FOUNDATION.md

ADD :

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 :

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 :

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.

7.1 KiB Raw Permalink Blame History