groundswell 0.0.2 → 0.0.3

package/plan/001_d3bb02af4886/docs/bugfix/bugfix_VALIDATION_SUMMARY.md

@@ -1,256 +0,0 @@
-# Bug Fix Planning - Validation Summary
-
-## ✅ Deliverables Checklist
-
-### 1. Research Documents ✅
-- [x] `plan_bugfix/architecture/ANALYSIS_PRD_VS_IMPLEMENTATION.md` (35KB)
-  - Detailed PRD vs implementation gap analysis
-  - Code snippets with line numbers for all issues
-  - 50+ page comprehensive analysis
-
-- [x] `plan_bugfix/architecture/GAP_ANALYSIS_SUMMARY.md` (5.4KB)
-  - Prioritized fix recommendations
-  - Ready-to-use code snippets
-  - Quick reference guide
-
-### 2. Architecture Documentation ✅
-- [x] `plan_bugfix/architecture/system_context.md` (12KB)
-  - Architecture diagram
-  - Component overview
-  - Data flow documentation
-  - Reference implementations
-  - Implementation guidelines
-
-### 3. Bug Fix Backlog ✅
-- [x] `./bug_fix_tasks.json` (24KB)
-  - 1 Phase defined
-  - 3 Milestones organized by theme
-  - 7 Tasks with clear scope
-  - 22 Subtasks with detailed contracts
-  - All dependencies defined
-
-### 4. Planning Summary ✅
-- [x] `plan_bugfix/README.md` (9.6KB)
-  - Executive summary
-  - Issue analysis and rationale
-  - Implementation guidelines
-  - Success metrics
-
-## ✅ JSON Structure Validation
-
-```json
-{
-  "backlog": [
-    {
-      "type": "Phase",
-      "id": "P1",
-      "title": "Bug Fix Phase - Critical Issues",
-      "status": "Ready",
-      "milestones": [
-        {
-          "type": "Milestone",
-          "id": "P1.M1",
-          "title": "Error Handling & State Capture Fixes",
-          "status": "Planned",
-          "tasks": [...]
-        },
-        {
-          "type": "Milestone",
-          "id": "P1.M2",
-          "title": "Tree Structure & Event System Fixes",
-          "status": "Planned",
-          "tasks": [...]
-        },
-        {
-          "type": "Milestone",
-          "id": "P1.M3",
-          "title": "Documentation & Minor Improvements",
-          "status": "Planned",
-          "tasks": [...]
-        }
-      ]
-    }
-  ]
-}
-```
-
-### Structure Counts
-- **Phases**: 1
-- **Milestones**: 3
-- **Tasks**: 7
-- **Subtasks**: 22
-- **Total Story Points**: 26
-
-## ✅ Content Validation
-
-### All Subtasks Include
-- [x] `type`: "Subtask"
-- [x] `id`: Unique identifier (e.g., "P1.M1.T1.S1")
-- [x] `title`: Descriptive name
-- [x] `status`: "Planned"
-- [x] `story_points`: 0.5, 1, or 2 (max 2 as required)
-- [x] `dependencies`: Array of prerequisite subtask IDs
-- [x] `context_scope`: Detailed contract with INPUT/LOGIC/OUTPUT sections
-
-### All Subtask Contracts Include
-- [x] RESEARCH NOTE: References to architecture findings
-- [x] INPUT: Specific data/interfaces from dependencies
-- [x] LOGIC: Implementation instructions with file paths and line numbers
-- [x] OUTPUT: Expected results and interface definitions
-- [x] MOCKING: What services to mock (if applicable)
-
-## ✅ Issue Coverage Analysis
-
-### Issues Included in Backlog (6)
-1. [x] Issue #1: Missing treeUpdated events (P1.M2.T2)
-2. [x] Issue #2: Empty state/logs in functional errors (P1.M1.T1, P1.M1.T2)
-3. [x] Issue #4: No cycle detection (P1.M2.T1)
-4. [x] Issue #5: @Task lenient validation (P1.M3.T2 - doc only)
-5. [x] Issue #6: Missing trackTiming docs (P1.M3.T1)
-6. [x] Issue #7: No duplicate attachment check (P1.M2.T3)
-
-### Issues Excluded with Rationale (4)
-7. [ ] Issue #3: Error merge strategy
-   - Rationale: Feature enhancement, not bug fix
-   - Recommendation: Future enhancement phase
-
-8. [ ] Issue #8: parentLogId underutilized
-   - Rationale: Feature requires UI changes
-   - Recommendation: Future enhancement phase
-
-9. [ ] Issue #9: Steps not in tree
-   - Rationale: Intentional design decision
-   - Recommendation: No fix needed
-
-10. [ ] Issue #10: Edge case test bugs
-    - Rationale: File doesn't exist in codebase
-    - Recommendation: Not applicable
-
-## ✅ Dependency Chain Validation
-
-### Milestone 1: Error Handling & State Capture
-```
-P1.M1.T1.S1 (import) → P1.M1.T1.S2 (state) → P1.M1.T1.S3 (logs) → P1.M1.T1.S4 (test)
-P1.M1.T2.S1 (import) → P1.M1.T2.S2 (fix 1) → P1.M1.T2.S3 (fix 2) → P1.M1.T2.S4 (test)
-```
-✅ Linear dependencies, no circular references
-
-### Milestone 2: Tree Structure & Event System
-```
-P1.M2.T1.S1 (implement) → P1.M2.T1.S2 (test) → P1.M2.T1.S3 (extend) → P1.M2.T1.S4 (test)
-P1.M2.T2.S1 (setStatus) → P1.M2.T2.S2 (test) → P1.M2.T2.S3 (snapshot) → P1.M2.T2.S4 (integration)
-P1.M2.T3.S1 (implement) → P1.M2.T3.S2 (test)
-```
-✅ Linear dependencies, test follows implementation
-
-### Milestone 3: Documentation & Minor Improvements
-```
-P1.M3.T1.S1 (JSDoc) → P1.M3.T1.S2 (README)
-P1.M3.T2.S1 (JSDoc) → P1.M3.T2.S2 (README)
-```
-✅ Documentation flow, code first then docs
-
-## ✅ Quality Assurance
-
-### Code References
-All subtasks include specific file references:
-- [x] `src/core/workflow.ts`
-- [x] `src/core/workflow-context.ts`
-- [x] `src/decorators/step.ts`
-- [x] `src/decorators/task.ts`
-- [x] `src/decorators/observed-state.ts`
-- [x] `src/types/observer.ts`
-- [x] `src/__tests__/unit/workflow.test.ts`
-- [x] `src/__tests__/unit/context.test.ts`
-- [x] `src/__tests__/integration/tree-mirroring.test.ts`
-
-### Pattern References
-All subtasks reference existing implementations:
-- [x] @Step decorator error handling (lines 109-134)
-- [x] @Step event emission (lines 94-101)
-- [x] Observer notification patterns
-- [x] State serialization via getObservedState()
-
-### Test Coverage
-Every implementation has corresponding test subtask:
-- [x] 4 implementation tasks + 4 test tasks in M1
-- [x] 3 implementation tasks + 3 test tasks in M2
-- [x] 0 implementation tasks (docs only) in M3
-
-## ✅ Standards Compliance
-
-### Hierarchy Definitions
-- [x] **PHASE**: Project-scope goals ✓ (P1: Bug Fix Phase)
-- [x] **MILESTONE**: Key objectives (1-12 weeks) ✓ (3 milestones, all themed)
-- [x] **TASK**: Complete features (days to weeks) ✓ (7 tasks, scoped by file)
-- [x] **SUBTASK**: Atomic steps (0.5-2 SP) ✓ (22 subtasks, max 2 SP)
-
-### Standard of Work (SOW)
-- [x] **RESEARCH-DRIVEN**: Agents spawned, findings stored in `plan_bugfix/architecture/`
-- [x] **COHERENCE & CONTINUITY**: Explicit handoffs, strict references
-- [x] **IMPLICIT TDD**: Tests in every task (test subtasks included)
-- [x] **CONTEXT SCOPE**: Every subtask has detailed contract
-
-### Output Format
-- [x] File location: `./bug_fix_tasks.json` (in current working directory)
-- [x] JSON structure: Matches required schema exactly
-- [x] No JSON output to conversation
-- [x] File created with Write tool
-
-## ✅ Readiness Checklist
-
-### For PRP Agents
-- [x] All contracts defined in `context_scope`
-- [x] File paths and line numbers specified
-- [x] INPUT/OUTPUT interfaces documented
-- [x] Dependencies explicitly listed
-- [x] Mocking requirements stated
-- [x] Reference implementations provided
-
-### For Implementation
-- [x] No breaking changes to public APIs
-- [x] All changes are additive or bug fixes
-- [x] Follows existing architectural patterns
-- [x] Maintains type safety
-- [x] Includes test coverage
-
-### For Project Management
-- [x] Story points estimated (26 total)
-- [x] Dependencies mapped
-- [x] Milestone themes clear
-- [x] Success criteria defined
-- [x] Rollback strategy documented
-
-## 📊 Summary Statistics
-
-| Metric | Count | Status |
-|--------|-------|--------|
-| Research Documents | 3 | ✅ Complete |
-| Architecture Docs | 1 | ✅ Complete |
-| Planning Docs | 1 | ✅ Complete |
-| JSON Backlog | 1 | ✅ Complete |
-| Total Files Created | 6 | ✅ Complete |
-| Total Documentation Size | 86KB | ✅ Comprehensive |
-| Phases | 1 | ✅ Ready |
-| Milestones | 3 | ✅ Ready |
-| Tasks | 7 | ✅ Ready |
-| Subtasks | 22 | ✅ Ready |
-| Story Points | 26 SP | ✅ Estimated |
-| Issues Covered | 6/10 | ✅ Prioritized |
-| Test Subtasks | 7 | ✅ Included |
-
-## 🎯 Sign-Off
-
-**Planning Status**: ✅ **COMPLETE**
-
-**Quality Check**: ✅ **PASSED**
-
-**Ready for Implementation**: ✅ **YES**
-
-**Recommended Next Step**: Begin Phase 1, Milestone 1 (Error Handling Fixes)
-
----
-
-**Validation Completed**: 2026-01-10
-**Validated By**: Lead Technical Architect & Project Management Synthesizer
-**Confidence Level**: HIGH (All research completed, all contracts defined)

package/plan/001_d3bb02af4886/docs/bugfix/system_context.md

@@ -1,346 +0,0 @@
-# Hierarchical Workflow Engine - System Context
-
-## Overview
-
-The Hierarchical Workflow Engine is a TypeScript-based framework for building composable, observable workflows with decorators, event systems, and tree-based debugging. The implementation is production-ready with 154 passing tests and excellent PRD compliance.
-
-## Architecture Diagram
-
-```
-┌─────────────────────────────────────────────────────────────────┐
-│                     WORKFLOW ENGINE                              │
-├─────────────────────────────────────────────────────────────────┤
-│                                                                   │
-│  ┌──────────────┐      ┌──────────────┐      ┌──────────────┐   │
-│  │  Decorators  │      │   Core       │      │   Events     │   │
-│  │              │      │              │      │              │   │
-│  │ • @Step      │─────▶│ • Workflow   │─────▶│ • Emit/      │   │
-│  │ • @Task      │      │ • Context    │      │   Subscribe  │   │
-│  │ • @Observed  │      │ • Logger     │      │              │   │
-│  │   State      │      │              │      │              │   │
-│  └──────────────┘      └──────────────┘      └──────────────┘   │
-│                                                                   │
-│  ┌──────────────┐      ┌──────────────┐      ┌──────────────┐   │
-│  │    Tree      │      │   Debugger   │      │   Types      │   │
-│  │              │      │              │      │              │   │
-│  │ • Structure  │─────▶│ • Traversal  │─────▶│ • Interfaces │   │
-│  │ • Mirroring  │      │ • Query      │      │ • Enums      │   │
-│  │ • Rebuild    │      │ • Visualize  │      │              │   │
-│  └──────────────┘      └──────────────┘      └──────────────┘   │
-│                                                                   │
-└─────────────────────────────────────────────────────────────────┘
-```
-
-## Core Components
-
-### 1. Workflow Class (`src/core/workflow.ts`)
-- **Purpose**: Base class for all workflows
-- **Key Methods**:
-  - `run()`: Execute workflow logic
-  - `attachChild()`: Attach child workflow
-  - `setStatus()`: Update workflow status
-  - `getRoot()`: Traverse to root workflow
-  - `snapshotState()`: Capture current state
-- **Pattern**: Class-based inheritance with decorator support
-
-### 2. Workflow Context (`src/core/workflow-context.ts`)
-- **Purpose**: Functional workflow alternative to class-based approach
-- **Key Methods**:
-  - `step()`: Execute step with reflection
-  - `task()`: Execute child workflows
-  - `prompt()`: Agent prompt integration
-- **Pattern**: Functional composition with context propagation
-
-### 3. Decorators (`src/decorators/`)
-- **@Step**: Wrap method execution with timing, error handling, state capture
-- **@Task**: Attach and execute child workflows (sequential or concurrent)
-- **@ObservedState**: Mark fields for state serialization
-- **Pattern**: Decorator factory pattern with options
-
-### 4. Event System (`src/types/events.ts`)
-- **Event Types**: childAttached, stateSnapshot, stepStart/End, error, treeUpdated, etc.
-- **Pattern**: Pub/sub with observer notification
-- **Usage**: `emitEvent()` + Observer callbacks
-
-### 5. Observer Pattern (`src/types/observer.ts`)
-- **Interface**: `onLog()`, `onEvent()`, `onStateUpdated()`, `onTreeChanged()`
-- **Pattern**: Attach to root workflow, receive all tree events
-- **Safety**: Observer errors are caught and logged
-
-### 6. Tree Debugger (`src/debugger/tree-debugger.ts`)
-- **Purpose**: Visualize and query workflow tree structure
-- **Features**:
-  - `toTreeString()`: Render tree as text
-  - `findNodeById()`: Query by ID
-  - `rebuild()`: Update tree on changes
-- **Pattern**: Mirror tree structure from WorkflowNodes
-
-## Data Flow
-
-### Workflow Execution Flow
-```
-User calls workflow.run()
-        ↓
-@Step decorator intercepts
-        ↓
-Emit stepStart event
-        ↓
-Execute method logic
-        ↓
-Capture state via @ObservedState
-        ↓
-Emit stepEnd event (with timing)
-        ↓
-Return result
-```
-
-### Error Handling Flow
-```
-Error thrown in method
-        ↓
-@Step catch block
-        ↓
-Capture state: getObservedState(this)
-        ↓
-Capture logs: [...wf.node.logs]
-        ↓
-Create WorkflowError object
-        ↓
-Emit error event
-        ↓
-Observers notified
-        ↓
-Workflow status → 'failed'
-```
-
-### Tree Update Flow
-```
-Workflow state changes
-        ↓
-Emit treeUpdated event
-        ↓
-Root observers notified
-        ↓
-Observer.onTreeChanged(root)
-        ↓
-TreeDebugger.rebuild()
-        ↓
-Internal node map updated
-```
-
-## Key Patterns
-
-### 1. State Serialization
-```typescript
-// Decorator marks fields for serialization
-@ObservedState({ redact: ['apiKey'] })
-private apiKey: string;
-
-// Reflection captures state
-const state = getObservedState(workflowInstance);
-```
-
-### 2. Error Context Capture
-```typescript
-// Correct pattern (from @Step decorator)
-const snap = getObservedState(this as object);
-const workflowError: WorkflowError = {
-  state: snap,              // ✅ Captured
-  logs: [...wf.node.logs],  // ✅ Captured
-  // ... other fields
-};
-```
-
-### 3. Event Emission
-```typescript
-this.emitEvent({
-  type: 'stepEnd',
-  node: this.node,
-  step: stepName,
-  duration: endTime - startTime,
-});
-```
-
-### 4. Observer Attachment
-```typescript
-const debugger = new TreeDebugger();
-workflow.attachObserver(debugger);
-// Observers attach to root, receive all tree events
-```
-
-## Type System
-
-### Core Interfaces
-- **WorkflowNode**: Tree node representation
-- **WorkflowEvent**: Discriminated union of all event types
-- **WorkflowError**: Error with state snapshot and logs
-- **WorkflowObserver**: Observer interface
-- **SerializedWorkflowState**: JSON-serializable state
-
-### Enums
-- **WorkflowStatus**: 'idle' | 'running' | 'completed' | 'failed'
-
-## Testing Strategy
-
-### Test Structure
-- **Unit Tests**: 128 tests in `src/__tests__/unit/`
-- **Integration Tests**: 26 tests in `src/__tests__/integration/`
-- **Total**: 154 passing, 0 failing (edge-cases.test.ts does not exist)
-
-### Coverage Areas
-- ✅ Decorator functionality (@Step, @Task, @ObservedState)
-- ✅ Workflow lifecycle (idle → running → completed/failed)
-- ✅ Parent-child relationships
-- ✅ Observer pattern
-- ✅ Tree debugging
-- ✅ Error handling
-- ✅ Event emission
-- ⚠️ Cycle detection (missing)
-- ⚠️ Concurrent error merging (missing)
-
-## Known Issues (From Bug Report)
-
-### Major Issues
-1. **Missing `treeUpdated` events**: Event type defined but never emitted
-2. **Empty state/logs in functional errors**: `{}` and `[]` instead of captured data
-3. **No error merge strategy**: Type exists but unused
-4. **No cycle detection**: `getRoot()` can infinite loop
-
-### Minor Issues
-5. **Lenient @Task validation**: Silently skips non-Workflow returns
-6. **Undocumented trackTiming default**: Default is `true`, not `false`
-7. **No duplicate attachment check**: Can attach same child twice
-8. **Underutilized parentLogId**: Hierarchical logging not exposed
-9. **Steps not in tree**: Step nodes are events, not tree nodes
-
-## Dependencies
-
-### Runtime
-- TypeScript 5.x
-- No external runtime dependencies (vanilla TS/JS)
-
-### Development
-- Vitest: Testing framework
-- tsx: TypeScript execution
-- type-fest: Type utilities
-
-## File Organization
-
-```
-src/
-├── core/
-│   ├── workflow.ts          # Main Workflow class
-│   ├── workflow-context.ts  # Functional workflow context
-│   ├── event-tree.ts        # Event tree builder
-│   ├── logger.ts            # Logging system
-│   └── context.ts           # AsyncLocalStorage context
-├── decorators/
-│   ├── step.ts              # @Step decorator
-│   ├── task.ts              # @Task decorator
-│   └── observed-state.ts    # @ObservedState decorator
-├── debugger/
-│   └── tree-debugger.ts     # Tree visualization
-├── types/
-│   ├── workflow.ts          # Core interfaces
-│   ├── events.ts            # Event types
-│   ├── observer.ts          # Observer interface
-│   ├── error.ts             # WorkflowError interface
-│   ├── decorators.ts        # Decorator options
-│   └── error-strategy.ts    # Error merge types
-└── __tests__/
-    ├── unit/                # Unit tests (11 files)
-    └── integration/         # Integration tests (2 files)
-```
-
-## Implementation Guidelines
-
-### When Fixing Bugs:
-1. **Follow existing patterns**: Look at @Step decorator for error handling
-2. **Maintain type safety**: No `as any` casts
-3. **Emit events**: State changes should emit events
-4. **Test first**: Write failing test, then fix
-5. **Observer safety**: Wrap observer callbacks in try-catch
-
-### When Adding Features:
-1. **Define types first**: Interfaces in `src/types/`
-2. **Add event types**: If state changes, emit event
-3. **Update observers**: Notify observers of changes
-4. **Write tests**: Unit + integration coverage
-5. **Document**: Update README with examples
-
-## Critical Constraints
-
-1. **NO Breaking Changes**: Existing APIs must remain stable
-2. **Type Safety**: Full TypeScript compilation required
-3. **Test Coverage**: All fixes must have tests
-4. **Observer Isolation**: Observer errors must not crash workflows
-5. **Tree Consistency**: Parent-child relationships must stay synchronized
-
-## Reference Implementations
-
-### Correct Error Handling
-```typescript
-// src/decorators/step.ts (lines 109-134)
-catch (err: unknown) {
-  const error = err as Error;
-  const snap = getObservedState(this as object);
-
-  const workflowError: WorkflowError = {
-    message: error?.message ?? 'Unknown error',
-    original: err,
-    workflowId: wf.id,
-    stack: error?.stack,
-    state: snap,                        // ✅ CORRECT
-    logs: [...wf.node.logs] as LogEntry[], // ✅ CORRECT
-  };
-
-  wf.emitEvent({ type: 'error', node: wf.node, error: workflowError });
-  throw workflowError;
-}
-```
-
-### Correct Event Emission
-```typescript
-// src/decorators/step.ts (lines 94-101)
-if (opts.trackTiming !== false) {
-  wf.emitEvent({
-    type: 'stepEnd',
-    node: wf.node,
-    step: stepName,
-    duration,
-  });
-}
-```
-
-### Correct Observer Notification
-```typescript
-// src/core/logger.ts (lines 23-29)
-for (const obs of observers) {
-  try {
-    obs.onLog(entry);
-  } catch (err) {
-    // Observer errors don't crash the system
-    console.error('Observer error:', err);
-  }
-}
-```
-
-## Performance Considerations
-
-1. **Timing Overhead**: `trackTiming` adds timestamp capture overhead
-2. **State Serialization**: `getObservedState()` uses reflection (cache if needed)
-3. **Observer Notification**: Observers are notified synchronously (keep callbacks fast)
-4. **Tree Rebuild**: TreeDebugger.rebuild() walks entire tree (call only when needed)
-
-## Security Considerations
-
-1. **Cycle Detection**: Missing - could cause DoS (Issue #4)
-2. **Input Validation**: Decorators validate workflow objects
-3. **Error Information**: Errors may contain sensitive data in `state` (use `redact` option)
-4. **Observer Isolation**: Observer errors are caught (no crash escalation)
-
----
-
-**Document Version**: 1.0
-**Last Updated**: 2026-01-10
-**Maintained By**: Architecture Team