refactor(cli-workflow): reduce cmdStepRead cognitive complexity

Extract four helper functions from cmdStepRead to reduce cognitive
complexity from 27 to ≤15:
- loadStepDetail: Load and validate step detail node
- loadTurnData: Load all turn nodes and extract content
- selectTurnsForQuota: Select turns within quota (≥1 always shown)
- formatStepMarkdown: Assemble final markdown output

All 6 existing tests pass. Zero Biome warnings. CLAUDE.md compliant.

Fixes #487

packages/cli-workflow/src/__tests__/solve-issue-tea-worktree.test.ts

@@ -70,6 +70,7 @@ describe("solve-issue workflow: tea pr create worktree fix", () => {
     // Basic structure validation
     expect(workflow.name).toBe("solve-issue");
     expect(workflow.roles).toBeDefined();
+    expect(workflow.conditions).toBeDefined();
     expect(workflow.graph).toBeDefined();
 
     // Verify committer role exists with required fields

packages/cli-workflow/src/__tests__/workflow-resolution.test.ts

@@ -25,6 +25,7 @@ async function storeWorkflow(uwf: UwfStore, name: string): Promise<CasRef> {
     name,
     description: "Test workflow",
     roles: {},
+    conditions: {},
     graph: {},
   };
   return await uwf.store.put(uwf.schemas.workflow, payload);
@@ -35,6 +36,7 @@ async function createWorkflowYaml(name: string, version: string | null = null):
     name,
     description: version !== null ? `Test workflow (${version})` : "Test workflow",
     roles: {},
+    conditions: {},
     graph: {},
   };
   const yaml = stringify(payload);
@@ -143,7 +145,7 @@ describe("Strategy 2: File Path Resolution", () => {
   test("should fail on valid YAML with invalid WorkflowPayload shape", async () => {
     await makeUwfStore(storageRoot);
     const yamlPath = join(tmpDir, "invalid-workflow.yaml");
-    await writeFile(yamlPath, "name: test\n# missing roles and graph");
+    await writeFile(yamlPath, "name: test\n# missing roles, conditions, and graph");
 
     await expect(cmdThreadStart(storageRoot, yamlPath, "prompt", projectRoot)).rejects.toThrow();
   });

packages/cli-workflow/src/commands/step.ts

@@ -1,3 +1,4 @@
+import type { BootstrapCapableStore } from "@uncaged/json-cas";
 import type {
   CasRef,
   StartEntry,
@@ -18,6 +19,11 @@ import {
   walkChain,
 } from "./shared.js";
 
+type TurnData = {
+  index: number;
+  content: string;
+};
+
 /**
  * List all steps in a thread (previously: thread steps)
  */
@@ -110,6 +116,108 @@ export async function cmdStepFork(
   };
 }
 
+/**
+ * Load and validate step detail node from CAS store
+ */
+function loadStepDetail(store: BootstrapCapableStore, detailRef: CasRef): Record<string, unknown> {
+  const detailNode = store.get(detailRef);
+  if (detailNode === null) {
+    fail(`detail node not found: ${detailRef}`);
+  }
+  return detailNode.payload as Record<string, unknown>;
+}
+
+/**
+ * Load all turn nodes from CAS store and extract content
+ */
+function loadTurnData(store: BootstrapCapableStore, turns: unknown): TurnData[] {
+  if (!Array.isArray(turns) || turns.length === 0) {
+    return [];
+  }
+
+  const turnData: TurnData[] = [];
+  for (const turnRef of turns) {
+    if (typeof turnRef !== "string") {
+      continue;
+    }
+    const turnNode = store.get(turnRef as CasRef);
+    if (turnNode === null) {
+      continue;
+    }
+    const turn = turnNode.payload as Record<string, unknown>;
+    if (typeof turn.content === "string") {
+      turnData.push({
+        index: typeof turn.index === "number" ? turn.index : turnData.length,
+        content: turn.content,
+      });
+    }
+  }
+  return turnData;
+}
+
+/**
+ * Select turns that fit within quota, working backwards from most recent
+ */
+function selectTurnsForQuota(turnData: TurnData[], availableQuota: number): TurnData[] {
+  const selectedTurns: TurnData[] = [];
+  let totalChars = 0;
+
+  for (let i = turnData.length - 1; i >= 0; i--) {
+    const turn = turnData[i];
+    if (turn === undefined) continue;
+
+    const turnHeader = `## Turn ${turn.index + 1}\n\n`;
+    const turnBlock = turnHeader + turn.content;
+    const separatorCost = selectedTurns.length > 0 ? 2 : 0;
+    const addCost = turnBlock.length + separatorCost;
+
+    if (totalChars + addCost > availableQuota && selectedTurns.length > 0) {
+      break;
+    }
+
+    selectedTurns.unshift(turn);
+    totalChars += addCost;
+  }
+
+  return selectedTurns;
+}
+
+/**
+ * Assemble final markdown output from header and selected turns
+ */
+function formatStepMarkdown(
+  stepHash: CasRef,
+  role: string,
+  agent: string,
+  turnData: TurnData[],
+  selectedTurns: TurnData[],
+): string {
+  const parts: string[] = [];
+  parts.push(`# Step ${stepHash}`);
+  parts.push("");
+  parts.push(`**Role:** ${role}`);
+  parts.push(`**Agent:** ${agent}`);
+
+  if (selectedTurns.length === 0) {
+    return parts.join("\n");
+  }
+
+  const skippedCount = turnData.length - selectedTurns.length;
+  if (skippedCount > 0) {
+    parts.push("");
+    parts.push(`_[Earlier turns omitted due to quota. Use --quota to increase.]_`);
+  }
+
+  for (const turn of selectedTurns) {
+    parts.push("");
+    parts.push(`## Turn ${turn.index + 1}`);
+    parts.push("");
+    parts.push(turn.content);
+  }
+
+  return parts.join("\n");
+}
+
 /**
  * Read a step's agent turns as human-readable markdown with quota enforcement
  */
@@ -128,103 +236,21 @@ export async function cmdStepRead(
   }
   const payload = node.payload as StepNodePayload;
 
-  // Build header section
-  const parts: string[] = [];
-  parts.push(`# Step ${stepHash}`);
-  parts.push("");
-  parts.push(`**Role:** ${payload.role}`);
-  parts.push(`**Agent:** ${payload.agent}`);
-
-  // If no detail, return metadata only
   if (payload.detail === null) {
-    return parts.join("\n");
+    return formatStepMarkdown(stepHash, payload.role, payload.agent, [], []);
   }
 
-  // Load detail node
-  const detailNode = uwf.store.get(payload.detail);
-  if (detailNode === null) {
-    fail(`detail node not found: ${payload.detail}`);
-  }
-
-  const detail = detailNode.payload as Record<string, unknown>;
-  const turns = detail.turns;
-
-  // If no turns array, return metadata only
-  if (!Array.isArray(turns) || turns.length === 0) {
-    return parts.join("\n");
-  }
-
-  // Load all turn nodes
-  type TurnData = {
-    index: number;
-    content: string;
-  };
-  const turnData: TurnData[] = [];
-  for (const turnRef of turns) {
-    if (typeof turnRef !== "string") {
-      continue;
-    }
-    const turnNode = uwf.store.get(turnRef as CasRef);
-    if (turnNode === null) {
-      continue;
-    }
-    const turn = turnNode.payload as Record<string, unknown>;
-    if (typeof turn.content === "string") {
-      turnData.push({
-        index: typeof turn.index === "number" ? turn.index : turnData.length,
-        content: turn.content,
-      });
-    }
-  }
+  const detail = loadStepDetail(uwf.store, payload.detail);
+  const turnData = loadTurnData(uwf.store, detail.turns);
 
   if (turnData.length === 0) {
-    return parts.join("\n");
+    return formatStepMarkdown(stepHash, payload.role, payload.agent, [], []);
   }
 
-  // Calculate header length for quota accounting
-  const headerSection = parts.join("\n");
-  const headerLength = headerSection.length;
+  const headerSection = formatStepMarkdown(stepHash, payload.role, payload.agent, [], []);
+  const BUFFER = 200;
+  const availableQuota = quota - headerSection.length - BUFFER;
+  const selectedTurns = selectTurnsForQuota(turnData, availableQuota);
 
-  // Select turns that fit within quota (working backwards from most recent)
-  const BUFFER = 200; // Conservative buffer for structural overhead
-  const availableQuota = quota - headerLength - BUFFER;
-
-  const selectedTurns: TurnData[] = [];
-  let totalChars = 0;
-
-  for (let i = turnData.length - 1; i >= 0; i--) {
-    const turn = turnData[i];
-    if (turn === undefined) continue;
-
-    // Calculate formatted turn length
-    const turnHeader = `## Turn ${turn.index + 1}\n\n`;
-    const turnBlock = turnHeader + turn.content;
-    const separatorCost = selectedTurns.length > 0 ? 2 : 0; // "\n\n" between turns
-    const addCost = turnBlock.length + separatorCost;
-
-    // Check quota - but always include at least one turn
-    if (totalChars + addCost > availableQuota && selectedTurns.length > 0) {
-      break;
-    }
-
-    selectedTurns.unshift(turn);
-    totalChars += addCost;
-  }
-
-  // Add skip hint if not all turns fit
-  const skippedCount = turnData.length - selectedTurns.length;
-  if (skippedCount > 0) {
-    parts.push("");
-    parts.push(`_[Earlier turns omitted due to quota. Use --quota to increase.]_`);
-  }
-
-  // Add selected turns
-  for (const turn of selectedTurns) {
-    parts.push("");
-    parts.push(`## Turn ${turn.index + 1}`);
-    parts.push("");
-    parts.push(turn.content);
-  }
-
-  return parts.join("\n");
+  return formatStepMarkdown(stepHash, payload.role, payload.agent, turnData, selectedTurns);
 }

packages/cli-workflow/src/commands/thread.ts

@@ -8,8 +8,10 @@ import type {
   AgentAlias,
   AgentConfig,
   CasRef,
+  ModeratorContext,
   StartNodePayload,
   StartOutput,
+  StepContext,
   StepNodePayload,
   StepOutput,
   ThreadId,
@@ -51,7 +53,6 @@ import {
 import { materializeWorkflowPayload } from "./workflow.js";
 
 const END_ROLE = "$END";
-const START_ROLE = "$START";
 export const THREAD_READ_DEFAULT_QUOTA = 4000;
 
 const PL_THREAD_START = "7HNQ4B2X";
@@ -669,32 +670,17 @@ function formatThreadReadMarkdown(options: {
   return parts.join("\n\n---\n\n");
 }
 
-type EvaluateLastOutput = Record<string, unknown> & { status: string };
-
-function resolveEvaluateArgs(
-  uwf: UwfStore,
-  chain: ChainState,
-): { lastRole: string; lastOutput: EvaluateLastOutput } {
-  if (chain.headIsStart) {
-    return { lastRole: START_ROLE, lastOutput: { status: "_" } };
-  }
-
-  const lastStep = chain.stepsNewestFirst[0];
-  if (lastStep === undefined) {
-    fail("empty step chain");
-  }
-
-  const raw = expandOutput(uwf, lastStep.output);
-  const base =
-    typeof raw === "object" && raw !== null && !Array.isArray(raw)
-      ? (raw as Record<string, unknown>)
-      : {};
-  const status = typeof base.status === "string" ? base.status : "_";
-
-  return {
-    lastRole: lastStep.role,
-    lastOutput: { ...base, status },
-  };
+function buildModeratorContext(uwf: UwfStore, chain: ChainState): ModeratorContext {
+  const chronological = [...chain.stepsNewestFirst].reverse();
+  const steps: StepContext[] = chronological.map((step) => ({
+    role: step.role,
+    output: expandOutput(uwf, step.output),
+    detail: step.detail,
+    agent: step.agent,
+    edgePrompt: step.edgePrompt ?? "",
+    content: null, // Moderator doesn't need content
+  }));
+  return { start: chain.start, steps };
 }
 
 function loadWorkflowPayload(uwf: UwfStore, workflowRef: CasRef): WorkflowPayload {
@@ -938,9 +924,9 @@ async function cmdThreadStepOnce(
   const chain = walkChain(uwf, headHash);
   const workflowHash = chain.start.workflow;
   const workflow = loadWorkflowPayload(uwf, workflowHash);
-  const { lastRole, lastOutput } = resolveEvaluateArgs(uwf, chain);
+  const context = buildModeratorContext(uwf, chain);
 
-  const nextResult = evaluate(workflow.graph, lastRole, lastOutput);
+  const nextResult = await evaluate(workflow, context);
   if (!nextResult.ok) {
     failStep(plog, `moderator evaluate failed: ${nextResult.error.message}`);
   }
@@ -990,11 +976,8 @@ async function cmdThreadStepOnce(
   await saveThreadsIndex(storageRoot, freshIndex);
 
   const chainAfter = walkChain(uwfAfter, newHead);
-  const { lastRole: lastRoleAfter, lastOutput: lastOutputAfter } = resolveEvaluateArgs(
-    uwfAfter,
-    chainAfter,
-  );
-  const afterResult = evaluate(workflow.graph, lastRoleAfter, lastOutputAfter);
+  const contextAfter = buildModeratorContext(uwfAfter, chainAfter);
+  const afterResult = await evaluate(workflow, contextAfter);
   if (!afterResult.ok) {
     failStep(plog, `post-step moderator evaluate failed: ${afterResult.error.message}`);
   }

packages/cli-workflow/src/commands/workflow.ts

@@ -2,7 +2,12 @@ import { readFile } from "node:fs/promises";
 
 import type { JSONSchema } from "@uncaged/json-cas";
 import { putSchema, validate } from "@uncaged/json-cas";
-import type { CasRef, RoleDefinition, Target, WorkflowPayload } from "@uncaged/workflow-protocol";
+import type {
+  CasRef,
+  RoleDefinition,
+  Transition,
+  WorkflowPayload,
+} from "@uncaged/workflow-protocol";
 import { parse } from "yaml";
 
 import {
@@ -46,23 +51,20 @@ function isJsonSchema(value: unknown): value is JSONSchema {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 
-/** Normalize graph: validate each status → target mapping. */
-function normalizeGraph(
-  graph: Record<string, Record<string, Target>>,
-): Record<string, Record<string, Target>> {
-  const result: Record<string, Record<string, Target>> = {};
-  for (const [node, statusMap] of Object.entries(graph)) {
-    const normalized: Record<string, Target> = {};
-    for (const [status, target] of Object.entries(statusMap)) {
-      if (typeof target.prompt !== "string" || target.prompt.trim() === "") {
-        fail(`graph[${node}][${status}] → "${target.role}": prompt is required (non-empty string)`);
+/** Normalize graph transitions: ensure condition is null (not undefined) for fallback entries. */
+function normalizeGraph(graph: Record<string, Transition[]>): Record<string, Transition[]> {
+  const result: Record<string, Transition[]> = {};
+  for (const [node, transitions] of Object.entries(graph)) {
+    result[node] = transitions.map((t) => {
+      if (typeof t.prompt !== "string" || t.prompt.trim() === "") {
+        fail(`graph[${node}] transition to "${t.role}": prompt is required (non-empty string)`);
       }
-      normalized[status] = {
-        role: target.role,
-        prompt: target.prompt,
+      return {
+        role: t.role,
+        condition: t.condition ?? null,
+        prompt: t.prompt,
       };
-    }
-    result[node] = normalized;
+    });
   }
   return result;
 }
@@ -104,6 +106,7 @@ export async function materializeWorkflowPayload(
     name: raw.name,
     description: raw.description,
     roles,
+    conditions: raw.conditions,
     graph: normalizeGraph(raw.graph),
   };
 }

packages/cli-workflow/src/validate.ts

@@ -30,12 +30,23 @@ function isRoleDefinition(value: unknown): boolean {
   );
 }
 
-function isTarget(value: unknown): boolean {
+function isConditionDefinition(value: unknown): boolean {
   if (!isRecord(value)) {
     return false;
   }
+  return typeof value.description === "string" && typeof value.expression === "string";
+}
+
+function isTransition(value: unknown): boolean {
+  if (!isRecord(value)) {
+    return false;
+  }
+  const condition = value.condition;
   return (
-    typeof value.role === "string" && typeof value.prompt === "string" && value.prompt.trim() !== ""
+    typeof value.role === "string" &&
+    typeof value.prompt === "string" &&
+    value.prompt.trim() !== "" &&
+    (condition === null || condition === undefined || typeof condition === "string")
   );
 }
 
@@ -51,7 +62,7 @@ function isGraph(value: unknown): boolean {
     return false;
   }
   return Object.values(value).every(
-    (statusMap) => isRecord(statusMap) && Object.values(statusMap).every((t) => isTarget(t)),
+    (transitions) => Array.isArray(transitions) && transitions.every((t) => isTransition(t)),
   );
 }
 
@@ -90,7 +101,11 @@ export function parseWorkflowPayload(raw: unknown): WorkflowPayload | null {
   if (typeof raw.name !== "string" || typeof raw.description !== "string") {
     return null;
   }
-  if (!isStringRecord(raw.roles, isRoleDefinition) || !isGraph(raw.graph)) {
+  if (
+    !isStringRecord(raw.roles, isRoleDefinition) ||
+    !isStringRecord(raw.conditions, isConditionDefinition) ||
+    !isGraph(raw.graph)
+  ) {
     return null;
   }
   return raw as WorkflowPayload;

packages/workflow-moderator/__tests__/evaluate.test.ts

@@ -1,95 +1,312 @@
 import { describe, expect, test } from "bun:test";
-import type { Target, WorkflowPayload } from "@uncaged/workflow-protocol";
+import type { ModeratorContext, WorkflowPayload } from "@uncaged/workflow-protocol";
 
 import { evaluate } from "../src/evaluate.js";
 
-const solveIssueGraph: WorkflowPayload["graph"] = {
-  $START: {
-    _: { role: "planner", prompt: "Start planning from the issue in the task." },
+const solveIssueWorkflow: WorkflowPayload = {
+  name: "solve-issue",
+  description: "End-to-end issue resolution",
+  roles: {
+    planner: {
+      description: "Creates implementation plan",
+      goal: "You are a planning agent.",
+      capabilities: ["planning"],
+      procedure: "Create a step-by-step plan.",
+      output: "Output the plan and steps.",
+      frontmatter: "5GWKR8TN1V3JA",
+    },
+    developer: {
+      description: "Implements code changes",
+      goal: "You are a developer agent.",
+      capabilities: ["coding"],
+      procedure: "Implement the plan.",
+      output: "List files changed and summary.",
+      frontmatter: "8CNWT4KR6D1HV",
+    },
+    reviewer: {
+      description: "Reviews code changes",
+      goal: "You are a code reviewer.",
+      capabilities: ["code-review"],
+      procedure: "Review the implementation.",
+      output: "Approve or reject with comments.",
+      frontmatter: "1VPBG9SM5E7WK",
+    },
   },
-  planner: {
-    _: { role: "developer", prompt: "Implement the plan: {{plan}}" },
+  conditions: {
+    needsClarification: {
+      description: "Planner requests clarification from user",
+      expression: "$exists($last('planner').needsClarification)",
+    },
+    rejected: {
+      description: "Reviewer rejected the implementation",
+      expression: "$last('reviewer').approved = false",
+    },
   },
-  developer: {
-    _: { role: "reviewer", prompt: "Review the changes: {{summary}}" },
-  },
-  reviewer: {
-    approved: { role: "$END", prompt: "Done." },
-    rejected: { role: "developer", prompt: "Fix: {{comments}}" },
+  graph: {
+    $START: [
+      {
+        role: "planner",
+        condition: null,
+        prompt: "Start planning from the issue in the task.",
+      },
+    ],
+    planner: [
+      {
+        role: "developer",
+        condition: "needsClarification",
+        prompt: "Clarification is needed; hand off to developer.",
+      },
+      { role: "$END", condition: null, prompt: "Planning complete; end workflow." },
+    ],
+    developer: [
+      {
+        role: "reviewer",
+        condition: null,
+        prompt: "Implementation done; send to reviewer.",
+      },
+    ],
+    reviewer: [
+      {
+        role: "developer",
+        condition: "rejected",
+        prompt: "Reviewer rejected; return to developer.",
+      },
+      { role: "$END", condition: null, prompt: "Review passed; end workflow." },
+    ],
   },
 };
 
+function makeContext(steps: ModeratorContext["steps"]): ModeratorContext {
+  return {
+    start: {
+      workflow: "4KNM2PXR3B1QW",
+      prompt: "Fix the login bug",
+    },
+    steps,
+  };
+}
+
 describe("evaluate", () => {
-  test("$START → first role (unit status _)", () => {
-    const result = evaluate(solveIssueGraph, "$START", { status: "_" });
+  test("$START → first role (fallback)", async () => {
+    const result = await evaluate(solveIssueWorkflow, makeContext([]));
     expect(result).toEqual({
       ok: true,
       value: { role: "planner", prompt: "Start planning from the issue in the task." },
     });
   });
 
-  test("status-based routing (reviewer rejected → developer)", () => {
-    const result = evaluate(solveIssueGraph, "reviewer", {
-      status: "rejected",
-      comments: "missing tests",
-    });
+  test("condition match (rejected → developer)", async () => {
+    const context = makeContext([
+      {
+        role: "reviewer",
+        output: { approved: false },
+        detail: "2MXBG6PN4A8JR",
+        agent: "uwf-hermes",
+      },
+    ]);
+    const result = await evaluate(solveIssueWorkflow, context);
     expect(result).toEqual({
       ok: true,
-      value: { role: "developer", prompt: "Fix: missing tests" },
+      value: { role: "developer", prompt: "Reviewer rejected; return to developer." },
     });
   });
 
-  test("status-based routing (reviewer approved → $END)", () => {
-    const result = evaluate(solveIssueGraph, "reviewer", { status: "approved" });
+  test("fallback when condition does not match → $END", async () => {
+    const context = makeContext([
+      {
+        role: "reviewer",
+        output: { approved: true },
+        detail: "2MXBG6PN4A8JR",
+        agent: "uwf-hermes",
+      },
+    ]);
+    const result = await evaluate(solveIssueWorkflow, context);
     expect(result).toEqual({
       ok: true,
-      value: { role: "$END", prompt: "Done." },
+      value: { role: "$END", prompt: "Review passed; end workflow." },
     });
   });
 
-  test("missing role in graph → error", () => {
-    const result = evaluate(solveIssueGraph, "unknown-role", { status: "_" });
+  test("missing role in graph → error", async () => {
+    const context = makeContext([
+      {
+        role: "unknown-role",
+        output: {},
+        detail: "2MXBG6PN4A8JR",
+        agent: "uwf-hermes",
+      },
+    ]);
+    const result = await evaluate(solveIssueWorkflow, context);
     expect(result.ok).toBe(false);
     if (!result.ok) {
       expect(result.error.message).toBe('no transitions defined for role "unknown-role"');
     }
   });
 
-  test("missing status in graph → error", () => {
-    const result = evaluate(solveIssueGraph, "reviewer", { status: "pending" });
-    expect(result.ok).toBe(false);
-    if (!result.ok) {
-      expect(result.error.message).toBe('no transition for role "reviewer" with status "pending"');
-    }
-  });
-
-  test("mustache template rendering with simple fields", () => {
-    const result = evaluate(solveIssueGraph, "planner", {
-      status: "_",
-      plan: "Add auth middleware",
-    });
+  test("output expansion in context works with JSONata", async () => {
+    const context = makeContext([
+      {
+        role: "planner",
+        output: { needsClarification: true },
+        detail: "7BQST3VW9F2MA",
+        agent: "uwf-hermes",
+      },
+    ]);
+    const result = await evaluate(solveIssueWorkflow, context);
     expect(result).toEqual({
       ok: true,
-      value: { role: "developer", prompt: "Implement the plan: Add auth middleware" },
+      value: { role: "developer", prompt: "Clarification is needed; hand off to developer." },
     });
   });
 
-  test("mustache template with nested object paths", () => {
-    const graph: Record<string, Record<string, Target>> = {
-      reviewer: {
-        _: {
-          role: "developer",
-          prompt: "Address: {{review.comments}}",
+  test("$last returns most recent matching role's frontmatter", async () => {
+    const workflow: WorkflowPayload = {
+      ...solveIssueWorkflow,
+      conditions: {
+        devFailed: {
+          description: "Developer failed",
+          expression: "$last('developer').status = 'failed'",
         },
       },
+      graph: {
+        $START: [
+          {
+            role: "developer",
+            condition: null,
+            prompt: "Begin development.",
+          },
+        ],
+        developer: [
+          { role: "$END", condition: "devFailed", prompt: "Development failed; end." },
+          {
+            role: "reviewer",
+            condition: null,
+            prompt: "Development succeeded; review.",
+          },
+        ],
+      },
     };
-    const result = evaluate(graph, "reviewer", {
-      status: "_",
-      review: { comments: "refactor the handler" },
-    });
+    const context = makeContext([
+      {
+        role: "developer",
+        output: { status: "done" },
+        detail: "1VPBG9SM5E7WK",
+        agent: "uwf-hermes",
+      },
+      {
+        role: "reviewer",
+        output: { approved: false },
+        detail: "2MXBG6PN4A8JR",
+        agent: "uwf-hermes",
+      },
+      {
+        role: "developer",
+        output: { status: "failed" },
+        detail: "3QNTH7WK8D2PA",
+        agent: "uwf-hermes",
+      },
+    ]);
+    const result = await evaluate(workflow, context);
     expect(result).toEqual({
       ok: true,
-      value: { role: "developer", prompt: "Address: refactor the handler" },
+      value: { role: "$END", prompt: "Development failed; end." },
+    });
+  });
+
+  test("$first returns earliest matching role's frontmatter", async () => {
+    const workflow: WorkflowPayload = {
+      ...solveIssueWorkflow,
+      conditions: {
+        firstPlanReady: {
+          description: "First planner run was ready",
+          expression: "$first('planner').status = 'ready'",
+        },
+      },
+      graph: {
+        $START: [
+          {
+            role: "planner",
+            condition: null,
+            prompt: "Begin planning.",
+          },
+        ],
+        planner: [
+          { role: "$END", condition: "firstPlanReady", prompt: "First plan was ready; end." },
+          {
+            role: "developer",
+            condition: null,
+            prompt: "Plan not ready on first pass; implement.",
+          },
+        ],
+      },
+    };
+    const context = makeContext([
+      {
+        role: "planner",
+        output: { status: "ready", plan: "ABC123" },
+        detail: "7BQST3VW9F2MA",
+        agent: "uwf-hermes",
+      },
+      {
+        role: "developer",
+        output: { status: "done" },
+        detail: "1VPBG9SM5E7WK",
+        agent: "uwf-hermes",
+      },
+      {
+        role: "planner",
+        output: { status: "revised", plan: "DEF456" },
+        detail: "4RNMK6PX8B3WQ",
+        agent: "uwf-hermes",
+      },
+    ]);
+    const result = await evaluate(workflow, context);
+    expect(result).toEqual({
+      ok: true,
+      value: { role: "$END", prompt: "First plan was ready; end." },
+    });
+  });
+
+  test("$last returns undefined for unmatched role", async () => {
+    const workflow: WorkflowPayload = {
+      ...solveIssueWorkflow,
+      conditions: {
+        hasReviewer: {
+          description: "Reviewer has run",
+          expression: "$exists($last('reviewer'))",
+        },
+      },
+      graph: {
+        $START: [
+          {
+            role: "planner",
+            condition: null,
+            prompt: "Begin planning.",
+          },
+        ],
+        planner: [
+          { role: "$END", condition: "hasReviewer", prompt: "Reviewer already ran; end." },
+          {
+            role: "developer",
+            condition: null,
+            prompt: "No reviewer yet; implement.",
+          },
+        ],
+      },
+    };
+    const context = makeContext([
+      {
+        role: "planner",
+        output: { status: "ready" },
+        detail: "7BQST3VW9F2MA",
+        agent: "uwf-hermes",
+      },
+    ]);
+    const result = await evaluate(workflow, context);
+    // no reviewer step → $exists returns false → fallback to developer
+    expect(result).toEqual({
+      ok: true,
+      value: { role: "developer", prompt: "No reviewer yet; implement." },
     });
   });
 });

packages/workflow-moderator/package.json

@@ -19,10 +19,9 @@
   },
   "dependencies": {
     "@uncaged/workflow-protocol": "workspace:^",
-    "mustache": "^4.2.0"
+    "jsonata": "^1.8.7"
   },
   "devDependencies": {
-    "@types/mustache": "^4.2.6",
     "typescript": "^5.8.3"
   },
   "publishConfig": {

packages/workflow-moderator/src/evaluate.ts

@@ -1,39 +1,65 @@
-import type { Target } from "@uncaged/workflow-protocol";
-import mustache from "mustache";
+import type { ModeratorContext, WorkflowPayload } from "@uncaged/workflow-protocol";
+import jsonata from "jsonata";
 
 import type { EvaluateResult, Result } from "./types.js";
 
 const START_ROLE = "$START";
-const UNIT_STATUS = "_";
 
-type LastOutput = Record<string, unknown> & { status: string };
-
-export function evaluate(
-  graph: Record<string, Record<string, Target>>,
-  lastRole: string,
-  lastOutput: LastOutput,
-): Result<EvaluateResult, Error> {
-  const status = lastRole === START_ROLE ? UNIT_STATUS : lastOutput.status;
-
-  const roleTargets = graph[lastRole];
-  if (roleTargets === undefined) {
-    return {
-      ok: false,
-      error: new Error(`no transitions defined for role "${lastRole}"`),
-    };
+function isTruthy(value: unknown): boolean {
+  if (value === null || value === undefined) {
+    return false;
   }
-
-  const target = roleTargets[status];
-  if (target === undefined) {
-    return {
-      ok: false,
-      error: new Error(`no transition for role "${lastRole}" with status "${status}"`),
-    };
+  if (typeof value === "boolean") {
+    return value;
   }
+  if (typeof value === "number") {
+    return value !== 0 && !Number.isNaN(value);
+  }
+  if (typeof value === "string") {
+    return value.length > 0;
+  }
+  return true;
+}
 
+function findByRole(
+  steps: ModeratorContext["steps"],
+  role: string,
+  direction: "first" | "last",
+): unknown {
+  if (direction === "last") {
+    for (let i = steps.length - 1; i >= 0; i--) {
+      if (steps[i].role === role) {
+        return steps[i].output;
+      }
+    }
+  } else {
+    for (const step of steps) {
+      if (step.role === role) {
+        return step.output;
+      }
+    }
+  }
+  return undefined;
+}
+
+async function evaluateJsonata(
+  expression: string,
+  context: ModeratorContext,
+): Promise<Result<unknown, Error>> {
   try {
-    const prompt = mustache.render(target.prompt, lastOutput);
-    return { ok: true, value: { role: target.role, prompt } };
+    const expr = jsonata(expression);
+    expr.registerFunction(
+      "first",
+      (role: string) => findByRole(context.steps, role, "first"),
+      "<s:x>",
+    );
+    expr.registerFunction(
+      "last",
+      (role: string) => findByRole(context.steps, role, "last"),
+      "<s:x>",
+    );
+    const result = await expr.evaluate(context);
+    return { ok: true, value: result };
   } catch (error) {
     return {
       ok: false,
@@ -41,3 +67,51 @@ export function evaluate(
     };
   }
 }
+
+function currentRole(context: ModeratorContext): string {
+  if (context.steps.length === 0) {
+    return START_ROLE;
+  }
+  return context.steps[context.steps.length - 1].role;
+}
+
+export async function evaluate(
+  workflow: WorkflowPayload,
+  context: ModeratorContext,
+): Promise<Result<EvaluateResult, Error>> {
+  const role = currentRole(context);
+  const transitions = workflow.graph[role];
+  if (transitions === undefined) {
+    return {
+      ok: false,
+      error: new Error(`no transitions defined for role "${role}"`),
+    };
+  }
+
+  for (const transition of transitions) {
+    if (transition.condition === null) {
+      return { ok: true, value: { role: transition.role, prompt: transition.prompt } };
+    }
+
+    const conditionDef = workflow.conditions[transition.condition];
+    if (conditionDef === undefined) {
+      return {
+        ok: false,
+        error: new Error(`unknown condition "${transition.condition}"`),
+      };
+    }
+
+    const evalResult = await evaluateJsonata(conditionDef.expression, context);
+    if (!evalResult.ok) {
+      return evalResult;
+    }
+    if (isTruthy(evalResult.value)) {
+      return { ok: true, value: { role: transition.role, prompt: transition.prompt } };
+    }
+  }
+
+  return {
+    ok: false,
+    error: new Error(`no transition matched for role "${role}"`),
+  };
+}

packages/workflow-protocol/src/index.ts

@@ -7,6 +7,7 @@ export type {
   AgentAlias,
   AgentConfig,
   CasRef,
+  ConditionDefinition,
   ModelAlias,
   ModelConfig,
   ModeratorContext,
@@ -25,12 +26,12 @@ export type {
   StepNodePayload,
   StepOutput,
   StepRecord,
-  Target,
   ThreadForkOutput,
   ThreadId,
   ThreadListItem,
   ThreadStepsOutput,
   ThreadsIndex,
+  Transition,
   WorkflowConfig,
   WorkflowName,
   WorkflowPayload,

packages/workflow-protocol/src/schemas.ts

@@ -14,11 +14,22 @@ const ROLE_DEFINITION: JSONSchema = {
   additionalProperties: false,
 };
 
-const TARGET: JSONSchema = {
+const CONDITION_DEFINITION: JSONSchema = {
   type: "object",
-  required: ["role", "prompt"],
+  required: ["description", "expression"],
+  properties: {
+    description: { type: "string" },
+    expression: { type: "string" },
+  },
+  additionalProperties: false,
+};
+
+const TRANSITION: JSONSchema = {
+  type: "object",
+  required: ["role", "condition", "prompt"],
   properties: {
     role: { type: "string" },
+    condition: { anyOf: [{ type: "string" }, { type: "null" }] },
     prompt: { type: "string" },
   },
   additionalProperties: false,
@@ -27,7 +38,7 @@ const TARGET: JSONSchema = {
 export const WORKFLOW_SCHEMA: JSONSchema = {
   title: "Workflow",
   type: "object",
-  required: ["name", "description", "roles", "graph"],
+  required: ["name", "description", "roles", "conditions", "graph"],
   properties: {
     name: { type: "string" },
     description: { type: "string" },
@@ -35,11 +46,15 @@ export const WORKFLOW_SCHEMA: JSONSchema = {
       type: "object",
       additionalProperties: ROLE_DEFINITION,
     },
+    conditions: {
+      type: "object",
+      additionalProperties: CONDITION_DEFINITION,
+    },
     graph: {
       type: "object",
       additionalProperties: {
-        type: "object",
-        additionalProperties: TARGET,
+        type: "array",
+        items: TRANSITION,
       },
     },
   },

packages/workflow-protocol/src/types.ts

@@ -27,16 +27,23 @@ export type RoleDefinition = {
   frontmatter: CasRef;
 };
 
-export type Target = {
+export type Transition = {
   role: string;
+  condition: string | null;
   prompt: string;
 };
 
+export type ConditionDefinition = {
+  description: string;
+  expression: string;
+};
+
 export type WorkflowPayload = {
   name: string;
   description: string;
   roles: Record<string, RoleDefinition>;
-  graph: Record<string, Record<string, Target>>;
+  conditions: Record<string, ConditionDefinition>;
+  graph: Record<string, Transition[]>;
 };
 
 // ── 4.3 Thread 节点 ─────────────────────────────────────────────────