@mawaru/sdk 0.37.0 → 0.38.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mawaru/sdk",
-  "version": "0.37.0",
+  "version": "0.38.0",
   "description": "mawaru 実行 repo の開発 SDK。契約スキーマ（config.json 規約・ループ graph API）の正 ＋ typegen / validate CLI",
   "type": "module",
   "bin": {

package/skills/create-loop/SKILL.md

@@ -59,7 +59,7 @@ secret）でも、**足りない値を推測・生成・空文字で代用しな
 
 疎通確認のあと `GET {MAWARU_API_URL}/tenants/{MAWARU_TENANT_ID}/openapi.json`
 （ヘッダ `x-api-key: $MAWARU_API_KEY`）を取得すると、機械 API 面
-（loops の一覧・作成・詳細・graph PUT、runs/start、runs/{runId}/cancel、runs/{runId}/complete、members、api-keys、steps の end / decision）の
+（loops の一覧・作成・詳細・graph PUT・versions/publish、runs/start、runs/{runId} の参照・cancel・complete、members、api-keys、steps の end / decision）の
 パス・メソッド・リクエストボディ（Zod 由来の JSON Schema）が載っている。ここが常に正。
 段階導入中で未掲載のエンドポイントもある（その場合だけ `api/index.ts` 相当を辿る）。
 
@@ -73,7 +73,15 @@ repo との矛盾・使用中ノードの削除は 409。**graph PUT は冪等
 
 ## 手順
 
-1. **設計**：要件から必要なノード（program / ai / human / wait / join）と流れを決め、ユーザーに一言で確認する。
+ループは次の4段階で作る。**言われなくても必ず 1 のスケルトンから始め、段階を飛ばさない。**
+graph の保存（`PUT loops/{loopId}/graph`）は常に下書き（draft）に入り、4 で publish するまで
+本番の run には使われない。
+
+### 1. スケルトンを作って合意する
+
+ノードの配置と接続だけを下書きに保存する。中身（repo のプログラム・prompt）はまだ作らない。
+
+1. **設計**：要件から必要なノード（program / ai / human / wait / join）と流れを決める。
    1つの出口から複数の線を引くと枝が並行に走る（fan-out）。枝の結果を待ち合わせるときは
    合流（`join`）を置く：線のつながった入口が全部揃うまで待ち、`{ [入口の key]: 値 }` にまとめて
    `main` から流す。並行した枝を合流させずに同じノード（待機など）へ戻すと、枝の数だけ走り続ける。
@@ -83,26 +91,56 @@ repo との矛盾・使用中ノードの削除は 409。**graph PUT は冪等
    （`component.component_loop_id`＝作った for）を置く。配置ノードの in / out は中身の型の配列に
    自動で焼き込まれ、全件そろうと入力と同じ順の配列で `main` から流れる（1件ずつは同時に走る）。
    中身の出口（end につないだ in）は1つにする。
-2. **repo 側の準備**：足りない program / ai は `nodes/program/<dir>/` / `nodes/ai/<dir>/` に作る
-   （config.json → `npx mawaru typegen` → main.ts 実装 → `npx mawaru validate`）。
-   **AI ノードの決定論的な処理は prompt ではなく `setup.sh` に書く**（下記）。
-   **作った・変えたものは GitHub へ push してから次へ進む**（mawaru は repo を GitHub 経由で
-   読むため、未 push だと graph 保存の検証・書き戻しと食い違って 409 になる）。
-3. **ループ作成**：`POST loops`。
-4. **graph ボディを組む**：
+2. **ループ作成**：`POST loops`（既存ループの更新なら不要）。
+3. **graph ボディを組む**（中身は空のまま）：
    - node / port の `id` はクライアント採番（`uuidgen` などで UUID を作る）
-   - program / ai ノードの ports は repo の config.json の inputs / outputs をそのまま写す
-     （in ポート key は `in`、out ポートは outputs の各 key）
-   - kind 別の固定ポート構成（human / wait / ai / join）は `port-spec.ts` の `kindPortsViolation` に従う。
-     join は in を枝の数だけ（key 自由。例 `in_1`, `in_2`）＋ out `main`。出口の型は自動で決まる
+   - program / ai ノードには `program` / `ai`（dir の指定）を付けない。dir 未設定のノードは
+     repo へ書き戻されないので、repo 側に何も無くても保存できる
+   - ポートは kind 別の固定構成（`port-spec.ts` の `kindPortsViolation`）と分岐する出口の key だけ
+     決め、`schema` は `{}`（未宣言）でよい。型は 2 で config.json と一緒に決める。
+     program の in は `in`。join は in を枝の数だけ（key 自由。例 `in_1`, `in_2`）＋ out `main`
+   - human は担当（`human.assignment.units`）が保存に必須なので、誰が承認するかもここで決める
    - ループ変数（refs＝run 全体で読める key→値 の袋）が要るならトップレベルの `refs` に入れる。
      ノード単位の宣言やバインドは無い。handler は実行時に `refs.json` で全量を受け取り、
      `end` の `refs` パッチで値を更新できる（config.json の `refs` はループ定義からの転写＝生成物）。
      キー `input` は予約（run の起動入力が自動で入る。定義に置くと 422）
    - `position_x` / `position_y` は左→右に流れる単純配置（例: x を 320 刻み、y は 240）
-5. **保存**：`PUT loops/{loopId}/graph`。400 / 422 / 409 ならメッセージを読んで直して再送。
-6. **報告**：エディタ URL `{MAWARU_APP_URL}/loops/{loopId}/edit` をユーザーに渡し、
-   見た目の確認と run はユーザーに委ねる。
+4. **保存**：`PUT loops/{loopId}/graph`。400 / 422 / 409 ならメッセージを読んで直して再送。
+5. **合意**：エディタ URL `{MAWARU_APP_URL}/loops/{loopId}/edit` をユーザーに渡し、ノードの並びと
+   つながりを見てもらう。**OK をもらうまで 2 へ進まない**（直しの依頼は graph を直して保存し、
+   もう一度見てもらう）。
+
+### 2. 各ノードの中身を実装し、1つずつ確かめる
+
+上流のノードから順に、1つずつ次を繰り返す：
+
+1. **repo 側の実装**：`nodes/program/<dir>/` / `nodes/ai/<dir>/` を作る
+   （config.json → `npx mawaru typegen` → main.ts 実装 → `npx mawaru validate`）。
+   config.json の inputs / outputs はスケルトンのポートの key に合わせ、ここで型を決める。
+   **AI ノードの決定論的な処理は prompt ではなく `setup.sh` に書く**（下記）。
+   **GitHub へ push してから次へ進む**（mawaru は repo を GitHub 経由で読むため、未 push だと
+   graph 保存の書き戻しと食い違って 409 になり、テスト実行も古い中身で走る）。
+2. **ノードに結びつける**：graph の該当ノードに `program.program_dir` / `ai.ai_dir` を設定し、
+   ports を config.json の inputs / outputs の写しにして保存する（in ポート key は `in`、
+   out ポートは outputs の各 key）。human は承認ビュー、wait は待ち方もここで設定する。
+3. **単体で確かめる**：そのノードだけをテスト実行する。`POST runs/start` に `kind: "test"`・
+   `test_scope: "only"`・`start_node_id`（そのノード）・`payload`（サンプル入力。上流を確かめ済みなら
+   その output を使う）・`start_by`（ユーザーの user_id。`GET members` で引く。API キー起動では必須）を
+   渡し、`GET runs/{runId}` で step の status と output を見る。下書きの program / ai は
+   ブランチ先頭の commit で走る。失敗したら直して push し、もう一度実行する。
+   human はテスト実行の担当が起動者になるので、承認・差し戻しはユーザーに操作してもらう。
+
+### 3. 全体を通して確かめる
+
+開始ノード（kind `start`）を `start_node_id` に、`test_scope: "from"` でテスト実行し、end まで
+流れることを確かめる（分岐があれば主な道を一通り）。human を通る道はユーザーに操作してもらう。
+結果をユーザーに報告する。
+
+### 4. publish して起動する
+
+ユーザーの OK をもらってから `POST loops/{loopId}/versions/publish` で下書きを公開する
+（AI / Program の実行 commit はここで固定される）。続けて `POST runs/start`（`loop_id`・`payload`。
+`kind` を省くと本番 run）で起動し、run の URL `{MAWARU_APP_URL}/runs/{runId}` をユーザーに渡す。
 
 ## AI ノード：出力は短く（既定）