genekogan/proof

proof — une vidéo non coupée du parcours modifié

Un relecteur doit pouvoir voir ce qu'un utilisateur verrait, à vitesse normale, du début à la fin. La vidéo est la preuve ; une capture d'écran, une planche contact ou un enregistrement accéléré ne suffisent pas.

Référence pour ce que chaque niveau nécessite : docs/process/PROOF-POLICY.yml (T0 rien ; T1 tests ciblés + vérification de type ; T2 ajoute une vidéo du parcours modifié, bureau, plus téléphone si la mise en page a changé, sur un monde à esprit factice ; T3/T4 ajoutent plus). Obtenez le niveau du diff actuel avec node tools/proof/tier.mjs --base origin/main.

Règles

• Non coupée et en temps réel. Un contexte de navigateur, une seule prise. Ne jamais couper, assembler, accélérer ou ralentir. Si le parcours dépasse le max_seconds de la politique, enregistrez un parcours plus court qui montre toujours le changement, pas un plus rapide.
• La prise commence à l'arrivée (par défaut) : l'enregistrement commence une fois que le monde est à l'écran et que la carte d'arrivée a disparu, donc la vidéo s'ouvre sur le monde, pas sur le chargement. De là, c'est une seule prise non coupée, en temps réel, du parcours, comme demandé par la politique. Lorsque le chargement ou l'arrivée est lui-même l'objet du changement (la carte d'arrivée, un écran de chargement, le premier affichage), ou que le parcours n'est pas sur une page de monde (la liste des mondes, la connexion), passez --from-load : la prise commence alors à la création de la page. Le start du fichier sidecar (arrival ou load) indique lequel a été utilisé, et upload.mjs --proof le copie dans proof.json media[].
• De jour. Sur une URL de monde locale, l'enregistreur règle le monde à midi avec son horloge en pause avant l'ouverture de la page (--time-of-day 12, par défaut ; la route god env en tant que propriétaire dev). Les mondes de développement démarrent à 06:00 et avancent d'un jour-monde par heure réelle, donc sans cela, un monde ouvert depuis 40 minutes serait la nuit. Le réglage crée une entrée world dans l'historique god du monde, et l'horloge reste en pause après. Passez une autre heure, ou --time-of-day keep lorsque l'horloge, la lumière ou l'historique god est l'objet du changement. Le worldTime du sidecar indique ce qui a été réglé.
• Entrée réelle. Utilisez page.mouse, page.keyboard, page.touchscreen ou des clics de localisateurs, comme le ferait un utilisateur. N'appelez pas les internes de l'application via page.evaluate pour faire avancer les choses devant la caméra.
• Esprits factices, données isolées. Mondes locaux uniquement, BRAIN_MODE=fake, un répertoire de données frais. N'enregistrez jamais contre un monde de production sauf si le mainteneur le demande, et jamais avec un profil de navigateur personnel connecté.
• Ne jamais intégrer la vidéo (ou les images) dans le dépôt. Travaillez sous .e2e/ (gitignoré).
• La vidéo doit montrer le changement. Regardez-la (ou au moins extrayez des images, ci-dessous) avant de l'attacher.

1. Démarrer un monde à esprit factice

Nécessite un client web compilé (pnpm install --frozen-lockfile && pnpm build ; sautez si apps/web/dist/index.html existe et est à jour pour votre changement). Dans un clone frais, la vérification pré-construction de la build échoue jusqu'à ce que les médias web soient en place : node tools/assets/pull.mjs --only 'apps/web/**' (quelques fichiers) suffit.

node tools/god-skill/dev-world.mjs proof 4710 --genesis worlds/templates/hello-hamlet.json --fresh --data .local/proof
# affiche http://127.0.0.1:4710/w/proof?dev=1 (pid N, log .lane/proof.log) ; le serveur continue de tourner en arrière-plan

La page d'accueil (liste des mondes, Nouveau monde) est servie par le lanceur de mondes, pas par un seul monde. Pour un parcours qui commence là, lancez un lanceur (ses mondes ont toujours des esprits factices) et créez un monde pour la liste via son API :

node tools/world-launcher/launcher.mjs --port 4720 --range 4721-4723 --data "$PWD/.local/proof-launcher" --eager 0 &
curl -s -X POST -H 'content-type: application/json' -H 'authorization: Bearer dev:proof' \
  -d '{"name":"Proof Garden","template":"hello-hamlet"}' http://127.0.0.1:4720/__sim/worlds
# enregistrez contre http://127.0.0.1:4720/ ; arrêtez le lanceur par son pid (il arrête ses mondes)

Choisissez le template qui contient la surface modifiée (worlds/templates/ : hello-hamlet est petit et rapide ; eden-2026, mars-two et d'autres sont plus grands). Utilisez un port libre ; e2e/config.mjs liste les ports réservés pour d'autres harnais. Arrêtez le serveur avec kill <pid> quand vous avez terminé.

Vérification rapide du fonctionnement de l'application : le smoke local

Avant d'enregistrer, ou comme preuve complète d'un changement T1 qui touche le serveur ou l'application web, exécutez le smoke local. Il démarre son propre lanceur isolé (esprits factices, connexion de développement, données sous le répertoire d'exécution) sur un port libre, ouvre la liste des mondes et un monde, vérifie qu'une personne est dessinée sans erreur de console et sans requête échouée, et arrête ce qu'il a démarré :

node e2e/local-smoke.mjs --port 9950 --clip      # --build d'abord sur un clone frais ; omettez --port pour un port libre
# → .local/e2e/<timestamp>/summary.json, shots/1-world-list.png 2-world.png 3-person.png, clip.mp4
node tools/proof/upload.mjs --pr $N .local/e2e/<timestamp>/summary.json .local/e2e/<timestamp>/shots/*.png

status: "pass" dans summary.json est la preuve ; sa vidéo est une seule prise non coupée, en temps réel, du parcours du smoke. Ce n'est pas une vidéo de votre changement : un changement T2 enregistre toujours son propre parcours ci-dessous. Détails : docs/testing/e2e.md#local-smoke.

2. Écrire les étapes

Copiez .claude/skills/proof/steps.example.mjs vers .e2e/proof/<slug>/steps.mjs et scriptez le parcours modifié : faites la chose, montrez le résultat. Avec le démarrage par défaut à l'arrivée, les étapes commencent sur le monde arrivé (le marqueur arrived est à 0:00) ; avec --from-load, elles commencent juste après la navigation. mark('label') inscrit un temps de chapitre dans le sidecar pour que la PR puisse dire "le panneau s'ouvre à 0:07". Limitez-vous au parcours affecté par le changement.

3. Enregistrer

node .claude/skills/proof/record.mjs --url 'http://127.0.0.1:4710/w/proof?dev=1' \
  --steps .e2e/proof/<slug>/steps.mjs --out .e2e/proof/<slug>/desktop.mp4 --viewport desktop
# mise en page ou tactile changé ? aussi :
node .claude/skills/proof/record.mjs --url '...' --steps .e2e/proof/<slug>/steps.mjs \
  --out .e2e/proof/<slug>/phone.mp4 --viewport phone

• Navigateurs : utilise PLAYWRIGHT_BROWSERS_PATH, sinon /opt/pw-browsers s'il est présent. Si Chromium manque : PLAYWRIGHT_BROWSERS_PATH="$PWD/.e2e/browsers" pnpm --filter mars-campus-viewer exec playwright install chromium.
• Playwright est résolu de la même manière que le harnais de test de jeu (tools/playtest/lib/platform.mjs : un playwright global, sinon @playwright/test depuis mars/viewer). Pas de GPU nécessaire ; WebGL tourne sur SwiftShader.
• --max-seconds par défaut sur le max_seconds de la politique. Le code de sortie 3 signifie que le parcours l'a dépassé : raccourcissez-le.
• Avec ffmpeg : un mp4 avec une barre de progression en bas et un timecode hh:mm:ss / total (le timecode nécessite un ffmpeg compilé avec drawtext ; le timecode du sidecar indique s'il est présent). Sans ffmpeg : le .webm brut ; mentionnez-le dans la PR (les lecteurs montrent toujours leur propre barre de défilement).
• Chaque vidéo reçoit un sidecar <clip>.json : url, viewport, durée, start, startedAt, marqueurs (arrived parmi eux), worldTime, erreurs console, commit et indicateur de modification. Un Playwright sans page.screencast enregistre depuis la création de la page même sans --from-load ; le sidecar le signale dans startFallback.
• La page a --arrival-seconds (120 par défaut) pour arriver avant le début de la prise ; une page qui n'affiche jamais de monde échoue (code 1) avec un conseil d'utiliser --from-load, une image fixe de l'endroit où elle a bloqué (<clip>.open-failed.png) et un sidecar. Les erreurs console dans le sidecar sont des constats : expliquez-les ou corrigez-les.

L'exécution prend bien moins que la limite de 10 minutes au premier plan. Pour plusieurs vidéos en une seule fois, exécutez-les en arrière-plan (nohup setsid node ... > .e2e/proof/<slug>/rec.log 2>&1 &) et surveillez le journal.

4. Vérifiez vous-même

for t in 1 4 8; do ffmpeg -loglevel error -y -ss $t -i .e2e/proof/<slug>/desktop.mp4 -frames:v 1 .e2e/proof/<slug>/t$t.png; done

Regardez les images (Lisez les PNG). L'état modifié doit être visible, le monde doit avoir été chargé (pas un canevas vierge ou en chargement), et rien dans le cadre ne doit être privé. Si cela ne montre pas le changement, corrigez les étapes et enregistrez une nouvelle prise ; n'attachez pas une vidéo qui ne prouve pas ce qui est affirmé.

5. Attachez-la à la PR (ne l'intégrez jamais)

Vérifiez chaque charge utile texte/JSON sortante avec node tools/proof/publication.mjs <fichiers de charge utile> avant publication. Inspectez les pixels, l'audio, les noms de fichiers et les métadonnées binaires séparément. Les chemins d'appareils, noms d'hôtes, adresses IP privées/d'appareils, URL locales et identifiants opérationnels n'appartiennent qu'aux enregistrements privés. Utilisez des chemins relatifs et des étiquettes de capture neutres. Le bloqueur de téléchargement détecte les fuites de texte avant de télécharger le lot ; cela ne peut pas certifier la confidentialité des médias.

node tools/proof/upload.mjs --pr $N --proof .e2e/journal/$ISSUE/proof.json .e2e/proof/$SLUG/desktop.mp4 .e2e/proof/$SLUG/phone.mp4

• La cible par défaut est la propre prerelease proofs-<n> de la PR (tag sur la branche par défaut, créée à la première utilisation) ; une release par PR maintient chaque release sous la limite de 1000 actifs de GitHub, que l'ancienne release partagée proofs avait atteinte. --release <tag> (ou SIM_PROOF_RELEASE) nomme une autre release. Les actifs sont nommés pr-<n>.<fichier>, et une nouvelle prise obtient -2, -3, donc les prises précédentes, y compris les échouées, restent liables. SIM_PROOF_UPLOAD_URL (+ SIM_PROOF_UPLOAD_TOKEN) bascule vers un autre point de terminaison, comme un CDN.
• Avec --proof, les liens des vidéos et images sont écrits dans proof.json media[], les autres fichiers (logs, JSON) dans files[], et proof.json est téléchargé en dernier. Collez son lien et les liens des vidéos dans la section Preuve de la PR. La compétence journal couvre proof.json.
• Aperçu inline. GitHub sert les actifs des releases comme des téléchargements, donc un lien mp4 ne se joue jamais dans la PR. Pour chaque vidéo, upload.mjs crée un petit GIF animé avec ffmpeg (<clip>.preview.gif : 6 s à vitesse réelle à partir du marqueur arrived de la vidéo, ou de 0 pour une prise --from-load ; au maximum 5 Mo), le télécharge à côté de la vidéo, l'enregistre comme media[].preview et imprime une ligne comme [![desktop.mp4](…pr-412.desktop.preview.gif)](…pr-412.desktop.mp4). Collez cette ligne : l'aperçu se joue dans la PR et cliquer dessus ouvre la vidéo complète. Lorsque le changement apparaît plus tard dans la vidéo, choisissez la fenêtre avec --preview-start <s> (et --preview-seconds <s>). L'aperçu est un indicateur, pas la preuve : le mp4 non coupé est la preuve. Mettez toujours un lien explicite Vidéo non coupée en pleine résolution avant chaque aperçu, indiquant les dimensions encodées réelles et la durée. Préservez la résolution de capture et cadrez l'action pour que le contact puisse être examiné. N'améliorez pas la résolution d'une capture et n'utilisez pas le GIF réduit pour prétendre à une preuve de mouvement.
• Code de sortie 3 : le téléchargement est bloqué (pas de gh, pas de connexion, pas de permission, ou pas de réseau, comme dans de nombreuses sessions cloud). Dites à l'utilisateur quelles vidéos attendent et où. Postez un commentaire PR avec la durée de chaque vidéo, le viewport, le résumé du sidecar nettoyé (marqueurs, erreurs console, commit), et une commande record.mjs relative au dépôt et le fichier d'étapes, afin que quiconque puisse ré-enregistrer. Marquez la preuve "en attente de téléchargement" dans le corps de la PR. Ne collez jamais la vidéo en base64, ne l'intégrez jamais et ne la poussez jamais vers une autre branche.

gh pr peut ne pas fonctionner dans les sessions cloud ; commentez avec gh api repos/$REPO/issues/$N/comments -F [email protected]/proof/$SLUG/comment.md.

Que écrire à côté de la vidéo

Une ligne par vidéo : quel parcours, quel template de monde, viewport, durée, commit, et le moment où le changement est visible ("0:07 le siège se surligne et le Soul s'assoit"). Plus les éventuelles erreurs console et pourquoi elles sont acceptables.