LifePlay-Revival/Docs/Migration/etat/AG/VAG1/VAG1-SPEC-01.md

VAG1-SPEC-01 : Tools\Vague.ps1, exécution d'une vague du gardien (W7)

Fiche VAG1-SPEC-01 — Niveau N1 — Modèle prévu sonnet | utilisé sonnet (claude-sonnet-5-5) — Agent session « Sonnet · VAG1 » (ex. QG1) — Skills lp-lot, lp-repo, sk-repo, sk-protocol, sk-windows-shell, sk-change-safety. Date : 2026-10-20. SPEC seule : aucun script écrit, aucune écriture git. L'IMPL attend l'accord de Big Boss.

Sources lues : etat\AG\PIPE1\PIPE1-INV-01-SUBSTITUTION.md (A9, A10), PIPE1-SPEC-01.md (V1-V10), lp-repo § 3, 6, 8, sk-repo § 2, 4, 9, 10, tickets réels (REP1-T6, VAGUE-20261019-2-PARTAGES), REPO-JOURNAL.md (formats des lignes), Tools\Verrou.ps1, Tools\PubCheck.ps1.

1. Objet

Un script qui exécute toute la vague : prend le verrou une fois, traite les tickets dans l'ordre V4, s'arrête au premier refus avec la ligne fautive, rend le verrou. L'agent lp-gardien n'intervient plus que sur un refus (V9) ou pour le pin du doc 21, qui reste un geste du gardien : le script s'arrête avant un ticket de type PIN.

2. Paramètres

Paramètre	Rôle
-Tickets <id[]> ou -File <chemin>	liste ordonnée d'identifiants, ou etat\REPO\FILE.md (colonne Ticket, dans l'ordre des rangs). Exactement l'un des deux, sinon code 2
-Essai (défaut)	à blanc : tous les contrôles qui n'écrivent rien ; aucun verrou pris (seulement lu), aucun fichier, index ni commit écrit
-Executer	exécute (verrou, statuts, lignes de journal, commits). Exclusif avec -Essai
-Session <nom>	écrit dans qui.txt du verrou (défaut : variable d'environnement de la session, sinon Vague.ps1)
-Trailer <ligne>	ligne de fin de message (défaut : la ligne Co-Authored-By du projet)
-Json	un objet JSON seul sur la sortie standard (verdicts, status)
-Racine, -Addon	chemins du jeu et de l'addon (défauts : copie 5.8 et worktree 5.8) ; servent aux essais sur clones

Plafond de V3 : 8 tickets ; au-delà, code 2 (« deux vagues de suite »). Jamais de push, de --amend, de --no-verify, de reset --hard, de add -A, ni de forçage du verrou : le script n'a aucun paramètre pour ça.

3. Entrées lues par ticket

Fichier etat\REPO\tickets\<id>.md (gabarit lp-repo § 8) : type (titre # Ticket <id> — <TYPE>), Statut, Dépôt, Branche attendue, HEAD attendu, bloc Fichiers : (lignes A|M|D <chemin>), Message :, CHG / ERR : (ticket PARTAGES), Accord utilisateur. Un champ absent ou illisible = refus FORMAT.

4. Contrôles, dans l'ordre (premier échec = arrêt, code 1, ligne fautive citée)

Avant la vague (une fois) : P1 plafond ≤ 8 ; P2 tous les tickets existent et leur statut est demandé (V7 : un ticket « à compléter » ou déjà fait = refus) ; P3 ordre V4 : tickets addon, puis un éventuel ticket PIN, puis tickets jeu, puis PARTAGES en dernier (un seul) ; P4 verrou : en -Executer, Verrou.ps1 -Prendre (ticket = premier de la vague) ; en -Essai, Verrou.ps1 -Etat doit dire LIBRE (sinon refus BLOCKED-VERROU, ancienneté > 30 min signalée sans forcer).

Par ticket COMMIT (R = règle ; entre parenthèses la source) :

#	Contrôle	Source	Ligne fautive citée
C1	type = COMMIT, ou PIN : arrêt propre ARRET-PIN (le gardien pose le pin) ; autre type (TAG, REPORT, RESTORE, PUSH, BRANCHE, HISTOIRE) : refus TYPE-NON-GERE (traité par l'agent)	sk-repo § 3	l'en-tête du ticket
C2	dépôt = l'un des deux arbres connus ; branche courante = attendue ; HEAD = attendu (quelconque admis seulement pour PARTAGES et pour un ticket dont le HEAD attendu est celui de la fin de la vague) ; aucun index.lock ; aucune opération en cours (rebase, merge, cherry-pick)	sk-repo § 4 étape 2	Branche attendue : … / HEAD attendu : …
C3	identité : user.name non vide, user.email de la forme …@users.noreply.github.com, et identique à l'auteur du commit HEAD (aucune valeur d'identité n'est écrite dans le script ni dans les sorties)	lp-repo § 2	user.email (valeur masquée)
C4	chemins interdits (liste de lp-repo § 3 : Tools/ du jeu, .claude/, .mcp.json, Mods/, Saved, `Content/Heavy	Saves	Modules, *.png
C5	périmètre : chaque A / M existe et diffère de HEAD, chaque D a disparu ; aucun fichier du ticket dans un autre ticket de la vague	sk-repo § 4 étape 3	le chemin
C6	index privé : GIT_INDEX_FILE = <git-dir>\index-gardien, read-tree HEAD, add -- <chemins> ; le diff --cached --name-status doit être exactement la liste du ticket (ordre libre) ; LP_REPO_TICKET posé pour le garde-fou	sk-repo § 4 étape 5	l'écart (en trop / manquant)
C7	PubCheck : Tools\PubCheck.ps1 -Depot <arbre> -Index (sur l'index privé) = 0 ; sortie intégrale citée (jamais la valeur)	sk-repo § 4 étape 4	la ligne chemin:ligne:catégorie
C8	fins de ligne inchangées : classe i/ de HEAD = classe de l'index pour chaque fichier ; refus si le diff réécrit tout le fichier (ajouts + suppressions ≥ 2 × lignes, fichier > 20 lignes)	sk-repo § 4 étape 4	le chemin et les comptes
C9	message : ligne Message : présente et sans contenu de jeu (PubCheck sur le texte) ; message final = résumé + ligne vide + Tickets : <id> + ligne vide + -Trailer ; le corps Tickets : du ticket doit contenir l'id	lp-repo § 8	la ligne Message :
C10	R-REPO1 : statut du ticket → en cours puis fait, et ligne de REPO-JOURNAL.md ajoutée avant le commit et emportée par lui. La ligne est composée par le script (date, ticket, dépôt, branche, COMMIT (index privé, N chemins explicites), aucun push, <HEAD avant> (hash : git log --grep <id>), N (A+M), lot, contrôles). Si REPO-JOURNAL.md porte déjà des lignes d'un autre passage, le blob indexé est HEAD + les seules lignes de ce ticket (hash-object + update-index --cacheinfo), jamais le fichier de travail entier	lp-repo § 4, ticket REP1-T6	—
C11	commit -F <message> sur l'index privé ; puis git reset -q -- <chemins> sur l'index commun ; jamais --no-verify	sk-repo § 4 étape 5	la sortie de git
C12	contre-contrôle : git show --name-status HEAD = liste du ticket (+ REPO-JOURNAL.md et le ticket lui-même s'ils sont listés) ; git status --porcelain des autres chemins identique au relevé d'avant ; sinon avertissement ECART-POST (le commit existe : jamais de reset, la correction est un nouveau commit décidé par Big Boss) et arrêt	sk-repo § 4 étape 6	l'écart

Ticket PARTAGES (V5, A10), en plus des C1-C12 : P5 les fichiers de la liste sont exactement ceux du § 6 de lp-repo (Journal_Modifications.md, Registre_Erreurs.md, README.md, NUMEROS.md, BOSS-ETAT.md, BOSS-JOURNAL.md, FILE.md, REPO-JOURNAL.md, tickets de la vague) ; P6 contrôle V5 ligne à ligne : pour chaque ligne ajoutée (git diff HEAD -U0) :

• Journal_Modifications.md : commence par | CHG-n | avec n listé dans CHG / ERR : du ticket ;
• Registre_Erreurs.md : | ERR-n | avec n listé ;
• NUMEROS.md : ligne | CHG|ERR|DOC | n | avec n listé ;
• REPO-JOURNAL.md : une ligne dont la colonne Ticket est l'un des tickets de la vague ;
• README.md : seule la ligne de plage du journal (CHG-001 à CHG-n, n listé) ;
• BOSS-ETAT.md, BOSS-JOURNAL.md, FILE.md : lignes de Big Boss, admises sans contrôle ;
• lignes vides : admises ; toute autre ligne ajoutée = refus avec le fichier, le numéro de ligne et la ligne (tronquée, sans valeur sensible).

5. Sorties et codes

Une ligne par ticket (format de sk-repo § 10) : VERDICT <ticket> — fait <hash> | essai-OK | refusé <contrôle> : <ligne fautive> | ARRET-PIN | BLOCKED-VERROU — fichiers <n>. Puis, pour chaque dépôt, STATUS <dépôt> : <git status --short --branch> tronqué à 20 lignes. En cas de refus, les tickets non traités sont listés EN-FILE <id> (V9 : ils restent demandé). Le verrou est rendu à la fin même en cas de refus (Verrou.ps1 -Rendre). Codes : 0 tous les tickets traités (ou essai concluant) ; 1 un refus, un ARRET-PIN ou un verrou occupé ; 2 usage (paramètres, ticket introuvable, plafond, ordre, racine introuvable). Un refus laisse le statut refusé (<contrôle> : <motif>) dans le ticket (en -Executer seulement), la ligne de journal du ticket corrigée en conséquence.

6. Ce que le script ne fait pas

Pin du doc 21 (gardien), TAG / REPORT / RESTORE / PUSH / BRANCHE / HISTOIRE (agent), réservation de numéros (Numero.ps1), écriture de la file (Big Boss, V1), correction d'un ticket (V9 : on le retire ou le remplace), lecture de diff par un humain : il contrôle (liste, PubCheck, EOL, V5) mais ne juge pas le sens d'un diff ; Big Boss garde son passage unique de contre-vérification (V10).

7. Plan d'essais (clones jetables, jamais les dépôts réels)

• Dossier : %TEMP%\claude\VAG1\ (jeu et addon). Méthode : git clone --local --no-checkout de chacun, puis sparse-checkout limité à Docs/ et à un fichier d'exemple ; -Racine / -Addon pointent sur ces clones ; le Tools\PubCheck.ps1 réel est appelé en lecture. Le verrou d'essai vit dans un dossier VERROU propre au clone (paramètre interne, jamais etat\REPO\VERROU réel). Si le clonage sparse pose problème (taille, jonctions), repli : deux dépôts jetables créés par git init avec la même arborescence minimale ; à signaler à Big Boss.
• Preuve par l'échec : un ticket fautif par règle, chacun doit être refusé avec la bonne ligne et les tickets suivants rester EN-FILE : verrou occupé (P4) ; plafond 9 tickets (P1) ; ordre jeu avant addon (P3) ; statut déjà fait (P2) ; mauvaise branche (C2) ; mauvais HEAD (C2) ; identité hors noreply (C3) ; chemin interdit (C4) ; fichier listé sans diff (C5) ; fichier modifié non listé… (C6 : écart en trop) ; PubCheck non nul (C7, valeur factice, non réelle) ; fins de ligne LF→CRLF d'un fichier entier (C8) ; message sans Tickets : (C9) ; PARTAGES avec ligne ajoutée inconnue (P6) ; ticket PIN (ARRET-PIN) ; type TAG (TYPE-NON-GERE).
• Cas de réussite : vague de 3 tickets (addon, jeu, PARTAGES) en -Executer ; en -Essai : mêmes verdicts essai-OK, git status des clones identique avant / après (preuve « rien d'écrit »).
• Mesures citées brutes dans l'IMPL : sortie complète de chaque essai, git log --stat des clones, MD5 du script.

8. Livrables et suite

Tools\Vague.ps1 (LF, .SYNOPSIS, ligne dans Tools\LISEZMOI.md, instantané Snapshot.ps1 -Lot VAG1 avant écriture, outil local non suivi : CHG et instantané remplacent le commit, lp-doc / sk-protocol § 7), VAG1-IMPL.md, VAG1-TACHES.md, puis VAG1-VAL.md par un lp-validator distinct (classe O de PIPE1-SPEC-03). Hors périmètre : modifier lp-repo / sk-repo / l'agent lp-gardien pour dire « la vague passe par Vague.ps1 » (textes à proposer après la VAL).

9. Points à trancher par Big Boss avant l'IMPL

1. Clones sparse ou dépôts git init pour les essais (§ 7) : je prends les clones sparse sauf avis contraire.
2. Journal d'un ticket addon : la ligne REPO-JOURNAL.md et le statut du ticket vivent dans le jeu ; le script les écrit dans le jeu et ils partent avec le commit du ticket PARTAGES suivant (pratique de la vague 3, REP1-T8) : à confirmer.
3. Trailer Co-Authored-By : paramétré (§ 2), défaut celui des commits actuels ; confirmer qu'il doit rester dans les messages de vague.
4. Hook ecriture-gardien : la liste blanche des rédacteurs doit-elle admettre le script lancé par Big Boss ? À vérifier à l'IMPL (le script est un outil, non un agent) ; en cas de refus, arrêt et compte rendu, sans contournement.

Tours : environ 16. Incertitudes : le comportement de git clone --local avec les jonctions de l'addon (Content) n'est pas encore mesuré ; la forme exacte des tickets PIN n'est pas lue (le script s'arrête avant, par le titre seul). Fichiers à commiter : jeu (A) Docs/Migration/etat/AG/VAG1/VAG1-SPEC-01.md, VAG1-TACHES.md. Suite : Big Boss doit donner l'accord (et trancher § 9) ; état : SPEC écrite.