From c91a3d1ec6bebdfdc91ec1ea0415f2f37c32fdd7 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E5=B0=8F=E6=A9=98?= <xiaoju@shazhou.work>
Date: Mon, 18 May 2026 08:41:29 +0000
Subject: [PATCH] docs: add description to condition definitions

---
 docs/wf-stateless-design.md | 15 ++++++++++++---
 1 file changed, 12 insertions(+), 3 deletions(-)

diff --git a/docs/wf-stateless-design.md b/docs/wf-stateless-design.md
index 3447f19..439c643 100644
--- a/docs/wf-stateless-design.md
+++ b/docs/wf-stateless-design.md
@@ -164,8 +164,12 @@ payload:
       systemPrompt: "You are a code reviewer..."
       outputSchema: "1VPBG9SM5E7WK"    # cas_ref → JSON Schema 节点
   conditions:
-    needsClarification: "$exists(steps[-1].output.needsClarification)"
-    notApproved: "steps[-1].output.approved = false"
+    needsClarification:
+      description: "Planner requests clarification from user"
+      expression: "$exists(steps[-1].output.needsClarification)"
+    notApproved:
+      description: "Reviewer rejected the implementation"
+      expression: "steps[-1].output.approved = false"
   graph:
     $START:
       - role: "planner"
@@ -398,11 +402,16 @@ type Transition = {
   condition: string | null;          // 引用 conditions 中的 key，null = fallback
 };
 
+type ConditionDefinition = {
+  description: string;
+  expression: string;                           // JSONata expression
+};
+
 type WorkflowPayload = {
   name: string;
   description: string;
   roles: Record<string, RoleDefinition>;
-  conditions: Record<string, string>;           // Record<Name, JSONata expression>
+  conditions: Record<string, ConditionDefinition>;
   graph: Record<string, Transition[]>;          // Record<Role | "$START", Transition[]>
 };
 ```