@assistkick/create 1.7.0 → 1.8.0

package/templates/assistkick-product-system/packages/shared/lib/workflow_engine.test.ts

@@ -0,0 +1,1753 @@
+import { describe, it, mock, beforeEach } from 'node:test';
+import assert from 'node:assert/strict';
+import { WorkflowEngine } from './workflow_engine.ts';
+
+// ── Default workflow graph (matches seeded data) ──────────────────────
+
+const DEFAULT_GRAPH = {
+  nodes: [
+    { id: 'start_1', type: 'start', position: { x: 50, y: 250 }, data: { label: 'Start' } },
+    { id: 'transition_1', type: 'transitionCard', position: { x: 250, y: 250 }, data: { label: 'Move to In Progress', fromColumn: 'todo', toColumn: 'in_progress' } },
+    { id: 'agent_dev', type: 'runAgent', position: { x: 500, y: 250 }, data: { label: 'Run Developer', agentId: 'dev-agent-id' } },
+    { id: 'transition_2', type: 'transitionCard', position: { x: 750, y: 250 }, data: { label: 'Move to In Review', fromColumn: 'in_progress', toColumn: 'in_review' } },
+    { id: 'agent_rev', type: 'runAgent', position: { x: 1000, y: 250 }, data: { label: 'Run Reviewer', agentId: 'rev-agent-id' } },
+    { id: 'check_pos', type: 'checkCardPosition', position: { x: 1250, y: 250 }, data: { label: 'Check Card Position' } },
+    { id: 'end_success', type: 'end', position: { x: 1500, y: 100 }, data: { label: 'End (Success)', outcome: 'success' } },
+    { id: 'check_cycle', type: 'checkCycleCount', position: { x: 1500, y: 400 }, data: { label: 'Check Cycle Count', maxCycles: 3 } },
+    { id: 'set_meta', type: 'setCardMetadata', position: { x: 1750, y: 400 }, data: { label: 'Set dev_blocked', key: 'dev_blocked', value: 'true' } },
+    { id: 'end_blocked', type: 'end', position: { x: 2000, y: 400 }, data: { label: 'End (Blocked)', outcome: 'blocked' } },
+  ],
+  edges: [
+    { id: 'e_start_t1', source: 'start_1', target: 'transition_1' },
+    { id: 'e_t1_dev', source: 'transition_1', target: 'agent_dev' },
+    { id: 'e_dev_t2', source: 'agent_dev', target: 'transition_2' },
+    { id: 'e_t2_rev', source: 'transition_2', target: 'agent_rev' },
+    { id: 'e_rev_check', source: 'agent_rev', target: 'check_pos' },
+    { id: 'e_check_success', source: 'check_pos', target: 'end_success', sourceHandle: 'qa', data: { label: 'qa' } },
+    { id: 'e_check_cycle', source: 'check_pos', target: 'check_cycle', sourceHandle: 'todo', data: { label: 'todo' } },
+    { id: 'e_cycle_dev', source: 'check_cycle', target: 'agent_dev', sourceHandle: 'under_limit', data: { label: '< 3' } },
+    { id: 'e_cycle_meta', source: 'check_cycle', target: 'set_meta', sourceHandle: 'at_limit', data: { label: '>= 3' } },
+    { id: 'e_meta_blocked', source: 'set_meta', target: 'end_blocked' },
+  ],
+};
+
+const WORKFLOW_ID = 'test-workflow-id';
+
+// ── Drizzle Condition Extraction ─────────────────────────────────────
+
+/**
+ * Recursively flatten drizzle SQL queryChunks into a flat array of
+ * Column, Param, and StringChunk objects.
+ */
+const flattenChunks = (obj: any): any[] => {
+  if (!obj || typeof obj !== 'object') return [];
+  if (Array.isArray(obj.queryChunks)) {
+    return obj.queryChunks.flatMap((c: any) => flattenChunks(c));
+  }
+  return [obj];
+};
+
+/**
+ * Extract {column, value} pairs from a drizzle eq()/and() condition.
+ * Column objects have .name (string) and .table (object).
+ * Param objects have .value (non-array scalar).
+ * StringChunk objects have .value as string[] — skipped.
+ */
+const extractEqPairs = (condition: any): Array<{ column: string; value: any }> => {
+  const flat = flattenChunks(condition);
+  const pairs: Array<{ column: string; value: any }> = [];
+  let lastColumnName: string | null = null;
+
+  for (const item of flat) {
+    if (!item || typeof item !== 'object') continue;
+
+    // Column: has 'name' (string) and 'table' (object reference)
+    if (typeof item.name === 'string' && item.table && typeof item.table === 'object') {
+      lastColumnName = item.name;
+    }
+    // Param: has 'value' that is NOT an array (StringChunks have string[] values)
+    else if ('value' in item && !Array.isArray(item.value) && lastColumnName !== null) {
+      pairs.push({ column: lastColumnName, value: item.value });
+      lastColumnName = null;
+    }
+  }
+
+  return pairs;
+};
+
+/** Convert snake_case DB column name to camelCase store key */
+const snakeToCamel = (s: string): string => {
+  return s.replace(/_([a-z])/g, (_, c) => c.toUpperCase());
+};
+
+// ── Mock Builders ─────────────────────────────────────────────────────
+
+/** In-memory store for workflow_executions and workflow_node_executions */
+const createMockDb = (graphData = DEFAULT_GRAPH) => {
+  const executionsStore: Record<string, any> = {};
+  const nodeExecutionsStore: Record<string, any> = {};
+  const toolCallsStore: Record<string, any> = {};
+  const workflowsStore: Record<string, any> = {
+    [WORKFLOW_ID]: {
+      id: WORKFLOW_ID,
+      name: 'Test Workflow',
+      description: null,
+      projectId: null,
+      isDefault: 1,
+      graphData: JSON.stringify(graphData),
+      createdAt: '2026-01-01T00:00:00.000Z',
+      updatedAt: '2026-01-01T00:00:00.000Z',
+    },
+  };
+  const agentsStore: Record<string, any> = {
+    'dev-agent-id': {
+      id: 'dev-agent-id',
+      name: 'Developer',
+      promptTemplate: 'Implement feature {{featureId}} in {{worktreePath}}',
+      projectId: null,
+      isDefault: 1,
+    },
+    'rev-agent-id': {
+      id: 'rev-agent-id',
+      name: 'Reviewer',
+      promptTemplate: 'Review feature {{featureId}}',
+      projectId: null,
+      isDefault: 1,
+    },
+  };
+  const graphNodesStore: Record<string, any> = {
+    'feat_test': {
+      id: 'feat_test',
+      type: 'feature',
+      name: 'Product Feature Walkthrough',
+      status: 'draft',
+      priority: 'medium',
+      body: '## Description\nA walkthrough video showing the product features.\n\n## Acceptance Criteria\n- AC 1\n',
+      projectId: null,
+    },
+  };
+
+  // Track all DB operations for assertions
+  const operations: Array<{ op: string; table: string; data: any }> = [];
+
+  // Helper to resolve table name from drizzle table reference
+  const resolveTableName = (table: any): string => {
+    if (table && typeof table === 'object') {
+      const name = table[Symbol.for('drizzle:Name')];
+      if (name) return name;
+    }
+    return 'unknown';
+  };
+
+  const getStoreForTable = (tableName: string): Record<string, any> | null => {
+    switch (tableName) {
+      case 'workflow_executions': return executionsStore;
+      case 'workflow_node_executions': return nodeExecutionsStore;
+      case 'workflow_tool_calls': return toolCallsStore;
+      case 'workflows': return workflowsStore;
+      case 'agents': return agentsStore;
+      case 'nodes': return graphNodesStore;
+      default: return null;
+    }
+  };
+
+  /** Match a row against a drizzle eq()/and() condition */
+  const matchesCondition = (row: any, condition: any, _tableName: string): boolean => {
+    const pairs = extractEqPairs(condition);
+    if (pairs.length === 0) return true;
+    return pairs.every(({ column, value }) => {
+      const prop = snakeToCamel(column);
+      return row[prop] === value;
+    });
+  };
+
+  // Build a chainable mock that handles select/from/where patterns
+  const db = {
+    _stores: { executionsStore, nodeExecutionsStore, toolCallsStore, workflowsStore, agentsStore, graphNodesStore },
+    _operations: operations,
+
+    select: () => ({
+      from: (table: any) => {
+        const tableName = resolveTableName(table);
+        return {
+          where: (condition: any) => {
+            const store = getStoreForTable(tableName);
+            if (!store) return [];
+            return Object.values(store).filter((row: any) => {
+              return matchesCondition(row, condition, tableName);
+            });
+          },
+        };
+      },
+    }),
+
+    insert: (table: any) => ({
+      values: (data: any) => {
+        const tableName = resolveTableName(table);
+        const store = getStoreForTable(tableName);
+        if (store && data.id) {
+          store[data.id] = { ...data };
+        }
+        operations.push({ op: 'insert', table: tableName, data });
+        return Promise.resolve();
+      },
+    }),
+
+    update: (table: any) => ({
+      set: (data: any) => ({
+        where: (condition: any) => {
+          const tableName = resolveTableName(table);
+          const store = getStoreForTable(tableName);
+          if (store) {
+            for (const [_key, row] of Object.entries(store)) {
+              if (matchesCondition(row, condition, tableName)) {
+                Object.assign(row as any, data);
+              }
+            }
+          }
+          operations.push({ op: 'update', table: tableName, data });
+          return Promise.resolve();
+        },
+      }),
+    }),
+  };
+
+  return db;
+};
+
+/** Creates a mock kanban with controllable card state */
+const createMockKanban = (initialColumn = 'todo') => {
+  const entries: Record<string, any> = {
+    'feat_test': {
+      column: initialColumn,
+      rejection_count: 0,
+      notes: [],
+      reviews: [],
+    },
+  };
+
+  return {
+    getKanbanEntry: mock.fn(async (featureId: string) => {
+      return entries[featureId] || null;
+    }),
+    saveKanbanEntry: mock.fn(async (featureId: string, entry: any) => {
+      entries[featureId] = { ...entry };
+    }),
+    _entries: entries,
+  };
+};
+
+const createMockClaudeService = () => ({
+  spawnClaude: mock.fn(async () => 'Agent output text'),
+  spawnCommand: mock.fn(async () => ''),
+});
+
+const createMockGitWorkflow = () => ({
+  createWorktree: mock.fn(async (featureId: string) => `/tmp/worktrees/${featureId}`),
+  removeWorktree: mock.fn(async () => {}),
+  deleteBranch: mock.fn(async () => {}),
+  commitChanges: mock.fn(async () => {}),
+  rebaseBranch: mock.fn(async () => {}),
+  mergeBranch: mock.fn(async () => {}),
+  fixMergeConflicts: mock.fn(async () => true),
+  stash: mock.fn(async () => false),
+  unstash: mock.fn(async () => {}),
+  getDirtyFiles: mock.fn(async () => []),
+});
+
+const createMockLog = () => mock.fn((_tag: string, _msg: string) => {});
+
+/** Default execution context for handler tests */
+const defaultContext = (overrides?: Record<string, unknown>) => ({
+  cycle: 0,
+  featureId: 'feat_test',
+  projectId: null,
+  worktreePath: '/tmp/wt',
+  branchName: 'feature/feat_test',
+  ...overrides,
+});
+
+// ── Tests ─────────────────────────────────────────────────────────────
+
+describe('WorkflowEngine', () => {
+  describe('resolvePromptTemplate', () => {
+    it('replaces known placeholders from context', () => {
+      const engine = new WorkflowEngine({
+        db: createMockDb() as any,
+        kanban: createMockKanban(),
+        claudeService: createMockClaudeService(),
+        gitWorkflow: createMockGitWorkflow(),
+        log: createMockLog(),
+      });
+
+      const result = (engine as any).resolvePromptTemplate(
+        'Feature: {{featureId}}, Path: {{worktreePath}}, Cycle: {{cycle}}',
+        { featureId: 'feat_001', worktreePath: '/tmp/wt', cycle: 2, projectId: null, branchName: 'feature/feat_001' },
+      );
+
+      assert.equal(result, 'Feature: feat_001, Path: /tmp/wt, Cycle: 2');
+    });
+
+    it('leaves unknown placeholders as-is', () => {
+      const engine = new WorkflowEngine({
+        db: createMockDb() as any,
+        kanban: createMockKanban(),
+        claudeService: createMockClaudeService(),
+        gitWorkflow: createMockGitWorkflow(),
+        log: createMockLog(),
+      });
+
+      const result = (engine as any).resolvePromptTemplate(
+        'Hello {{featureId}} and {{unknownVar}}',
+        { featureId: 'feat_001', worktreePath: '/tmp', cycle: 1, projectId: null, branchName: 'b' },
+      );
+
+      assert.equal(result, 'Hello feat_001 and {{unknownVar}}');
+    });
+
+    it('resolves mainToolsDir, mainSkillDir, and pidFlag from context', () => {
+      const engine = new WorkflowEngine({
+        db: createMockDb() as any,
+        kanban: createMockKanban(),
+        claudeService: createMockClaudeService(),
+        gitWorkflow: createMockGitWorkflow(),
+        log: createMockLog(),
+      });
+
+      const context = {
+        featureId: 'feat_001',
+        worktreePath: '/tmp/wt',
+        cycle: 0,
+        projectId: 'proj_abc',
+        branchName: 'feature/feat_001',
+        mainSkillDir: '/repo/root',
+        mainToolsDir: '/repo/root/packages/shared/tools',
+        pidFlag: ' --project-id proj_abc',
+      };
+
+      const result = (engine as any).resolvePromptTemplate(
+        'cd {{mainSkillDir}} && node {{mainToolsDir}}/get_node.ts {{featureId}}{{pidFlag}}',
+        context,
+      );
+
+      assert.equal(
+        result,
+        'cd /repo/root && node /repo/root/packages/shared/tools/get_node.ts feat_001 --project-id proj_abc',
+      );
+    });
+  });
+
+  describe('resolveNextNode', () => {
+    it('follows single outgoing edge when outputLabel is null', () => {
+      const engine = new WorkflowEngine({
+        db: createMockDb() as any,
+        kanban: createMockKanban(),
+        claudeService: createMockClaudeService(),
+        gitWorkflow: createMockGitWorkflow(),
+        log: createMockLog(),
+      });
+
+      const result = (engine as any).resolveNextNode(DEFAULT_GRAPH, 'start_1', null);
+      assert.equal(result, 'transition_1');
+    });
+
+    it('follows edge matching sourceHandle', () => {
+      const engine = new WorkflowEngine({
+        db: createMockDb() as any,
+        kanban: createMockKanban(),
+        claudeService: createMockClaudeService(),
+        gitWorkflow: createMockGitWorkflow(),
+        log: createMockLog(),
+      });
+
+      const result = (engine as any).resolveNextNode(DEFAULT_GRAPH, 'check_pos', 'qa');
+      assert.equal(result, 'end_success');
+    });
+
+    it('follows todo edge from check_pos', () => {
+      const engine = new WorkflowEngine({
+        db: createMockDb() as any,
+        kanban: createMockKanban(),
+        claudeService: createMockClaudeService(),
+        gitWorkflow: createMockGitWorkflow(),
+        log: createMockLog(),
+      });
+
+      const result = (engine as any).resolveNextNode(DEFAULT_GRAPH, 'check_pos', 'todo');
+      assert.equal(result, 'check_cycle');
+    });
+
+    it('follows under_limit edge from check_cycle', () => {
+      const engine = new WorkflowEngine({
+        db: createMockDb() as any,
+        kanban: createMockKanban(),
+        claudeService: createMockClaudeService(),
+        gitWorkflow: createMockGitWorkflow(),
+        log: createMockLog(),
+      });
+
+      const result = (engine as any).resolveNextNode(DEFAULT_GRAPH, 'check_cycle', 'under_limit');
+      assert.equal(result, 'agent_dev');
+    });
+
+    it('follows at_limit edge from check_cycle', () => {
+      const engine = new WorkflowEngine({
+        db: createMockDb() as any,
+        kanban: createMockKanban(),
+        claudeService: createMockClaudeService(),
+        gitWorkflow: createMockGitWorkflow(),
+        log: createMockLog(),
+      });
+
+      const result = (engine as any).resolveNextNode(DEFAULT_GRAPH, 'check_cycle', 'at_limit');
+      assert.equal(result, 'set_meta');
+    });
+
+    it('returns null when no outgoing edges exist', () => {
+      const engine = new WorkflowEngine({
+        db: createMockDb() as any,
+        kanban: createMockKanban(),
+        claudeService: createMockClaudeService(),
+        gitWorkflow: createMockGitWorkflow(),
+        log: createMockLog(),
+      });
+
+      const result = (engine as any).resolveNextNode(DEFAULT_GRAPH, 'end_success', null);
+      assert.equal(result, null);
+    });
+
+    it('throws when no edge matches the output label', () => {
+      const engine = new WorkflowEngine({
+        db: createMockDb() as any,
+        kanban: createMockKanban(),
+        claudeService: createMockClaudeService(),
+        gitWorkflow: createMockGitWorkflow(),
+        log: createMockLog(),
+      });
+
+      assert.throws(() => {
+        (engine as any).resolveNextNode(DEFAULT_GRAPH, 'check_pos', 'nonexistent');
+      }, /No outgoing edge.*matches output label "nonexistent"/);
+    });
+  });
+
+  describe('handleTransitionCard', () => {
+    it('moves card from source to target column', async () => {
+      const kanban = createMockKanban('todo');
+      const engine = new WorkflowEngine({
+        db: createMockDb() as any,
+        kanban,
+        claudeService: createMockClaudeService(),
+        gitWorkflow: createMockGitWorkflow(),
+        log: createMockLog(),
+      });
+
+      const node = { id: 't1', type: 'transitionCard', data: { fromColumn: 'todo', toColumn: 'in_progress' } };
+
+      const result = await (engine as any).handleTransitionCard(node, defaultContext());
+
+      assert.equal(result.outputLabel, null);
+      assert.equal(kanban._entries['feat_test'].column, 'in_progress');
+      assert.equal(kanban.saveKanbanEntry.mock.calls.length, 1);
+    });
+
+    it('throws when card is not in expected source column', async () => {
+      const kanban = createMockKanban('in_review');
+      const engine = new WorkflowEngine({
+        db: createMockDb() as any,
+        kanban,
+        claudeService: createMockClaudeService(),
+        gitWorkflow: createMockGitWorkflow(),
+        log: createMockLog(),
+      });
+
+      const node = { id: 't1', type: 'transitionCard', data: { fromColumn: 'todo', toColumn: 'in_progress' } };
+
+      await assert.rejects(
+        () => (engine as any).handleTransitionCard(node, defaultContext()),
+        /Expected card in "todo" but found in "in_review"/,
+      );
+    });
+
+    it('throws when feature not found in kanban', async () => {
+      const kanban = createMockKanban();
+      const engine = new WorkflowEngine({
+        db: createMockDb() as any,
+        kanban,
+        claudeService: createMockClaudeService(),
+        gitWorkflow: createMockGitWorkflow(),
+        log: createMockLog(),
+      });
+
+      const node = { id: 't1', type: 'transitionCard', data: { fromColumn: 'todo', toColumn: 'in_progress' } };
+
+      await assert.rejects(
+        () => (engine as any).handleTransitionCard(node, defaultContext({ featureId: 'nonexistent' })),
+        /not found in kanban/,
+      );
+    });
+  });
+
+  describe('handleCheckCardPosition', () => {
+    it('returns column name as outputLabel when card is in qa', async () => {
+      const kanban = createMockKanban('qa');
+      const engine = new WorkflowEngine({
+        db: createMockDb() as any,
+        kanban,
+        claudeService: createMockClaudeService(),
+        gitWorkflow: createMockGitWorkflow(),
+        log: createMockLog(),
+      });
+
+      const node = { id: 'cp', type: 'checkCardPosition', data: {} };
+
+      const result = await (engine as any).handleCheckCardPosition(node, defaultContext({ cycle: 1 }));
+      assert.equal(result.outputLabel, 'qa');
+    });
+
+    it('treats in_review as rejection and returns todo', async () => {
+      const kanban = createMockKanban('in_review');
+      const engine = new WorkflowEngine({
+        db: createMockDb() as any,
+        kanban,
+        claudeService: createMockClaudeService(),
+        gitWorkflow: createMockGitWorkflow(),
+        log: createMockLog(),
+      });
+
+      const node = { id: 'cp', type: 'checkCardPosition', data: {} };
+
+      const result = await (engine as any).handleCheckCardPosition(node, defaultContext({ cycle: 1 }));
+      assert.equal(result.outputLabel, 'todo');
+      assert.equal(kanban._entries['feat_test'].column, 'todo');
+    });
+
+    it('returns todo when card is in todo', async () => {
+      const kanban = createMockKanban('todo');
+      const engine = new WorkflowEngine({
+        db: createMockDb() as any,
+        kanban,
+        claudeService: createMockClaudeService(),
+        gitWorkflow: createMockGitWorkflow(),
+        log: createMockLog(),
+      });
+
+      const node = { id: 'cp', type: 'checkCardPosition', data: {} };
+
+      const result = await (engine as any).handleCheckCardPosition(node, defaultContext({ cycle: 1 }));
+      assert.equal(result.outputLabel, 'todo');
+    });
+  });
+
+  describe('handleCheckCycleCount', () => {
+    it('returns under_limit when cycle < max', async () => {
+      const engine = new WorkflowEngine({
+        db: createMockDb() as any,
+        kanban: createMockKanban(),
+        claudeService: createMockClaudeService(),
+        gitWorkflow: createMockGitWorkflow(),
+        log: createMockLog(),
+      });
+
+      const node = { id: 'cc', type: 'checkCycleCount', data: { maxCycles: 3 } };
+      const context = defaultContext();
+
+      const result = await (engine as any).handleCheckCycleCount(node, context);
+      assert.equal(result.outputLabel, 'under_limit');
+      assert.equal(context.cycle, 1);
+    });
+
+    it('returns at_limit when cycle reaches max', async () => {
+      const engine = new WorkflowEngine({
+        db: createMockDb() as any,
+        kanban: createMockKanban(),
+        claudeService: createMockClaudeService(),
+        gitWorkflow: createMockGitWorkflow(),
+        log: createMockLog(),
+      });
+
+      const node = { id: 'cc', type: 'checkCycleCount', data: { maxCycles: 3 } };
+      const context = defaultContext({ cycle: 2 });
+
+      const result = await (engine as any).handleCheckCycleCount(node, context);
+      assert.equal(result.outputLabel, 'at_limit');
+      assert.equal(context.cycle, 3);
+    });
+
+    it('increments cycle counter in context', async () => {
+      const engine = new WorkflowEngine({
+        db: createMockDb() as any,
+        kanban: createMockKanban(),
+        claudeService: createMockClaudeService(),
+        gitWorkflow: createMockGitWorkflow(),
+        log: createMockLog(),
+      });
+
+      const node = { id: 'cc', type: 'checkCycleCount', data: { maxCycles: 5 } };
+      const context = defaultContext({ cycle: 1 });
+
+      await (engine as any).handleCheckCycleCount(node, context);
+      assert.equal(context.cycle, 2);
+      await (engine as any).handleCheckCycleCount(node, context);
+      assert.equal(context.cycle, 3);
+    });
+  });
+
+  describe('handleSetCardMetadata', () => {
+    it('sets boolean metadata on card', async () => {
+      const kanban = createMockKanban('todo');
+      const engine = new WorkflowEngine({
+        db: createMockDb() as any,
+        kanban,
+        claudeService: createMockClaudeService(),
+        gitWorkflow: createMockGitWorkflow(),
+        log: createMockLog(),
+      });
+
+      const node = { id: 'sm', type: 'setCardMetadata', data: { key: 'dev_blocked', value: 'true' } };
+
+      const result = await (engine as any).handleSetCardMetadata(node, defaultContext({ cycle: 3 }));
+      assert.equal(result.outputLabel, null);
+      assert.equal(kanban._entries['feat_test'].dev_blocked, true);
+    });
+
+    it('sets string metadata on card', async () => {
+      const kanban = createMockKanban('todo');
+      const engine = new WorkflowEngine({
+        db: createMockDb() as any,
+        kanban,
+        claudeService: createMockClaudeService(),
+        gitWorkflow: createMockGitWorkflow(),
+        log: createMockLog(),
+      });
+
+      const node = { id: 'sm', type: 'setCardMetadata', data: { key: 'reason', value: 'too many cycles' } };
+
+      await (engine as any).handleSetCardMetadata(node, defaultContext({ cycle: 3 }));
+      assert.equal(kanban._entries['feat_test'].reason, 'too many cycles');
+    });
+  });
+
+  describe('handleStart', () => {
+    it('returns null outputLabel (passthrough)', async () => {
+      const engine = new WorkflowEngine({
+        db: createMockDb() as any,
+        kanban: createMockKanban(),
+        claudeService: createMockClaudeService(),
+        gitWorkflow: createMockGitWorkflow(),
+        log: createMockLog(),
+      });
+
+      const node = { id: 's1', type: 'start', data: {} };
+
+      const result = await (engine as any).handleStart(node, defaultContext());
+      assert.equal(result.outputLabel, null);
+    });
+  });
+
+  describe('handleEnd', () => {
+    it('merges, cleans up worktree, and sets completed on success outcome', async () => {
+      const db = createMockDb();
+      const gitWorkflow = createMockGitWorkflow();
+      const execId = 'test-exec-id';
+
+      db._stores.executionsStore[execId] = {
+        id: execId, workflowId: WORKFLOW_ID, featureId: 'feat_test',
+        status: 'running', currentNodeId: 'end_success',
+        context: '{}', startedAt: '2026-01-01', updatedAt: '2026-01-01',
+      };
+
+      const engine = new WorkflowEngine({
+        db: db as any, kanban: createMockKanban(), claudeService: createMockClaudeService(),
+        gitWorkflow, log: createMockLog(),
+      });
+
+      const node = { id: 'end_success', type: 'end', data: { outcome: 'success' } };
+      const context = defaultContext({ cycle: 1 });
+
+      await (engine as any).handleEnd(node, context, execId);
+
+      assert.equal(gitWorkflow.mergeBranch.mock.calls.length, 1);
+      assert.equal(gitWorkflow.removeWorktree.mock.calls.length, 1);
+      assert.equal(gitWorkflow.deleteBranch.mock.calls.length, 1);
+      assert.equal(db._stores.executionsStore[execId].status, 'completed');
+    });
+
+    it('cleans up worktree without merge and sets completed on blocked outcome', async () => {
+      const db = createMockDb();
+      const gitWorkflow = createMockGitWorkflow();
+      const execId = 'test-exec-id';
+
+      db._stores.executionsStore[execId] = {
+        id: execId, workflowId: WORKFLOW_ID, featureId: 'feat_test',
+        status: 'running', currentNodeId: 'end_blocked',
+        context: '{}', startedAt: '2026-01-01', updatedAt: '2026-01-01',
+      };
+
+      const engine = new WorkflowEngine({
+        db: db as any, kanban: createMockKanban(), claudeService: createMockClaudeService(),
+        gitWorkflow, log: createMockLog(),
+      });
+
+      const node = { id: 'end_blocked', type: 'end', data: { outcome: 'blocked' } };
+      const context = defaultContext({ cycle: 3 });
+
+      await (engine as any).handleEnd(node, context, execId);
+
+      assert.equal(gitWorkflow.mergeBranch.mock.calls.length, 0);
+      assert.equal(gitWorkflow.removeWorktree.mock.calls.length, 1);
+      assert.equal(gitWorkflow.deleteBranch.mock.calls.length, 1);
+      assert.equal(db._stores.executionsStore[execId].status, 'completed');
+    });
+
+    it('cleans up worktree without merge and sets failed on failed outcome', async () => {
+      const db = createMockDb();
+      const gitWorkflow = createMockGitWorkflow();
+      const execId = 'test-exec-id';
+
+      db._stores.executionsStore[execId] = {
+        id: execId, workflowId: WORKFLOW_ID, featureId: 'feat_test',
+        status: 'running', currentNodeId: 'end_fail',
+        context: '{}', startedAt: '2026-01-01', updatedAt: '2026-01-01',
+      };
+
+      const engine = new WorkflowEngine({
+        db: db as any, kanban: createMockKanban(), claudeService: createMockClaudeService(),
+        gitWorkflow, log: createMockLog(),
+      });
+
+      const node = { id: 'end_fail', type: 'end', data: { outcome: 'failed' } };
+      const context = defaultContext({ cycle: 1 });
+
+      await (engine as any).handleEnd(node, context, execId);
+
+      assert.equal(gitWorkflow.mergeBranch.mock.calls.length, 0);
+      assert.equal(gitWorkflow.removeWorktree.mock.calls.length, 1);
+      assert.equal(db._stores.executionsStore[execId].status, 'failed');
+    });
+  });
+
+  describe('handleRunAgent', () => {
+    it('loads agent, resolves template, calls spawnClaude, and stores actual output', async () => {
+      const db = createMockDb();
+      const claudeService = createMockClaudeService();
+      claudeService.spawnClaude = mock.fn(async () => 'The agent wrote this output text');
+
+      const engine = new WorkflowEngine({
+        db: db as any, kanban: createMockKanban(), claudeService,
+        gitWorkflow: createMockGitWorkflow(), log: createMockLog(),
+      });
+
+      const node = { id: 'run1', type: 'runAgent', data: { agentId: 'dev-agent-id' } };
+      const context = defaultContext({ cycle: 1 });
+
+      const result = await (engine as any).handleRunAgent(node, context, 'exec-id');
+
+      assert.equal(result.outputLabel, null);
+      // AC: actual output stored in outputData
+      assert.equal(result.outputData.output, 'The agent wrote this output text');
+      assert.equal(result.outputData.agentId, 'dev-agent-id');
+      assert.equal(result.outputData.agentName, 'Developer');
+
+      // Verify spawnClaude called with resolved prompt and worktree path
+      const call = claudeService.spawnClaude.mock.calls[0];
+      assert.equal(call.arguments[0], 'Implement feature feat_test in /tmp/wt');
+      assert.equal(call.arguments[1], '/tmp/wt');
+    });
+
+    it('passes onToolUse and onResult callbacks to spawnClaude', async () => {
+      const db = createMockDb();
+      const claudeService = createMockClaudeService();
+      claudeService.spawnClaude = mock.fn(async (_prompt: string, _cwd: string, _label: string, opts: any) => {
+        // Simulate tool use callbacks
+        if (opts?.onToolUse) {
+          opts.onToolUse('Read', { file_path: '/tmp/test.ts' });
+          opts.onToolUse('Edit', { file_path: '/tmp/test.ts' });
+          opts.onToolUse('Bash', { command: 'npm test' });
+          opts.onToolUse('Read', { file_path: '/tmp/other.ts' });
+        }
+        // Simulate result callback
+        if (opts?.onResult) {
+          opts.onResult({
+            costUsd: 0.5432,
+            numTurns: 12,
+            stopReason: 'end_turn',
+            model: 'claude-sonnet-4-6',
+            contextWindow: 42,
+          });
+        }
+        return 'Agent output';
+      });
+
+      const engine = new WorkflowEngine({
+        db: db as any, kanban: createMockKanban(), claudeService,
+        gitWorkflow: createMockGitWorkflow(), log: createMockLog(),
+      });
+
+      const node = { id: 'run1', type: 'runAgent', data: { agentId: 'dev-agent-id' } };
+      const context = defaultContext({ cycle: 1 });
+
+      const result = await (engine as any).handleRunAgent(node, context, 'exec-id');
+
+      // Verify tool calls accumulated correctly
+      assert.deepEqual(result.outputData.toolCalls, {
+        total: 4, read: 2, write: 0, edit: 1, bash: 1, glob: 0, grep: 0,
+      });
+      assert.equal(result.outputData.costUsd, 0.5432);
+      assert.equal(result.outputData.numTurns, 12);
+      assert.equal(result.outputData.stopReason, 'end_turn');
+      assert.equal(result.outputData.model, 'claude-sonnet-4-6');
+      assert.equal(result.outputData.contextWindowPct, 42);
+    });
+
+    it('stores zero metrics when no callbacks fire', async () => {
+      const db = createMockDb();
+      const claudeService = createMockClaudeService();
+
+      const engine = new WorkflowEngine({
+        db: db as any, kanban: createMockKanban(), claudeService,
+        gitWorkflow: createMockGitWorkflow(), log: createMockLog(),
+      });
+
+      const node = { id: 'run1', type: 'runAgent', data: { agentId: 'dev-agent-id' } };
+      const context = defaultContext({ cycle: 1 });
+
+      const result = await (engine as any).handleRunAgent(node, context, 'exec-id');
+
+      // Tool calls should be all zeros
+      assert.deepEqual(result.outputData.toolCalls, {
+        total: 0, read: 0, write: 0, edit: 0, bash: 0, glob: 0, grep: 0,
+      });
+      // Result metrics should be null (no callback fired)
+      assert.equal(result.outputData.costUsd, null);
+      assert.equal(result.outputData.numTurns, null);
+      assert.equal(result.outputData.stopReason, null);
+      assert.equal(result.outputData.model, null);
+      assert.equal(result.outputData.contextWindowPct, null);
+    });
+
+    it('throws when agent is not found in DB', async () => {
+      const db = createMockDb();
+
+      const engine = new WorkflowEngine({
+        db: db as any, kanban: createMockKanban(), claudeService: createMockClaudeService(),
+        gitWorkflow: createMockGitWorkflow(), log: createMockLog(),
+      });
+
+      const node = { id: 'run1', type: 'runAgent', data: { agentId: 'nonexistent-id' } };
+      const context = defaultContext({ cycle: 1 });
+
+      await assert.rejects(
+        () => (engine as any).handleRunAgent(node, context, 'exec-id'),
+        /Agent nonexistent-id not found/,
+      );
+    });
+
+    it('resolves multiple placeholders in prompt template', async () => {
+      const db = createMockDb();
+      db._stores.agentsStore['custom-agent'] = {
+        id: 'custom-agent',
+        name: 'Custom',
+        promptTemplate: 'Feature: {{featureId}}, Branch: {{branchName}}, Cycle: {{cycle}}',
+        projectId: null,
+        isDefault: 0,
+      };
+      const claudeService = createMockClaudeService();
+
+      const engine = new WorkflowEngine({
+        db: db as any, kanban: createMockKanban(), claudeService,
+        gitWorkflow: createMockGitWorkflow(), log: createMockLog(),
+      });
+
+      const node = { id: 'run1', type: 'runAgent', data: { agentId: 'custom-agent' } };
+      const context = defaultContext({ cycle: 2 });
+
+      await (engine as any).handleRunAgent(node, context, 'exec-id');
+
+      const call = claudeService.spawnClaude.mock.calls[0];
+      assert.equal(call.arguments[0], 'Feature: feat_test, Branch: feature/feat_test, Cycle: 2');
+    });
+  });
+
+  describe('getExecutionMetrics', () => {
+    it('returns metrics for runAgent nodes only', async () => {
+      const db = createMockDb();
+      const execId = 'metrics-exec-id';
+
+      // Pre-populate execution
+      db._stores.executionsStore[execId] = {
+        id: execId, workflowId: WORKFLOW_ID, featureId: 'feat_test',
+        status: 'completed', currentNodeId: 'end_success',
+        context: '{}', startedAt: '2026-01-01', updatedAt: '2026-01-01',
+      };
+
+      // Pre-populate node executions — mix of runAgent and non-runAgent
+      db._stores.nodeExecutionsStore['ne-start'] = {
+        id: 'ne-start', executionId: execId, nodeId: 'start_1',
+        status: 'completed', startedAt: '2026-01-01', completedAt: '2026-01-01',
+        outputData: null, error: null, attempt: 1,
+      };
+      db._stores.nodeExecutionsStore['ne-dev'] = {
+        id: 'ne-dev', executionId: execId, nodeId: 'agent_dev',
+        status: 'completed', startedAt: '2026-01-01', completedAt: '2026-01-01',
+        outputData: JSON.stringify({
+          agentName: 'Developer', toolCalls: { total: 10, read: 5, write: 2, edit: 1, bash: 2, glob: 0, grep: 0 },
+          costUsd: 0.25, numTurns: 8, stopReason: 'end_turn', model: 'claude-sonnet-4-6', contextWindowPct: 35,
+        }),
+        error: null, attempt: 1,
+      };
+      db._stores.nodeExecutionsStore['ne-rev'] = {
+        id: 'ne-rev', executionId: execId, nodeId: 'agent_rev',
+        status: 'completed', startedAt: '2026-01-01', completedAt: '2026-01-01',
+        outputData: JSON.stringify({
+          agentName: 'Reviewer', toolCalls: { total: 3, read: 2, write: 0, edit: 0, bash: 1, glob: 0, grep: 0 },
+          costUsd: 0.10, numTurns: 4, stopReason: 'end_turn', model: 'claude-haiku-4-5', contextWindowPct: 12,
+        }),
+        error: null, attempt: 1,
+      };
+      db._stores.nodeExecutionsStore['ne-transition'] = {
+        id: 'ne-transition', executionId: execId, nodeId: 'transition_1',
+        status: 'completed', startedAt: '2026-01-01', completedAt: '2026-01-01',
+        outputData: null, error: null, attempt: 1,
+      };
+
+      const engine = new WorkflowEngine({
+        db: db as any, kanban: createMockKanban(), claudeService: createMockClaudeService(),
+        gitWorkflow: createMockGitWorkflow(), log: createMockLog(),
+      });
+
+      const metrics = await engine.getExecutionMetrics(execId);
+
+      assert.equal(metrics.length, 2);
+      assert.equal(metrics[0].agentName, 'Developer');
+      assert.equal(metrics[0].costUsd, 0.25);
+      assert.equal(metrics[0].numTurns, 8);
+      assert.deepEqual(metrics[0].toolCalls, { total: 10, read: 5, write: 2, edit: 1, bash: 2, glob: 0, grep: 0 });
+      assert.equal(metrics[1].agentName, 'Reviewer');
+      assert.equal(metrics[1].costUsd, 0.10);
+    });
+
+    it('returns empty array when execution not found', async () => {
+      const db = createMockDb();
+      const engine = new WorkflowEngine({
+        db: db as any, kanban: createMockKanban(), claudeService: createMockClaudeService(),
+        gitWorkflow: createMockGitWorkflow(), log: createMockLog(),
+      });
+
+      const metrics = await engine.getExecutionMetrics('nonexistent');
+      assert.deepEqual(metrics, []);
+    });
+  });
+
+  describe('handleGroup', () => {
+    it('expands group internal nodes and executes them', async () => {
+      // A group containing: start → transitionCard (todo→in_progress)
+      const groupGraph = {
+        nodes: [
+          { id: 'start_1', type: 'start', data: {} },
+          { id: 'group_1', type: 'group', data: {
+            groupId: 'grp-1',
+            groupName: 'My Group',
+            internalNodes: [
+              { id: 'inner_start', type: 'start', data: {} },
+              { id: 'inner_transition', type: 'transitionCard', data: { fromColumn: 'todo', toColumn: 'in_progress' } },
+            ],
+            internalEdges: [
+              { id: 'inner_e1', source: 'inner_start', target: 'inner_transition' },
+            ],
+            inputHandles: ['input'],
+            outputHandles: ['output'],
+          }},
+          { id: 'end_1', type: 'end', data: { outcome: 'success' } },
+        ],
+        edges: [
+          { id: 'e1', source: 'start_1', target: 'group_1' },
+          { id: 'e2', source: 'group_1', target: 'end_1' },
+        ],
+      };
+
+      const db = createMockDb(groupGraph);
+      const kanban = createMockKanban('todo');
+      const gitWorkflow = createMockGitWorkflow();
+
+      const engine = new WorkflowEngine({
+        db: db as any, kanban, claudeService: createMockClaudeService(),
+        gitWorkflow, log: createMockLog(),
+      });
+
+      const { executionId } = await engine.start('feat_test', WORKFLOW_ID, 'proj_test');
+
+      // Wait for async fire-and-forget execution
+      await new Promise(resolve => setTimeout(resolve, 100));
+
+      // Card should have been moved from todo → in_progress by the inner transition node
+      assert.equal(kanban._entries['feat_test'].column, 'in_progress');
+      // Execution should have completed (success outcome)
+      assert.equal(db._stores.executionsStore[executionId].status, 'completed');
+    });
+
+    it('skips empty group and continues traversal', async () => {
+      const engine = new WorkflowEngine({
+        db: createMockDb() as any,
+        kanban: createMockKanban(),
+        claudeService: createMockClaudeService(),
+        gitWorkflow: createMockGitWorkflow(),
+        log: createMockLog(),
+      });
+
+      const emptyGroupNode = {
+        id: 'g1', type: 'group', data: {
+          groupId: 'grp-empty',
+          groupName: 'Empty Group',
+          internalNodes: [],
+          internalEdges: [],
+          inputHandles: ['input'],
+          outputHandles: ['output'],
+        },
+      };
+
+      const result = await (engine as any).handleGroup(emptyGroupNode, defaultContext(), 'exec-id');
+      assert.equal(result.outputLabel, null);
+    });
+  });
+
+  describe('executeNode', () => {
+    it('dispatches group node type correctly', async () => {
+      const engine = new WorkflowEngine({
+        db: createMockDb() as any,
+        kanban: createMockKanban(),
+        claudeService: createMockClaudeService(),
+        gitWorkflow: createMockGitWorkflow(),
+        log: createMockLog(),
+      });
+
+      const groupNode = {
+        id: 'g1', type: 'group', data: {
+          groupId: 'grp-1', groupName: 'Test Group',
+          internalNodes: [], internalEdges: [],
+          inputHandles: ['input'], outputHandles: ['output'],
+        },
+      };
+
+      // Should not throw — dispatches to handleGroup
+      const result = await (engine as any).executeNode(groupNode, defaultContext(), 'exec-id');
+      assert.equal(result.outputLabel, null);
+    });
+
+    it('throws for unknown node type', async () => {
+      const engine = new WorkflowEngine({
+        db: createMockDb() as any,
+        kanban: createMockKanban(),
+        claudeService: createMockClaudeService(),
+        gitWorkflow: createMockGitWorkflow(),
+        log: createMockLog(),
+      });
+
+      const node = { id: 'x', type: 'unknownType', data: {} };
+
+      await assert.rejects(
+        () => (engine as any).executeNode(node, defaultContext(), 'exec-id'),
+        /Unknown node type: unknownType/,
+      );
+    });
+  });
+
+  describe('start (integration)', () => {
+    it('passes projectId into context with computed mainSkillDir, mainToolsDir, and pidFlag', async () => {
+      const simpleGraph = {
+        nodes: [
+          { id: 'start_1', type: 'start', data: {} },
+          { id: 'end_1', type: 'end', data: { outcome: 'success' } },
+        ],
+        edges: [
+          { id: 'e1', source: 'start_1', target: 'end_1' },
+        ],
+      };
+
+      const db = createMockDb(simpleGraph);
+
+      const engine = new WorkflowEngine({
+        db: db as any, kanban: createMockKanban(),
+        claudeService: createMockClaudeService(),
+        gitWorkflow: createMockGitWorkflow(),
+        log: createMockLog(),
+      });
+
+      const { executionId } = await engine.start('feat_test', WORKFLOW_ID, 'proj_abc123');
+
+      await new Promise(resolve => setTimeout(resolve, 50));
+
+      const execution = db._stores.executionsStore[executionId];
+      const context = JSON.parse(execution.context);
+
+      assert.equal(context.projectId, 'proj_abc123');
+      assert.equal(context.pidFlag, ' --project-id proj_abc123');
+      assert.equal(context.mainSkillDir, process.cwd());
+      assert.ok(context.mainToolsDir.endsWith('packages/shared/tools'));
+    });
+
+    it('uses workflow.projectId when no projectId argument is passed', async () => {
+      const simpleGraph = {
+        nodes: [
+          { id: 'start_1', type: 'start', data: {} },
+          { id: 'end_1', type: 'end', data: { outcome: 'success' } },
+        ],
+        edges: [
+          { id: 'e1', source: 'start_1', target: 'end_1' },
+        ],
+      };
+
+      const db = createMockDb(simpleGraph);
+      // Set projectId on the workflow itself
+      db._stores.workflowsStore[WORKFLOW_ID].projectId = 'proj_from_workflow';
+
+      const engine = new WorkflowEngine({
+        db: db as any, kanban: createMockKanban(),
+        claudeService: createMockClaudeService(),
+        gitWorkflow: createMockGitWorkflow(),
+        log: createMockLog(),
+      });
+
+      const { executionId } = await engine.start('feat_test', WORKFLOW_ID, 'proj_test');
+
+      await new Promise(resolve => setTimeout(resolve, 50));
+
+      const execution = db._stores.executionsStore[executionId];
+      const context = JSON.parse(execution.context);
+
+      // projectId passed explicitly always takes precedence
+      assert.equal(context.projectId, 'proj_test');
+      assert.equal(context.pidFlag, ' --project-id proj_test');
+    });
+
+    it('creates execution, worktree, and traverses a simple graph to completion', async () => {
+      const simpleGraph = {
+        nodes: [
+          { id: 'start_1', type: 'start', data: {} },
+          { id: 'end_1', type: 'end', data: { outcome: 'success' } },
+        ],
+        edges: [
+          { id: 'e1', source: 'start_1', target: 'end_1' },
+        ],
+      };
+
+      const db = createMockDb(simpleGraph);
+      const gitWorkflow = createMockGitWorkflow();
+
+      const engine = new WorkflowEngine({
+        db: db as any, kanban: createMockKanban(),
+        claudeService: createMockClaudeService(), gitWorkflow,
+        log: createMockLog(),
+      });
+
+      const { executionId } = await engine.start('feat_test', WORKFLOW_ID, 'proj_test');
+
+      // Wait for async fire-and-forget execution to complete
+      await new Promise(resolve => setTimeout(resolve, 50));
+
+      // Execution row was created
+      assert.ok(db._stores.executionsStore[executionId]);
+      // Worktree was created
+      assert.equal(gitWorkflow.createWorktree.mock.calls.length, 1);
+      assert.equal(gitWorkflow.createWorktree.mock.calls[0].arguments[0], 'feat_test');
+      // Merge was called (success outcome)
+      assert.equal(gitWorkflow.mergeBranch.mock.calls.length, 1);
+      // Execution completed
+      assert.equal(db._stores.executionsStore[executionId].status, 'completed');
+      // Node executions were created for both nodes
+      const nodeExecs = Object.values(db._stores.nodeExecutionsStore);
+      assert.equal(nodeExecs.length, 2);
+    });
+
+    it('sets execution status to failed when a node throws', async () => {
+      const badGraph = {
+        nodes: [
+          { id: 'start_1', type: 'start', data: {} },
+          { id: 't1', type: 'transitionCard', data: { fromColumn: 'in_progress', toColumn: 'in_review' } },
+        ],
+        edges: [
+          { id: 'e1', source: 'start_1', target: 't1' },
+        ],
+      };
+
+      const db = createMockDb(badGraph);
+      const kanban = createMockKanban('todo'); // Card is in 'todo', not 'in_progress'
+
+      const engine = new WorkflowEngine({
+        db: db as any, kanban,
+        claudeService: createMockClaudeService(),
+        gitWorkflow: createMockGitWorkflow(),
+        log: createMockLog(),
+      });
+
+      const { executionId } = await engine.start('feat_test', WORKFLOW_ID, 'proj_test');
+
+      await new Promise(resolve => setTimeout(resolve, 50));
+
+      // Execution should be failed because transitionCard expected in_progress but got todo
+      assert.equal(db._stores.executionsStore[executionId].status, 'failed');
+      // Node execution for t1 should be failed
+      const failedNodes = Object.values(db._stores.nodeExecutionsStore)
+        .filter((ne: any) => ne.status === 'failed');
+      assert.equal(failedNodes.length, 1);
+      assert.match((failedNodes[0] as any).error, /Expected card in "in_progress"/);
+    });
+
+    it('enriches context with featureDescription from node body', async () => {
+      const simpleGraph = {
+        nodes: [
+          { id: 'start_1', type: 'start', data: {} },
+          { id: 'end_1', type: 'end', data: { outcome: 'success' } },
+        ],
+        edges: [
+          { id: 'e1', source: 'start_1', target: 'end_1' },
+        ],
+      };
+
+      const db = createMockDb(simpleGraph);
+
+      const engine = new WorkflowEngine({
+        db: db as any, kanban: createMockKanban(),
+        claudeService: createMockClaudeService(),
+        gitWorkflow: createMockGitWorkflow(),
+        log: createMockLog(),
+      });
+
+      const { executionId } = await engine.start('feat_test', WORKFLOW_ID, 'proj_test');
+      await new Promise(resolve => setTimeout(resolve, 50));
+
+      const execution = db._stores.executionsStore[executionId];
+      const context = JSON.parse(execution.context);
+
+      assert.equal(context.featureDescription, 'A walkthrough video showing the product features.');
+    });
+
+    it('enriches context with compositionName derived from feature name', async () => {
+      const simpleGraph = {
+        nodes: [
+          { id: 'start_1', type: 'start', data: {} },
+          { id: 'end_1', type: 'end', data: { outcome: 'success' } },
+        ],
+        edges: [
+          { id: 'e1', source: 'start_1', target: 'end_1' },
+        ],
+      };
+
+      const db = createMockDb(simpleGraph);
+
+      const engine = new WorkflowEngine({
+        db: db as any, kanban: createMockKanban(),
+        claudeService: createMockClaudeService(),
+        gitWorkflow: createMockGitWorkflow(),
+        log: createMockLog(),
+      });
+
+      const { executionId } = await engine.start('feat_test', WORKFLOW_ID, 'proj_test');
+      await new Promise(resolve => setTimeout(resolve, 50));
+
+      const execution = db._stores.executionsStore[executionId];
+      const context = JSON.parse(execution.context);
+
+      assert.equal(context.compositionName, 'product-feature-walkthrough');
+    });
+
+    it('enriches context with iterationComments from kanban notes', async () => {
+      const simpleGraph = {
+        nodes: [
+          { id: 'start_1', type: 'start', data: {} },
+          { id: 'end_1', type: 'end', data: { outcome: 'success' } },
+        ],
+        edges: [
+          { id: 'e1', source: 'start_1', target: 'end_1' },
+        ],
+      };
+
+      const db = createMockDb(simpleGraph);
+      const kanban = createMockKanban();
+      kanban._entries['feat_test'].notes = ['Fix scene 2 narration', 'Add outro scene'];
+
+      const engine = new WorkflowEngine({
+        db: db as any, kanban,
+        claudeService: createMockClaudeService(),
+        gitWorkflow: createMockGitWorkflow(),
+        log: createMockLog(),
+      });
+
+      const { executionId } = await engine.start('feat_test', WORKFLOW_ID, 'proj_test');
+      await new Promise(resolve => setTimeout(resolve, 50));
+
+      const execution = db._stores.executionsStore[executionId];
+      const context = JSON.parse(execution.context);
+
+      assert.ok(context.iterationComments.includes('Fix scene 2 narration'));
+      assert.ok(context.iterationComments.includes('Add outro scene'));
+      assert.ok(context.iterationComments.includes('Previous Review Notes'));
+    });
+
+    it('sets iterationComments to empty string when no kanban notes exist', async () => {
+      const simpleGraph = {
+        nodes: [
+          { id: 'start_1', type: 'start', data: {} },
+          { id: 'end_1', type: 'end', data: { outcome: 'success' } },
+        ],
+        edges: [
+          { id: 'e1', source: 'start_1', target: 'end_1' },
+        ],
+      };
+
+      const db = createMockDb(simpleGraph);
+
+      const engine = new WorkflowEngine({
+        db: db as any, kanban: createMockKanban(),
+        claudeService: createMockClaudeService(),
+        gitWorkflow: createMockGitWorkflow(),
+        log: createMockLog(),
+      });
+
+      const { executionId } = await engine.start('feat_test', WORKFLOW_ID, 'proj_test');
+      await new Promise(resolve => setTimeout(resolve, 50));
+
+      const execution = db._stores.executionsStore[executionId];
+      const context = JSON.parse(execution.context);
+
+      assert.equal(context.iterationComments, '');
+    });
+  });
+
+  describe('resume (integration)', () => {
+    it('resumes from a failed node, re-executes it, and completes', async () => {
+      const simpleGraph = {
+        nodes: [
+          { id: 'start_1', type: 'start', data: {} },
+          { id: 'end_1', type: 'end', data: { outcome: 'success' } },
+        ],
+        edges: [
+          { id: 'e1', source: 'start_1', target: 'end_1' },
+        ],
+      };
+
+      const db = createMockDb(simpleGraph);
+      const gitWorkflow = createMockGitWorkflow();
+      const execId = 'resume-exec-id';
+
+      // Pre-populate a failed execution at end_1
+      db._stores.executionsStore[execId] = {
+        id: execId, workflowId: WORKFLOW_ID, featureId: 'feat_test',
+        status: 'failed', currentNodeId: 'end_1',
+        context: JSON.stringify({
+          cycle: 0, featureId: 'feat_test', projectId: null,
+          worktreePath: '/tmp/worktrees/feat_test', branchName: 'feature/feat_test',
+        }),
+        startedAt: '2026-01-01', updatedAt: '2026-01-01',
+      };
+
+      // Pre-populate the failed node execution
+      db._stores.nodeExecutionsStore['ne-1'] = {
+        id: 'ne-1', executionId: execId, nodeId: 'end_1',
+        status: 'failed', startedAt: '2026-01-01', completedAt: null,
+        outputData: null, error: 'Previous error', attempt: 1,
+      };
+
+      const engine = new WorkflowEngine({
+        db: db as any, kanban: createMockKanban(),
+        claudeService: createMockClaudeService(), gitWorkflow,
+        log: createMockLog(),
+      });
+
+      await engine.resume(execId);
+
+      // Wait for async execution
+      await new Promise(resolve => setTimeout(resolve, 50));
+
+      // Execution should be completed
+      assert.equal(db._stores.executionsStore[execId].status, 'completed');
+      // The node execution was re-attempted (attempt incremented)
+      assert.ok(db._stores.nodeExecutionsStore['ne-1'].attempt >= 2);
+      // Merge was called (success outcome)
+      assert.equal(gitWorkflow.mergeBranch.mock.calls.length, 1);
+    });
+
+    it('resumes a stuck running execution by marking it failed first', async () => {
+      const db = createMockDb();
+      const execId = 'running-exec-id';
+
+      db._stores.executionsStore[execId] = {
+        id: execId, workflowId: WORKFLOW_ID, featureId: 'feat_test',
+        status: 'running', currentNodeId: 'start_1',
+        context: '{}', startedAt: '2026-01-01', updatedAt: '2026-01-01',
+      };
+
+      const engine = new WorkflowEngine({
+        db: db as any, kanban: createMockKanban(),
+        claudeService: createMockClaudeService(),
+        gitWorkflow: createMockGitWorkflow(),
+        log: createMockLog(),
+      });
+
+      // Should not throw — instead marks as failed then resumes
+      await engine.resume(execId);
+
+      // Wait for async execution
+      await new Promise(resolve => setTimeout(resolve, 50));
+
+      // The execution was marked as failed (from 'running') then resumed
+      // It may end up completed, failed (if no matching node in mock graph), or running
+      const finalStatus = db._stores.executionsStore[execId].status;
+      assert.ok(
+        ['running', 'completed', 'failed'].includes(finalStatus),
+        `Expected valid status, got: ${finalStatus}`,
+      );
+    });
+
+    it('throws when execution not found', async () => {
+      const db = createMockDb();
+
+      const engine = new WorkflowEngine({
+        db: db as any, kanban: createMockKanban(),
+        claudeService: createMockClaudeService(),
+        gitWorkflow: createMockGitWorkflow(),
+        log: createMockLog(),
+      });
+
+      await assert.rejects(
+        () => engine.resume('nonexistent-id'),
+        /not found/,
+      );
+    });
+  });
+
+  describe('constructor', () => {
+    it('accepts all required dependencies', () => {
+      const engine = new WorkflowEngine({
+        db: createMockDb() as any,
+        kanban: createMockKanban(),
+        claudeService: createMockClaudeService(),
+        gitWorkflow: createMockGitWorkflow(),
+        log: createMockLog(),
+      });
+
+      assert.ok(engine);
+      assert.equal(typeof engine.start, 'function');
+      assert.equal(typeof engine.resume, 'function');
+      assert.equal(typeof engine.getStatus, 'function');
+    });
+  });
+
+  describe('extractToolTarget', () => {
+    let engine: WorkflowEngine;
+
+    beforeEach(() => {
+      engine = new WorkflowEngine({
+        db: createMockDb() as any,
+        kanban: createMockKanban(),
+        claudeService: createMockClaudeService(),
+        gitWorkflow: createMockGitWorkflow(),
+        log: createMockLog(),
+      });
+    });
+
+    it('extracts file_path for Read tool', () => {
+      const result = (engine as any).extractToolTarget('Read', { file_path: '/src/index.ts' });
+      assert.equal(result, '/src/index.ts');
+    });
+
+    it('extracts file_path for Write tool', () => {
+      const result = (engine as any).extractToolTarget('Write', { file_path: '/src/app.ts', content: '...' });
+      assert.equal(result, '/src/app.ts');
+    });
+
+    it('extracts file_path for Edit tool', () => {
+      const result = (engine as any).extractToolTarget('Edit', { file_path: '/src/utils.ts', old_string: 'a', new_string: 'b' });
+      assert.equal(result, '/src/utils.ts');
+    });
+
+    it('extracts command for Bash tool', () => {
+      const result = (engine as any).extractToolTarget('Bash', { command: 'pnpm test' });
+      assert.equal(result, 'pnpm test');
+    });
+
+    it('extracts pattern for Grep tool', () => {
+      const result = (engine as any).extractToolTarget('Grep', { pattern: 'TODO', path: '/src' });
+      assert.equal(result, 'TODO');
+    });
+
+    it('extracts pattern for Glob tool', () => {
+      const result = (engine as any).extractToolTarget('Glob', { pattern: '**/*.ts' });
+      assert.equal(result, '**/*.ts');
+    });
+
+    it('handles case-insensitive tool names', () => {
+      const result = (engine as any).extractToolTarget('read', { file_path: '/foo.ts' });
+      assert.equal(result, '/foo.ts');
+    });
+
+    it('falls back to common fields for unknown tools', () => {
+      const result = (engine as any).extractToolTarget('CustomTool', { command: 'run-it' });
+      assert.equal(result, 'run-it');
+    });
+
+    it('returns empty string when no known fields present', () => {
+      const result = (engine as any).extractToolTarget('CustomTool', { foo: 'bar' });
+      assert.equal(result, '');
+    });
+
+    it('prefers filePath camelCase variant', () => {
+      const result = (engine as any).extractToolTarget('Read', { filePath: '/alt.ts' });
+      assert.equal(result, '/alt.ts');
+    });
+  });
+
+  describe('extractFeatureDescription', () => {
+    let engine: WorkflowEngine;
+
+    beforeEach(() => {
+      engine = new WorkflowEngine({
+        db: createMockDb() as any,
+        kanban: createMockKanban(),
+        claudeService: createMockClaudeService(),
+        gitWorkflow: createMockGitWorkflow(),
+        log: createMockLog(),
+      });
+    });
+
+    it('extracts description section from node body', () => {
+      const body = '## Description\nA video about our product.\n\n## Acceptance Criteria\n- AC 1\n';
+      const result = (engine as any).extractFeatureDescription(body, 'Fallback');
+      assert.equal(result, 'A video about our product.');
+    });
+
+    it('returns fallback when body is null', () => {
+      const result = (engine as any).extractFeatureDescription(null, 'Fallback Name');
+      assert.equal(result, 'Fallback Name');
+    });
+
+    it('returns fallback when body has no Description section', () => {
+      const body = '## Acceptance Criteria\n- AC 1\n';
+      const result = (engine as any).extractFeatureDescription(body, 'Feature Name');
+      assert.equal(result, 'Feature Name');
+    });
+
+    it('returns fallback when Description section is empty', () => {
+      const body = '## Description\n\n## Acceptance Criteria\n- AC 1\n';
+      const result = (engine as any).extractFeatureDescription(body, 'Feature Name');
+      assert.equal(result, 'Feature Name');
+    });
+
+    it('handles multiline descriptions', () => {
+      const body = '## Description\nLine one.\nLine two.\n\n## Notes\n';
+      const result = (engine as any).extractFeatureDescription(body, 'Fallback');
+      assert.equal(result, 'Line one.\nLine two.');
+    });
+  });
+
+  describe('deriveCompositionName', () => {
+    let engine: WorkflowEngine;
+
+    beforeEach(() => {
+      engine = new WorkflowEngine({
+        db: createMockDb() as any,
+        kanban: createMockKanban(),
+        claudeService: createMockClaudeService(),
+        gitWorkflow: createMockGitWorkflow(),
+        log: createMockLog(),
+      });
+    });
+
+    it('converts feature name to kebab-case', () => {
+      const result = (engine as any).deriveCompositionName('Product Feature Walkthrough');
+      assert.equal(result, 'product-feature-walkthrough');
+    });
+
+    it('strips special characters', () => {
+      const result = (engine as any).deriveCompositionName('My Video: Part 1 (Draft)');
+      assert.equal(result, 'my-video-part-1-draft');
+    });
+
+    it('removes leading and trailing hyphens', () => {
+      const result = (engine as any).deriveCompositionName('--test--');
+      assert.equal(result, 'test');
+    });
+  });
+
+  describe('getMonitorData', () => {
+    it('returns null when no execution exists for feature', async () => {
+      const db = createMockDb();
+      const engine = new WorkflowEngine({
+        db: db as any,
+        kanban: createMockKanban(),
+        claudeService: createMockClaudeService(),
+        gitWorkflow: createMockGitWorkflow(),
+        log: createMockLog(),
+      });
+
+      const result = await engine.getMonitorData('feat_nonexistent');
+      assert.equal(result, null);
+    });
+
+    it('returns full monitor data for an existing execution', async () => {
+      const db = createMockDb();
+      const execId = 'exec-1';
+      const nodeExecId = 'ne-1';
+
+      // Seed execution
+      db._stores.executionsStore[execId] = {
+        id: execId,
+        workflowId: WORKFLOW_ID,
+        featureId: 'feat_test',
+        status: 'completed',
+        currentNodeId: 'end_success',
+        startedAt: '2026-01-01T00:01:00.000Z',
+        updatedAt: '2026-01-01T00:05:00.000Z',
+        contextData: null,
+      };
+
+      // Seed node execution
+      db._stores.nodeExecutionsStore[nodeExecId] = {
+        id: nodeExecId,
+        executionId: execId,
+        nodeId: 'agent_dev',
+        status: 'completed',
+        startedAt: '2026-01-01T00:02:00.000Z',
+        completedAt: '2026-01-01T00:04:00.000Z',
+        outputData: JSON.stringify({ result: 'ok' }),
+        error: null,
+        attempt: 1,
+      };
+
+      // Seed tool calls
+      db._stores.toolCallsStore['tc-1'] = {
+        id: 'tc-1',
+        nodeExecutionId: nodeExecId,
+        timestamp: '2026-01-01T00:02:30.000Z',
+        toolName: 'Read',
+        target: '/src/index.ts',
+      };
+      db._stores.toolCallsStore['tc-2'] = {
+        id: 'tc-2',
+        nodeExecutionId: nodeExecId,
+        timestamp: '2026-01-01T00:03:00.000Z',
+        toolName: 'Edit',
+        target: '/src/app.ts',
+      };
+
+      const engine = new WorkflowEngine({
+        db: db as any,
+        kanban: createMockKanban(),
+        claudeService: createMockClaudeService(),
+        gitWorkflow: createMockGitWorkflow(),
+        log: createMockLog(),
+      });
+
+      const result = await engine.getMonitorData('feat_test');
+
+      assert.ok(result);
+      assert.equal(result.executionId, execId);
+      assert.equal(result.workflowId, WORKFLOW_ID);
+      assert.equal(result.workflowName, 'Test Workflow');
+      assert.equal(result.featureId, 'feat_test');
+      assert.equal(result.status, 'completed');
+      assert.equal(result.currentNodeId, 'end_success');
+
+      // Check graph data is parsed
+      const graphData = result.graphData as { nodes: any[]; edges: any[] };
+      assert.ok(graphData.nodes.length > 0);
+      assert.ok(graphData.edges.length > 0);
+
+      // Check node executions
+      const nodeExecs = result.nodeExecutions as Record<string, any>;
+      assert.ok(nodeExecs['agent_dev']);
+      assert.equal(nodeExecs['agent_dev'].status, 'completed');
+      assert.deepEqual(nodeExecs['agent_dev'].outputData, { result: 'ok' });
+
+      // Check tool calls grouped under node execution
+      const toolCalls = nodeExecs['agent_dev'].toolCalls as any[];
+      assert.equal(toolCalls.length, 2);
+      assert.equal(toolCalls[0].toolName, 'Read');
+      assert.equal(toolCalls[0].target, '/src/index.ts');
+      assert.equal(toolCalls[1].toolName, 'Edit');
+      assert.equal(toolCalls[1].target, '/src/app.ts');
+    });
+
+    it('returns most recent execution when multiple exist', async () => {
+      const db = createMockDb();
+
+      // Older execution
+      db._stores.executionsStore['exec-old'] = {
+        id: 'exec-old',
+        workflowId: WORKFLOW_ID,
+        featureId: 'feat_test',
+        status: 'completed',
+        currentNodeId: 'end_success',
+        startedAt: '2026-01-01T00:00:00.000Z',
+        updatedAt: '2026-01-01T00:01:00.000Z',
+        contextData: null,
+      };
+
+      // Newer execution
+      db._stores.executionsStore['exec-new'] = {
+        id: 'exec-new',
+        workflowId: WORKFLOW_ID,
+        featureId: 'feat_test',
+        status: 'running',
+        currentNodeId: 'agent_dev',
+        startedAt: '2026-01-02T00:00:00.000Z',
+        updatedAt: '2026-01-02T00:01:00.000Z',
+        contextData: null,
+      };
+
+      const engine = new WorkflowEngine({
+        db: db as any,
+        kanban: createMockKanban(),
+        claudeService: createMockClaudeService(),
+        gitWorkflow: createMockGitWorkflow(),
+        log: createMockLog(),
+      });
+
+      const result = await engine.getMonitorData('feat_test');
+      assert.ok(result);
+      assert.equal(result.executionId, 'exec-new');
+      assert.equal(result.status, 'running');
+    });
+
+    it('returns empty tool calls array when node has no tool calls', async () => {
+      const db = createMockDb();
+      const execId = 'exec-notc';
+
+      db._stores.executionsStore[execId] = {
+        id: execId,
+        workflowId: WORKFLOW_ID,
+        featureId: 'feat_test',
+        status: 'completed',
+        currentNodeId: 'end_success',
+        startedAt: '2026-01-01T00:00:00.000Z',
+        updatedAt: '2026-01-01T00:01:00.000Z',
+        contextData: null,
+      };
+
+      db._stores.nodeExecutionsStore['ne-notc'] = {
+        id: 'ne-notc',
+        executionId: execId,
+        nodeId: 'transition_1',
+        status: 'completed',
+        startedAt: '2026-01-01T00:00:10.000Z',
+        completedAt: '2026-01-01T00:00:11.000Z',
+        outputData: null,
+        error: null,
+        attempt: 1,
+      };
+
+      const engine = new WorkflowEngine({
+        db: db as any,
+        kanban: createMockKanban(),
+        claudeService: createMockClaudeService(),
+        gitWorkflow: createMockGitWorkflow(),
+        log: createMockLog(),
+      });
+
+      const result = await engine.getMonitorData('feat_test');
+      assert.ok(result);
+      const nodeExecs = result.nodeExecutions as Record<string, any>;
+      assert.deepEqual(nodeExecs['transition_1'].toolCalls, []);
+    });
+  });
+});