groundswell 0.0.2 → 1.0.0

package/plan/001_d3bb02af4886/bugfix/RESEARCH_SUMMARY.md

@@ -1,346 +0,0 @@
-# Bug Fix Research Summary - Hierarchical Workflow Engine
-
-**Date:** 2025-01-12
-**Project:** Hierarchical Workflow Engine Bug Fixes
-**Document:** Bug Fix Requirements (Creative PRD Validation Testing)
-
----
-
-## Executive Summary
-
-This document summarizes the research phase for the Hierarchical Workflow Engine bug fix project. All 9 bugs identified during PRD validation testing have been analyzed, validated against the codebase, and decomposed into atomic implementation tasks.
-
-### Key Findings
-
-- **All 9 bug report claims VALIDATED** - Code exists exactly as stated in the bug report
-- **344 existing tests** - 100% pass rate maintained throughout bug fixes
-- **4 Phases, 4 Milestones, 11 Tasks, 46 Subtasks** - Complete implementation plan created
-- **Backward compatibility prioritized** - All fixes maintain existing API contracts where possible
-
----
-
-## Research Artifacts Created
-
-### Architecture Documentation
-
-Three comprehensive architecture documents were created in `plan/bugfix/architecture/`:
-
-#### 1. codebase_structure.md (14KB)
-**Purpose:** Complete codebase mapping and bug claim validation
-
-**Contents:**
-- Directory structure overview
-- Key files and responsibilities
-- Validation of all 7 bug report claims with evidence
-- Decorator system pattern analysis
-- Error class hierarchy
-- Observer pattern implementation
-- Logger architecture details
-- Dual tree architecture explanation
-- Event type catalog
-- Testing strategy overview
-- Dependencies list
-
-**Key Validation:** Confirmed all bug report claims are accurate with line numbers and code snippets.
-
-#### 2. error_handling_patterns.md (9.6KB)
-**Purpose:** Deep analysis of error handling architecture and Promise.all usage
-
-**Contents:**
-- WorkflowError interface structure
-- All Promise.all usage locations (3 found)
-- Step-by-step error propagation flow
-- Why ErrorMergeStrategy exists but isn't used (4 reasons)
-- Recommended Promise.allSettled implementation pattern
-- Production-ready code examples
-- Usage examples for error aggregation
-- Additional findings (error events, state capture, recovery patterns, testing coverage)
-
-**Key Finding:** ErrorMergeStrategy is defined but completely unused - requires TaskOptions extension and Promise.allSettled implementation.
-
-#### 3. concurrent_execution_best_practices.md (47KB)
-**Purpose:** Research on production workflow engine patterns and best practices
-
-**Contents:**
-- Promise.all vs Promise.allSettled technical comparison
-- Production patterns from Temporal.io, AWS Step Functions, Cadence, Apache Airflow
-- 4 error aggregation strategies with analysis
-- Decision framework for fail-fast vs complete-all
-- Strategy selection matrix (10 real-world scenarios)
-- Groundswell-specific recommendations with code examples
-- 4-phase implementation roadmap
-- Complete code examples for WorkflowAggregateError
-
-**Key Recommendation:** Default to 'complete-all' strategy for observability, maintain 'fail-fast' as initial default for backward compatibility.
-
----
-
-## Bug Fix Task Breakdown
-
-### File: `./bug_fix_tasks.json` (36KB, 436 lines)
-
-**Structure:**
-```json
-{
-  "backlog": [
-    {
-      "type": "Phase",
-      "id": "P1",
-      "title": "Bug Fixes - Hierarchical Workflow Engine",
-      "status": "Ready",
-      "milestones": [
-        { "type": "Milestone", "id": "P1.M1", ... },  // Critical Fixes
-        { "type": "Milestone", "id": "P1.M2", ... },  // Major Fixes
-        { "type": "Milestone", "id": "P1.M3", ... },  // Minor Fixes
-        { "type": "Milestone", "id": "P1.M4", ... }   // Validation
-      ]
-    }
-  ]
-}
-```
-
-### Milestone Breakdown
-
-#### P1.M1: Critical Fixes - Signature Mismatches (1 Task, 4 Subtasks)
-**Focus:** WorkflowLogger.child() signature mismatch
-
-**Task:** Fix WorkflowLogger.child() Signature Mismatch
-- S1: Research PRD specification (1 SP)
-- S2: Update signature to accept Partial<LogEntry> (2 SP)
-- S3: Add tests for new signature (2 SP)
-- S4: Verify backward compatibility (1 SP)
-
-**Story Points:** 6
-
-**Key Deliverable:** child() accepts Partial<LogEntry> while maintaining backward compatibility with string argument.
-
----
-
-#### P1.M2: Major Fixes - Concurrent Execution & Error Handling (3 Tasks, 11 Subtasks)
-**Focus:** Promise.all replacement and ErrorMergeStrategy implementation
-
-**Task 1:** Replace Promise.all with Promise.allSettled
-- S1: Analyze current implementation (1 SP)
-- S2: Implement Promise.allSettled (2 SP)
-- S3: Add concurrent failure tests (2 SP)
-- S4: Run full test suite (1 SP)
-
-**Task 2:** Implement ErrorMergeStrategy Support
-- S1: Add to TaskOptions interface (1 SP)
-- S2: Implement aggregation logic (2 SP)
-- S3: Create default merger (1 SP)
-- S4: Add tests (2 SP)
-
-**Task 3:** Document trackTiming Default
-- S1: Locate PRD section (1 SP)
-- S2: Update documentation (1 SP)
-
-**Story Points:** 14
-
-**Key Deliverable:** Concurrent tasks use Promise.allSettled with opt-in error aggregation via ErrorMergeStrategy.
-
----
-
-#### P1.M3: Minor Fixes - Logging & Performance (4 Tasks, 11 Subtasks)
-**Focus:** Observer error handling, performance optimizations, validation
-
-**Task 1:** Replace console.error with Logger
-- S1: Find all console.error calls (1 SP)
-- S2: Replace with logger.error (2 SP)
-- S3: Add tests (1 SP)
-
-**Task 2:** Optimize Tree Debugger Node Map
-- S1: Analyze onTreeChanged (1 SP)
-- S2: Implement incremental updates (2 SP)
-- S3: Add benchmarks (1 SP)
-
-**Task 3:** Add Workflow Name Validation
-- S1: Determine requirements (1 SP)
-- S2: Implement validation (1 SP)
-- S3: Add tests (1 SP)
-
-**Task 4:** Consider Exposing isDescendantOf
-- S1: Evaluate use cases (1 SP)
-- S2: Implement if approved (1 SP)
-- S3: Add tests (1 SP)
-
-**Story Points:** 14
-
-**Key Deliverable:** Observer errors use logger, tree debugger has incremental updates, optional name validation.
-
----
-
-#### P1.M4: Validation & Documentation (3 Tasks, 7 Subtasks)
-**Focus:** Testing, documentation, and backward compatibility
-
-**Task 1:** Run Full Test Suite
-- S1: Execute tests (1 SP)
-- S2: Fix failures (2 SP)
-
-**Task 2:** Create Bug Fix Summary
-- S1: Document fixes (2 SP)
-- S2: Update changelog (1 SP)
-
-**Task 3:** Verify Backward Compatibility
-- S1: Audit breaking changes (1 SP)
-- S2: Add compatibility tests (2 SP)
-
-**Story Points:** 9
-
-**Key Deliverable:** All tests pass, complete documentation, backward compatibility verified.
-
----
-
-## Total Project Metrics
-
-- **Total Story Points:** 43
-- **Estimated Effort:** ~2-3 weeks (1 developer)
-- **Critical Issues:** 1 fixed
-- **Major Issues:** 3 fixed
-- **Minor Issues:** 5 fixed (2 evaluated, may not implement)
-- **Test Coverage:** 344+ existing tests maintained
-- **Documentation:** 3 architecture docs (70KB) + task breakdown (36KB)
-
----
-
-## Risk Assessment
-
-### High Risk Items
-1. **WorkflowLogger.child() signature change** - Public API change, requires careful backward compatibility
-2. **Promise.all to Promise.allSettled** - Changes concurrent execution semantics, may break existing error handling expectations
-
-### Medium Risk Items
-1. **ErrorMergeStrategy implementation** - New feature added to existing codebase, requires thorough testing
-2. **Observer error handling** - Changes internal error flow, may affect debugging workflows
-
-### Low Risk Items
-1. **Documentation updates** - No code changes
-2. **Performance optimizations** - Implementation detail, doesn't change behavior
-3. **Validation additions** - Only affects previously invalid inputs
-
----
-
-## Migration Considerations
-
-### Breaking Changes
-1. **WorkflowLogger.child() signature**
-   - Old: `child(parentLogId: string)`
-   - New: `child(meta: Partial<LogEntry>)`
-   - Migration: String argument still works (backward compatible), but users should migrate to Partial<LogEntry> for new features
-
-### Non-Breaking Changes
-1. **Promise.allSettled** - Behavior change but API unchanged
-2. **ErrorMergeStrategy** - Opt-in new feature
-3. **Observer error logging** - Internal implementation detail
-4. **Tree debugger optimization** - Performance improvement, behavior unchanged
-
----
-
-## Testing Strategy
-
-### Existing Tests
-- **344 tests** - All must continue passing
-- **100% pass rate** - Quality gate for completion
-- **Adversarial tests** - Edge case coverage already exists
-
-### New Tests Required
-1. **WorkflowLogger.child()** - 4 test scenarios
-2. **Concurrent failures** - 4 test scenarios
-3. **ErrorMergeStrategy** - 3 test scenarios
-4. **Observer error logging** - 2 test scenarios
-5. **Tree debugger performance** - Benchmark tests
-6. **Name validation** - 3 test scenarios (if implemented)
-7. **Backward compatibility** - Migration path tests
-
-### Test Execution
-```bash
-# Run all tests
-npm test
-
-# Run specific test suites
-npm test -- logger
-npm test -- concurrent
-npm test -- error-merge
-```
-
----
-
-## Implementation Order Recommendation
-
-### Phase 1: Critical Fixes (Week 1, Days 1-2)
-1. Fix WorkflowLogger.child() signature
-2. Verify backward compatibility
-3. Update PRD documentation for trackTiming
-
-### Phase 2: Major Fixes (Week 1, Days 3-5)
-1. Implement Promise.allSettled
-2. Add ErrorMergeStrategy support
-3. Test concurrent execution scenarios
-
-### Phase 3: Minor Fixes (Week 2, Days 1-3)
-1. Replace console.error with logger
-2. Optimize tree debugger
-3. Evaluate name validation and isDescendantOf
-
-### Phase 4: Validation (Week 2, Days 4-5)
-1. Full test suite execution
-2. Documentation and changelog
-3. Backward compatibility verification
-
----
-
-## Success Criteria
-
-### Must Have (Blocking)
-- ✅ All 344 existing tests pass
-- ✅ All critical bugs fixed (child() signature)
-- ✅ All major bugs fixed (Promise.allSettled, ErrorMergeStrategy)
-- ✅ No regressions introduced
-- ✅ Backward compatibility maintained
-
-### Should Have (Important)
-- ✅ Observer errors use logger
-- ✅ Tree debugger performance optimized
-- ✅ Complete documentation and changelog
-- ✅ Comprehensive test coverage for new features
-
-### Could Have (Nice to Have)
-- ⚠️ Workflow name validation (decision pending)
-- ⚠️ Public isDescendantOf API (decision pending)
-
----
-
-## Next Steps
-
-1. **Review this research summary** with stakeholders
-2. **Approve task breakdown** in `bug_fix_tasks.json`
-3. **Begin implementation** starting with P1.M1 (Critical Fixes)
-4. **Track progress** using task IDs (e.g., P1.M1.T1.S1)
-5. **Update research docs** if implementation reveals new information
-
----
-
-## Appendix: File Locations
-
-### Research Documents
-- `plan/bugfix/architecture/codebase_structure.md` - Codebase mapping
-- `plan/bugfix/architecture/error_handling_patterns.md` - Error analysis
-- `plan/bugfix/architecture/concurrent_execution_best_practices.md` - Best practices
-- `plan/bugfix/RESEARCH_SUMMARY.md` - This document
-
-### Implementation Artifacts
-- `./bug_fix_tasks.json` - Complete task breakdown (USE THIS FILE)
-
-### Source Files Referenced
-- `src/core/logger.ts:84` - child() method
-- `src/decorators/task.ts:112` - Promise.all usage
-- `src/types/error-strategy.ts` - ErrorMergeStrategy interface
-- `src/decorators/step.ts:94` - trackTiming default
-- `src/core/workflow.ts:376,124-139` - Observer errors and getRootObservers
-- `src/debugger/tree-debugger.ts:80-84` - Tree rebuild logic
-
----
-
-**Document Status:** ✅ Complete
-**Ready for Implementation:** ✅ Yes
-**Task Breakdown Available:** ✅ Yes (`./bug_fix_tasks.json`)

package/plan/001_d3bb02af4886/bugfix/architecture/codebase_structure.md

@@ -1,311 +0,0 @@
-# Codebase Structure Analysis - Hierarchical Workflow Engine
-
-## 1. Directory Structure Overview
-
-```
-/home/dustin/projects/groundswell/
-├── src/
-│   ├── core/              # Core workflow engine
-│   │   ├── workflow.ts    # Main Workflow class
-│   │   ├── logger.ts      # WorkflowLogger
-│   │   ├── agent.ts       # Agent class
-│   │   ├── prompt.ts      # Prompt class
-│   │   ├── context.ts     # Execution context
-│   │   ├── workflow-context.ts
-│   │   ├── event-tree.ts  # Event tree implementation
-│   │   ├── factory.ts     # Factory functions
-│   │   └── mcp-handler.ts # MCP (Model Context Protocol) handler
-│   ├── decorators/        # Decorator implementations
-│   │   ├── step.ts        # @Step decorator
-│   │   ├── task.ts        # @Task decorator
-│   │   └── observed-state.ts  # @ObservedState decorator
-│   ├── types/            # TypeScript type definitions
-│   │   ├── workflow.ts   # WorkflowNode, WorkflowStatus
-│   │   ├── error.ts      # WorkflowError interface
-│   │   ├── error-strategy.ts  # ErrorMergeStrategy
-│   │   ├── observer.ts   # WorkflowObserver interface
-│   │   ├── events.ts     # WorkflowEvent discriminated union
-│   │   ├── logging.ts    # LogEntry, LogLevel
-│   │   ├── decorators.ts # StepOptions, TaskOptions
-│   │   └── index.ts      # Type exports
-│   ├── debugger/         # Debugging tools
-│   │   └── tree-debugger.ts  # WorkflowTreeDebugger
-│   ├── cache/            # Caching system
-│   │   ├── cache.ts      # LLMCache
-│   │   └── cache-key.ts  # Cache key generation
-│   ├── reflection/       # Reflection system
-│   │   └── reflection.ts # ReflectionManager
-│   ├── tools/            # Introspection tools
-│   │   └── introspection.ts
-│   ├── utils/            # Utilities
-│   │   ├── id.ts         # generateId()
-│   │   └── observable.ts # Observable class
-│   ├── __tests__/        # Test suites
-│   │   ├── unit/
-│   │   ├── integration/
-│   │   └── adversarial/  # Edge case and stress tests
-│   └── index.ts          # Main exports
-├── examples/             # Example workflows
-├── docs/                 # Documentation
-└── package.json          # Project configuration
-```
-
-## 2. Key Files and Their Responsibilities
-
-| File | Responsibility |
-|------|----------------|
-| `src/core/workflow.ts` | Main Workflow class supporting both class-based (subclass with run()) and functional (executor) patterns. Manages parent-child relationships, observers, event emission, and tree structure validation. |
-| `src/core/logger.ts` | WorkflowLogger class that emits log entries to workflow nodes and observers with hierarchical logging support via child() method. |
-| `src/decorators/step.ts` | @Step decorator that wraps methods to emit stepStart/stepEnd events, track timing, handle errors, and optionally snapshot state. |
-| `src/decorators/task.ts` | @Task decorator that wraps methods returning child workflows, automatically attaches them, and supports concurrent execution. |
-| `src/decorators/observed-state.ts` | @ObservedState decorator for marking fields to include in state snapshots with support for redaction and hiding. |
-| `src/debugger/tree-debugger.ts` | WorkflowTreeDebugger observer that builds node lookup maps and renders ASCII tree visualizations. |
-| `src/types/error.ts` | WorkflowError interface containing message, original error, workflowId, stack, state snapshot, and logs. |
-| `src/types/error-strategy.ts` | ErrorMergeStrategy interface for merging multiple errors from concurrent operations. |
-| `src/types/observer.ts` | WorkflowObserver interface defining onLog, onEvent, onStateUpdated, and onTreeChanged methods. |
-| `src/utils/observable.ts` | Lightweight Observable implementation for event streaming with subscription management. |
-| `src/utils/id.ts` | generateId() utility using crypto.randomUUID with timestamp fallback. |
-
-## 3. Bug Report Claim Validation
-
-| Claim | Location | Status | Evidence |
-|-------|----------|--------|----------|
-| **WorkflowLogger.child() signature** | `src/core/logger.ts:84` | ✅ **CONFIRMED** | Line 84: `child(parentLogId: string): WorkflowLogger {` - Returns new WorkflowLogger with parentLogId passed to constructor |
-| **Concurrent task execution** | `src/decorators/task.ts:112` | ✅ **CONFIRMED** | Line 112: `await Promise.all(runnable.map((w) => w.run()));` - Executes runnable workflows in parallel when `opts.concurrent` is true |
-| **ErrorMergeStrategy definition** | `src/types/error-strategy.ts` | ✅ **CONFIRMED** | File exists with interface defining `enabled: boolean`, `maxMergeDepth?: number`, and `combine?(errors: WorkflowError[]): WorkflowError` |
-| **trackTiming default** | `src/decorators/step.ts:94` | ✅ **CONFIRMED** | Line 94: `if (opts.trackTiming !== false)` - Default is true (timing tracked unless explicitly disabled) |
-| **Observer error handling** | `src/core/workflow.ts:376` | ✅ **CONFIRMED** | Lines 367-377: Observer callbacks wrapped in try-catch with `console.error('Observer onEvent error:', err);` at line 376 |
-| **getRootObservers method** | `src/core/workflow.ts:124-139` | ✅ **CONFIRMED** | Lines 124-139: Private method traversing parent chain with cycle detection using visited Set |
-| **Tree debugger node map** | `src/debugger/tree-debugger.ts:80-84` | ✅ **CONFIRMED** | Lines 80-84: onTreeChanged() clears nodeMap and calls buildNodeMap(root); buildNodeMap() at line 54 uses `this.nodeMap.set(node.id, node);` |
-
-**All 7 bug report claims are VALID and the code exists exactly as stated.**
-
-## 4. Decorator System Pattern
-
-The codebase uses **standard ECMAScript Stage 3 Decorators** (not legacy TypeScript decorators).
-
-### Pattern Structure
-
-All decorators follow this pattern:
-```typescript
-export function DecoratorName(opts: Options = {}) {
-  return function <This, Args extends unknown[], Return>(
-    originalMethod: (this: This, ...args: Args) => Promise<Return>,
-    context: ClassMethodDecoratorContext<This, (this: This, ...args: Args) => Promise<Return>>
-  ) {
-    // CRITICAL: Use regular function, not arrow function
-    async function wrapper(this: This, ...args: Args): Promise<Return> {
-      // Cast to WorkflowLike for accessing workflow properties
-      const wf = this as unknown as WorkflowLike;
-
-      // Pre-processing (emit events, capture start time)
-
-      const result = await originalMethod.call(this, ...args);
-
-      // Post-processing (emit events, attach children, etc.)
-
-      return result;
-    }
-
-    return wrapper;
-  };
-}
-```
-
-### Key Design Decisions
-
-1. **Regular function over arrow functions** - Preserves `this` binding for instance access
-2. **WorkflowLike interface casting** - Enables duck-typing for workflow-like objects
-3. **Lenient validation** - Non-workflow returns are silently skipped rather than throwing
-4. **Event emission pattern** - All decorators emit events via `wf.emitEvent()`
-
-## 5. Error Class Hierarchy
-
-```
-WorkflowError (interface)
-├── message: string
-├── original: unknown          // Original thrown error
-├── workflowId: string         // ID where error occurred
-├── stack?: string            // Stack trace if available
-├── state: SerializedWorkflowState  // State snapshot at error time
-└── logs: LogEntry[]          // Logs from failing node
-
-ErrorMergeStrategy (interface)
-├── enabled: boolean          // Enable error merging (default: false)
-├── maxMergeDepth?: number    // Maximum depth to merge errors
-└── combine?(errors: WorkflowError[]): WorkflowError  // Custom combiner
-```
-
-Error handling flow:
-1. Errors caught in decorator wrappers (@Step, @Task)
-2. Enriched with workflow context (state, logs, workflowId)
-3. Emitted as 'error' events to observers
-4. Re-thrown for upstream handling
-
-## 6. Observer Pattern Implementation
-
-### Observer Interface
-
-```typescript
-interface WorkflowObserver {
-  onLog(entry: LogEntry): void;
-  onEvent(event: WorkflowEvent): void;
-  onStateUpdated(node: WorkflowNode): void;
-  onTreeChanged(root: WorkflowNode): void;
-}
-```
-
-### Observer Management
-
-- **Registration**: `workflow.addObserver(observer)` - Only allowed on root workflows
-- **Storage**: Private `observers: WorkflowObserver[]` array on root workflow
-- **Propagation**: Child workflows access root observers via `getRootObservers()` method
-- **Error isolation**: All observer callbacks wrapped in try-catch to prevent observer failures from affecting workflow execution
-
-### Event Flow
-
-```
-Workflow.emitEvent()
-  ├── Push to node.events array
-  ├── Get observers via getRootObservers()
-  └── For each observer:
-      ├── Call onEvent(event)
-      ├── Call onTreeChanged(root) if tree update event
-      └── Catch and log errors (console.error)
-```
-
-### Key Implementation Details
-
-1. **Root-only observers**: Observers can only be added to root workflows (throws error if parent exists)
-2. **Cycle-safe traversal**: `getRootObservers()` uses visited Set to detect circular parent-child relationships
-3. **Lazy initialization**: Logger created with root observers in constructor
-4. **Multiple observer types**: WorkflowTreeDebugger, custom observers can be attached
-
-## 7. Logger Architecture
-
-### WorkflowLogger Class
-
-```typescript
-class WorkflowLogger {
-  private readonly parentLogId?: string;
-
-  constructor(
-    private readonly node: WorkflowNode,
-    private readonly observers: WorkflowObserver[],
-    parentLogId?: string
-  )
-
-  // Logging methods
-  debug(message: string, data?: unknown): void
-  info(message: string, data?: unknown): void
-  warn(message: string, data?: unknown): void
-  error(message: string, data?: unknown): void
-
-  // Hierarchical logging
-  child(parentLogId: string): WorkflowLogger
-}
-```
-
-### Log Entry Structure
-
-```typescript
-interface LogEntry {
-  id: string;                  // Unique identifier
-  workflowId: string;          // Workflow that created log
-  timestamp: number;           // Unix timestamp in ms
-  level: LogLevel;             // 'debug' | 'info' | 'warn' | 'error'
-  message: string;             // Log message
-  data?: unknown;              // Optional structured data
-  parentLogId?: string;        // Parent log ID for hierarchy
-}
-```
-
-### Logging Flow
-
-1. Log method called → `log(level, message, data)`
-2. LogEntry created with metadata and parentLogId if child logger
-3. Entry pushed to `node.logs` array
-4. All observers notified via `obs.onLog(entry)`
-5. Observer errors caught and logged to console
-
-### Key Features
-
-- **Hierarchical logging**: `child()` method creates logger with parentLogId reference
-- **Observer broadcast**: All log entries sent to all root observers
-- **Error isolation**: Observer onLog errors don't stop logging
-- **Timestamp tracking**: Automatic timestamp generation
-
-## 8. Additional Architecture Patterns
-
-### Dual Tree Architecture
-
-The codebase maintains **two synchronized tree structures**:
-
-1. **Workflow Tree**: `workflow.children` array (Workflow class instances)
-2. **Node Tree**: `node.children` array (WorkflowNode data structures)
-
-This 1:1 mirror is maintained in:
-- `attachChild()`: Adds to both trees and sets parent references
-- `detachChild()`: Removes from both trees and clears parent references
-
-### Cycle Detection
-
-Three methods use visited Set pattern for cycle detection:
-
-1. `getRootObservers()` - Lines 124-139
-2. `isDescendantOf()` - Lines 151-169 (private helper for attachChild validation)
-3. `getRoot()` - Lines 175-190
-
-All throw `'Circular parent-child relationship detected'` if cycle found.
-
-### Event Types
-
-The discriminated union includes 17+ event types:
-- Core: childAttached, childDetached, stateSnapshot, stepStart, stepEnd, error, taskStart, taskEnd, treeUpdated
-- Agent: agentPromptStart, agentPromptEnd
-- Tools: toolInvocation, mcpEvent
-- Reflection: reflectionStart, reflectionEnd
-- Cache: cacheHit, cacheMiss
-
-## 9. Testing Strategy
-
-The test suite is organized into:
-
-- **Unit tests**: Individual component testing
-- **Integration tests**: Multi-component workflows
-- **Adversarial tests**: Edge cases, circular references, deep hierarchies, PRD compliance
-
-Test coverage includes:
-- Decorator behavior
-- Tree mirroring (workflow/node tree consistency)
-- Reparenting workflows
-- Observer propagation
-- attachChild/detachChild validation
-- Circular reference detection
-- Performance benchmarks (attachChild performance)
-
-## 10. Dependencies
-
-**Core Runtime**:
-- `@anthropic-ai/sdk` ^0.71.1 - Anthropic Claude API
-- `zod` ^3.23.0 - Schema validation
-- `lru-cache` ^10.4.3 - LLM response caching
-
-**Development**:
-- `typescript` ^5.2.0 - Stage 3 decorators support
-- `vitest` ^1.0.0 - Testing framework
-- `tsx` ^4.21.0 - TypeScript execution
-
-## Summary
-
-The Hierarchical Workflow Engine is a well-architected TypeScript library that provides:
-
-1. **Validated bug report claims** - All 7 claims confirmed accurate
-2. **Modern decorator pattern** - ECMAScript Stage 3 decorators with proper `this` preservation
-3. **Robust observer system** - Root-based observer management with error isolation
-4. **Dual tree architecture** - Synchronized workflow and node trees with cycle detection
-5. **Rich error context** - WorkflowError includes state snapshots and logs
-6. **Hierarchical logging** - Parent-child log relationships via child() method
-7. **Comprehensive tooling** - Debugger, caching, reflection, and introspection
-
-The codebase demonstrates strong engineering practices with clear separation of concerns, extensive type safety, and thorough test coverage including adversarial test cases.