feat: initial public release (MAESTRO)

2026-06-03 05:08:00 +00:00
commit f5c7666f6b
823 changed files with 184150 additions and 0 deletions
@@ -0,0 +1,42 @@
+# チェックリスト系ツール（CreateChecklist / CheckItem / GetChecklist）
+
+複数アイテム（ファイル、ページ、URL等）を順次処理するときの進捗管理に使う。
+**「1件処理→即CheckItem」のループを厳守すること。**
+
+## 基本ワークフロー
+
+```
+1. CreateChecklist({ name: "ocr-pages", items: ["page-001.png", "page-002.png", ...] })
+2. for each item:
+     a. アイテムを1件処理する（OCR、ダウンロード、加工など）
+     b. CheckItem({ name: "ocr-pages", item: "page-001.png", status: "done" }) を即呼ぶ
+     c. 次のアイテムに進む
+3. GetChecklist({ name: "ocr-pages" }) で漏れがないか確認
+```
+
+## ステータス
+
+- `done` — 正常完了
+- `failed` — 処理失敗（後で再試行・スキップ判断）
+- `skipped` — 意図的にスキップ（理由を summary に書く）
+
+## 厳禁パターン
+
+❌ **複数アイテムをまとめて処理してから後でまとめて CheckItem を呼ぶ**
+- 途中でクラッシュ・中断したときに進捗が失われる
+- アイテム順がブレる
+- レビュー時に作業順序が追えない
+
+✅ **1件処理 → 即 CheckItem → 次のアイテム** を1件ずつ繰り返す
+
+## ファイルの保存場所
+
+`logs/checklists/{name}.json` に保存される。再開時に GetChecklist で前回の状態を取り出せる。
+
+## いつ使うべきか
+
+- 同種のアイテムを 3 件以上順次処理するとき
+- 処理が長時間にわたり、中断・再開がありえるとき
+- 後で何が処理済み／失敗かを振り返る必要があるとき
+
+逆に、1〜2件しかない・1ステップで終わる処理には不要。