步驟5 缺口①：引擎通用具名分支邊（ON_TRUE/ON_FALSE/ON_BRANCH）＝Arcrun#5 根治

問題（「全變成 code」的根）：if_control 回 {result, branch} 卻沒有邊讀得懂它，
圖的邊只有 ON_SUCCESS/IF/FOREACH ⇒ 就算照規矩用零件，仍得寫 code 判斷走哪條。
leo 08-01 追問「你改了 if，有改 switch 嗎？switch 更嚴重」——確認 switch(N 路)
與 try_catch(try/catch) 同病，故一次做成通用機制，不留「為 switch 再改一次」的債。

設計：三顆流程控制零件的 output_schema 本來就都收斂到同一形狀 data.branch: string
（if_control→true/false；switch→case 名或 default_branch；try_catch→try/catch）
⇒ 引擎只需「依標籤選邊」一個機制 ON_BRANCH；ON_TRUE/ON_FALSE 是布林路的語法糖，
底層同一條路（測試已證等價）。讀不出分支＝不走（誠實，不亂挑一條）。

- types/schemas/constants：新增三邊型（純新增，既有列舉不動）＋ GraphEdge.branch
- graph-executor：readBranch() 依 data.branch → branch → data.result → result 四層相容
- 中文語意詞：成立時/為真時=ON_TRUE，不成立時/為假時/否則=ON_FALSE，BRANCH=ON_BRANCH

分支用法要「查得到」（leo 08-01：AI 可能像 n8n 那樣逐顆查、自己組圖）：
新增 lib/branch-hints.ts，讓 if_control/switch/try_catch 的查詢回應自帶 branch_hint
（branch_field/branches/edge_types/usage/example）——只看這一顆的回應就知道怎麼接下一步，
不必回頭讀 skill。四條回應路徑全wire：catalog found／legacy 逐顆／步驟4 substitution／
target=component 名字搜尋（＝n8n 式那條）。不分岔的零件不加此欄，避免噪音。

測試（先寫測試再改引擎，紅線要求）：tests/conditional-edges.test.ts 16 項全綠
——if 兩路／switch 多路＋default／try_catch 成功與失敗路／語法糖等價／
context 傳遞／同分支 fan-out／無匹配不走／混合邊時 PIPE 不受影響／schema 放行。
零變化保證：195 passed（前 179 +16 新），失敗數維持既有 9 筆未變（console/portal
HTML 資產未建置＋executor 斷言字串漂移，皆與本次無關）；tsc --noEmit 綠。
現存 workflow/example 用到新邊型＝0 筆（grep 實查）⇒ 既有行為不可能被改動。

SDD: workflow-discovery task 3.11｜CP: arcrun-usable 步驟 5

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

cypher-executor/src/actions/search-nodes.ts

@@ -3,6 +3,8 @@ import { resolveNodeRole, isVirtualIoName } from './triplet-parser';
 import { wasmWorkerUrl } from '../lib/component-loader';
 import { resolveRecipe } from '../routes/recipes';
 import type { RecipeDefinition } from '../routes/recipes';
+import { branchHintFor } from '../lib/branch-hints';
+import type { BranchHint } from '../lib/branch-hints';
 
 /**
  * `not_found` 而非 `missing`：欄位契約以頂層機械考
@@ -63,6 +65,13 @@ export type NodeInfo = {
   similar_recipes?: string[];
   /** resolved 時的替換明細（步驟 4：意圖節點 → 真實零件/recipe）。 */
   substitution?: NodeSubstitution;
+  /**
+   * 分支用法自我說明（3.11）：只有「本身會分岔」的零件才有
+   * （if_control／switch／try_catch）。
+   * 存在的理由＝走 n8n 式「逐顆查、自己組圖」的 AI，光看 input_schema 不知道
+   * 「判斷完之後兩條路怎麼接」⇒ 會回頭寫 code。判準：只看這一顆的回應就知道怎麼接下一步。
+   */
+  branch_hint?: BranchHint;
 };
 
 export type SearchResult = {
@@ -216,6 +225,7 @@ export async function searchNodes(
         input_schema: hit.input_schema,
         success_rate: typeof hit.success_rate === 'number' ? hit.success_rate : undefined,
         stability: typeof hit.stability === 'string' ? hit.stability : undefined,
+        branch_hint: branchHintFor(componentId),
       };
       continue;
     }
@@ -355,6 +365,7 @@ async function legacyPerNodeLookup(
       info: {
         status: 'found', componentId, type: role, source: 'component',
         input_schema: q.entry.input_schema, success_rate: q.entry.success_rate, stability: q.entry.stability,
+        branch_hint: branchHintFor(componentId),
       },
       missing: false,
     };
@@ -407,7 +418,7 @@ async function legacyPerNodeLookup(
 type SubstitutionHit = Pick<
   NodeInfo,
   'status' | 'componentId' | 'source' | 'substitution' |
-  'input_schema' | 'success_rate' | 'stability' | 'description' | 'endpoint'
+  'input_schema' | 'success_rate' | 'stability' | 'description' | 'endpoint' | 'branch_hint'
 >;
 
 function trySubstitution(
@@ -472,6 +483,9 @@ function trySubstitution(
     input_schema: top.entry.input_schema,
     success_rate: typeof top.entry.success_rate === 'number' ? top.entry.success_rate : undefined,
     stability: typeof top.entry.stability === 'string' ? top.entry.stability : undefined,
+    // 替換成分岔零件時（例「判斷有沒有新資料」→ if_control）一併附分支用法，
+    // 否則 AI 換到零件卻不知道怎麼接兩條路，仍會退回寫 code。
+    branch_hint: branchHintFor(top.entry.canonical_id),
     substitution: {
       from: nodeName,
       componentId: top.entry.canonical_id,

cypher-executor/src/actions/target-search.ts

@@ -17,6 +17,7 @@
 import { wasmWorkerUrl } from '../lib/component-loader';
 import { fetchTenantWorkflowSearch } from '../lib/workflow-search';
 import { listAllRecipes, type SearchNodesEnv } from './search-nodes';
+import { branchHintFor } from '../lib/branch-hints';
 
 export type TargetQueryEnv = SearchNodesEnv & {
   KBDB_BASE_URL?: string;
@@ -44,12 +45,21 @@ export async function searchByTarget(
       );
       if (!res.ok) return { ok: false, status: 502, error: `registry 搜尋失敗（HTTP ${res.status}）` };
       const body = (await res.json()) as { data?: { results?: unknown[]; count?: number } };
+      // 3.11：逐顆查零件（n8n 式「自己一顆一顆填」）時，會分岔的零件要自我說明分支用法。
+      // leo 08-01：「它可以一一查詢自己手工填寫每個零件，就像在 n8n 那樣」——
+      // 這條路徑若只回 input_schema，AI 拿到 if_control／switch 仍不知道兩條路怎麼接 ⇒ 回頭寫 code。
+      const results = (body.data?.results ?? []).map(r => {
+        if (!r || typeof r !== 'object') return r;
+        const rec = r as Record<string, unknown>;
+        const hint = branchHintFor(typeof rec.canonical_id === 'string' ? rec.canonical_id : undefined);
+        return hint ? { ...rec, branch_hint: hint } : rec;
+      });
       return {
         ok: true,
         body: {
           target,
           query,
-          results: body.data?.results ?? [],
+          results,
           count: body.data?.count ?? 0,
         },
       };