| name | upstream-merge |
| description | /upstream:merge - Interactive Upstream Merge Workflow. upstream scratch-editor の変更を Smalruby に取り込む半自動ワークフロー。 |
/upstream:merge - Interactive Upstream Merge Workflow
upstream scratch-editor の変更を Smalruby fork に取り込む半自動ワークフロー。
⚠️ 必読・絶対ルール: 差分比較の基準は release タグ / recorded lastMerge.upstreamCommit。
ghq ローカルの develop は stale で誤判定の原因になる（develop-trap、過去2回発生）。また
postMergeReverts に登録された pre-spork 残債は lost-fix ではない。詳細:
.claude/rules/upstream-tracking.md。
ワークフロー全体像
| Phase | ファイル | 内容 |
|---|
| 1 | phase1-prepare.md | Prerequisites確認 → ブランチ作成 → マージ実行 |
| 2 | phase2-conflicts.md | コンフリクト解決ガイド（既知パターン + ガイダンス） |
| 3 | phase3-validation.md | コミット → divergence 監査 → lint → build → テスト → CI |
| 4 | phase4-finalize.md | merge history更新 → PR作成 → 手動テスト |
リファレンス（必要時に読み込む）:
| ファイル | 内容 |
|---|
reference-api-migration.md | ScratchBlocks API 変更一覧 |
reference-test-patterns.md | テスト修正の既知パターン集 |
.upstream-merge-history.json スキーマ
{
"lastMerge": {
"date": "YYYY-MM-DD",
"upstreamCommit": "<upstream commit hash>",
"targetRelease": "vX.Y.Z",
"scratchWwwProductionSha": "<scratch-www production deploy commit>",
"scratchGuiVersion": "X.Y.Z",
"smalrubyCommit": "<smalruby commit hash before merge>",
"mergeCommit": "<merge commit hash>",
"notes": "description"
},
"postMergeReverts": [
{
"date": "YYYY-MM-DD",
"pr": "#NNN",
"reason": "why the revert was needed",
"scope": "short scope label",
"affectedAreas": [
{
"category": "human-readable category name",
"files": ["path/to/file1", "path/to/file2"],
"detail": "what was reverted and why"
}
],
"nextMergeGuidance": "instructions for how to handle these files on the next upstream merge"
}
],
"previousMerges": [
{ "...(rotated from lastMerge)" }
]
}
postMergeReverts の意味
upstream merge 後に、取り込んだ変更の一部を revert した場合に記録する。
- Git 上は
lastMerge.upstreamCommit まで取り込み済みだが、一部のファイルは revert されていることを示す
- 次回の upstream merge 時、
affectedAreas のファイルでコンフリクトが発生する可能性が高い
nextMergeGuidance に従ってコンフリクトを解決する- revert の原因が解消された場合（upstream 側で修正された等）、merge 完了後に該当エントリを削除する
進め方
- Phase 1 から順番に実行する
- 各フェーズの開始時に該当ファイルを読み込む
- Phase 1 で
postMergeReverts がある場合は、Phase 2 の前にユーザーと方針を確認する
- コンフリクト解決やテスト修正で詰まったら、リファレンスファイルを読み込む
- 各フェーズが完了したら次のフェーズに進む
絶対に守るルール
git add . は使わない — git add -u (tracked files のみ) を使うnotes/ は絶対にコミットしない — .gitignore で除外済みだが、明示パス指定や -f で追加されうる- ファイル指定で add — merge history 更新時は
git add .upstream-merge-history.json のみ
- PR マージは
--merge — squash merge は禁止。gh pr merge <number> --merge --delete-branch
- ドキュメントはPRの説明文に記載 — リポジトリにファイルとしてコミットしない
開始
Phase 1 のファイルを読み込んで開始:
.claude/skills/upstream-merge/phase1-prepare.md
