@mawaru/sdk 0.8.0 → 0.11.0

package/_schemas/ai-manifest.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, it } from "vitest"
-import { aiManifestSchema } from "./ai-manifest.js"
+import { AI_MODELS, aiManifestSchema } from "./ai-manifest.js"
 import { envelopeSchemaOf, instructionSchema } from "./port-spec.js"
 
 const envelope = envelopeSchemaOf({ type: "string" })
@@ -32,11 +32,18 @@ describe("aiManifestSchema", () => {
       outputs: { main: envelope },
     })
     expect(manifest.name).toBeUndefined()
-    expect(manifest.model).toBe("claude-opus-4-8")
+    expect(manifest.model).toBe("claude-opus-5")
     expect(manifest.skills).toEqual([])
     expect(manifest.env).toEqual([])
   })
 
+  it("model は AI_MODELS の enum（バージョン固定。外の値は拒否）", () => {
+    for (const model of AI_MODELS) {
+      expect(aiManifestSchema.parse({ ...valid, model }).model).toBe(model)
+    }
+    expect(() => aiManifestSchema.parse({ ...valid, model: "opus" })).toThrow()
+  })
+
   it("prompt は必須・非空（repo に置く時点で完成品）", () => {
     expect(() => aiManifestSchema.parse({ ...valid, prompt: "" })).toThrow()
     const { prompt: _prompt, ...rest } = valid

package/_schemas/ai-manifest.ts

@@ -2,15 +2,18 @@ import { z } from "zod"
 import { jsonSchemaSchema } from "./node.js"
 import { isAiEnvelopeSchema, manifestInKeysViolation } from "./port-spec.js"
 
-// AI ノードのモデル選択肢（既定は Opus：下書き品質が価値の中心。費用はユーザー持ち）
+// AI ノードのモデル選択肢（既定は Opus：下書き品質が価値の中心。費用はユーザー持ち）。
+// エイリアス（"opus" 等）は採らずバージョンを固定する：実行のたびに黙って別モデルへ
+// 乗り換わると品質も費用も再現しないため。新モデルが出たらこの配列を足して SDK を publish する
 export const AI_MODELS = [
+  "claude-opus-5",
   "claude-opus-4-8",
   "claude-sonnet-5",
   "claude-haiku-4-5",
 ] as const
 export const aiModelSchema = z.enum(AI_MODELS)
 export type AiModel = z.infer<typeof aiModelSchema>
-export const DEFAULT_AI_MODEL = "claude-opus-4-8" satisfies AiModel
+export const DEFAULT_AI_MODEL = "claude-opus-5" satisfies AiModel
 
 // nodes/ai/<dir>/config.json（実行repoの構造見直し）。AI ノードの定義（prompt/model/skills/
 // 入出力スキーマ/env）は repo 側が正で、エディタが取り込んで ports を自動生成する

package/_schemas/graph.test.ts

@@ -261,6 +261,37 @@ describe("humanConfigSchema", () => {
       humanConfigSchema.parse({ assignment: { units: [["not-a-uuid"]] } }),
     ).toThrow()
   })
+
+  it("run_starter：固定メンバーと混ぜて受け付ける（実行時に start_by で解決）", () => {
+    const u1 = uuid()
+    const parsed = humanConfigSchema.parse({
+      assignment: {
+        strategy: "fixed",
+        approval_mode: "all",
+        units: [["run_starter", u1]],
+      },
+    })
+    expect(parsed.assignment.units).toEqual([["run_starter", u1]])
+  })
+
+  it("run_starter：交代制（round_robin）との併用を拒否する", () => {
+    expect(() =>
+      humanConfigSchema.parse({
+        assignment: {
+          strategy: "round_robin",
+          units: [["run_starter"], [uuid()]],
+        },
+      }),
+    ).toThrow()
+  })
+
+  it("run_starter：ユニット内の重複を拒否する", () => {
+    expect(() =>
+      humanConfigSchema.parse({
+        assignment: { units: [["run_starter", "run_starter"]] },
+      }),
+    ).toThrow()
+  })
 })
 
 describe("saveGraphBodySchema", () => {

package/_schemas/graph.ts

@@ -130,9 +130,16 @@ export const aiConfigSchema = z.object({
 })
 export type AiConfig = z.infer<typeof aiConfigSchema>
 
+// 担当ユニットのメンバー：user_id の名指し、または動的な担当「ループを実行した人」
+// （run の起動者。実行時に runs.start_by で解決し、解決できなければその1人だけ落ちる。
+// docs/tasks/wip/Human担当に「ループを実行した人」を追加する.md）
+export const RUN_STARTER = "run_starter"
+export const assignMemberSchema = z.union([z.uuid(), z.literal(RUN_STARTER)])
+export type AssignMember = z.infer<typeof assignMemberSchema>
+
 // Human ノードの kind 別設定（node_humans ＋ node_human_assignees に対応）。
 // 担当 ＝ ユニット（1人以上のメンバー）の順序付きリスト ＋ 承認モード ＋ 選出戦略。
-// units[i] は user_id の配列（1人＝個人・複数＝グループ）。units 空 = tenant の誰でも。
+// units[i] はメンバーの配列（1人＝個人・複数＝グループ）。units 空 = tenant の誰でも。
 // approval_mode はノード単位（any=誰か1人 / all=全員。差し戻しは1人で成立＝veto）。
 // メンバーが tenant の membership であることの検証は保存 API 側で行う
 // （docs/tasks/backlog/Human担当者の高度化（複数人承認とラウンドロビン）.md）
@@ -147,7 +154,7 @@ export const humanConfigSchema = z.object({
     .object({
       strategy: z.enum(["fixed", "round_robin"]).default("fixed"),
       approval_mode: z.enum(["any", "all"]).default("any"),
-      units: z.array(z.array(z.uuid()).min(1)).default([]),
+      units: z.array(z.array(assignMemberSchema).min(1)).default([]),
     })
     .superRefine((assignment, ctx) => {
       if (assignment.strategy === "fixed" && assignment.units.length > 1) {
@@ -167,13 +174,25 @@ export const humanConfigSchema = z.object({
           message: "round_robin にはユニットが2つ以上必要です",
         })
       }
+      // 交代制と「ループを実行した人」は排他：どの回に誰が担当かが起動者と交代位置の
+      // 掛け算になって読めなくなるため、設定できる形の方を減らす
+      if (
+        assignment.strategy === "round_robin" &&
+        assignment.units.some((unit) => unit.includes(RUN_STARTER))
+      ) {
+        ctx.addIssue({
+          code: "custom",
+          path: ["units"],
+          message: "round_robin の担当に「ループを実行した人」は入れられません",
+        })
+      }
       // ユニット内の重複は拒否（またぐ重複は「Aは毎回・相手が交代」の形があるので許す）
       assignment.units.forEach((unit, i) => {
         if (new Set(unit).size !== unit.length) {
           ctx.addIssue({
             code: "custom",
             path: ["units", i],
-            message: "ユニット内で user_id が重複しています",
+            message: "ユニット内で担当が重複しています",
           })
         }
       })

package/dist/_schemas/ai-manifest.d.ts

@@ -1,17 +1,19 @@
 import { z } from "zod";
-export declare const AI_MODELS: readonly ["claude-opus-4-8", "claude-sonnet-5", "claude-haiku-4-5"];
+export declare const AI_MODELS: readonly ["claude-opus-5", "claude-opus-4-8", "claude-sonnet-5", "claude-haiku-4-5"];
 export declare const aiModelSchema: z.ZodEnum<{
+    "claude-opus-5": "claude-opus-5";
     "claude-opus-4-8": "claude-opus-4-8";
     "claude-sonnet-5": "claude-sonnet-5";
     "claude-haiku-4-5": "claude-haiku-4-5";
 }>;
 export type AiModel = z.infer<typeof aiModelSchema>;
-export declare const DEFAULT_AI_MODEL = "claude-opus-4-8";
+export declare const DEFAULT_AI_MODEL = "claude-opus-5";
 export declare const aiManifestSchema: z.ZodObject<{
     name: z.ZodOptional<z.ZodString>;
     description: z.ZodOptional<z.ZodString>;
     prompt: z.ZodString;
     model: z.ZodDefault<z.ZodEnum<{
+        "claude-opus-5": "claude-opus-5";
         "claude-opus-4-8": "claude-opus-4-8";
         "claude-sonnet-5": "claude-sonnet-5";
         "claude-haiku-4-5": "claude-haiku-4-5";

package/dist/_schemas/ai-manifest.js

@@ -1,14 +1,17 @@
 import { z } from "zod";
 import { jsonSchemaSchema } from "./node.js";
 import { isAiEnvelopeSchema, manifestInKeysViolation } from "./port-spec.js";
-// AI ノードのモデル選択肢（既定は Opus：下書き品質が価値の中心。費用はユーザー持ち）
+// AI ノードのモデル選択肢（既定は Opus：下書き品質が価値の中心。費用はユーザー持ち）。
+// エイリアス（"opus" 等）は採らずバージョンを固定する：実行のたびに黙って別モデルへ
+// 乗り換わると品質も費用も再現しないため。新モデルが出たらこの配列を足して SDK を publish する
 export const AI_MODELS = [
+    "claude-opus-5",
     "claude-opus-4-8",
     "claude-sonnet-5",
     "claude-haiku-4-5",
 ];
 export const aiModelSchema = z.enum(AI_MODELS);
-export const DEFAULT_AI_MODEL = "claude-opus-4-8";
+export const DEFAULT_AI_MODEL = "claude-opus-5";
 // nodes/ai/<dir>/config.json（実行repoの構造見直し）。AI ノードの定義（prompt/model/skills/
 // 入出力スキーマ/env）は repo 側が正で、エディタが取り込んで ports を自動生成する
 // （実行時の正は ports テーブルのまま。プログラム規約 v2 と同じ関係）。

package/dist/_schemas/graph.d.ts

@@ -47,6 +47,9 @@ export declare const aiConfigSchema: z.ZodObject<{
     ref: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 export type AiConfig = z.infer<typeof aiConfigSchema>;
+export declare const RUN_STARTER = "run_starter";
+export declare const assignMemberSchema: z.ZodUnion<readonly [z.ZodUUID, z.ZodLiteral<"run_starter">]>;
+export type AssignMember = z.infer<typeof assignMemberSchema>;
 export declare const humanConfigSchema: z.ZodObject<{
     view: z.ZodOptional<z.ZodString>;
     view_config: z.ZodOptional<z.ZodNullable<z.ZodUnknown>>;
@@ -59,7 +62,7 @@ export declare const humanConfigSchema: z.ZodObject<{
             any: "any";
             all: "all";
         }>>;
-        units: z.ZodDefault<z.ZodArray<z.ZodArray<z.ZodUUID>>>;
+        units: z.ZodDefault<z.ZodArray<z.ZodArray<z.ZodUnion<readonly [z.ZodUUID, z.ZodLiteral<"run_starter">]>>>>;
     }, z.core.$strip>;
 }, z.core.$strip>;
 export type HumanConfig = z.infer<typeof humanConfigSchema>;
@@ -143,7 +146,7 @@ export declare const graphNodeSchema: z.ZodObject<{
                 any: "any";
                 all: "all";
             }>>;
-            units: z.ZodDefault<z.ZodArray<z.ZodArray<z.ZodUUID>>>;
+            units: z.ZodDefault<z.ZodArray<z.ZodArray<z.ZodUnion<readonly [z.ZodUUID, z.ZodLiteral<"run_starter">]>>>>;
         }, z.core.$strip>;
     }, z.core.$strip>>;
     component: z.ZodOptional<z.ZodObject<{
@@ -225,7 +228,7 @@ export declare const saveGraphBodySchema: z.ZodObject<{
                     any: "any";
                     all: "all";
                 }>>;
-                units: z.ZodDefault<z.ZodArray<z.ZodArray<z.ZodUUID>>>;
+                units: z.ZodDefault<z.ZodArray<z.ZodArray<z.ZodUnion<readonly [z.ZodUUID, z.ZodLiteral<"run_starter">]>>>>;
             }, z.core.$strip>;
         }, z.core.$strip>>;
         component: z.ZodOptional<z.ZodObject<{

package/dist/_schemas/graph.js

@@ -91,9 +91,14 @@ export const aiConfigSchema = z.object({
         .refine((v) => !v.includes("/") && !v.includes("\\") && v !== "." && v !== "..", "ai_dir は nodes/ai/ 直下のディレクトリ名で指定してください"),
     ref: z.string().min(1).optional(),
 });
+// 担当ユニットのメンバー：user_id の名指し、または動的な担当「ループを実行した人」
+// （run の起動者。実行時に runs.start_by で解決し、解決できなければその1人だけ落ちる。
+// docs/tasks/wip/Human担当に「ループを実行した人」を追加する.md）
+export const RUN_STARTER = "run_starter";
+export const assignMemberSchema = z.union([z.uuid(), z.literal(RUN_STARTER)]);
 // Human ノードの kind 別設定（node_humans ＋ node_human_assignees に対応）。
 // 担当 ＝ ユニット（1人以上のメンバー）の順序付きリスト ＋ 承認モード ＋ 選出戦略。
-// units[i] は user_id の配列（1人＝個人・複数＝グループ）。units 空 = tenant の誰でも。
+// units[i] はメンバーの配列（1人＝個人・複数＝グループ）。units 空 = tenant の誰でも。
 // approval_mode はノード単位（any=誰か1人 / all=全員。差し戻しは1人で成立＝veto）。
 // メンバーが tenant の membership であることの検証は保存 API 側で行う
 // （docs/tasks/backlog/Human担当者の高度化（複数人承認とラウンドロビン）.md）
@@ -108,7 +113,7 @@ export const humanConfigSchema = z.object({
         .object({
         strategy: z.enum(["fixed", "round_robin"]).default("fixed"),
         approval_mode: z.enum(["any", "all"]).default("any"),
-        units: z.array(z.array(z.uuid()).min(1)).default([]),
+        units: z.array(z.array(assignMemberSchema).min(1)).default([]),
     })
         .superRefine((assignment, ctx) => {
         if (assignment.strategy === "fixed" && assignment.units.length > 1) {
@@ -126,13 +131,23 @@ export const humanConfigSchema = z.object({
                 message: "round_robin にはユニットが2つ以上必要です",
             });
         }
+        // 交代制と「ループを実行した人」は排他：どの回に誰が担当かが起動者と交代位置の
+        // 掛け算になって読めなくなるため、設定できる形の方を減らす
+        if (assignment.strategy === "round_robin" &&
+            assignment.units.some((unit) => unit.includes(RUN_STARTER))) {
+            ctx.addIssue({
+                code: "custom",
+                path: ["units"],
+                message: "round_robin の担当に「ループを実行した人」は入れられません",
+            });
+        }
         // ユニット内の重複は拒否（またぐ重複は「Aは毎回・相手が交代」の形があるので許す）
         assignment.units.forEach((unit, i) => {
             if (new Set(unit).size !== unit.length) {
                 ctx.addIssue({
                     code: "custom",
                     path: ["units", i],
-                    message: "ユニット内で user_id が重複しています",
+                    message: "ユニット内で担当が重複しています",
                 });
             }
         });

package/dist/typegen.js

@@ -146,7 +146,14 @@ export const renderTypesFile = (manifest, rawConfig) => {
         envelopeUnionType(Object.keys(manifest.outputs)),
         "",
         ...(refEntries.length > 0
-            ? [`export type Refs = {\n${refEntries.join("\n")}\n}`, ""]
+            ? [
+                `export type Refs = {\n${refEntries.join("\n")}\n}`,
+                "",
+                "// run の第2引数：refs＝届いた袋の読み、setRefs＝袋へのパッチの宣言",
+                "// （書いたキーだけが完了時に袋へマージされ、下流のノードから読める）",
+                "export type Ctx = { refs: Refs; setRefs: (patch: Partial<Refs>) => void }",
+                "",
+            ]
             : []),
     ].join("\n");
 };

package/docs/development.md

@@ -26,10 +26,17 @@ skills/<dir>/      # AI ノードが参照する skill（SKILL.md）
 
 - `config.json` — 入出力スキーマ等の宣言。正は `_schemas/program-manifest.ts`
   （`inputs` は `"in"` の1件だけ・`outputs` は1件以上・`env` は必要な secret 名の宣言）
-- `main.ts` — `run(input, ctx)` を export する。`ctx.refs` にループ変数が入る。戻り値：
+- `main.ts` — `run(input, ctx)` を export する。戻り値：
   - `{ <出口ポートのkey>: <データ> }` の**単一キー封筒**（どの出口から出るかを戻り値自身が運ぶ）
   - `"pending"` — 完了保留（外部イベントで後から end が届く）
-- 型生成：`npx mawaru typegen` が config.json から `types.d.ts`（Input / Outputs 型）を生成する
+- `ctx` — ループ変数の袋の読み書き：
+  - `ctx.refs` — 届いた袋（loop に定義された変数の、この step 開始時点の値）
+  - `ctx.setRefs({ key: value })` — 袋へのパッチの宣言。**完了時にだけ**反映され、以降の
+    ノードが `ctx.refs` で読める（動的な値を下流へ渡す唯一の経路）。何度呼んでもトップレベル
+    キー後勝ちで畳まれる。`"pending"` を返す実行では反映されない。loop に定義の無いキーを
+    書くと step は failed になる
+- 型生成：`npx mawaru typegen` が config.json から `types.d.ts`（Input / Outputs / Refs / Ctx 型）を
+  生成する
 - **ノード単位の npm 依存**：`<dir>/package.json` を置けば実行前にそのディレクトリで
   `npm ci` される。`package-lock.json` の commit が必須（無いと明瞭に失敗する）
 - 環境変数：`config.json` の `env` に宣言した secret（repo の Actions secrets）だけが

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mawaru/sdk",
-  "version": "0.8.0",
+  "version": "0.11.0",
   "description": "mawaru 実行 repo の開発 SDK。契約スキーマ（config.json 規約・ループ graph API）の正 ＋ typegen / validate CLI",
   "type": "module",
   "bin": {
@@ -33,7 +33,8 @@
     "prepack": "pnpm build",
     "typecheck": "tsc --noEmit",
     "test": "vitest run",
-    "test:watch": "vitest"
+    "test:watch": "vitest",
+    "release": "sh -c 'pnpm typecheck && pnpm test && npm version --no-git-tag-version ${1:-minor} && npm publish --access public' release"
   },
   "dependencies": {
     "zod": "^4.4.3",

package/skills/create-loop/SKILL.md

@@ -14,19 +14,33 @@ repo ルートの `.env` に以下の4変数が揃っているか確認する。
 セットアップまで面倒を見る**（ユーザーに手作業のセットアップを求めない）：
 
 1. `.gitignore` に `.env` が入っていることを確認する。無ければ追加する（API キーをコミットさせない）。
-2. `.env` を作成・追記する：
+2. `.env` を作成・追記する。**足りない変数は推測で埋めず、その場でユーザーに聞く**（下の
+   「環境変数が足りないとき」の原則に従う）：
    - `MAWARU_API_URL` — API のベース URL（例: `https://api.mawaru.ai`。ローカル開発は `http://localhost:9000`）
    - `MAWARU_APP_URL` — フロントの URL（例: `https://app.mawaru.ai`。ローカル開発は `http://localhost:3000`）
    - `MAWARU_TENANT_ID` — tenant の ID
    - `MAWARU_API_KEY` — tenant の API キー
-   接続先が本番かローカルかはユーザーに確認する。API キーは mawaru のテナント設定画面
-   （`{MAWARU_APP_URL}/settings` の「API キー」。admin のみ）で発行・コピーできるので、
-   ユーザーに案内して値を入力してもらう。**キーの値をチャット・ログ・コミットに出さない。**
+   接続先が本番かローカルかはユーザーに確認する（URL 2つはこれで決まる）。API キーは mawaru の
+   テナント設定画面（`{MAWARU_APP_URL}/settings` の「API キー」。admin のみ）で発行・コピーできるので、
+   発行手順を案内したうえで `.env` に入れてもらう。**キーの値をチャット・ログ・コミットに出さない。**
 3. 疎通確認：`GET {MAWARU_API_URL}/tenants/{MAWARU_TENANT_ID}/loops` が 200 を返せば完了。
    401 なら API キー、404 なら tenant ID を疑う。
 
 認証は全リクエスト共通でヘッダ `x-api-key: $MAWARU_API_KEY`。
 
+## 環境変数が足りないとき（全体の原則）
+
+このスキルの `.env` でも、ノードの `env` 宣言（program / ai の handler・setup.sh・prompt が使う
+secret）でも、**足りない値を推測・生成・空文字で代用しない。作業を止めてユーザーに対話的に聞く。**
+
+- 足りないものは**まとめて1回で聞く**：変数名・何に使う値か・どこで取れるか（画面・発行手順）・
+  形式の例を添える。答えを待ってから作業を再開する（タイムアウトを承認扱いにしない）。
+- **秘密の値はチャットに書かせない・出力しない**。`.env` へはユーザー自身の手で追記してもらう
+  （例: `echo 'MAWARU_API_KEY=xxxx' >> .env` を実行してもらう）。ノードの `env` 宣言分は
+  実行 repo の Settings → Secrets and variables → Actions に登録してもらい、こちらは**名前だけ**扱う。
+- 受け取ったら「効いていること」まで確かめてから次へ進む（`.env` なら疎通確認、
+  Actions secrets なら名前が config.json の `env` と一致していること）。
+
 ## 契約の読み方（最重要）
 
 **API のボディ形をこの文書は説明しない。正はこのパッケージ内の Zod スキーマなので、必ずソースを読むこと**：
@@ -62,6 +76,7 @@ repo との矛盾・使用中ノードの削除は 409。**graph PUT は冪等
 1. **設計**：要件から必要なノード（program / ai / human / wait）と流れを決め、ユーザーに一言で確認する。
 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`。
@@ -78,6 +93,35 @@ repo との矛盾・使用中ノードの削除は 409。**graph PUT は冪等
 6. **報告**：エディタ URL `{MAWARU_APP_URL}/loops/{loopId}/edit` をユーザーに渡し、
    見た目の確認と run はユーザーに委ねる。
 
+## AI ノード：決定論的な処理は prompt でなく setup.sh に書く
+
+やることが決まっている準備＝**外部 repo の clone / skill の持ち込み / 認証キーのファイル化 /
+ツールの用意**は、prompt で AI にやらせず `nodes/ai/<dir>/setup.sh` に書く。prompt には
+「どこに何が置いてあるか」と、そこから先の判断だけを書く。
+
+理由：LLM にやらせるとトークンを食い flaky で、失敗が「セットアップの失敗」として明瞭に出ない。
+skill の配置は Claude Code 起動前に完了している必要もある。
+
+規約（実行 repo 側。config.json への宣言は不要、ファイルの存在が正）：
+
+```bash
+# nodes/ai/<dir>/setup.sh
+set -euo pipefail
+git clone --depth 1 "https://x-access-token:${SOME_REPO_TOKEN}@github.com/owner/repo.git" workspace/repo
+cp -r workspace/repo/.claude/skills/some-skill skills/   # copySkills の前に走るので自動発見に乗る
+printf '%s' "$SOME_SA_KEY" > workspace/key.json
+```
+
+- 実行順は `env 注入 → input.json 書き出し → setup.sh → copySkills → 本体（Claude Code）`。
+  `bash nodes/ai/<dir>/setup.sh "$INPUT_JSON"`（実行ビット不要）、cwd は checkout ルート。
+- **入力は `$1`（JSON 文字列）か `input.json`** で参照できる（`jq` はランナー同梱）。
+- **環境変数は config.json の `env` 宣言分だけ**が注入される。必要な secret は `env` に宣言し、
+  実行 repo の Actions secrets に登録してもらう（→「環境変数が足りないとき」）。
+- **受け渡しはファイルで**。別プロセスなので `export` は本体に引き継がれない。clone 先・キーは
+  ワークスペース内の既知パス（`workspace/` 配下を推奨）に置き、prompt / skill はそのパスを参照する。
+- **非 0 exit は step failed**（本体は実行されない）。`set -euo pipefail` を付ける。
+- program ノードにも同じ規約が効く（`nodes/program/<dir>/setup.sh`）。
+
 ## 注意
 
 - **graph PUT は全量置換**。既存ループを更新するときは、必ず先に `GET loops/{loopId}` で