self-update

name	self-update
description	pkdxを最新版に更新する。構築・育成データを保護しながらスキルやCLIツールを安全にアップデートする。更新したい・アップデート・最新にしたい時に使用。
allowed-tools	Bash, AskUserQuestion

Self-Update

最新変更を安全に取り込むスキル。フォーク運用・clone運用どちらにも対応する。ユーザーは非技術者を想定し、git関連の技術用語はコミュニケーションではできる限り使わない。

パス定義

SKILL_DIR=（このSKILL.mdが置かれたディレクトリ）
REPO_ROOT=$SKILL_DIR/../../..

Phase 0: 前提確認

0-1: 運用モデル判定

cd $REPO_ROOT && git remote -v

以下のパターンで判定:

A. フォーク運用 — origin がユーザーのフォーク、upstream が本家

• upstream が存在する → そのまま続行
• origin が pkdxtools/pkdx（旧 ushironoko/pkdx 含む）でない + upstream がない → setup.sh を実行して自動設定:

  cd $REPO_ROOT && ./setup.sh
  

  （setup.sh が upstream remote を自動追加する）

B. clone運用 — origin が pkdxtools/pkdx（旧 ushironoko/pkdx からのリダイレクト含む）で、upstream が存在しない

• origin から直接 pull する（upstream の代わりに origin を使う）
• 以降のフェーズで upstream と記載された箇所を origin に読み替える

判定後、使用するリモート名を $UPDATE_REMOTE に設定:

# フォーク運用
UPDATE_REMOTE="upstream"
# clone運用
UPDATE_REMOTE="origin"

clone運用の場合、以下のメッセージを表示:

ℹ GitHubアカウントを作成してフォークに移行すると、構築・育成データの
  バージョン管理（変更履歴の保存・復元・クラウドバックアップ）が利用できます。
  詳しくは README.md の「セットアップ方法」を参照してください。

0-2: default branch 検出

UPSTREAM_BRANCH=$(git symbolic-ref refs/remotes/$UPDATE_REMOTE/HEAD 2>/dev/null | sed "s|refs/remotes/${UPDATE_REMOTE}/||")
if [ -z "$UPSTREAM_BRANCH" ]; then
  UPSTREAM_BRANCH="main"
fi

0-3: ワーキングツリーの状態確認

cd $REPO_ROOT && git status --porcelain

未コミットの変更がある場合（tracked + untracked）:

AskUserQuestion（1問）:

#	質問	header	オプション
1	未保存の変更があります。バックアップして続行しますか？	確認	はい(desc: 変更をバックアップして続行), いいえ(desc: 中断)

「いいえ」→ スキル終了。 「はい」→:

cd $REPO_ROOT && git branch backup/pre-update-$(date +%Y%m%d-%H%M%S)
cd $REPO_ROOT && git stash push -u -m "self-update: auto-stash $(date +%Y%m%d-%H%M%S)"

メモ: Phase 1 はソース更新とバイナリ更新の双方を含む。差分の有無に関係なく Phase 1-4（バイナリ更新）まで必ず到達する設計。

Phase 1: Fetch & Merge

cd $REPO_ROOT && git fetch $UPDATE_REMOTE

git fetch が失敗した場合、以下のフォールバック判定を行う:

1-F: Web環境フォールバック（フォーク運用 + fetch失敗時）

条件: $UPDATE_REMOTE が upstream （フォーク運用）かつ git fetch upstream が失敗（exit code ≠ 0）

この状況は Claude Code on the web 環境で発生する。web環境では git proxy がセッション対象リポジトリ（origin）のみにアクセスを制限するため、upstream への fetch がブロックされる。

手順:

1. ユーザーに状況を説明し、GitHub Web UIでの操作を案内する:

⚠ この環境では upstream リポジトリへの直接アクセスが制限されています。
  GitHub の Web UI から最新版を取り込む必要があります。

AskUserQuestion（1問）:

#	質問	header	オプション
1	GitHub Web UIでフォークを同期してください。\n\n手順:\n1. ブラウザで自分のフォークリポジトリページを開く\n2. 「Sync fork」ボタンをクリック\n3. 「Update branch」をクリック\n4. 完了したら「完了」を選択してください	フォーク同期	完了(desc: Sync forkを実行しました), 中断(desc: 更新を中断します)

「中断」→ Phase 2（Stash復元）へスキップしてスキル終了。

「完了」→ origin から pull して最新を取り込む:

cd $REPO_ROOT && git pull origin $UPSTREAM_BRANCH

pull 成功後、Phase 1-1（差分確認）をスキップし Phase 1-4（バイナリ更新） へ進む。 pull 失敗時は通常のコンフリクト処理（Phase 1-3）と同様に処理する。

---

git fetch が成功した場合、以下の通常フローを続行する:

1-1: 差分確認

cd $REPO_ROOT && git log --oneline HEAD..$UPDATE_REMOTE/$UPSTREAM_BRANCH | head -20

差分がない場合は「すでに最新です」と表示し、Phase 1-4（バイナリ更新） へ進む。バイナリ更新はソース差分の有無に関係なく必ず実行する（GitHub Releases のアセット差し替え、ローカルバイナリ欠損、version drift 残留などをカバーするため）。

1-2: マージ実行

cd $REPO_ROOT && git merge $UPDATE_REMOTE/$UPSTREAM_BRANCH --no-edit

1-3: コンフリクト処理

マージが失敗した場合:

cd $REPO_ROOT && git diff --name-only --diff-filter=U

コンフリクトファイルを一覧表示し:

• box/ 内のコンフリクト → ユーザー側(ours)を優先 (構築・育成・ブログ記事・サイト設定はユーザー所有):

  git checkout --ours box/<path> && git add box/<path>
  

  対象例: box/teams/**, box/pokemons/**, box/blog/**, box/site.config.json

• .claude/skills/ 内のコンフリクト → 更新元(theirs)を優先:

  git checkout --theirs .claude/skills/<path> && git add .claude/skills/<path>
  

• site/** のコンフリクト → 更新元(theirs)を優先 (Astro サイト本体は upstream 管理):

  git checkout --theirs site/<path> && git add site/<path>
  

  例外: site/public/CNAME はユーザーがカスタムドメイン用に追加する想定なので、存在すれば ours を保持する。

• .github/workflows/** のコンフリクト → 更新元(theirs)を優先 (CI/CD は upstream 管理):

  git checkout --theirs .github/workflows/<path> && git add .github/workflows/<path>
  

• box/blog/TEMPLATE.md.example のコンフリクト → 更新元(theirs)を優先 (ひな形は upstream が更新):

  git checkout --theirs box/blog/TEMPLATE.md.example && git add box/blog/TEMPLATE.md.example
  

• その他のコンフリクト → ユーザーに判断を求める:

AskUserQuestion（コンフリクトファイルごと）:

#	質問	header	オプション
1	<ファイルパス> の変更が衝突しています。どちらを残しますか？	衝突解決	ours(desc: 自分の変更を残す), theirs(desc: 更新元の変更を採用)

全コンフリクト解決後:

cd $REPO_ROOT && git commit --no-edit

1-4: バイナリ更新（GitHub Releases ダウンロード固定）

ソース差分の有無に関係なく必ず実行する。GitHub Releases のアセット差し替え、ローカルバイナリ欠損、moon.mod.json との version drift 残留などをまとめてカバーするため、ユーザーへの選択肢提示は行わない。./setup.sh が以下を一括で行う:

• 古いバイナリキャッシュのクリア
• GitHub Releases から最新 pkdx バイナリをダウンロード
• pokedex / champout submodule の同期
• pkdx_patch/{009..012}/data.json 再生成 → champions.db 再構築 → pkdx migrate 実行
• box/**/*.meta.json の schema マイグレーション（<path>.bak を 1 回だけ作成、既存 .bak は上書きしない）

CACHE_DIR="${XDG_CACHE_HOME:-$HOME/.cache}/pkdx"
rm -f "$CACHE_DIR"/pkdx-*
cd $REPO_ROOT && ./setup.sh

pkdx migrate は bookkeeping を持たない seed-script モデルで、全マイグレーションが冪等（UPDATE / INSERT OR REPLACE / existence-check / 自己所有テーブルの DELETE→再投入）として実装されているため、再適用しても DB は data.json の状態へ収束する。

ローカル開発でビルド済みバイナリを使いたい場合は、./setup.sh を流した後に手動で cd pkdx && moon build --target native --release src/main を打つ。

1-5: 動作確認

$REPO_ROOT/bin/pkdx version
$REPO_ROOT/bin/pkdx context --json | grep -o '"version_drift":[^,]*'

"version_drift":false が出ればバイナリと repo の version が一致している。true の場合（例: GitHub Releases にまだ最新版が反映されていない、./setup.sh の DL が失敗した）は再度 1-4 を流すか、ユーザーに状況を報告して指示を仰ぐ。SessionStart hook が同じ判定を毎回エージェントに注入するので、放置すると以後のセッションで毎回 drift 通知が出る。

Phase 2: Stash復元

Phase 0でstashした場合:

cd $REPO_ROOT && git stash pop

stash popでコンフリクトが発生した場合:

• box/ 内 → stash側を優先（ユーザーの作業中データ）
• その他 → AskUserQuestionでユーザーに判断を求める

Phase 3: 完了レポート

=== pkdxバージョンアップ完了 ===
マージ元: $UPDATE_REMOTE/$UPSTREAM_BRANCH
取り込み方法: <fetch & merge / fetch (差分なし) / Sync fork経由>
新規コミット数: <N>
コンフリクト解決: <あり/なし>
pkdx tools: 更新済み (GitHub Releases)
version_drift: <false / true (要対処)>
バックアップ: <復元済み/なし>

「取り込み方法」のラベル選択指針:

• fetch & merge: ソース差分があり git merge を実行したケース
• fetch (差分なし): 差分ゼロでバイナリ更新のみを行ったケース
• Sync fork経由: Phase 1-F で GitHub Web UI の Sync fork → git pull を踏んだケース