genekogan/proof — 変更済みジャーニーの無編集クリップ

proof — 変更済みジャーニーの無編集クリップ は何をしますか？

レビューアは、ユーザーが見るであろうものを、通常速度で最初から最後まで見ることができるべきです。クリップが証拠です。スクリーンショット、コンタクトシート、または高速再生された録画は証拠になりません。

ティアが必要とするものの真実の情報源: docs/process/PROOF-POLICY.yml (T0 なし; T1 重点テスト + 型チェック; T2 は変更されたジャーニーのクリップ1つを追加、デスクトップ、およびレイアウト変更がある場合はスマートフォンも、フェイクマインドワールド上で; T3/T4 はさらに追加)。現在の差分のティアを取得するには node tools/proof/tier.mjs --base origin/main を実行します。

ルール

• 無編集で実速度。 1つのブラウザコンテキスト、1テイク。トリミング、結合、スピードアップ、スローダウンは決してしないでください。ジャーニーがポリシーの max_seconds より長い場合は、より速いジャーニーではなく、それでも変更を示す短いジャーニーを録画してください。
• テイクは到着から開始します（デフォルト）: 録画はワールドが画面に表示され、到着カードが消えた後から始まります。つまり、クリップはローディングではなくワールドから始まります。そこから、ポリシーが要求するように、ジャーニーの無編集・実速度の1テイクです。ローディングや到着自体が変更の対象である場合（到着カード、ローディング画面、初回描画）、またはジャーニーがワールドページ上にない場合（ワールドリスト、サインイン）は、--from-load を渡します。その場合、テイクはページ作成から始まります。サイドカーの start (arrival または load) がどちらが使用されたかを示し、upload.mjs --proof がそれを proof.json の media[] にコピーします。
• 日中に。 ローカルワールドURLでは、レコーダーはページを開く前にワールドの時刻を正午に設定し、時計を停止します（--time-of-day 12、デフォルト。god env ルートを開発所有者として使用）。開発ワールドは06:00に起動し、実時間1時間でワールドの1日が進行します。そのため、この設定がないと40分経過したワールドは夜になります。設定すると、ワールドのgod履歴に1つの world エントリが追加され、その後時計は停止したままになります。時計、照明、またはgod履歴が変更の対象である場合は、別の時間または --time-of-day keep を渡します。サイドカーの worldTime が設定された時刻を示します。
• 実際の入力。 ユーザーが行うように、page.mouse、page.keyboard、page.touchscreen、またはロケータークリックで操作します。page.evaluate からアプリ内部を呼び出してカメラ上でイベントを発生させないでください。
• フェイクマインド、分離されたデータ。 ローカルワールドのみ、BRAIN_MODE=fake、新しいデータディレクトリ。メンテナーが依頼した場合を除き、本番ワールドに対して録画しないでください。また、サインイン済みの個人ブラウザプロファイルでは決して録画しないでください。
• 動画（またはフレーム）をリポジトリにコミットしないでください。 .e2e/ ディレクトリ（gitignore対象）で作業します。
• クリップは変更を示さなければなりません。添付する前に、クリップを見るか（少なくともフレームを抽出して）確認してください。

1. フェイクマインドワールドを起動する

ビルド済みのWebクライアントが必要です (pnpm install --frozen-lockfile && pnpm build; apps/web/dist/index.html が存在し、変更に対して最新の場合はスキップ)。新しいクローンでは、Webメディアが配置されるまでプリビルドチェックが失敗します: node tools/assets/pull.mjs --only 'apps/web/**' (数ファイル) で十分です。

node tools/god-skill/dev-world.mjs proof 4710 --genesis worlds/templates/hello-hamlet.json --fresh --data .local/proof
# http://127.0.0.1:4710/w/proof?dev=1 を出力 (pid N, ログ .lane/proof.log); サーバーはデタッチされて実行を続けます

ホームページ（ワールドリスト、New world）はワールドランチャーによって提供され、単一のワールドではありません。そこから始まるジャーニーの場合は、ランチャーを実行し（そのワールドは常にフェイクマインドを取得）、その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
# http://127.0.0.1:4720/ に対して録画します; ランチャーはそのpidで停止します（ワールドも停止します）

変更された画面を含むテンプレートを選択します (worlds/templates/: hello-hamlet は小さくて高速; eden-2026、mars-two などはより大きい)。空いているポートを使用します; e2e/config.mjs に他のハーネス用に予約されたポートがリストされています。完了したら kill <pid> でサーバーを停止します。

アプリが動作する簡単な証明: ローカルスモークテスト

録画前、またはサーバーやWebアプリに触れるT1変更の証明全体として、ローカルスモークテストを実行します。これは、自身の分離されたランチャー（フェイクマインド、開発サインイン、データは実行ディレクトリ下）を空いているポートで起動し、ワールドリストと1つのワールドを開き、人物がコンソールエラーや失敗したリクエストなしで描画されることを確認し、起動したものを停止します:

node e2e/local-smoke.mjs --port 9950 --clip      # 新しいクローンでは --build を最初に; 空いているポートには --port を省略
# → .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

summary.json の status: "pass" が証拠です。そのクリップはスモークジャーニーの無編集・実速度の1テイクです。これは変更のクリップではありません: T2変更は依然として以下で独自のジャーニーを録画します。詳細: docs/testing/e2e.md#local-smoke。

2. ステップを書く

.claude/skills/proof/steps.example.mjs を .e2e/proof/<slug>/steps.mjs にコピーし、変更されたジャーニーをスクリプト化します: 操作を行い、結果を示します。デフォルトの到着開始では、ステップは到着したワールドから始まります（arrived マークは 0:00）; --from-load では、ナビゲーションの直後から始まります。mark('label') はサイドカーにチャプタータイムをスタンプするため、PRで「パネルは0:07に開く」と言えます。変更が影響するジャーニーに限定してください。

3. 録画する

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
# レイアウトまたはタッチが変更された場合も:
node .claude/skills/proof/record.mjs --url '...' --steps .e2e/proof/<slug>/steps.mjs \
  --out .e2e/proof/<slug>/phone.mp4 --viewport phone

• ブラウザ: PLAYWRIGHT_BROWSERS_PATH を使用し、存在しない場合は /opt/pw-browsers を使用します。Chromium がない場合: PLAYWRIGHT_BROWSERS_PATH="$PWD/.e2e/browsers" pnpm --filter mars-campus-viewer exec playwright install chromium。
• Playwright の解決方法はプレイテストハーネスと同じです (tools/playtest/lib/platform.mjs: グローバルの playwright、なければ mars/viewer の @playwright/test)。GPUは不要です。WebGL は SwiftShader で動作します。
• --max-seconds はデフォルトでポリシーの max_seconds になります。終了コード3はジャーニーがそれを超えたことを意味します: 短くしてください。
• ffmpeg あり: 下部にプログレスバーと hh:mm:ss / total タイムコードが入ったmp4（タイムコードには drawtext でビルドされた ffmpeg が必要; サイドカーの timecode が存在するかどうかを示します）。ffmpeg なし: 生の .webm; PR でその旨を伝えてください（プレイヤーは独自のスクラブバーを表示します）。
• 各クリップには <clip>.json サイドカーが付属します: url、ビューポート、duration、start、startedAt、マーク（arrived を含む）、worldTime、コンソールエラー、コミット、ダーティフラグ。page.screencast のない Playwright は --from-load がなくてもページ作成から録画します; サイドカーは startFallback でその旨を示します。
• ページにはテイク開始前の到着まで --arrival-seconds（デフォルト120）があります; ワールドを決して表示しないページは、--from-load を使用するヒント、スタックした場所の静止画 (<clip>.open-failed.png)、およびサイドカーとともに失敗します（終了コード1）。サイドカーのコンソールエラーは発見事項です: 説明するか修正してください。

実行は10分のフォアグラウンド制限を十分下回ります。複数のクリップを一度に実行するには、バックグラウンドで実行してください（nohup setsid node ... > .e2e/proof/<slug>/rec.log 2>&1 &）そしてログをポーリングします。

4. 自分で確認する

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

フレームを確認します（PNGを読んでください）。変更された状態が表示されている必要があり、ワールドがロードされている必要があり（空白やローディング中のキャンバスではない）、フレーム内にプライベートなものが含まれていない必要があります。変更が表示されていない場合は、ステップを修正して新しいテイクを録画してください; 主張を証明しないクリップを添付しないでください。

5. PRに添付する（決してコミットしない）

公開前に、すべての送信テキスト/JSONペイロードを node tools/proof/publication.mjs <payload files> で確認します。メディアのピクセル、音声、ファイル名、バイナリメタデータを個別に検査します。デバイスパス、ホスト名、デバイス/プライベートIP、ローカルURL、運用識別子はプライベートレコードのみに属します。相対パスと中立的なキャプチャラベルを使用します。アップローダーはバッチをアップロードする前に検出されたテキスト漏洩をブロックします; これによりメディアのプライバシーを保証することはできません。

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

• デフォルトのターゲットはPR自身のプレリリース proofs-<n>（デフォルトブランチのタグ、初回使用時に作成されます）; PRごとに1つのリリースで、各リリースをGitHubの1000アセット制限未満に保ちます。古い共有 proofs リリースはこの制限に達しました。--release <tag>（または SIM_PROOF_RELEASE）で別のリリースを指定します。アセットは pr-<n>.<file> という名前になり、再テイクでは -2、-3 が付くため、失敗したテイクを含む以前のテイクもリンク可能なままです。SIM_PROOF_UPLOAD_URL（+ SIM_PROOF_UPLOAD_TOKEN）で別のエンドポイント（CDNなど）に切り替えます。
• --proof を使用すると、クリップと画像のリンクが proof.json の media[] に書き込まれ、他のファイル（ログ、JSON）は files[] に書き込まれ、proof.json が最後にアップロードされます。そのリンクとクリップリンクをPRの「Proof」セクションに貼り付けてください。journal スキルが proof.json をカバーします。
• インラインプレビュー。 GitHub はリリースアセットをダウンロードとして提供するため、mp4 リンクはPR内で再生されません。各動画について、upload.mjs は ffmpeg で小さなアニメーションGIFを作成します（<clip>.preview.gif: クリップの arrived マークから、または --from-load テイクの場合は0から、実速度で6秒、最大5 MB）、クリップの隣にアップロードし、media[].preview として記録し、次のような行を出力します: [![desktop.mp4](…pr-412.desktop.preview.gif)](…pr-412.desktop.mp4)。その行を貼り付けると、プレビューがPR内で再生され、クリックでフルクリップが開きます。変更がクリップの後半で表示される場合は、--preview-start <s>（および --preview-seconds <s>）でウィンドウを選択します。プレビューはポインターであり、証明ではありません: 無編集のmp4が証明です。各プレビューの前に、常に明示的な フル解像度無編集動画 リンクを配置し、実際のエンコードされた寸法と duration を記載します。キャプチャの解像度を維持し、アクションをフレーミングして、連絡先がレビューできるようにします。キャプチャをアップスケールしたり、動きの証明として縮小GIFを使用しないでください。
• 終了コード3: アップロードがブロックされました（gh がない、サインインしていない、権限がない、または多くのクラウドセッションのようにネットワークがない）。どのクリップが待機中でどこにあるかをユーザーに伝えてください。各クリップのduration、ビューポート、サニタイズされたサイドカーサマリー（マーク、コンソールエラー、コミット）、およびリポジトリ相対の record.mjs コマンドとステップファイルを含むPRコメントを投稿し、誰でも再録画できるようにします。PR本文でプルーフを「アップロード保留中」とマークします。動画をbase64として貼り付けたり、コミットしたり、別のブランチにプッシュしたりしないでください。

gh pr はクラウドセッションで機能しない場合があります。次のようにコメントしてください: gh api repos/$REPO/issues/$N/comments -F [email protected]/proof/$SLUG/comment.md。

クリップの横に書くべきこと

クリップごとに1行: どのジャーニー、どのワールドテンプレート、ビューポート、duration、コミット、および変更が表示される瞬間（「0:07 に座席がハイライト表示され、Soulが座る」）。さらに、コンソールエラーとそれらが許容される理由も記載します。