docs: update README and related documentation for new features and improvements

- Added a link to the development notes in the README.
- Updated the status of LLVM IR generation for various blocks in the README and architecture documentation.
- Enhanced the description of supported opcodes and their implementation status in the blocks documentation.
- Revised the CLI documentation to reflect changes in supported commands and their expected behavior.
- Created a new development notes document to guide contributors on setup, editing, and documentation updates.
- Clarified the current limitations and expected future implementations in the architecture and development documentation.

Author: Kicky1618

README.md

@@ -48,14 +48,14 @@
 | `project.json` を取り出して表示する | `json` | ✅ |
 | ブロック数・使用 opcode を確認する | `stats` | ✅ |
 | hat block からスレッドを抽出する | `run` | ✅ |
-| 動き系命令、見た目の大きさ変更系命令、変数代入、それらの入力式に使われる演算子や変数参照を LLVM IR へ変換し、JIT で実行する | `run` | 🚧 一部 |
+| 動き系命令の一部、見た目の say/think と大きさ変更、変数代入と加算、制御の repeat/forever/if/ifelse/wait until、それらの入力式に使われる演算子や変数参照を LLVM IR へ変換し、JIT で実行する | `run` | 🚧 一部 |
 | 生成した LLVM IR を `.ll` ファイルへ保存する | `compile` | ✅ |
 | JSON パースエラー時の位置情報・コンテキスト表示 | — | ✅ |
 | 完全な Scratch 互換実行 | — | ❌ |
 
 ## まだ開発途中のこと
 
-- Scratch opcode の網羅的な IR 実装（現状はスレッド本体が動き系、見た目の大きさ変更系、変数代入、タイマーリセットのみ。動き系は `motion_movesteps` を含めて実装済み。式はリテラル、演算子、変数参照、見た目の大きさレポーター、タイマーレポーターのみ）
+- Scratch opcode の網羅的な IR 実装（現状はスレッド本体が動き系の一部、見た目の say/think と大きさ変更、変数代入と加算、制御の repeat/forever/if/ifelse/wait until、タイマーリセットのみ。動き系は `motion_movesteps` を含めて実装済み。式はリテラル、演算子、変数参照、見た目の大きさレポーター、タイマーレポーターのみ）
 - Scratch VM 相当のイベントランタイムの完成
 - 生成した IR から実行可能ファイルへつなぐフロー
 - 互換性検証とリグレッションテストの拡充
@@ -142,7 +142,7 @@ cargo run -- json my_project.sb3 | jq '[.targets[].blocks[].opcode] | unique | s
 cargo run -- run <path-to-project.sb3>
 ```
 
-`run` は現状もっとも実験的なコマンドです。文ブロックは動き系、見た目の大きさ変更系、変数代入、タイマーリセット、入力式はリテラル・演算子・変数参照・大きさレポーター・タイマーレポーターのみを含むシンプルなプロジェクトから試すことを推奨します。動き系では `motion_movesteps` も実装済みです。成功時は各スレッドの状態が実行中に定期的に標準出力へ表示されます。
+`run` は現状もっとも実験的なコマンドです。文ブロックは動き系の一部、見た目の say/think と大きさ変更、変数代入と加算、制御の repeat/forever/if/ifelse/wait until、タイマーリセット、入力式はリテラル・演算子・変数参照・大きさレポーター・タイマーレポーターのみを含むシンプルなプロジェクトから試すことを推奨します。動き系では `motion_movesteps` も実装済みです。成功時は各スレッドの状態が実行中に定期的に標準出力へ表示されます。
 
 ```text
 SpriteStruct { sprite_x: 100.0, sprite_y: 0.0, sprite_rotate: 90.0, sprite_size: 100.0, ... }
@@ -164,7 +164,7 @@ cargo run -- compile <path-to-project.sb3>
 
 ## 入力ファイルについて
 
-このリポジトリには現在、配布用の `.sb3` サンプルは含まれていません。Scratch エディタでプロジェクトを作成し、**「ファイル」→「コンピューターに保存する」** で `.sb3` を書き出して入力に使ってください。
+このリポジトリには動作確認用の `examples/script.sb3` が含まれています。まずはこのファイルで `stats` や `json` を試せます。追加の入力を用意したい場合は、Scratch エディタでプロジェクトを作成し、**「ファイル」→「コンピューターに保存する」** で `.sb3` を書き出してください。
 
 `run` で最後まで通したい場合は、文ブロックを動き系（「〇歩動かす」「x座標を〇にする」など）、見た目の大きさ変更系（「大きさを〇ずつ変える」「大きさを〇%にする」）、変数代入、タイマーリセットに絞り、その入力式にリテラル・演算子・変数参照・大きさレポーター・タイマーレポーターだけを使ったシンプルなプロジェクトから始めると確認しやすいです。
 
@@ -179,7 +179,7 @@ xyo-rust/
 │   ├── types/           Scratch JSON 構造を受ける型定義
 │   ├── parser/          Scratch ブロック列を Stmt / Expr に変換
 │   └── compiler/        LLVM IR 生成
-├── tests/               CLI テスト
+├── examples/            動作確認用の .sb3 サンプル
 ├── bitcodes/            C ソースと生成済み bitcode / IR
 ├── docs/                Markdown ソースと Taiga サイト生成ファイル
 ├── build.rs             ビルドスクリプト (C → bitcode)
@@ -228,6 +228,7 @@ CLANGXX=clang++-23 \
 | [CLI](./docs/markdown/cli.md) | サブコマンドの詳細・出力例・エラーの読み方 |
 | [対応ブロック一覧](./docs/markdown/blocks.md) | opcode ごとのパーサー / IR 対応状況 |
 | [アーキテクチャ](./docs/markdown/architecture.md) | パイプラインの詳細・モジュール設計 |
+| [開発メモ](./docs/markdown/development.md) | 開発時の確認手順・生成物・ドキュメント更新方針 |
 
 ## Star History
 

docs/markdown/README.md

@@ -17,6 +17,7 @@ Scratch の `.sb3` プロジェクトを読み込み、解析し、LLVM IR を
 - [CLI](./cli.md)
 - [対応ブロック一覧](./blocks.md)
 - [アーキテクチャ](./architecture.md)
+- [開発メモ](./development.md)
 
 ## Scratch と `.sb3` について
 
@@ -67,7 +68,7 @@ Scratch プロジェクトは `.sb3` という拡張子で保存されます。`
 | 2 | `project.json` を Scratch プロジェクト構造へ変換する | ✅ 完成 |
 | 3 | hat block からスレッドを解析する | ✅ 完成 |
 | 4 | `Stmt` / `Expr` に変換する（パーサー） | ✅ ほぼ完成（87 opcode） |
-| 5 | 一部の式 / 文を LLVM IR へ変換し、JIT で実行する | 🚧 一部実装（文は動き系、見た目の大きさ変更系、変数代入、タイマーリセット。動き系は `motion_movesteps` を含めて実装済み。式はリテラル + 演算子 + 変数参照 + 見た目の大きさレポーター + タイマーレポーター） |
+| 5 | 一部の式 / 文を LLVM IR へ変換し、JIT で実行する | 🚧 一部実装（文は動き系の一部、見た目の say/think と大きさ変更、変数代入と加算、制御の repeat/forever/if/ifelse/wait until、タイマーリセット。動き系は `motion_movesteps` を含めて実装済み。式はリテラル + 演算子 + 変数参照 + 見た目の大きさレポーター + タイマーレポーター） |
 | 6 | 生成した IR から実行可能ファイルを作る | ❌ 未実装 |
 
 ```warn
@@ -115,18 +116,18 @@ IR 生成（src/compiler/）
 | コマンドの使い方を知りたい | [CLI](./cli.md) |
 | 対応済み opcode を確認したい | [対応ブロック一覧](./blocks.md) |
 | 内部構造を把握したい | [アーキテクチャ](./architecture.md) |
-| コントリビュートしたい | [アーキテクチャ](./architecture.md) → [対応ブロック一覧](./blocks.md) |
+| コントリビュートしたい | [開発メモ](./development.md) → [アーキテクチャ](./architecture.md) → [対応ブロック一覧](./blocks.md) |
 
 ## 現時点での注意点
 
 - Scratch VM との完全互換は未実装です
 - LLVM 21.1.x 系を前提にしています（他のバージョンではビルドが失敗します）
-- 配布用の `.sb3` サンプルは同梱されていません。Scratch エディタからエクスポートしてください
-- `run` サブコマンドは実験的で、スレッド本体は動き系文ブロック、見た目の大きさ変更系、変数代入、タイマーリセットのみ、入力式はリテラル、演算子、変数参照、見た目の大きさレポーター、タイマーレポーターのみ対応しています。動き系では `motion_movesteps` も実装済みです
+- 動作確認用の `.sb3` サンプルとして `examples/script.sb3` を同梱しています。追加の検証には Scratch エディタからエクスポートした `.sb3` を使ってください
+- `run` サブコマンドは実験的で、スレッド本体は動き系の一部、見た目の say/think と大きさ変更、変数代入と加算、制御の repeat/forever/if/ifelse/wait until、タイマーリセットのみ、入力式はリテラル、演算子、変数参照、見た目の大きさレポーター、タイマーレポーターのみ対応しています。動き系では `motion_movesteps` も実装済みです
 
 ## 関連リンク
 
-- [リポジトリの README](../README.md)
+- [リポジトリの README](../../README.md)
 - [GitHub](https://github.com/pnsk-lab/xyo-rust)
 - [Scratch 公式サイト](https://scratch.mit.edu/)
 - [LLVM 公式サイト](https://llvm.org/)

docs/markdown/architecture.md

@@ -439,6 +439,8 @@ for stmt in &thread.stmts {
         Stmt::Motion(v) => parse_motion_stmt(builders, v, &function, thread.target_idx),
         Stmt::Looks(v) => parse_looks_stmt(builders, v, &function, thread.target_idx),
         Stmt::DataStmt(v) => parse_data_stmt(builders, v, &function, thread.target_idx),
+        Stmt::Control(v) => parse_control_stmt(builders, v, &function, thread.target_idx),
+        Stmt::Sensing(v) => parse_sensing_stmt(builders, v, &function, thread.target_idx),
         _ => todo!("やります"),  // 未実装
     }
 }
@@ -448,7 +450,7 @@ builder.build_return(None);  // void return
 
 ### 実行状態
 
-各スレッドは `SpriteStruct` の状態ポインタを受け取り、`MotionSetX` や `LooksSetSizeTo` などは `build_struct_gep` を使ってそのフィールドを更新します。大きさ変更系の Looks ブロックは、現在コスチュームの幅・高さから Scratch と同じ最小・最大スケールを計算し、`fmin` / `fmax` で丸めた値を `sprite_size` に保存します。`DataSetVariableTo` は対象変数 ID を解決し、入力値を `DynamicStruct` へ変換してグローバル変数スロットへ保存します。JIT 実行時にも同じ `SpriteStruct` が `Debug` 形式で表示されます。
+各スレッドは `SpriteStruct` の状態ポインタを受け取り、`MotionSetX` や `LooksSetSizeTo` などは `build_struct_gep` を使ってそのフィールドを更新します。大きさ変更系の Looks ブロックは、現在コスチュームの幅・高さから Scratch と同じ最小・最大スケールを計算し、`fmin` / `fmax` で丸めた値を `sprite_size` に保存します。`LooksSay` / `LooksThink` は `print` ヘルパーに文字列を渡し、`DataSetVariableTo` と `DataChangeVariableBy` は対象変数 ID を解決してグローバル変数スロットへ反映します。`ControlRepeat` / `ControlForever` / `ControlIf` / `ControlIfElse` / `ControlWaitUntil` は、サブスタックを別関数として呼び出すか、`wait_tick` を挟むループに変換されます。JIT 実行時にも同じ `SpriteStruct` が `Debug` 形式で表示されます。
 
 ### 式の IR 変換
 
@@ -507,17 +509,19 @@ IR 生成後、`default<O3>` パスが適用されます。有効化されてい
 
 ### 現在の制約
 
-- **IR 生成**: スレッド本体は動き系命令、見た目の大きさ変更系、変数代入、タイマーリセットのみ。式はリテラル、演算子、変数参照、見た目の大きさレポーター、タイマーレポーターが中心。`run` で残りの文 opcode や未実装式に当たると `todo!()` パニックが起きる
+- **IR 生成**: スレッド本体は動き系の一部、見た目の say/think と大きさ変更、変数代入と加算、制御の repeat/forever/if/ifelse/wait until、タイマーリセットのみ。式はリテラル、演算子、変数参照、見た目の大きさレポーター、タイマーレポーターが中心。`run` で残りの文 opcode や未実装式に当たると `todo!()` パニックが起きる
 - **ランタイム**: Scratch のイベントループや broadcast / clone を含む完全な VM は未実装。いまの `run` は JIT で各 thread を実行し、状態を標準出力へ定期的に返す
 - **コスチューム・サウンド**: コスチューム寸法は大きさの丸めに使うが、コスチューム切り替えやサウンド再生の IR 生成は未対応
 - **スレッド間通信**: ブロードキャスト・メッセージ処理は未実装
 
 ### 今後の実装が期待される部分
 
-- `ControlStmt` (if/else, repeat, forever など) の IR 生成
-- `DataStmt` (変数加算、モニター表示、リスト操作) の IR 生成
-- `LooksStmt` (大きさ以外の見た目変更) の IR 生成（実際のレンダリングは別ライブラリが必要）
+- `ControlStmt` の残り分岐（wait, repeat until, while, clone, stop, counter など）の IR 生成
+- `DataExpr` / `DataStmt` のリスト系 IR 生成
+- `LooksStmt` の残り分岐（say/think 以外の見た目変更）の IR 生成（実際のレンダリングは別ライブラリが必要）
 - `run` の未実装分岐に対する安全なフォールバック（パニックを避けてエラー報告する）
 - 生成した IR を `clang` や `llc` でリンク・コンパイルするフロー
 
 前のページ: [CLI](./cli.md)
+
+次のページ: [開発メモ](./development.md)