elsabro 7.0.0 → 7.1.0

package/flow-engine/tests/runner.test.js

@@ -229,6 +229,463 @@ describe('serializeContext / deserializeContext', () => {
   });
 });
 
+// ---------- Failure mode flow definitions ----------
+
+const flowWithOnError = {
+  id: 'onerror_flow',
+  version: '1.0.0',
+  config: {},
+  nodes: [
+    { id: 'start', type: 'entry', runtime_status: 'implemented', next: 'risky_agent' },
+    {
+      id: 'risky_agent',
+      type: 'agent',
+      runtime_status: 'implemented',
+      agent: 'test-agent',
+      inputs: {},
+      onError: 'error_exit',
+      next: 'success_exit'
+    },
+    {
+      id: 'success_exit',
+      type: 'exit',
+      runtime_status: 'implemented',
+      status: 'success',
+      outputs: { result: 'ok' }
+    },
+    {
+      id: 'error_exit',
+      type: 'exit',
+      runtime_status: 'implemented',
+      status: 'cancelled',
+      outputs: { result: 'handled_error' }
+    }
+  ]
+};
+
+const flowWithoutOnError = {
+  id: 'no_onerror_flow',
+  version: '1.0.0',
+  config: {},
+  nodes: [
+    { id: 'start', type: 'entry', runtime_status: 'implemented', next: 'risky_agent' },
+    {
+      id: 'risky_agent',
+      type: 'agent',
+      runtime_status: 'implemented',
+      agent: 'test-agent',
+      inputs: {},
+      next: 'end'
+    },
+    { id: 'end', type: 'exit', runtime_status: 'implemented', status: 'success', outputs: {} }
+  ]
+};
+
+const flowWithLoop = {
+  id: 'loop_flow',
+  version: '1.0.0',
+  config: {},
+  nodes: [
+    { id: 'start', type: 'entry', runtime_status: 'implemented', next: 'loop_node' },
+    {
+      id: 'loop_node',
+      type: 'condition',
+      runtime_status: 'implemented',
+      condition: '{{inputs.always_true}}',
+      true: 'loop_node',
+      false: 'end'
+    },
+    { id: 'end', type: 'exit', runtime_status: 'implemented', status: 'success', outputs: {} }
+  ]
+};
+
+const flowWithParallel = {
+  id: 'parallel_flow',
+  version: '1.0.0',
+  config: {},
+  nodes: [
+    { id: 'start', type: 'entry', runtime_status: 'implemented', next: 'par' },
+    {
+      id: 'par',
+      type: 'parallel',
+      runtime_status: 'implemented',
+      branches: [
+        { id: 'b1', agent: 'agent-a', inputs: {} },
+        { id: 'b2', agent: 'agent-b', inputs: {} }
+      ],
+      timeout: 5000,
+      next: 'end'
+    },
+    { id: 'end', type: 'exit', runtime_status: 'implemented', status: 'success', outputs: {} }
+  ]
+};
+
+const flowWithParallelOnError = {
+  id: 'parallel_onerror_flow',
+  version: '1.0.0',
+  config: {},
+  nodes: [
+    { id: 'start', type: 'entry', runtime_status: 'implemented', next: 'par' },
+    {
+      id: 'par',
+      type: 'parallel',
+      runtime_status: 'implemented',
+      branches: [
+        { id: 'b1', agent: 'agent-a', inputs: {} }
+      ],
+      onError: 'error_exit',
+      next: 'end'
+    },
+    { id: 'end', type: 'exit', runtime_status: 'implemented', status: 'success', outputs: {} },
+    {
+      id: 'error_exit',
+      type: 'exit',
+      runtime_status: 'implemented',
+      status: 'cancelled',
+      outputs: { result: 'parallel_error_handled' }
+    }
+  ]
+};
+
+const flowWithMaxIterations = {
+  id: 'maxiter_flow',
+  version: '1.0.0',
+  config: {},
+  nodes: [
+    { id: 'start', type: 'entry', runtime_status: 'implemented', next: 'par' },
+    {
+      id: 'par',
+      type: 'parallel',
+      runtime_status: 'implemented',
+      branches: [{ id: 'b1', agent: 'agent-a', inputs: {} }],
+      maxIterations: 1,
+      next: 'end'
+    },
+    { id: 'end', type: 'exit', runtime_status: 'implemented', status: 'success', outputs: {} }
+  ]
+};
+
+const flowWithMaxIterationsHandler = {
+  id: 'maxiter_handler_flow',
+  version: '1.0.0',
+  config: {},
+  nodes: [
+    { id: 'start', type: 'entry', runtime_status: 'implemented', next: 'par' },
+    {
+      id: 'par',
+      type: 'parallel',
+      runtime_status: 'implemented',
+      branches: [{ id: 'b1', agent: 'agent-a', inputs: {} }],
+      maxIterations: 1,
+      onMaxIterations: 'limit_exit',
+      next: 'end'
+    },
+    { id: 'end', type: 'exit', runtime_status: 'implemented', status: 'success', outputs: {} },
+    {
+      id: 'limit_exit',
+      type: 'exit',
+      runtime_status: 'implemented',
+      status: 'cancelled',
+      outputs: { result: 'max_iterations_reached' }
+    }
+  ]
+};
+
+// Note: flowWithBadRef not needed — loadFlow validates references at load time.
+// The runner's node-not-found path (L66-69) is tested via graph mutation after load.
+
+// ---------- Failure mode tests ----------
+
+describe('Failure modes — onError routing', () => {
+  it('routes to onError node when executor throws', async () => {
+    const engine = new FlowEngine();
+    engine.loadFlow(flowWithOnError);
+
+    const result = await engine.run({}, {
+      onAgent: async () => { throw new Error('agent exploded'); }
+    });
+
+    assert.equal(result.success, false);
+    assert.equal(result.outputs.result, 'handled_error');
+    assert.ok(result.nodesVisited.includes('error_exit'));
+    assert.ok(!result.nodesVisited.includes('success_exit'));
+  });
+
+  it('stores error message in outputs when using onError', async () => {
+    const engine = new FlowEngine();
+    engine.loadFlow(flowWithOnError);
+
+    const result = await engine.run({}, {
+      onAgent: async () => { throw new Error('kaboom'); }
+    });
+
+    // The risky_agent node should have error info in its outputs
+    assert.equal(result.context.nodes.risky_agent.outputs.error, 'kaboom');
+  });
+
+  it('propagates error when node has no onError', async () => {
+    const engine = new FlowEngine();
+    engine.loadFlow(flowWithoutOnError);
+
+    await assert.rejects(
+      engine.run({}, {
+        onAgent: async () => { throw new Error('unhandled boom'); }
+      }),
+      (err) => {
+        assert.equal(err.message, 'unhandled boom');
+        return true;
+      }
+    );
+  });
+
+  it('saves checkpoint before onError redirect', async () => {
+    const engine = new FlowEngine();
+    engine.loadFlow(flowWithOnError);
+
+    const checkpoints = [];
+    await engine.run({}, {
+      onAgent: async () => { throw new Error('checkpoint test'); },
+      onCheckpoint: async (data) => checkpoints.push(data)
+    });
+
+    // Find checkpoint for risky_agent → should point to error_exit
+    const agentCheckpoint = checkpoints.find(cp => cp.currentNode === 'risky_agent');
+    assert.ok(agentCheckpoint, 'checkpoint for risky_agent should exist');
+    assert.equal(agentCheckpoint.nextNode, 'error_exit');
+  });
+});
+
+describe('Failure modes — maxNodes loop guard', () => {
+  it('throws RunnerError when exceeding 200 node traversals', async () => {
+    const engine = new FlowEngine();
+    engine.loadFlow(flowWithLoop);
+
+    await assert.rejects(
+      engine.run({ always_true: true }, {}),
+      (err) => {
+        assert.equal(err.name, 'RunnerError');
+        assert.ok(err.message.includes('200'));
+        assert.ok(err.message.includes('infinite loop'));
+        return true;
+      }
+    );
+  });
+
+  it('RunnerError includes current node id', async () => {
+    const engine = new FlowEngine();
+    engine.loadFlow(flowWithLoop);
+
+    await assert.rejects(
+      engine.run({ always_true: true }, {}),
+      (err) => {
+        assert.equal(err.nodeId, 'loop_node');
+        return true;
+      }
+    );
+  });
+
+  it('checkpoints are saved during loop before guard triggers', async () => {
+    const engine = new FlowEngine();
+    engine.loadFlow(flowWithLoop);
+
+    const checkpoints = [];
+    await assert.rejects(
+      engine.run({ always_true: true }, {
+        onCheckpoint: async (data) => checkpoints.push(data)
+      })
+    );
+
+    // entry (1) + 199 loop iterations before guard fires on 201st attempt = 200 checkpoints
+    assert.ok(checkpoints.length >= 200, `expected >= 200 checkpoints, got ${checkpoints.length}`);
+  });
+});
+
+describe('Failure modes — parallel callback failures', () => {
+  it('parallel node with onError routes there when onParallel rejects', async () => {
+    const engine = new FlowEngine();
+    engine.loadFlow(flowWithParallelOnError);
+
+    const result = await engine.run({}, {
+      onParallel: async () => { throw new Error('parallel failed'); }
+    });
+
+    assert.equal(result.success, false);
+    assert.equal(result.outputs.result, 'parallel_error_handled');
+    assert.ok(result.nodesVisited.includes('error_exit'));
+  });
+
+  it('parallel node without onError propagates callback rejection', async () => {
+    const engine = new FlowEngine();
+    engine.loadFlow(flowWithParallel);
+
+    await assert.rejects(
+      engine.run({}, {
+        onParallel: async () => { throw new Error('unhandled parallel'); }
+      }),
+      (err) => {
+        assert.equal(err.message, 'unhandled parallel');
+        return true;
+      }
+    );
+  });
+
+  it('timeout value is passed to onParallel callback', async () => {
+    const engine = new FlowEngine();
+    engine.loadFlow(flowWithParallel);
+
+    let capturedArgs = null;
+    await engine.run({}, {
+      onParallel: async (args) => {
+        capturedArgs = args;
+        return [{ id: 'b1', result: 'ok' }, { id: 'b2', result: 'ok' }];
+      }
+    });
+
+    assert.ok(capturedArgs, 'onParallel should have been called');
+    assert.equal(capturedArgs.timeout, 5000);
+    assert.equal(capturedArgs.nodeId, 'par');
+    assert.equal(capturedArgs.joinType, 'all');
+  });
+
+  it('parallel node handles missing onParallel gracefully', async () => {
+    const engine = new FlowEngine();
+    engine.loadFlow(flowWithParallel);
+
+    // No onParallel callback provided
+    const result = await engine.run({}, {});
+
+    assert.equal(result.success, true);
+    // Branches should be marked as skipped
+    const parOutputs = result.context.nodes.par.outputs;
+    assert.ok(parOutputs.branches, 'branches should exist in outputs');
+    assert.equal(parOutputs.branches.b1.skipped, true);
+    assert.equal(parOutputs.branches.b2.skipped, true);
+  });
+});
+
+describe('Failure modes — context serialization', () => {
+  it('serializeContext handles circular references gracefully', () => {
+    const ctx = {
+      inputs: { task: 'test' },
+      nodes: {},
+      steps: {},
+      state: {},
+      _iterations: {}
+    };
+    // Create a circular reference
+    ctx.state.self = ctx.state;
+
+    const serialized = serializeContext(ctx);
+
+    // state should be null due to circular ref
+    assert.equal(serialized.state, null);
+    // Other keys should still be fine
+    assert.deepEqual(serialized.inputs, { task: 'test' });
+    assert.deepEqual(serialized.nodes, {});
+  });
+
+  it('serializeContext preserves all standard keys', () => {
+    const ctx = {
+      inputs: { a: 1 },
+      nodes: { n1: { outputs: { x: 2 } } },
+      steps: { s1: { output: 'data' } },
+      state: { flag: true },
+      _iterations: { n1: 3 }
+    };
+
+    const serialized = serializeContext(ctx);
+
+    assert.deepEqual(serialized.inputs, ctx.inputs);
+    assert.deepEqual(serialized.nodes, ctx.nodes);
+    assert.deepEqual(serialized.steps, ctx.steps);
+    assert.deepEqual(serialized.state, ctx.state);
+    assert.deepEqual(serialized._iterations, ctx._iterations);
+  });
+
+  it('serializeContext ignores unknown keys', () => {
+    const ctx = {
+      inputs: {},
+      nodes: {},
+      steps: {},
+      state: {},
+      _iterations: {},
+      extraField: 'should be ignored',
+      _internal: { secret: true }
+    };
+
+    const serialized = serializeContext(ctx);
+
+    assert.equal(serialized.extraField, undefined);
+    assert.equal(serialized._internal, undefined);
+    assert.ok('inputs' in serialized);
+  });
+});
+
+describe('Failure modes — maxIterations fallback', () => {
+  it('parallel node falls through to next when maxIterations reached without handler', async () => {
+    const engine = new FlowEngine();
+    engine.loadFlow(flowWithMaxIterations);
+
+    const result = await engine.run({}, {
+      onParallel: async () => [{ id: 'b1', result: 'done' }]
+    });
+
+    // Should reach 'end' via node.next even though maxIterations=1 was hit
+    assert.equal(result.success, true);
+    assert.ok(result.nodesVisited.includes('end'));
+    assert.ok(!result.nodesVisited.includes('limit_exit'));
+  });
+
+  it('parallel node routes to onMaxIterations when handler defined', async () => {
+    const engine = new FlowEngine();
+    engine.loadFlow(flowWithMaxIterationsHandler);
+
+    const result = await engine.run({}, {
+      onParallel: async () => [{ id: 'b1', result: 'done' }]
+    });
+
+    // Should route to limit_exit via onMaxIterations
+    assert.equal(result.success, false); // limit_exit is cancelled status
+    assert.equal(result.outputs.result, 'max_iterations_reached');
+    assert.ok(result.nodesVisited.includes('limit_exit'));
+  });
+});
+
+describe('Failure modes — runner edge cases', () => {
+  it('RunnerError thrown for node not found in graph at runtime', async () => {
+    const engine = new FlowEngine();
+    engine.loadFlow(miniFlow);
+
+    // Mutate graph after loading: point entry to a non-existent node
+    const startNode = engine.graph.nodes.get('start');
+    startNode.next = 'ghost_node';
+
+    await assert.rejects(
+      engine.run({ task: 'test', go: true }, {}),
+      (err) => {
+        assert.equal(err.name, 'RunnerError');
+        assert.ok(err.message.includes('ghost_node'));
+        assert.ok(err.message.includes('not found'));
+        return true;
+      }
+    );
+  });
+
+  it('RunnerError thrown when no flow loaded', async () => {
+    const engine = new FlowEngine();
+    // Do NOT call loadFlow
+
+    await assert.rejects(
+      engine.run({}, {}),
+      (err) => {
+        assert.equal(err.name, 'RunnerError');
+        assert.ok(err.message.includes('loadFlow'));
+        return true;
+      }
+    );
+  });
+});
+
 describe('CheckpointManager', () => {
   const tmpDir = path.join(os.tmpdir(), `elsabro-test-cp-${Date.now()}`);
 

package/flows/development-flow.json

@@ -6,23 +6,22 @@
 
   "config": {
     "timeout": 3600000,
-    "maxRetries": 3,
     "checkpointEnabled": true,
     "interruptEnabled": true,
     "errorPolicy": "quorum"
   },
 
   "sync_metadata": {
-    "last_audit": "2026-02-07",
+    "last_audit": "2026-02-08",
     "audit_result": {
-      "total_nodes": 42,
-      "implemented": 40,
+      "total_nodes": 44,
+      "implemented": 42,
       "partial": 0,
       "not_implemented": 0,
       "deprecated": 2,
       "implementation_rate": "95%"
     },
-    "note": "P5 (M4): All 42 nodes handled. 40 implemented, 2 deprecated (teams_spawn, interrupt_teams_failed). post_mortem implemented with agent step. Zero not_implemented nodes remain."
+    "note": "M5-P2: Added design_ui + interrupt_design_complete (2 new implemented nodes). 42 implemented, 2 deprecated (teams_spawn, interrupt_teams_failed). design_ui is optional side-branch, not on mandatory path."
   },
 
   "inputs": {
@@ -980,6 +979,44 @@
       }
     },
 
+    {
+      "id": "design_ui",
+      "type": "agent",
+      "description": "Optional: Design UI screens with Stitch AI before implementation",
+      "runtime_status": "implemented",
+      "implemented_in": "commands/elsabro/design-ui.md",
+      "agent": "elsabro-ux-designer",
+      "config": { "model": "sonnet", "timeout": 600000 },
+      "inputs": {
+        "task": "{{inputs.task}}",
+        "context": "{{state.loadedContext}}"
+      },
+      "next": "interrupt_design_complete"
+    },
+
+    {
+      "id": "interrupt_design_complete",
+      "type": "interrupt",
+      "description": "After design-ui: choose next step (implement, plan, or done)",
+      "runtime_status": "implemented",
+      "implemented_in": "commands/elsabro/design-ui.md#siguiente_paso",
+      "reason": "Design screens generated - choose next action",
+      "display": {
+        "title": "Diseno UI Completado",
+        "content": "Se han generado los screens de UI. Elige como continuar.",
+        "options": [
+          { "id": "implement", "label": "Implementar los disenos ahora" },
+          { "id": "plan", "label": "Planificar la implementacion primero" },
+          { "id": "done", "label": "Listo por ahora" }
+        ]
+      },
+      "routes": {
+        "implement": "standard_analyze",
+        "plan": "interview_default",
+        "done": "end_success"
+      }
+    },
+
     {
       "id": "end_cancelled",
       "type": "exit",

package/flows/quick-flow.json

@@ -6,7 +6,6 @@
 
   "config": {
     "timeout": 900000,
-    "maxRetries": 2,
     "checkpointEnabled": true,
     "interruptEnabled": false,
     "errorPolicy": "continue_all"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "elsabro",
-  "version": "7.0.0",
+  "version": "7.1.0",
   "description": "Sistema de desarrollo AI-powered para Claude Code - BMAD Method Integration, Spec-Driven Development, Party Mode, Next Step Suggestions, Stitch UI Design, Agent Teams, blocking code review, orquestación avanzada con flows declarativos",
   "bin": {
     "elsabro": "bin/install.js",

package/references/command-flow.md

@@ -14,26 +14,26 @@ Los comandos ELSABRO se sincronizan a través de un sistema de estado compartido
 │                    (Entry Point - Orquestador)                       │
 └─────────────────────────┬───────────────────────────────────────────┘
                           │
-          ┌───────────────┼───────────────┬───────────────┐
-          ▼               ▼               ▼               ▼
-    ┌──────────┐    ┌──────────┐    ┌──────────┐    ┌──────────┐
-    │  :new    │    │  :plan   │    │  :debug  │    │  :quick  │
-    │ Proyecto │    │ Feature  │    │  Bugs    │    │  Rápido  │
-    │  nuevo   │    │  nueva   │    │          │    │          │
-    └────┬─────┘    └────┬─────┘    └────┬─────┘    └────┬─────┘
-         │               │               │               │
-         ▼               ▼               ▼               ▼
-    ┌──────────┐    ┌──────────┐    ┌──────────┐         │
-    │ :execute │◄───│ :execute │◄───│ :execute │         │
-    │          │    │          │    │          │         │
-    └────┬─────┘    └────┬─────┘    └────┬─────┘         │
-         │               │               │               │
-         └───────────────┴───────────────┴───────────────┘
-                                │
-                                ▼
-                         ┌──────────────┐
-                         │ :verify-work │
-                         │  (Siempre)   │
+      ┌───────────────┬───┼───────────────┬───────────────┐
+      ▼               ▼   ▼               ▼               ▼
+┌──────────┐    ┌──────────┐    ┌──────────┐    ┌──────────┐    ┌────────────┐
+│  :new    │    │  :plan   │    │  :debug  │    │  :quick  │    │ :design-ui │
+│ Proyecto │    │ Feature  │    │  Bugs    │    │  Rápido  │    │  Diseño    │
+│  nuevo   │    │  nueva   │    │          │    │          │    │  visual    │
+└────┬─────┘    └────┬─────┘    └────┬─────┘    └────┬─────┘    └─────┬──────┘
+     │               │               │               │                │
+     ▼               ▼               ▼               ▼                │
+┌──────────┐    ┌──────────┐    ┌──────────┐         │                │
+│ :execute │◄───│ :execute │◄───│ :execute │         │          ┌─────┘
+│          │    │          │    │          │         │          │
+└────┬─────┘    └────┬─────┘    └────┬─────┘         │          │
+     │               │               │               │          │
+     └───────────────┴───────────────┴───────────────┘          │
+                                │                               │
+                                ▼                               │
+                         ┌──────────────┐                       │
+                         │ :verify-work │◄──────────────────────┘
+                         │  (Siempre)   │  (o :execute / :plan)
                          └──────────────┘
 ```
 
@@ -202,6 +202,7 @@ start → new         ✓ (proyecto nuevo)
 start → plan        ✓ (feature en proyecto existente)
 start → debug       ✓ (resolver problema)
 start → quick       ✓ (tarea simple)
+start → design-ui   ✓ (explorar visualmente / diseñar interfaz)
 
 new → plan          ✓ (siguiente paso natural)
 new → execute       ✗ (necesita plan primero)
@@ -220,6 +221,10 @@ debug → plan        ✓ (fix complejo necesita plan)
 
 quick → verify      ✓ (verificar tarea rápida)
 quick → [done]      ✓ (tarea completada)
+
+design-ui → plan    ✓ (planificar implementación de diseños)
+design-ui → execute ✓ (implementar diseños directamente)
+design-ui → [done]  ✓ (solo diseñar por ahora)
 ```
 
 ---