iaip-mcp-pde 2.0.2

package/scenarios/04-dependency-resolution.md

@@ -0,0 +1,163 @@
+# Scenario 04: Dependency Resolution
+
+## Objective
+Test that the PDE correctly identifies and resolves dependencies between tasks, ensuring proper execution ordering and detecting potential issues like circular dependencies.
+
+## Scenario Description
+Complex workflows have tasks that depend on each other. The PDE must:
+- Build accurate dependency graphs
+- Identify the critical path
+- Detect circular dependencies
+- Enable parallel execution where safe
+
+## Test Cases
+
+### Case A: Linear Dependencies
+```
+Research best practices, then design the architecture, then implement the solution, then write tests
+```
+
+Expected Graph:
+```
+research → design → implement → write tests
+```
+
+### Case B: Parallel Opportunities
+```
+Create user service, create order service, create product service, then integrate all services
+```
+
+Expected Graph:
+```
+create user ─┐
+create order─┼→ integrate
+create product┘
+```
+
+### Case C: Mixed Dependencies
+```
+Analyze requirements, create database schema, create API endpoints, write unit tests, write integration tests, deploy
+```
+
+Expected Graph:
+```
+analyze → create schema ─→ write unit tests ─┐
+                  ↓                          ├→ deploy
+         create API ──→ write integration tests┘
+```
+
+## Test Steps for LLM Agent
+
+### Test Case A: Linear Dependencies
+
+1. **Decompose Linear Workflow**
+   ```
+   Use tool: pde_decompose
+   Arguments: { "prompt": "Research best practices, then design the architecture, then implement the solution, then write tests" }
+   ```
+
+2. **Verify Ordering**
+   - [ ] Research task has no dependencies
+   - [ ] Design depends on Research
+   - [ ] Implement depends on Design
+   - [ ] Tests depend on Implement
+
+3. **Check Critical Path**
+   - [ ] Critical path includes all 4 tasks in order
+   - [ ] `metadata.parallelizableTasks` is 0 or very low
+
+### Test Case B: Parallel Opportunities
+
+1. **Decompose Parallel Workflow**
+   ```
+   Use tool: pde_decompose
+   Arguments: { "prompt": "Create user service, create order service, create product service, then integrate all services" }
+   ```
+
+2. **Verify Parallelization**
+   - [ ] Three create tasks have no dependencies on each other
+   - [ ] `metadata.parallelizableTasks` >= 3
+   - [ ] Integrate task depends on all create tasks
+
+3. **Check Execution Type**
+   - [ ] Stage containing create tasks has `executionType: 'parallel'`
+
+### Test Case C: Mixed Dependencies
+
+1. **Decompose Mixed Workflow**
+   ```
+   Use tool: pde_decompose
+   Arguments: { "prompt": "Analyze requirements, create database schema, create API endpoints, write unit tests, write integration tests, deploy" }
+   ```
+
+2. **Verify Dependency Structure**
+   - [ ] Analyze has no dependencies
+   - [ ] Schema creation depends on Analyze
+   - [ ] API creation depends on Schema
+   - [ ] Tests depend on their respective targets
+   - [ ] Deploy depends on all tests
+
+3. **Check for Cycles**
+   - [ ] No circular dependencies detected
+
+## Circular Dependency Detection
+
+### Case D: Intentional Cycle (Edge Case)
+```
+Module A imports from Module B, Module B imports from Module A, refactor to remove cycle
+```
+
+1. **Decompose Potentially Cyclic Request**
+   - [ ] PDE should detect the cycle
+   - [ ] May flag as ambiguity or issue
+   - [ ] Should not crash or hang
+
+## Validation Steps
+
+1. **Validate Each Plan**
+   ```
+   Use tool: pde_validate_plan
+   Arguments: { "planId": "<planId>" }
+   ```
+
+2. **Check Validation Results**
+   - [ ] `isValid` reflects dependency correctness
+   - [ ] Missing dependencies flagged as issues
+   - [ ] Circular dependencies flagged if present
+
+## Success Criteria
+
+- ✅ Linear dependencies correctly ordered
+- ✅ Parallel opportunities correctly identified
+- ✅ Mixed dependency graphs accurately represented
+- ✅ Critical path correctly calculated
+- ✅ No false circular dependency detection
+- ✅ Actual circular dependencies detected (if any)
+
+## Technical Details
+
+### Dependency Graph Structure
+```typescript
+interface DependencyGraph {
+  nodes: DependencyNode[];      // All tasks
+  edges: DependencyEdge[];      // Dependencies
+  parallelGroups: string[][];   // Tasks that can run together
+  criticalPath: string[];       // Longest dependency chain
+  hasCycles: boolean;           // Cycle detection result
+}
+```
+
+### Edge Types
+- `must-precede`: Task A must complete before Task B
+- `must-follow`: Task A must happen after Task B  
+- `blocks`: Task A blocks Task B from parallel execution
+- `enables`: Task A enables optional path to Task B
+
+## Performance Considerations
+
+For large dependency graphs:
+- Graph construction should be O(n²) worst case
+- Cycle detection uses DFS: O(V + E)
+- Critical path: O(V + E) with topological sort
+
+The `maxDepth` option (default: 5) limits recursion depth to prevent performance issues with deeply nested dependencies.

package/scenarios/05-checkpoint-recovery.md

@@ -0,0 +1,171 @@
+# Scenario 05: Checkpoint and Recovery
+
+## Objective
+Test that the PDE creates proper checkpoints during workflow execution and enables recovery from failures.
+
+## Scenario Description
+In real-world usage, workflows may fail partway through. The PDE must:
+- Create checkpoints after each stage
+- Store context snapshots for recovery
+- Enable resumption from last successful checkpoint
+- Provide clear recovery instructions
+
+## Test Workflow
+```
+Create database models, generate API routes, write tests, deploy to staging
+```
+
+## Expected Checkpoint Structure
+
+After each stage completes:
+```typescript
+{
+  checkpointId: "uuid",
+  workflowId: "workflow-uuid",
+  stageId: "stage-south",
+  taskId: "task-3",
+  timestamp: "2026-01-30T10:00:00Z",
+  contextSnapshot: {
+    completedTasks: ["task-1", "task-2", "task-3"],
+    outputs: {...},
+    environment: {...}
+  },
+  resumeInstructions: "Resume from stage stage-west, task task-4"
+}
+```
+
+## Test Steps for LLM Agent
+
+### Step 1: Create Initial Plan
+
+1. **Decompose Workflow**
+   ```
+   Use tool: pde_decompose
+   Arguments: { 
+     "prompt": "Create database models, generate API routes, write tests, deploy to staging"
+   }
+   ```
+
+2. **Note Plan Structure**
+   - [ ] Record `planId` for later use
+   - [ ] Record `workflowId` for checkpoint retrieval
+   - [ ] Verify `checkpointAfter: true` on stages
+
+### Step 2: Simulate Stage Completion
+
+For this test, we verify the checkpoint structure is correct. In a real execution:
+
+1. **Execute First Stage** (simulated)
+   - Stage SOUTH completes
+   - Checkpoint should be created
+
+2. **Get Checkpoint**
+   ```
+   Use tool: pde_get_checkpoint
+   Arguments: { 
+     "workflowId": "<workflowId from step 1>"
+   }
+   ```
+
+3. **Verify Checkpoint** (if exists)
+   - [ ] Contains `checkpointId`
+   - [ ] Contains `workflowId` matching plan
+   - [ ] Contains `contextSnapshot`
+   - [ ] Contains `resumeInstructions`
+
+### Step 3: Verify Recovery Readiness
+
+1. **Check Plan for Recovery Data**
+   ```
+   Use tool: pde_get_plan
+   Arguments: { "planId": "<planId>" }
+   ```
+
+2. **Examine Task Recovery Strategies**
+   For each task in `plan.tasks`:
+   - [ ] Has `recoveryStrategy` defined
+   - [ ] `onFailure` is one of: 'retry', 'skip', 'alternative', 'abort'
+   - [ ] `retryCount` is reasonable (1-5)
+
+3. **Examine Checkpoint Data**
+   For each task:
+   - [ ] Has `checkpointData` defined
+   - [ ] `saves` lists expected outputs
+   - [ ] `restoresFrom` references valid checkpoint (if applicable)
+
+### Step 4: List and Verify Workflows
+
+1. **List All Workflows**
+   ```
+   Use tool: pde_list_workflows
+   Arguments: { "status": "all", "limit": 10 }
+   ```
+
+2. **Verify Workflow Appears**
+   - [ ] Workflow from Step 1 is in list
+   - [ ] Shows correct `intention`
+   - [ ] Shows correct `taskCount`
+
+## Expected Recovery Flow
+
+When a failure occurs at Stage WEST (testing):
+
+```
+Workflow Execution:
+  ✓ Stage EAST  - Vision Inquiry (completed)
+  ✓ Stage SOUTH - Implementation (completed)
+    📍 Checkpoint created: cp-123
+  ✗ Stage WEST  - Validation (FAILED at task-5)
+    └─ Error: Test assertion failed
+    └─ Recovery: retry (attempt 1/3)
+    └─ Checkpoint available: cp-123
+  
+Resume Options:
+  1. Retry from task-5 (same approach)
+  2. Retry from task-5 (alternative approach)
+  3. Skip task-5 and continue
+  4. Rollback to checkpoint cp-123
+```
+
+## Success Criteria
+
+- ✅ Each stage has `checkpointAfter: true`
+- ✅ Tasks have valid `recoveryStrategy` definitions
+- ✅ Tasks have valid `checkpointData` definitions
+- ✅ Checkpoint retrieval works by workflowId
+- ✅ Resume instructions are clear and actionable
+- ✅ Workflow appears in list with correct metadata
+
+## Recovery Strategy Types
+
+| Strategy | Use Case |
+|----------|----------|
+| `retry` | Transient failures (network, timeout) |
+| `skip` | Non-critical tasks that can be skipped |
+| `alternative` | When different approach might succeed |
+| `abort` | Critical failures requiring human intervention |
+
+## Checkpoint Best Practices
+
+1. **Checkpoint Granularity**: After each stage, not each task
+2. **Context Preservation**: Save all outputs and relevant state
+3. **Clear Instructions**: Tell user exactly how to resume
+4. **Minimal Overhead**: Don't checkpoint trivially small operations
+
+## Error Handling Verification
+
+1. **Missing Workflow**
+   ```
+   Use tool: pde_get_checkpoint
+   Arguments: { "workflowId": "non-existent-id" }
+   ```
+   - [ ] Returns graceful "not found" message
+   - [ ] Does not crash or throw error
+
+2. **Invalid Plan ID**
+   ```
+   Use tool: pde_validate_plan
+   Arguments: { "planId": "invalid-id" }
+   ```
+   - [ ] Returns `isValid: false`
+   - [ ] Includes helpful error message