| 2026-03-03 | 運用単位を workflow package（flow + schedules）へ変更し、実装計画とRunbookを更新 |

| 2026-03-03 | `delete -> create` と hash 管理の運用ガード（preflight / fail closed / post-verify）およびCRLF対策を追記 |

docs/flow-manage/10_マスタードキュメント_Windmillフロー管理_API一本化編.md

@@ -42,9 +42,10 @@
 1. ローカルリポジトリは、サーバー側Gitをリモートにしない
 2. Windmillの実体変更は **Windmill REST API 経由のみ**
 3. 作業開始時にAPIでサーバー状態を取り込み、サーバーが新しければローカルへ同期
-4. ローカル変更はAPIでサーバーへ反映
-5. サーバー側の Git Sync Workflow は定期記録用途として継続
-6. ローカルGitコミットは手動（またはAI）で実施し、監査/履歴用途として扱う
+4. **運用単位は「workflow package（flow + schedules）」を基本**とする
+5. ローカル変更はAPIでサーバーへ反映
+6. サーバー側の Git Sync Workflow は定期記録用途として継続
+7. ローカルGitコミットは手動（またはAI）で実施し、監査/履歴用途として扱う
 
 ---
 
@@ -78,6 +79,13 @@
 - ローカルファイルは「編集用ワークツリー + 監査ログ」
 - ローカルGitはサーバー同期の必須経路ではない
 
+### 管理単位（重要）
+
+- 単体オブジェクト運用（scriptだけ、flowだけ）は補助用途
+- 標準運用は **workflow package 単位** とする
+  - `flow` 本体
+  - その `flow path` に紐づく `schedules`（`is_flow=true` かつ `script_path == flow.path`）
+
 ### 既存の主要オブジェクト（例）
 
 - script: `u/admin/alexa_speak`
@@ -98,11 +106,18 @@
 - サーバー `updated_at` / `hash` とローカル管理メタ情報を比較
 - サーバーが新しければローカルを更新
 
-### 対象API
+### 対象API（オブジェクト単体）
 
 - `GET /api/w/{workspace}/scripts/get/p/{path}`
 - `GET /api/w/{workspace}/flows/get/{path}`
-- `GET /api/w/{workspace}/schedules/get/{path}`（必要時）
+- `GET /api/w/{workspace}/schedules/get/{path}`
+
+### workflow package Pull（標準）
+
+1. `GET /flows/get/{flow_path}` で flow 本体取得
+2. `GET /schedules/list` で schedule 一覧取得
+3. `script_path == flow_path` の schedule 群を抽出
+4. ローカルへ一括保存（flow + schedules）
 
 ## 5.2 Push（ローカル -> サーバー）
 
@@ -132,6 +147,14 @@
   1. `DELETE /flows/delete/{path}`
   2. `POST /flows/create`
 
+### schedule反映API（workflow package の一部）
+
+- workflow package Push時は、対象 flow に紐づく schedule も同時同期する
+- 原則:
+  1. サーバー現行 schedule（`script_path == flow_path`）一覧取得
+  2. ローカル定義との差分計算（追加・更新・削除）
+  3. `DELETE /schedules/delete/{path}` と `POST /schedules/create` で収束
+
 ---
 
 ## 6. 競合時の動作仕様
@@ -148,6 +171,15 @@
 
 - 削除再作成前に最新を必ずPullしてローカル保存
 - 競合が疑われる場合は自動実行せず手動確認にフォールバック
+- **Preflight必須**: Push直前に `remote_index` の既知hashとサーバー現在hashを比較し、不一致ならPush中断（fail closed）
+- Push後は `post-verify`（再取得して期待JSON一致確認）を必須化
+
+### schedulePush競合
+
+- `schedule.path` 重複や同名上書きに注意
+- workflow package Push時は、対象 flow の schedule 群をまとめて同期し、中途半端な状態を残さない
+- 失敗時は flow と schedules の両方を再取得して整合を確認
+- schedule 同期も Preflight/`post-verify` の対象に含める
 
 ---
 
@@ -157,7 +189,7 @@
 
 - 本ドキュメント作成
 
-## Phase 1: API運用コマンド整備（次タスク）
+## Phase 1: API運用コマンド整備（完了）
 
 `wm-api.sh` へ追加:
 
@@ -168,17 +200,26 @@
 5. `pull-all`（scripts/flowsの一覧取得 + 一括保存）
 6. `status-remote`（ローカルとサーバーのhash比較）
 
-## Phase 2: メタ情報管理
+## Phase 2: workflow package 対応（次タスク）
 
-- `state/remote_index.json` を導入し、`path -> hash/updated_at` を保持
-- Pull前後で差分判定可能にする
+`wm-api.sh` へ追加:
 
-## Phase 3: 標準化
+1. `pull-workflow <flow_path>`（flow + schedules 一括取得）
+2. `push-workflow <workflow-dir>`（flow反映 + schedules差分同期）
+3. `status-workflow [flow_path]`（workflow単位の差分表示）
+4. `pull-all-workflows`（flow全件を workflow package で取得）
+
+## Phase 3: メタ情報管理
+
+- `state/remote_index.json` を拡張し、`scripts/flows/schedules` を保持
+- `state/workflow_index.json` を導入し、`workflow -> flow_hash + schedule_hashes` を保持
+
+## Phase 4: 標準化
 
 - `docs/flow-manage` に操作例を固定
 - 「作業開始時は必ずpull」を運用ルール化
 
-## Phase 4: 半自動化（任意）
+## Phase 5: 半自動化（任意）
 
 - AI/スクリプトで
   - 変更検知
@@ -193,14 +234,16 @@
 
 1. `pull-all` でサーバー最新を取得
 2. ローカル編集
-3. `push-script` / `push-flow` で反映
-4. 必要に応じてローカルGitにコミット
+3. workflow修正時は `push-workflow` で反映（flow + schedules）
+4. script単体修正時のみ `push-script` を使う
+5. 必要に応じてローカルGitにコミット
 
 ### 8.2 サーバーで変更されたものを取り込む
 
 1. `status-remote` 実行
-2. サーバー新規/更新分を `pull-*` で取得
-3. ローカル履歴としてコミット（任意）
+2. workflow単位の変更は `status-workflow` / `pull-workflow` で取得
+3. 単体変更は `pull-*` で取得
+4. ローカル履歴としてコミット（任意）
 
 ### 8.3 `alexa_speak` 更新例（現在の具体例）
 
@@ -228,7 +271,8 @@
 
 1. Push前に対象オブジェクトをバックアップ保存（必須）
 2. Push後に `post-verify`（再取得して期待値比較）を必須化
-3. 失敗時は「再実行」ではなく「現状確認 -> 復旧」の順で実施
+3. Push直前に `preflight hash check` を必須化し、不一致時はPush停止（fail closed）
+4. 失敗時は「再実行」ではなく「現状確認 -> 復旧」の順で実施
 
 ### 10.2 標準復旧手順
 
@@ -246,6 +290,13 @@
 2. 依存スケジュールの有効性を確認
 3. 関連ジョブの手動実行で動作確認
 
+### 10.4 delete -> create 運用ガード（必須）
+
+1. `push-flow` / `push-workflow` 前に対象flowのバックアップJSONを必ず保存
+2. Preflightで hash 不一致なら自動Pushしない（手動レビューへフォールバック）
+3. Push後に flow と schedules を再取得し、ローカル期待値と一致確認
+4. 不一致時は即時にバックアップから復元し、復旧ログを残す
+
 ---
 
 ## 11. Windmill依存を薄くする方針（必須）
@@ -256,7 +307,7 @@ Windmill API依存は避けられないため、依存点を最小化する。
 
 - `scripts`: `list/get/create`
 - `flows`: `list/get/create/delete`
-- `schedules`: `list/get/create/delete`（必要時）
+- `schedules`: `list/get/create/delete`（workflow package 同期で常用）
 
 上記以外のAPIは原則使わない。
 
@@ -278,18 +329,20 @@ Windmill API依存は避けられないため、依存点を最小化する。
 
 以下を満たせば「このプロジェクトはサーバーのワークフローを管理するためのもの」と言える状態:
 
-1. ローカルから scripts/flows の Pull/Push がAPIで完結
-2. サーバー更新がローカルで検知できる（hash比較）
-3. 競合時の復旧手順が定義済み
+1. ローカルから workflow package（flow + schedules）の Pull/Push がAPIで完結
+2. サーバー更新が workflow 単位でローカル検知できる
+3. 競合時の復旧手順が flow/schedule 両方で定義済み
 4. 運用手順がこの文書だけで再現可能
 
 ---
 
 ## 13. 既知の注意点
 
-1. `wm-api.sh` は現状 `bash` 前提だが、Windowsで改行がCRLFだと shebang 実行失敗する場合がある
+1. `wm-api.sh` は `bash` 前提。WindowsのCRLF混入で shebang 実行失敗し得るため、`.gitattributes` で `*.sh text eol=lf` を固定し、実行は `bash wm-api.sh ...` を標準とする
 2. フロー更新は環境により `PUT` できないため削除再作成を標準とする
-3. API応答仕様はWindmillバージョン差で微差が出るため、初回導入時は `get` のレスポンス形を確認する
+3. 削除再作成は `version_id/hash/edited_at` を更新するため、Preflight hash check がないと競合上書きを見落とす可能性がある
+4. 1つのflowに複数scheduleが紐づくことがあるため、`script_path` ベースで束ねて管理する
+5. API応答仕様はWindmillバージョン差で微差が出るため、初回導入時は `get` のレスポンス形を確認する
 
 ---
 
@@ -299,3 +352,5 @@ Windmill API依存は避けられないため、依存点を最小化する。
 |------|----------|
 | 2026-03-03 | 初版作成（API一本化方針、同期仕様、実装計画、Runbookを定義） |
 | 2026-03-03 | 障害前提の復旧設計、Windmill依存を薄くする方針を必須要件として追記 |
+| 2026-03-03 | 運用単位を workflow package（flow + schedules）へ変更し、実装計画とRunbookを更新 |
+| 2026-03-03 | `delete -> create` と hash 管理の運用ガード（preflight / fail closed / post-verify）およびCRLF対策を追記 |