chore(upstream): pre-spork 巻き戻し (#270) の取り残しを監査し v13.7.2 ベースラインへ再整合する計画

[takaokouji]

Goal

smalruby は upstream scratch-editor v13.7.2 + scratch-blocks v2.1.19（modern Blockly） を基盤とする。
しかし Issue #270 / commit 84f87e9152（"restore upstream source files to pre-spork state (scratch-blocks v1.3.0)"）が
22 ソースファイルを pre-spork（classic Blockly v1.3.0）状態へ巻き戻し、その後の v13.7.2 マージで
scratch-blocks を v2.1.19 へ再アップグレードした際にこれらを modern 状態へ再移行しなかった。

結果、modern Blockly エンジン (v2.1.19) の上で pre-spork のソースが band-aid で糊付けされて動いている
状態になっている。拡張機能の HAT/EVENT ブロックが帽子型に描画されない不具合（旧 PR #748）はこの取り残しの一症状。

当初は 監査専任 Issue として起票したが、実作業の中で監査 → 段階的な再整合の実装・検証まで実施した（下記「実装状況」「当初計画外の追加作業」参照）。

経緯（git 履歴・.upstream-merge-history.json から確定）

日付	出来事
2026-03-08	upstream マージで scratch-blocks v2.0.0（spork）導入 → 「定義」ブロック引数ドラッグが壊れる
2026-03-11	Issue #270 / 84f87e9152 で v1.3.0 へダウングレードし 22 ソースファイルを pre-spork 状態へ巻き戻し
2026-05-03	v13.7.2 マージ（352a334b）で scratch-blocks を v2.1.19 へ再アップグレード。だが巻き戻した 22 ファイルは modern へ再移行されず、band-aid で糊付け

実装状況（topic ブランチ topic/upstream-realign-v13.7.2 に集約）

PR	内容	状態
#751	Step 1: colour→style / shape_hat / monitor_block / setBlockStyle 復元 + develop-trap ガード + doc 整理	✅ topic にマージ
#753	Step 2: コメントイベント modern 化 + ${block.id}_comment 契約（blocks.js / adapter.js / comment.js / sb3 周辺）	✅ topic にマージ
#754	Step 3: band-aid auto-style-patch.js 撤去	✅ topic にマージ
#756	chore: mesh リグレッションスクリプト headless 化 + tools/playwright-verify を rules に明記	✅ topic にマージ
#755	topic → develop（リリース取り込み）	⏳ オープン・最終マージ待ち

Implementation Steps（調査フェーズ）

• Phase 0-A ベースライン固定 — .claude/rules/upstream-tracking.md に baseline（v13.7.2 / scratch-blocks v2.1.19）+ develop-trap を恒久ルール化。.upstream-merge-history.json の postMergeReverts・upstream-merge skill・bin/upstream-divergence-audit にも反映
• Phase 0-B ファイル別乖離カタログ — 22 ファイルを v13.7.2 と diff し A/B/C 分類（詳細は監査ドキュメント。color-mode 4 ファイルは整合済 = 0、blocks.jsx 703 / define-dynamic-block 457 等が大乖離）
• Phase 0-C band-aid 棚卸し — auto-style-patch.js・colour 復元・v1 field API・v2-bridge guard 等を列挙し、再整合後の要否を明記
• Phase 0-D 再整合計画 + follow-up Issue 起票 — chore(upstream): pre-spork 再整合の残債を v13.7.2 へ追従する (follow-up of #749/#751) #752 起票。計画を Step 1〜3 として 実装まで完了（fix: re-align pre-spork-reverted files to upstream v13.7.2 (#749) #751/fix(scratch-vm): re-align comment handling to upstream v13.7.2 (Step 2, #752) #753/refactor(scratch-gui): retire auto-style-patch band-aid (Step 3, #752) #754）。PR fix(scratch-vm): 拡張機能の HAT/EVENT ブロックを modern Blockly で帽子型に描画 #748 は superseded として close 済み
• Phase 0-E エビデンス取得 — ⚠️ 当初は「再整合前(before)」採取予定だったが、実装を先行したため 再整合後(after)の検証に変更（Playwright + ホスト Chrome 実機）。before スクショは未取得（実装が完了しているため再現には develop を別途 checkout する必要あり）

Definition of Done

• 監査ドキュメント作成（baseline + develop-trap + 22 ファイル分類 + band-aid 一覧 + 段階計画）— ⚠️ 配置変更: 当初予定の docs/upstream-tracking/ ではなく、ユーザー指示により git 管理外 notes/upstream-tracking/ に退避（一度きりの作業成果物のため）。今後参照する forward-looking 情報のみ .claude/rules/upstream-tracking.md に残した
• 22 ファイルすべてを A/B/C 分類
• band-aid 一覧に「再整合後に削除可能か」を明記
• follow-up Issue を起票（chore(upstream): pre-spork 再整合の残債を v13.7.2 へ追従する (follow-up of #749/#751) #752）
• PR fix(scratch-vm): 拡張機能の HAT/EVENT ブロックを modern Blockly で帽子型に描画 #748 を superseded として close
• エビデンス取得（Playwright / ホスト Chrome、notes/ 配下）— ただし下記は after-state での確認（before ではなく）:
  • 拡張 HAT/EVENT（koshien connect_game・micro:bit when ...）が帽子型で描画される（修正後）
  • 拡張ブロックの色が維持（style 名前付きスタイル経由）
  • 「定義」ブロックの引数ドラッグ / モーダルが動く（fix: downgrade scratch-blocks from v2.0.3 to v1.3.0 to restore custom block argument dragging #270 元不具合の非再発を after で確認）
  • レポーターのモニタ（チェックボックス）が表示（monitor_block、koshien_mapAll で確認）
  • ⚠️ 再整合前(before) の「平らな上端」「auto-style 経由の色」スクショは未取得（after 検証で代替）

当初計画外の追加作業（実装中に発生）

監査専任の当初スコープを超えて実施した作業:

• 再整合の実装まで実施（当初は follow-up Issue に委譲予定）— Step 1〜3 を fix: re-align pre-spork-reverted files to upstream v13.7.2 (#749) #751/fix(scratch-vm): re-align comment handling to upstream v13.7.2 (Step 2, #752) #753/refactor(scratch-gui): retire auto-style-patch band-aid (Step 3, #752) #754 として実装・CI green・topic マージ
• 敵対的レビュー 2 観点（差分正当性 / 将来の誤ベース化リスク）を subagent で実施し PR にコメント、MUST 指摘を適用
• 将来の誤ベース化防止ガード（develop-trap を phase1-prepare.md / SKILL.md / bin/upstream-divergence-audit / postMergeReverts / .claude/rules/upstream-tracking.md に反映）
• ドキュメント整理: 一度きりの監査詳細・スクショを git 管理外 notes/ へ、forward-looking を .claude/rules へ分離
• topic ブランチ運用（段階 PR をスタック → topic 集約 → fix: re-align pre-spork files to upstream v13.7.2 — extension hat shape + comments + band-aid cleanup (#749) #755 で develop へ）
• band-aid auto-style-patch.js の実削除（当初は「棚卸し」のみの予定。Step 1 の named style 復元で不要化を実証し Step 3 で削除）
• mesh リグレッション検証 + ツール改善（unit 391 / integration 34 / mesh-v2-classroom-binding.mjs 全 pass。スクリプトを headless 対応化、tools/playwright-verify を rules に明記 = chore(test): headless-capable mesh verify script + document playwright-verify in rules #756）
• Playwright MCP 接続・警告解消（ホスト MCP の --host 0.0.0.0、--disable-blink-features=AutomationControlled 警告を ignoreDefaultArgs config で除去）— memory に記録

残作業（敵対的観点での洗い出し）

• fix: re-align pre-spork files to upstream v13.7.2 — extension hat shape + comments + band-aid cleanup (#749) #755 (topic → develop) の最終マージ — リリース判断待ち（CI green 済み）
• chore(upstream): pre-spork 再整合の残債を v13.7.2 へ追従する (follow-up of #749/#751) #752 の残債（未実装・低優先）:
  • make-toolbox-xml.js カテゴリ名 %{BKY_CATEGORY_*} → ScratchMsgs.translate（cosmetic・v2.1.19 で動作はする）
  • blocks.jsx の v2-bridge guard（forceRerender try/catch・componentWillUnmount optional-chaining・My Blocks 再構築）の除去可否検証
  • runtime.js の EXTENSION_DATA_LOADING 再追加 / BEFORE_STEP（mesh 依存・要マーカー化）の小整合
  • ※ Step 2 で対応済み: vm blocks.js コメントイベント / adapter・sb3・comment の id 契約（fix(scratch-vm): re-align comment handling to upstream v13.7.2 (Step 2, #752) #753）
• before スクショ不足（必要なら develop を checkout して再整合前の状態を採取）

Test Plan（実績）

Type	実績
unit / integration	scratch-vm/gui の関連テスト + mesh（unit 391 / integration 34）green。各 PR で CI 9/9 green
ブラウザ検証 (Playwright + ホスト Chrome)	hat/色/monitor/screenshot/palette/zoom/定義モーダル/コメント往復/Ruby コメント/mesh shadow ドロップダウン
mesh リグレッション	tools/playwright-verify/mesh-v2-classroom-binding.mjs 全 PASS

関連

• Issue fix: downgrade scratch-blocks from v2.0.3 to v1.3.0 to restore custom block argument dragging #270（pre-spork ダウングレードの元 Issue, CLOSED）/ #3450（upstream の引数ドラッグ修正）
• Steps: fix: re-align pre-spork-reverted files to upstream v13.7.2 (#749) #751 / fix(scratch-vm): re-align comment handling to upstream v13.7.2 (Step 2, #752) #753 / refactor(scratch-gui): retire auto-style-patch band-aid (Step 3, #752) #754 / chore chore(test): headless-capable mesh verify script + document playwright-verify in rules #756 / topic→develop fix: re-align pre-spork files to upstream v13.7.2 — extension hat shape + comments + band-aid cleanup (#749) #755
• Follow-up（残債）: chore(upstream): pre-spork 再整合の残債を v13.7.2 へ追従する (follow-up of #749/#751) #752
• Superseded: fix(scratch-vm): 拡張機能の HAT/EVENT ブロックを modern Blockly で帽子型に描画 #748
• .upstream-merge-history.json（lastMerge: v13.7.2 / 352a334b）/ .claude/rules/upstream-tracking.md

[takaokouji]

監査完了 + Phase 1 再整合を実装 → PR #751

ユーザー指示により、監査だけでなく Phase 1（color/blockJSON + 機械的整合）の再整合まで実装し、PR を作成しました: #751

完了

• Phase 0-A ベースライン固定 — docs/upstream-tracking/pre-spork-realignment-audit.md に記録（v13.7.2 / scratch-blocks v2.1.19、develop-trap 警告）。ghq scratch-editor は v13.7.2 へ checkout 済み
• Phase 0-B ファイル別乖離カタログ — 22 ファイルを A/B/C 分類（監査ドキュメントの表）
• Phase 0-C band-aid 棚卸し — auto-style-patch / v2-bridge guard / colour 復元等を一覧化、再整合後の扱いを明記
• Phase 0-D 再整合計画 + PR — Phase 1 を PR fix: re-align pre-spork-reverted files to upstream v13.7.2 (#749) #751 で実装。後続（vm/blocks.js コメントイベント、adapter/sb3 コメント id、make-toolbox-xml カテゴリ名、band-aid 除去）は follow-up に整理
• Phase 0-E 現状/再整合後エビデンス — Playwright スクリーンショットを docs/upstream-tracking/screenshots/ に格納

Phase 1 で実施（PR #751）

• scratch-vm: runtime.js（style + extensions + shape_hat + monitor_block）、comment.js（collapsed 属性）
• scratch-gui: blocks.jsx（setBlockStyle 復元）、define-dynamic-block.js（style）、custom-procedures.jsx（theme）、radix shim 削除、block-to-image.js
• 旧 PR fix(scratch-vm): 拡張機能の HAT/EVENT ブロックを modern Blockly で帽子型に描画 #748 は superseded として close 済み

follow-up（本 Issue 外・別 Issue 候補）

• vm blocks.js のコメントイベント dual-path 整理
• adapter.js/sb3.js/comment.js のコメント id 契約整合
• make-toolbox-xml.js のカテゴリ名 %{BKY_...}→ScratchMsgs.translate（cosmetic）
• scratch-blocks-auto-style-patch.js / v2-bridge band-aid の除去可否検証と削除

[takaokouji]

完了 → close

pre-spork 巻き戻し (#270) の取り残しを upstream v13.7.2 / scratch-blocks v2.1.19 へ再整合する一連の作業が develop に取り込まれました（#755 merge commit 675a5d90d7、CI 9/9 green）。

develop に入った内容

PR	内容
#751	Step 1: colour→style / shape_hat / monitor_block / setBlockStyle 復元 + develop-trap ガード + doc 整理
#753	Step 2: コメントイベント modern 化 + ${block.id}_comment 契約
#754	Step 3: band-aid auto-style-patch.js 撤去
#756	mesh 回帰スクリプト headless 化 + tools/playwright-verify を rules に明記
#757	#752 remainder: runtime EXTENSION_DATA_LOADING/BEFORE_STEP 整合 + 残差分の再分類
#755	topic → develop 取り込み

達成事項

• 拡張機能の HAT/EVENT ブロックが modern Blockly で帽子型に描画される（本 Issue の出発点となった不具合を根本解決）。色・モニタチェックボックスも style 名前付きスタイル経由で正常
• 将来の誤ベース化を防ぐ恒久ガード: .claude/rules/upstream-tracking.md（baseline = v13.7.2 / scratch-blocks v2.1.19 + develop-trap）、.upstream-merge-history.json の postMergeReverts、upstream-merge skill / bin/upstream-divergence-audit に反映
• 検証: 全 PR CI green + ホスト Chrome 実機（hat/色/monitor/screenshot/palette/zoom/定義モーダル/コメント往復/Ruby コメント/mesh shadow ドロップダウン）+ mesh 回帰（unit 391 / integration 34 / mesh-v2-classroom-binding.mjs 全 pass）

残差分は「意図的」と確定（#752 で close 済み）

v2-bridge guard（scratch-blocks#3460 / forceRerender フリーズ対策）は 正当な v2.1.19 互換修正、make-toolbox %{BKY_CATEGORY_*} は benign、BEFORE_STEP は Mesh 依存 → いずれも維持・記録済み。lost-fix ではない。

関連

• 元不具合: fix: downgrade scratch-blocks from v2.0.3 to v1.3.0 to restore custom block argument dragging #270 / upstream 修正: #3450 / 暫定対応 superseded: fix(scratch-vm): 拡張機能の HAT/EVENT ブロックを modern Blockly で帽子型に描画 #748
• 実装: fix: re-align pre-spork-reverted files to upstream v13.7.2 (#749) #751 fix(scratch-vm): re-align comment handling to upstream v13.7.2 (Step 2, #752) #753 refactor(scratch-gui): retire auto-style-patch band-aid (Step 3, #752) #754 chore(test): headless-capable mesh verify script + document playwright-verify in rules #756 chore(upstream): finish #752 — runtime alignment + reclassify v2-bridge guards as legitimate (not band-aids) #757 / 取り込み: fix: re-align pre-spork files to upstream v13.7.2 — extension hat shape + comments + band-aid cleanup (#749) #755 / 残債追跡（close 済み）: chore(upstream): pre-spork 再整合の残債を v13.7.2 へ追従する (follow-up of #749/#751) #752
• 監査ドキュメント（git 管理外）: notes/upstream-tracking/、forward-looking: .claude/rules/upstream-tracking.md

→ 完了。close。