Hermes バージョン追従スキル

対象: このリポジトリ（Hermes Desktop ガイド）。前回の追従作業（v0.20.0 → v0.21.0、2026-09-02）で確立した手順を定型化したもの。スクリプトは scripts/hermes-audit/、委譲プロンプト雛形は templates/ にある。

前提と判断原則

• 正本は実機チェックアウト ~/.hermes/hermes-agent（git インストール）。読み取りのみ。git fetch / checkout / stash は禁止
• ガイドは実機コミットにピン留めする（hermes_commit は引用付き 8 桁）。リリースノートとソースが食い違えばソース・実機を優先
• 各ページ本文に版数を書かない。変更の記録は vault/06_リファレンス/04_変更履歴.md に集約
• 探索・執筆はサブエージェントへ委譲し、親は 40 行サマリだけ受け取る（レポート本体は scratchpad）。使用上限で止まった子は、解除後に SendMessage「続きから」で再開できる
• GUI 操作は rules/gui-automation.md に従う。着手前に「Mac を触らないで」と伝え、終了時に「OK」と伝える。作成・保存・更新ボタンは押さない
• ユーザーが監査中に hermes update すると実機コミットが動く。撮影後・執筆後に git rev-parse HEAD を再確認し、動いていたら Phase 0 の差分確認をやり直して再ピンする
• 実機は partial clone（blob:none）。手元に無いオブジェクトを参照すると git が黙って遅延 fetch する（v0.22.1 監査で最新タグの merge-base が fetch を始めた）。実機に対する git はすべて export GIT_NO_LAZY_FETCH=1 を付ける。委譲プロンプトにも必ず書く
• サブエージェントは Write でのレポート保存を拒否されることがある。その場合は返答本文が自動通知の途中で切れるので、「続きを SendMessage（to: team-lead）で」と頼み、親が scratchpad に保存する

Phase 0 ─ ピン確定（自分で実行、5 分）

OUT=<scratchpad>/audit
scripts/hermes-audit/preflight.sh $OUT <前回監査コミット8桁> [対象タグ]

対象タグを省略すると HEAD を指すタグを使う（無ければ最新リリース。ユーザーが更新した直後に次のパッチが出ていることがあるので、最新リリース＝実機とは限らない）。

出力で確認: バージョン行、HEAD、_config_version、対象タグとその祖先関係、前回からのコミット数、設定関連 4 パスの diff stat、diff-defaults.txt（追加/削除/変更の件数）、diff-commands.txt。リリースノートは $OUT/release-<tag>.md。

diff-defaults.txt は AST で評価できる項目だけの比較。preflight の出力に出る UNRESOLVED（f 文字列で組み立てる terminal.singularity_image、_aux() 呼び出しの auxiliary.* など）は差分に数えられないので、新旧で一覧を突き合わせて手で補う（v0.23.0 では削除 2・追加 2 が漏れ、照合で見つかった）。

前回コミットは memory hermes-rolling-main-version-pinned または vault/06_リファレンス/02_バージョンと調査根拠.md の対象表から取る。

Phase 1 ─ ソース差分調査（並列 6 体）

templates/prompts.md の「調査」節を使い、同一メッセージで起動する。モデルは差分読解が要る A/B/C/E を opus、機械比較 D と vault マップ F を sonnet / explorer。

名前	担当
A	設定サイドバー構成 + モデル / プロバイダー / ツールとキー / 認証情報
B	外観 / チャット / 詳細 / メモリ / 音声 / プロファイルスコープ / Browser
C	ゲートウェイ / キーバインド既定（lib/keybinds/actions.ts）/ 通知 / 請求 / 情報 / プラグイン / 横断機能
D	既定値とコマンドの機械比較（Phase 0 の JSON を渡すだけで済むなら省略可）
E	設定以外のデスクトップ変更（メインナビ・plugins/・新機能の UI 所在、ノートとの食い違い）
F	vault 全ページのトピック対応表と陳腐化しうる横断的主張

差分が 7,000 行を超えたら A/B/C の担当をさらに割る。

バックエンドが生成する一覧は設定 UI の差分に出ない。 プロバイダーのカード（hermes_cli/provider_catalog.py の CANONICAL_PROVIDERS）、ツールとキーの行、メッセージング連携の一覧はサーバー側のカタログから描画されるため、apps/desktop/src/app/settings/ の差分が 0 でも変わる。v0.23.0 では GitHub Copilot がコアからプラグインへ移り（hermes_cli/left_core_migration.py）、さらにガイドの API キー表が以前から 14 枚不足していたのが見つかった。A の担当にカタログの新旧比較と、実機スクショとの件数照合を含める。全員に scratchpad へのレポート書き出しと 未確認 欄を義務付ける。

Phase 2 ─ 実機スクリーンショット（GUI 自動操作）

Hermes は Electron で AX ツリーを公開しないため、座標クリック + screencapture。詳細は memory hermes-desktop-screenshot-capture。

1. ユーザーに「数分 Mac を触らない」と伝える。撮影したい状態（ローカルゲートウェイか、hermes desktop --local 起動か）を先に確認する
2. scripts/hermes-audit/capture/calibrate.sh $OUT/shots → 00_calibrate_s.png を Read し、カーソルが「モデル」に乗っていることを確認する。縮小→論理の係数はディスプレイ設定で変わる（calibrate.sh が出す撮影画像の幅 / 2 / 1280。3600px なら 1.40625、3024px なら 1.18125）
3. v0.22 以降のサイドバーはアコーディオン式（選択中の画面だけ子項目が開く）。SHOTS=$OUT/shots shot.sh t_chat 130 <チャットの y> でチャットを開いてから SHOTS=$OUT/shots capture_subpages.sh で全サブページを撮る（座標表は v0.22.1 時点）。撮影後、各 *_0_s.png のパンくずを 1 枚の一覧画像に切り貼りして着弾を確認する。旧 capture_settings.sh は 18 画面・旧幾何用
4. メイン画面系は画面ごとに shot.sh で撮り、1 枚目を Read して次の座標を決める（ナビ・タブ・cron の ✕ は v0.22.1 で位置が変わった。旧 capture_main.sh の座標表は使えない）
5. restore.sh $OUT/shots で他アプリを再表示し、ユーザーに「OK」と伝える
6. 落とし穴: モーダルの ✕ は Esc で閉じない / 子項目の展開で下の項目が子の数 × 1 行ずつずれる / スクロールはマウス直下の容器が動くのでテーマ格子・ペット格子を避ける / 透過モーダルに背景が透けるので他アプリを隠す / hide 直後に Hermes が別ディスプレイへ戻ることがある / Superset 等のターミナルから初めて screencapture すると macOS の画面収録の確認ダイアログが出てクリックを吸う（押さずに撮影を止め、ユーザーに処理を頼む）
7. v0.23.0 で分かったこと: 撮影中にユーザーが入力すると他アプリが前面に戻ってクリックを吸い、それ以降の着弾が連鎖してずれる（パンくず一覧で検出し、ずれた範囲だけ撮り直す）/ 設定 > プラグインは設定ページを持つプラグインの数だけ子項目が増え、「情報」の y がずれる / 「Web アクセス」はリモート接続中はサイドバーに出ない（撮るにはこのマシンのゲートウェイに接続する）/ 夜間に画面がロックされると screencapture は黒画面、Hermes のウィンドウ数は 0 になる。撮り直しが要る画面はロック前に済ませる
8. 外観と接続先: Hermes の外観は「システム」なので、朝は macOS に合わせてライト表示になる。掲載画像はダークで揃えているため、撮影前にユーザーに macOS をダークへ切り替えてもらう（Hermes のテーマ画面上部の切り替えは、スクロール位置が記憶されていて自動操作では出せなかった）。「Web アクセス」はステータスバー左の接続先メニュー（縮小座標 93,663）→「This device」で出る。撮影後は元の接続先へ戻す。ローカルは cron が 0 件なので、cron の新規作成フォームを個人情報なしで撮れる（保存せずキャンセル）。コマンドパレットへの keystroke は日本語入力が有効だと化けるので、英数キー（key code 102）を先に送る。Esc の 2 回目は設定モーダルを閉じる

撮れない画面（SSH 登録が要る Managed updates、平文トークン警告 等）は無理に作らず「ソース根拠」と明記して残す。

Phase 3 ─ スクショ照合（1 体、opus）

templates/prompts.md の「照合」節。全スクショを書き起こし、Phase 1 レポートの主張と突き合わせて「確認 / 未確認 / 食い違い」を判定させる。調査エージェント同士の食い違い（例: F12 トグルの所在）はここで裁定する。OCR の読み違い（例: ブレーンプリント / ブループリント）があるので、表記が争点なら原寸を切り出して自分で確認する。

Phase 4 ─ 執筆（並列 5 体、hermes-docs-writer）

1. templates/writer-common.md をコピーし、プレースホルダを Phase 0〜3 の確定値で埋めて scratchpad に置く
2. templates/prompts.md の「執筆」節で W1〜W5 を起動（画面グループ別。新設ページのファイル名・slug・order は親が先に確定して雛形に書く）
3. サイドバー order の再採番（新設画面の挿入）と astro.config.mjs の変更は親が先にやる。writer は Edit のみで Write は新規ページに限る
4. 執筆中に届く申し送り（既定値変更・索引の件数・表記統一）はリファレンス担当（W4）へ SendMessage で転送する

Phase 5 ─ 画像の切り出し・マスク・差し替え（1 体、opus）

templates/prompts.md の「加工」節。scripts/hermes-audit/crop_mask.py に渡す jobs.json を作らせ、src/assets/screenshots/ へ出力させる。出力名は settings-<slug末尾>.webp を基本とし、writer と同じ名前表を渡す。マスク必須: リモート URL / IP、残高・プラン、セッション名、cron 名・プロンプト・実行履歴、ボット名と状態文、適用対象チップの default 以外、モデル選択値、絶対パス、コミットハッシュ、トークン断片、右ペインのファイル木。加工後に 2〜3 枚を自分で Read して確認する。

Phase 6 ─ 整合と品質ゲート（自分で実行）

scripts/hermes-audit/bump_frontmatter.sh <version> <commit8> <YYYY-MM-DD>   # writer が触らなかったページも揃える
scripts/hermes-audit/check_refs.sh <version> <commit8> <YYYY-MM-DD>        # 画像参照・未参照画像・ピン・版数記載
npm run quality

check_refs.sh の版数検出は 00_ホーム.md の更新履歴と 06_リファレンス を除外している。UI 文言の引用に含まれる em ダッシュは許容。

Phase 7 ─ コミット・デプロイ・記録

• コミットメッセージは前回（git log --grep 'Hermes v0.2'）の書式に揃える。main へ push すると Workers Builds が本番デプロイする。反映は curl で新規ページの 200 と画像名の埋め込みを実測する
• memory hermes-rolling-main-version-pinned の「現在の状態」をピン・画面数・件数で更新する
• 派生ドキュメントを見直す: KNOWN_ISSUES.md（設定画面の表示順とファイル接頭辞の対応表）、README.md の frontmatter 例のピン、docs/ 配下の版数・ページ数の記述、templates/writer-common.md の例示値
• 残った未確認項目は本文に明記した状態で終える。ユーザーが「残課題も」と言ったら Phase 2 を条件付き（--local 起動、ゲートウェイ切替）で再実行する

所要の目安（v0.23.0 実績）

設定 UI の差分 8,000 行・20 画面（Web アクセス新設）。調査 5 体（A/B/C/E + F。D は Phase 0 の出力で足りたので省略）20 分 → 撮影 15 分（ユーザー入力で着弾ずれ、2 回撮り直し）→ 照合 1 体と画像加工 1 体を並列で 25 分 → 執筆 5 体 10〜15 分 → プロバイダー表の作り直し 10 分 → 整合・品質 10 分。ユーザーが不在のまま最後まで進めた。

所要の目安（v0.22.1 実績）

設定差分 3.3 万行・19 画面のサブページ化という大型更新。調査 10 体（A/B/C/E を各 2 分割 + D + F）20 分 → 撮影 15 分（185 枚、権限ダイアログで 1 回中断）→ 照合 1 体 30 分 → 執筆 6 体 + 画像加工 1 体 + アイコン CSS 1 体を並列で 20〜40 分（使用上限で 2 回中断）→ 整合・品質 10 分。依存が未インストールのことがあるので、品質ゲートの前に node_modules の有無を確かめて npm ci する。

所要の目安（v0.21.0 実績）

調査 6 体 15 分 → 撮影 20 分（座標校正の手戻り込み）→ 照合 10 分 → 執筆 5 体 30 分（上限停止で中断あり）→ 加工 10 分 → 品質・デプロイ 5 分。スクリプト化後は撮影と整合チェックが短縮される見込み。