groundswell 0.0.2 → 1.0.0

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

@@ -1,529 +0,0 @@
-name: "P1.M1.T1.S3 - Fix Empty Logs in runFunctional() Error Handler"
-description: |
-  Bug fix for functional workflow error handler missing actual logs capture
----
-
-## Goal
-
-**Feature Goal**: Replace the empty `logs: []` array in the `runFunctional()` catch block with actual captured logs from `this.node.logs`
-
-**Deliverable**: Single line change in `src/core/workflow.ts` line 295: `logs: []` → `logs: [...this.node.logs] as LogEntry[]`
-
-**Success Definition**: Error events emitted from functional workflows contain populated `logs` array with all log entries captured during execution, enabling debugging context for failure analysis.
-
-## User Persona
-
-**Target User**: Developer debugging functional workflow failures
-
-**Use Case**: When a functional workflow (created using executor pattern) throws an error, the developer needs to inspect both state AND logs to understand what went wrong
-
-**User Journey**:
-1. Developer creates functional workflow using `new Workflow({ name: 'MyWorkflow' }, async (ctx) => { ... })`
-2. Workflow executes and throws an error
-3. Error event is emitted to observers
-4. Developer inspects `error.logs` array to see log messages leading up to failure
-5. Developer uses logs + state to diagnose root cause
-
-**Pain Points Addressed**:
-- Currently `error.logs` is always empty `[]` in functional workflows
-- No debugging context when functional workflows fail
-- Inconsistent with `@Step` decorator which correctly captures logs
-- Developers must manually add logging to diagnose functional workflow failures
-
-## Why
-
-- **Debugging Capability**: Developers can see actual logs when functional workflows fail
-- **Error Introspection**: Error events contain complete debugging context (state + logs)
-- **PRD Compliance**: Meets Section 5.1 requirements that `WorkflowError` must be populated with actual data
-- **Consistency**: Functional workflows now behave consistently with class-based `@Step` decorator pattern
-- **Completeness**: S3 completes the error handler fix started in S2 (state capture)
-
-## What
-
-Replace `logs: []` with `logs: [...this.node.logs] as LogEntry[]` in the `runFunctional()` catch block at line 295 of `src/core/workflow.ts`.
-
-### Success Criteria
-
-- [ ] Line 295 modified: `logs: []` → `logs: [...this.node.logs] as LogEntry[]`
-- [ ] Error events from functional workflows contain populated logs array
-- [ ] Log entries include timestamp, level, and message data
-- [ ] No mutation of original `this.node.logs` array (spread creates copy)
-- [ ] All existing tests still pass
-- [ ] No TypeScript compilation errors
-
-## All Needed Context
-
-### Context Completeness Check
-
-**No Prior Knowledge Test**: If someone knew nothing about this codebase, would they have everything needed to implement this successfully?
-
-**YES** - This PRP provides:
-- Exact file location and line number
-- Current code snippet and target code snippet
-- Reference implementation from `@Step` decorator
-- Type definitions for all involved types
-- Validation commands specific to this project
-- Test framework and patterns used in codebase
-
-### Documentation & References
-
-```yaml
-# MUST READ - Critical implementation context
-- file: src/core/workflow.ts
-  why: Target file containing the bug - runFunctional() catch block at lines 282-300
-  pattern: Error object structure with WorkflowError interface
-  gotcha: Line 295 has `logs: []` that must be replaced with actual logs capture
-  line: 295
-
-- file: src/decorators/step.ts
-  why: Reference implementation showing CORRECT pattern for logs capture
-  pattern: Line 122 - `logs: [...wf.node.logs] as LogEntry[]`
-  critical: Use this EXACT pattern in runFunctional() error handler
-  line: 116-123
-
-- file: src/types/logging.ts
-  why: LogEntry type definition - understand what logs array contains
-  pattern: Interface with id, workflowId, timestamp, level, message, data?, parentLogId?
-  section: Lines 9-24
-
-- file: src/core/workflow.ts
-  why: WorkflowNode type - this.node.logs property structure
-  pattern: node.logs: LogEntry[] (line 104)
-  gotcha: Logs are populated by WorkflowLogger via this.node.logs.push(entry)
-
-- file: src/core/logger.ts
-  why: Understand how logs are populated in this.node.logs
-  pattern: emit() method at line 22: this.node.logs.push(entry)
-  critical: Confirms logs array is populated during workflow execution
-
-# DEPENDENCY CONTEXT - Must be complete before S3
-- file: src/core/workflow.ts
-  why: P1.M1.T1.S1 already added getObservedState import (line 10)
-  dependency: S1 must be complete before S2/S3 implementation
-  line: 10
-
-- file: src/core/workflow.ts
-  why: P1.M1.T1.S2 already fixed state capture (line 294)
-  dependency: S2 must be complete - S3 modifies same error object
-  line: 294
-
-# TESTING PATTERNS
-- file: src/__tests__/unit/workflow.test.ts
-  why: Example test patterns for workflow testing
-  pattern: Uses vitest, WorkflowObserver pattern for capturing events/logs
-  critical: Observer pattern for testing error events with logs
-
-- file: package.json
-  why: Test scripts and dependencies
-  pattern: `"test": "vitest run"`, `"test:watch": "vitest"`
-  critical: Use `npm test` to run tests
-
-- file: vitest.config.ts
-  why: Test configuration
-  pattern: Test files in `src/__tests__/**/*.test.ts`
-```
-
-### Current Codebase Tree
-
-```bash
-groundswell/
-├── src/
-│   ├── core/
-│   │   ├── workflow.ts          # TARGET FILE - Line 295
-│   │   ├── logger.ts            # Log population logic
-│   │   └── workflow-context.ts  # Related error handlers (P1.M1.T2)
-│   ├── decorators/
-│   │   ├── step.ts              # REFERENCE PATTERN - Line 122
-│   │   └── observed-state.ts    # getObservedState function
-│   ├── types/
-│   │   ├── logging.ts           # LogEntry interface
-│   │   ├── observer.ts          # WorkflowObserver interface
-│   │   └── index.ts             # Type exports
-│   └── __tests__/
-│       ├── unit/
-│       │   ├── workflow.test.ts     # Workflow test patterns
-│       │   └── decorators.test.ts   # Decorator test patterns
-│       └── integration/
-│           └── agent-workflow.test.ts
-├── plan_bugfix/
-│   └── P1M1T1S3/
-│       └── PRP.md                # THIS DOCUMENT
-└── package.json                   # npm test script
-```
-
-### Desired Codebase Tree (No new files - modification only)
-
-```bash
-# No new files created - only modification to existing file
-# Modified: src/core/workflow.ts (line 295)
-```
-
-### Known Gotchas & Library Quirks
-
-```typescript
-// CRITICAL: TypeScript spread operator creates shallow copy
-// [...this.node.logs] copies array references, not deep copy
-// For LogEntry[] this is acceptable - entries are simple objects
-
-// CRITICAL: Type assertion 'as LogEntry[]' is required
-// Even though this.node.logs is typed as LogEntry[], the spread
-// operator can cause type inference issues in error object context
-// Solution: Use 'as LogEntry[]' for explicit type safety
-
-// GOTCHA: getObservedState import already added in P1.M1.T1.S1
-// Line 10: import { getObservedState } from '../decorators/observed-state.js';
-// Do NOT add this import again - it's already there
-
-// GOTCHA: State capture already fixed in P1.M1.T1.S2
-// Line 294: state: getObservedState(this),
-// Only modify line 295 for logs - do NOT touch line 294
-
-// PATTERN: Follow @Step decorator exactly (src/decorators/step.ts:122)
-// logs: [...wf.node.logs] as LogEntry[]
-// Replace 'wf' with 'this' for runFunctional() context
-
-// TESTING: Vitest is the test framework
-// Run tests with: npm test
-// Watch mode: npm run test:watch
-
-// BUILD: TypeScript compilation check
-// Run: npm run lint (tsc --noEmit)
-```
-
-## Implementation Blueprint
-
-### Data Models and Structure
-
-```typescript
-// LogEntry type (from src/types/logging.ts)
-interface LogEntry {
-  id: string;
-  workflowId: string;
-  timestamp: number;
-  level: LogLevel;  // 'debug' | 'info' | 'warn' | 'error'
-  message: string;
-  data?: unknown;
-  parentLogId?: string;
-}
-
-// WorkflowError type (from src/types/error.ts)
-interface WorkflowError {
-  message: string;
-  original: unknown;
-  workflowId: string;
-  stack?: string;
-  state: SerializedWorkflowState;
-  logs: LogEntry[];  // TARGET FIELD - Currently empty []
-}
-```
-
-### Implementation Tasks
-
-```yaml
-Task 1: MODIFY src/core/workflow.ts line 295
-  - LOCATION: runFunctional() method catch block (lines 282-300)
-  - CURRENT: logs: [],
-  - REPLACE_WITH: logs: [...this.node.logs] as LogEntry[],
-  - FOLLOW_PATTERN: src/decorators/step.ts line 122
-  - PRESERVE: All other error object fields (message, original, workflowId, stack, state)
-  - TYPE_SAFETY: Add 'as LogEntry[]' type assertion for explicit typing
-
-Task 2: VALIDATE TypeScript compilation
-  - RUN: npm run lint (tsc --noEmit)
-  - EXPECTED: Zero compilation errors
-  - VERIFY: No type errors related to LogEntry or spread operator
-  - FIX_IF_NEEDED: Type assertion should resolve any inference issues
-
-Task 3: VALIDATE existing tests still pass
-  - RUN: npm test (vitest run)
-  - EXPECTED: All existing tests pass
-  - VERIFY: No regressions in workflow or decorator tests
-  - FIX_IF_NEEDED: Should be no failures - this is a pure data capture improvement
-```
-
-### Implementation Patterns & Key Details
-
-```typescript
-// CURRENT CODE (src/core/workflow.ts:286-297)
-this.emitEvent({
-  type: 'error',
-  node: this.node,
-  error: {
-    message: error instanceof Error ? error.message : 'Unknown error',
-    original: error,
-    workflowId: this.id,
-    stack: error instanceof Error ? error.stack : undefined,
-    state: getObservedState(this),  // FIXED in P1.M1.T1.S2
-    logs: [],                       // BUG: Empty array - FIX THIS LINE
-  },
-});
-
-// TARGET CODE (only change line 295)
-this.emitEvent({
-  type: 'error',
-  node: this.node,
-  error: {
-    message: error instanceof Error ? error.message : 'Unknown error',
-    original: error,
-    workflowId: this.id,
-    stack: error instanceof Error ? error.stack : undefined,
-    state: getObservedState(this),
-    logs: [...this.node.logs] as LogEntry[],  // FIXED: Capture actual logs
-  },
-});
-
-// REFERENCE PATTERN (src/decorators/step.ts:116-123)
-const workflowError: WorkflowError = {
-  message: error?.message ?? 'Unknown error',
-  original: err,
-  workflowId: wf.id,
-  stack: error?.stack,
-  state: snap,
-  logs: [...wf.node.logs] as LogEntry[],  // EXACT PATTERN TO FOLLOW
-};
-
-// KEY DIFFERENCES:
-// - @Step uses 'wf' (decorator context), runFunctional uses 'this'
-// - @Step uses 'error?.message', runFunctional uses conditional
-// - LOGS PATTERN IS IDENTICAL: [...source.node.logs] as LogEntry[]
-```
-
-### Integration Points
-
-```yaml
-DEPENDENCIES:
-  - P1.M1.T1.S1: MUST be complete (getObservedState import added)
-  - P1.M1.T1.S2: MUST be complete (state: getObservedState(this) fixed)
-  - Both S1 and S2 modify same error object - ensure they're complete
-
-INTEGRATION:
-  - this.node.logs: Populated by WorkflowLogger during execution
-  - getObservedState: Already imported and used for state capture
-  - WorkflowError: Type expects logs: LogEntry[] field
-
-NO_CHANGES_TO:
-  - Import statements (already added in S1)
-  - Error object structure (only populating logs field)
-  - Event emission logic (only changing logs content)
-```
-
-## Validation Loop
-
-### Level 1: Syntax & Style (Immediate Feedback)
-
-```bash
-# TypeScript compilation check
-npm run lint
-# Runs: tsc --noEmit
-# Expected: Zero errors
-# If errors: Check type assertion 'as LogEntry[]' is present
-
-# Type check specific file
-npx tsc --noEmit src/core/workflow.ts
-# Expected: No type errors related to logs or LogEntry
-
-# Build check
-npm run build
-# Runs: tsc (compiles to dist/)
-# Expected: Successful compilation, no errors
-```
-
-### Level 2: Unit Tests (Component Validation)
-
-```bash
-# Run all tests
-npm test
-# Runs: vitest run
-# Expected: All tests pass
-
-# Run specific workflow test file
-npx vitest run src/__tests__/unit/workflow.test.ts
-# Expected: All workflow tests pass
-
-# Run decorator tests (reference implementation)
-npx vitest run src/__tests__/unit/decorators.test.ts
-# Expected: All decorator tests pass (verifies pattern is correct)
-
-# Watch mode for development
-npm run test:watch
-# Runs: vitest (watch mode)
-# Use for iterative development
-```
-
-### Level 3: Integration Testing (System Validation)
-
-```bash
-# Run integration tests
-npx vitest run src/__tests__/integration/
-# Expected: All integration tests pass
-
-# Manual test: Functional workflow with error
-# Create test file: test-functional-error-logs.ts
-import { Workflow } from './dist/index.js';
-
-const wf = new Workflow({ name: 'TestWorkflow' }, async (ctx) => {
-  ctx.logger.info('Before error');
-  ctx.logger.error('About to fail');
-  throw new Error('Test error');
-});
-
-const observer = {
-  onLog: () => {},
-  onEvent: (event) => {
-    if (event.type === 'error') {
-      console.log('Error logs:', event.error.logs);
-      // Expected: Array with 2 log entries
-      console.log('Log count:', event.error.logs.length);
-      // Expected: 2
-    }
-  },
-  onStateUpdated: () => {},
-  onTreeChanged: () => {},
-};
-
-wf.addObserver(observer);
-await wf.run().catch(() => {});
-
-# Expected output:
-# Error logs: [
-#   { id: '...', workflowId: '...', timestamp: ..., level: 'info', message: 'Before error' },
-#   { id: '...', workflowId: '...', timestamp: ..., level: 'error', message: 'About to fail' }
-# ]
-# Log count: 2
-```
-
-### Level 4: Domain-Specific Validation
-
-```bash
-# Verify logs are not mutated (shallow copy test)
-# Add test to verify spread operator creates copy
-test('runFunctional error logs should be a copy', async () => {
-  const wf = new Workflow({ name: 'Test' }, async (ctx) => {
-    ctx.logger.info('Test');
-    throw new Error('Fail');
-  });
-
-  let errorLogs: LogEntry[] | null = null;
-  const observer = {
-    onLog: () => {},
-    onEvent: (event) => {
-      if (event.type === 'error') {
-        errorLogs = event.error.logs;
-      }
-    },
-    onStateUpdated: () => {},
-    onTreeChanged: () => {},
-  };
-
-  wf.addObserver(observer);
-  await wf.run().catch(() => {});
-
-  // Verify logs are captured
-  expect(errorLogs).toBeDefined();
-  expect(errorLogs!.length).toBeGreaterThan(0);
-
-  // Verify it's a copy (not reference to node.logs)
-  expect(errorLogs).not.toBe(wf.getNode().logs);
-
-  // Verify content is the same
-  expect(errorLogs).toEqual(wf.getNode().logs);
-});
-
-# Verify log entries have required fields
-test('runFunctional error logs should have all LogEntry fields', async () => {
-  const wf = new Workflow({ name: 'Test' }, async (ctx) => {
-    ctx.logger.info('Test message', { data: 'test' });
-    throw new Error('Fail');
-  });
-
-  let errorLogs: LogEntry[] | null = null;
-  const observer = {
-    onLog: () => {},
-    onEvent: (event) => {
-      if (event.type === 'error') {
-        errorLogs = event.error.logs;
-      }
-    },
-    onStateUpdated: () => {},
-    onTreeChanged: () => {},
-  };
-
-  wf.addObserver(observer);
-  await wf.run().catch(() => {});
-
-  const log = errorLogs![0];
-  expect(log.id).toBeDefined();
-  expect(log.workflowId).toBe(wf.id);
-  expect(log.timestamp).toBeDefined();
-  expect(log.level).toBe('info');
-  expect(log.message).toBe('Test message');
-  expect(log.data).toEqual({ data: 'test' });
-});
-```
-
-## Final Validation Checklist
-
-### Technical Validation
-
-- [ ] Line 295 modified: `logs: []` → `logs: [...this.node.logs] as LogEntry[]`
-- [ ] TypeScript compilation passes: `npm run lint` (zero errors)
-- [ ] Build succeeds: `npm run build` (no errors)
-- [ ] All tests pass: `npm test` (100% pass rate)
-
-### Feature Validation
-
-- [ ] Error events from functional workflows contain populated logs array
-- [ ] Log entries include all required fields (id, workflowId, timestamp, level, message, data?)
-- [ ] Logs array is a copy (not reference) - `error.logs !== this.node.logs`
-- [ ] Logs content matches `this.node.logs` at time of error
-- [ ] No mutation of original `this.node.logs` array
-
-### Code Quality Validation
-
-- [ ] Follows `@Step` decorator pattern exactly (line 122 in step.ts)
-- [ ] Type assertion `as LogEntry[]` properly applied
-- [ ] No behavioral side effects - pure data capture improvement
-- [ ] No changes to other error object fields (message, original, workflowId, stack, state)
-
-### Integration Validation
-
-- [ ] P1.M1.T1.S1 dependency satisfied (getObservedState import present)
-- [ ] P1.M1.T1.S2 dependency satisfied (state capture working)
-- [ ] Compatible with WorkflowError interface type definition
-- [ ] Works with existing WorkflowObserver pattern
-
----
-
-## Anti-Patterns to Avoid
-
-- ❌ Don't use `logs: this.node.logs` (direct reference - allows mutation)
-- ❌ Don't use `logs: this.node.logs.slice()` (less idiomatic than spread)
-- ❌ Don't omit the `as LogEntry[]` type assertion (type safety)
-- ❌ Don't modify lines 286-294 (only change line 295)
-- ❌ Don't add new imports (already added in P1.M1.T1.S1)
-- ❌ Don't create new test files (P1.M1.T1.S4 will handle testing)
-- ❌ Don't modify other error handlers (only runFunctional() in this task)
-
----
-
-## Success Metrics
-
-**Confidence Score**: 10/10 for one-pass implementation success
-
-**Rationale**:
-- Single line change with exact pattern to follow
-- Reference implementation exists in `@Step` decorator
-- Type definitions are clear and stable
-- No new files or dependencies required
-- Validation commands are project-specific and verified
-- All context is specific and actionable
-
-**Risk Assessment**: Very Low
-- Change is isolated to single line
-- Pattern is proven in existing code
-- No breaking changes to public API
-- Backward compatible (only adds data, doesn't remove)
-
-**Next Steps After Implementation**:
-1. Complete P1.M1.T1.S4 (Write test for functional workflow error state capture)
-2. Begin P1.M1.T2 (Fix empty state/logs in WorkflowContext.step() error handlers)

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

@@ -1,142 +0,0 @@
-# Bug Fix Implementation - Quick Reference
-
-## 🚀 Quick Start
-
-```bash
-# View the backlog
-cat bug_fix_tasks.json | jq '.backlog[0].milestones[] | {title, status}'
-
-# Start first task
-# Task: P1.M1.T1.S1 - Add getObservedState import to workflow.ts
-```
-
-## 📋 Task Structure
-
-Every subtask has:
-- **ID**: Unique identifier (e.g., `P1.M1.T1.S1`)
-- **Title**: What to do
-- **SP**: Story points (0.5, 1, or 2)
-- **Dependencies**: Must complete these first
-- **context_scope**: Complete implementation contract
-
-## 🔍 Reading a Subtask Contract
-
-```json
-"context_scope": "CONTRACT DEFINITION:\n1. RESEARCH NOTE: ... \n2. INPUT: ... \n3. LOGIC: ... \n4. OUTPUT: ..."
-```
-
-**Example**: P1.M1.T1.S2
-```
-INPUT: getObservedState function from dependency P1.M1.T1.S1
-LOGIC: Replace 'state: {}' with 'state: getObservedState(this)'
-OUTPUT: Updated error object with actual captured state
-```
-
-## 📁 File Locations
-
-| Component | File |
-|-----------|------|
-| Main Workflow | `src/core/workflow.ts` |
-| Workflow Context | `src/core/workflow-context.ts` |
-| @Step Decorator | `src/decorators/step.ts` |
-| @Task Decorator | `src/decorators/task.ts` |
-| Observed State | `src/decorators/observed-state.ts` |
-| Unit Tests | `src/__tests__/unit/*.test.ts` |
-| Integration Tests | `src/__tests__/integration/*.test.ts` |
-
-## 🔑 Reference Implementations
-
-### Error Handling (Follow This Pattern)
-```typescript
-// ✅ CORRECT - From src/decorators/step.ts:109-134
-catch (err: unknown) {
-  const snap = getObservedState(this as object);
-  const workflowError: WorkflowError = {
-    state: snap,                        // ✅ Captured
-    logs: [...wf.node.logs],           // ✅ Captured
-    // ... other fields
-  };
-  wf.emitEvent({ type: 'error', node: wf.node, error: workflowError });
-  throw workflowError;
-}
-```
-
-### Event Emission
-```typescript
-// ✅ CORRECT - From src/decorators/step.ts:94-101
-if (opts.trackTiming !== false) {
-  wf.emitEvent({
-    type: 'stepEnd',
-    node: wf.node,
-    step: stepName,
-    duration,
-  });
-}
-```
-
-## 📊 Milestone Overview
-
-### M1: Error Handling & State Capture (10 SP)
-- Fix empty `state: {}` → `state: getObservedState(this)`
-- Fix empty `logs: []` → `logs: [...this.node.logs]`
-- Files: `workflow.ts`, `workflow-context.ts`
-
-### M2: Tree Structure & Events (12 SP)
-- Add cycle detection to `getRoot()`
-- Emit `treeUpdated` events in `setStatus()`
-- Prevent duplicate attachments
-- File: `workflow.ts`
-
-### M3: Documentation (4 SP)
-- Document `trackTiming` default (true)
-- Document `@Task` lenient validation
-- Files: JSDoc comments, README.md
-
-## ⚠️ Common Pitfalls
-
-1. **Forgetting imports**: Add `import { getObservedState }` before using it
-2. **Wrong context**: Use `this.workflow` in WorkflowContext, not `this`
-3. **Missing spread**: Use `[...this.node.logs]` to copy array
-4. **Type assertions**: Add `as LogEntry[]` for type safety
-5. **Event emission**: Always emit events after state changes
-
-## ✅ Definition of Done
-
-- [ ] Code implements `context_scope` LOGIC exactly
-- [ ] Tests pass (new test written)
-- [ ] TypeScript compiles (no errors)
-- [ ] No existing tests broken
-- [ ] Follows patterns from system_context.md
-
-## 🆘 Getting Help
-
-| Question | Answer Location |
-|----------|-----------------|
-| What's the architecture? | `plan_bugfix/architecture/system_context.md` |
-| Why this fix? | `plan_bugfix/architecture/GAP_ANALYSIS_SUMMARY.md` |
-| Full details? | `plan_bugfix/architecture/ANALYSIS_PRD_VS_IMPLEMENTATION.md` |
-| What's the contract? | `bug_fix_tasks.json` - subtask `context_scope` |
-
-## 📈 Progress Tracking
-
-```bash
-# Count completed subtasks
-cat bug_fix_tasks.json | jq '[.backlog[].milestones[].tasks[].subtasks[] | select(.status == "Complete")] | length'
-
-# View pending subtasks
-cat bug_fix_tasks.json | jq '.backlog[].milestones[].tasks[].subtasks[] | select(.status == "Planned") | {id, title}'
-```
-
-## 🎯 First 5 Subtasks
-
-1. **P1.M1.T1.S1** (1 SP) - Add getObservedState import
-2. **P1.M1.T1.S2** (1 SP) - Fix state capture in runFunctional()
-3. **P1.M1.T1.S3** (1 SP) - Fix logs capture in runFunctional()
-4. **P1.M1.T1.S4** (2 SP) - Write test for functional workflow errors
-5. **P1.M1.T2.S1** (1 SP) - Add import to workflow-context.ts
-
-**Total**: 6 SP to complete Milestone 1.1, Task 1
-
----
-
-**Pro Tip**: Always read the `context_scope` before starting. It tells you exactly what to implement!