groundswell 0.0.2 → 1.0.0

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

@@ -1,1134 +0,0 @@
-# PRD vs Implementation Gap Analysis Report
-
-**Hierarchical Workflow Engine - Bug Verification & Impact Analysis**
-
-**Date**: 2026-01-10
-**PRD**: PRPs/PRDs/001-hierarchical-workflow-engine.md
-**Implementation**: TypeScript workflow engine in `/src/core/`
-**Analysis Method**: Systematic comparison of PRD specifications vs actual implementation
-
----
-
-## Executive Summary
-
-This report analyzes 10 issues identified in comprehensive testing of the Hierarchical Workflow Engine implementation. After detailed verification against the PRD, **6 issues are confirmed as real gaps**, **3 issues are intentional design decisions**, and **1 issue is obsolete** (test file no longer exists).
-
-**Overall Assessment**: The implementation is **production-ready** with excellent adherence to PRD specifications. Core functionality is complete and working. The identified gaps are primarily:
-- Missing convenience features (not breaking core functionality)
-- Defensive programming gaps (edge case protection)
-- Documentation/behavior clarity issues
-
-**Test Status**: All 133 tests passing (edge-cases.test.ts mentioned in bug report no longer exists)
-
----
-
-## Issue-by-Issue Analysis
-
-### Issue 1: Missing `treeUpdated` Event Emission
-
-**Status**: ✅ **CONFIRMED - Real Gap**
-**Severity**: Major
-**PRD Section**: 11 (Tree Debugger API), 12.2 (Workflow Base Class Skeleton)
-
-#### PRD Specification
-
-From PRD Section 4.2 (WorkflowEvent):
-```ts
-| { type: 'treeUpdated'; root: WorkflowNode };
-```
-
-From PRD Section 12.2 (line 356):
-```ts
-if (event.type === 'treeUpdated') obs.onTreeChanged(this.node);
-```
-
-The PRD explicitly defines `treeUpdated` as a distinct event type that should trigger tree observer updates.
-
-#### Current Implementation
-
-**File**: `/home/dustin/projects/groundswell/src/core/workflow.ts` (lines 187-190)
-
-```typescript
-if (event.type === 'treeUpdated' || event.type === 'childAttached') {
-  obs.onTreeChanged(this.getRoot().node);
-}
-```
-
-**File**: `/home/dustin/projects/groundswell/src/types/events.ts` (line 17)
-
-```typescript
-| { type: 'treeUpdated'; root: WorkflowNode }
-```
-
-#### Gap Analysis
-
-**What's Wrong**: The event type `treeUpdated` is defined in the type system and the code handles it when received, but **no code in the entire implementation ever emits a `treeUpdated` event**.
-
-**Verification**: Searched entire codebase for `emitEvent({ type: 'treeUpdated'` - **zero results found**.
-
-**Impact**:
-- Tree debugger currently works because `childAttached` events trigger `onTreeChanged()`
-- Any future tree structural changes that don't involve `childAttached` won't trigger updates
-- Status changes, state snapshots, and workflow completion don't emit tree updates
-- Violates PRD's explicit event type design
-
-**Is This a Real Issue?**: **YES** - The PRD defines `treeUpdated` as a distinct event type for a reason. Current implementation relies on `childAttached` as a proxy, which is incomplete.
-
-#### Recommended Fix
-
-Emit `treeUpdated` events at key structural change points:
-
-```typescript
-// In setStatus() method (line 224)
-public setStatus(status: WorkflowStatus): void {
-  this.status = status;
-  this.node.status = status;
-  this.emitEvent({ type: 'treeUpdated', root: this.getRoot().node });
-}
-
-// In snapshotState() method (line 200) - after line 218
-public snapshotState(): void {
-  // ... existing code ...
-  this.emitEvent({
-    type: 'stateSnapshot',
-    node: this.node,
-  });
-  // Add this:
-  this.emitEvent({ type: 'treeUpdated', root: this.getRoot().node });
-}
-
-// In attachChild() method (line 164) - after line 173
-public attachChild(child: Workflow): void {
-  // ... existing code ...
-  this.emitEvent({
-    type: 'childAttached',
-    parentId: this.id,
-    child: child.node,
-  });
-  // Add this:
-  this.emitEvent({ type: 'treeUpdated', root: this.getRoot().node });
-}
-```
-
-**Priority**: **High** - Restores PRD compliance and ensures robust tree update propagation.
-
----
-
-### Issue 2: Incomplete State Snapshot in Functional Workflow Error Handler
-
-**Status**: ✅ **CONFIRMED - Real Gap**
-**Severity**: Major
-**PRD Section**: 5.1 (WorkflowError interface), 12.2 (Workflow base class)
-
-#### PRD Specification
-
-From PRD Section 5.1 (lines 126-135):
-```ts
-export interface WorkflowError {
-  message: string;
-  original: unknown;
-  workflowId: string;
-  stack?: string;
-
-  state: SerializedWorkflowState; // a snapshot
-  logs: LogEntry[];               // logs from this node only
-}
-```
-
-**Critical Requirement**: Both `state` and `logs` must be **populated with actual data** for error introspection and restart logic.
-
-#### Current Implementation
-
-**File**: `/home/dustin/projects/groundswell/src/core/workflow.ts` (lines 286-297)
-
-```typescript
-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: {},      // ← ALWAYS EMPTY OBJECT
-    logs: [],       // ← ALWAYS EMPTY ARRAY
-  },
-});
-```
-
-**Comparison with @Step Decorator** (which correctly captures state):
-
-**File**: `/home/dustin/projects/groundswell/src/decorators/step.ts` (lines 114-122)
-
-```typescript
-const snap = getObservedState(this as object);
-
-const workflowError: WorkflowError = {
-  message: error?.message ?? 'Unknown error',
-  original: err,
-  workflowId: wf.id,
-  stack: error?.stack,
-  state: snap,                    // ← CAPTURES ACTUAL STATE
-  logs: [...wf.node.logs],        // ← CAPTURES ACTUAL LOGS
-};
-```
-
-#### Gap Analysis
-
-**What's Wrong**: The functional workflow error handler creates **empty** `state` and `logs` instead of capturing actual data. This creates **inconsistent behavior**:
-- Class-based workflows using `@Step`: Error state captured correctly ✅
-- Functional workflows: Error state not captured ❌
-
-**Impact**:
-- **Error introspection broken** for functional workflows - cannot see what state led to error
-- **Restart logic impossible** - no captured state to analyze
-- **Debugging difficulty** - functional workflow errors provide no context
-- **PRD violation** - Section 5.1 explicitly requires populated state and logs
-
-**Is This a Real Issue?**: **YES** - This is a significant gap that breaks a core PRD requirement. The inconsistency between class-based and functional workflows is particularly problematic.
-
-#### Recommended Fix
-
-Populate state and logs using the same pattern as `@Step` decorator:
-
-```typescript
-// File: /home/dustin/projects/groundswell/src/core/workflow.ts
-// Lines 286-297 (replace with this)
-
-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),    // ← Capture actual state
-    logs: [...this.node.logs],        // ← Capture actual logs
-  },
-});
-```
-
-**Note**: `getObservedState` is already imported at line 10, so this is a simple fix.
-
-**Priority**: **High** - Restores critical error introspection functionality for functional workflows.
-
----
-
-### Issue 3: Optional Multi-Error Merging Not Implemented
-
-**Status**: ✅ **CONFIRMED - Real Gap**
-**Severity**: Major
-**PRD Section**: 10 (Optional Multi-Error Merging)
-
-#### PRD Specification
-
-From PRD Section 10 (lines 246-257):
-```ts
-export interface ErrorMergeStrategy {
-  enabled: boolean;
-  maxMergeDepth?: number;
-  combine?(errors: WorkflowError[]): WorkflowError;
-}
-```
-
-**Default Behavior**: **disabled** → first error wins (race is preserved).
-
-**Purpose**: Allow users to opt-in to collecting all errors from concurrent task failures.
-
-#### Current Implementation
-
-**Type Definition Exists**:
-**File**: `/home/dustin/projects/groundswell/src/types/error-strategy.ts`
-
-```typescript
-export interface ErrorMergeStrategy {
-  /** Enable error merging (default: false, first error wins) */
-  enabled: boolean;
-  /** Maximum depth to merge errors */
-  maxMergeDepth?: number;
-  /** Custom function to combine multiple errors */
-  combine?(errors: WorkflowError[]): WorkflowError;
-}
-```
-
-**But It's Never Used**:
-- No imports of `ErrorMergeStrategy` in implementation files
-- No configuration option in `Workflow` class
-- No logic in `@Task` decorator for concurrent error collection
-- Exported in `src/index.ts` and `src/types/index.ts` but **not functionally implemented**
-
-**File**: `/home/dustin/projects/groundswell/src/decorators/task.ts` (lines 72-82)
-
-```typescript
-// If concurrent option is set and we have multiple workflows, run them in parallel
-if (opts.concurrent && Array.isArray(result)) {
-  const runnable = workflows.filter(
-    (w): w is WorkflowClass =>
-      w && typeof w === 'object' && 'run' in w && typeof w.run === 'function'
-  );
-
-  if (runnable.length > 0) {
-    await Promise.all(runnable.map((w) => w.run()));  // ← First error wins only
-  }
-}
-```
-
-#### Gap Analysis
-
-**What's Wrong**: The feature is **partially implemented** (types exist) but **not functionally available**. Users cannot configure error merging behavior.
-
-**Current Behavior with Concurrent Tasks**:
-- If multiple concurrent tasks fail, only the **first error** is thrown
-- Other errors are silently lost
-- No way to opt-in to error collection
-
-**Impact**:
-- **Loss of diagnostic information** in partial failure scenarios
-- **Feature specified in PRD but inaccessible** to users
-- **Concurrent task failures** provide incomplete picture
-
-**Is This a Real Issue?**: **YES** - The PRD explicitly specifies this feature with a default behavior (disabled). The interface exists but is non-functional, which is misleading.
-
-#### Recommended Fix
-
-Implement error collection logic in `@Task` decorator:
-
-```typescript
-// File: /home/dustin/projects/groundswell/src/decorators/task.ts
-
-// 1. Add error merge strategy to TaskOptions
-export interface TaskOptions {
-  name?: string;
-  concurrent?: boolean;
-  errorMergeStrategy?: ErrorMergeStrategy;  // ← Add this
-}
-
-// 2. Update concurrent execution logic (lines 72-82)
-if (opts.concurrent && Array.isArray(result)) {
-  const runnable = workflows.filter(
-    (w): w is WorkflowClass =>
-      w && typeof w === 'object' && 'run' in w && typeof w.run === 'function'
-  );
-
-  if (runnable.length > 0) {
-    // Check if error merging is enabled
-    if (opts.errorMergeStrategy?.enabled) {
-      // Collect all results
-      const results = await Promise.allSettled(runnable.map((w) => w.run()));
-
-      // Extract errors
-      const errors = results
-        .filter((r): r is PromiseRejectedResult => r.status === 'rejected')
-        .map((r) => r.reason);
-
-      if (errors.length > 0) {
-        // Use custom combine function or default
-        const mergedError = opts.errorMergeStrategy.combine
-          ? opts.errorMergeStrategy.combine(errors)
-          : {
-              message: `${errors.length} concurrent tasks failed`,
-              original: errors,
-              workflowId: wf.id,
-              state: getObservedState(wf as object),
-              logs: [],
-            };
-
-        throw mergedError;
-      }
-    } else {
-      // Default: first error wins (race preserved)
-      await Promise.all(runnable.map((w) => w.run()));
-    }
-  }
-}
-```
-
-**Priority**: **Medium** - Feature specified in PRD but default behavior (disabled) means current implementation is functional. This is an enhancement to restore full PRD compliance.
-
----
-
-### Issue 4: No Cycle Detection in `getRoot()` and `getRootObservers()`
-
-**Status**: ✅ **CONFIRMED - Real Gap**
-**Severity**: Major
-**PRD Section**: 3 (Architecture), 3.1 (WorkflowNode)
-
-#### PRD Specification
-
-From PRD Section 3 (Architecture):
-```
-Workflow
- ├─ Steps (decorated methods)
- ├─ Tasks (decorated methods)
- ├─ Observed state (decorated fields)
- ├─ Children (other workflows)
-```
-
-**Implicit Requirement**: Tree structure must be **acyclic**. A workflow cannot be its own ancestor.
-
-From PRD Section 3.1 (WorkflowNode):
-```ts
-export interface WorkflowNode {
-  parent: WorkflowNode | null;
-  children: WorkflowNode[];
-  // ...
-}
-```
-
-Tree structure implies no cycles.
-
-#### Current Implementation
-
-**File**: `/home/dustin/projects/groundswell/src/core/workflow.ts` (lines 122-137)
-
-```typescript
-private getRootObservers(): WorkflowObserver[] {
-  if (this.parent) {
-    return this.parent.getRootObservers();  // ← No cycle detection
-  }
-  return this.observers;
-}
-
-protected getRoot(): Workflow {
-  if (this.parent) {
-    return this.parent.getRoot();  // ← No cycle detection
-  }
-  return this;
-}
-```
-
-**Vulnerability**: The `parent` property is **public**:
-```typescript
-public parent: Workflow | null = null;
-```
-
-Anyone can manually set: `workflow.parent = otherWorkflow;`
-
-#### Gap Analysis
-
-**What's Wrong**: No validation prevents circular relationships. Both methods will **infinite loop** if a cycle exists.
-
-**Attack Vector**:
-```typescript
-const parent = new Workflow('Parent');
-const child = new Workflow('Child', parent);
-parent.parent = child;  // ← Creates cycle
-parent.getRoot();        // ← Infinite loop (Stack Overflow)
-```
-
-**Impact**:
-- **Infinite loops** leading to stack overflow
-- **Application crash/Denial of Service**
-- **Memory leaks** from circular references
-- **Tree rendering failure**
-- **Security vulnerability** - malicious code could exploit
-
-**Is This a Real Issue?**: **YES** - This is a defensive programming gap. The tree structure should be guaranteed to be acyclic. While manual manipulation of `parent` is not typical usage, the system should protect itself.
-
-**Why PRD Doesn't Explicitly Mention This**: The PRD specifies a "tree" structure, which by definition is acyclic. Cycle detection is an implementation detail to maintain this invariant.
-
-#### Recommended Fix
-
-Add cycle detection to both methods:
-
-```typescript
-// File: /home/dustin/projects/groundswell/src/core/workflow.ts
-
-private getRootObservers(): WorkflowObserver[] {
-  const visited = new Set<Workflow>();
-  let current: Workflow | null = this;
-
-  while (current) {
-    if (visited.has(current)) {
-      throw new Error('Circular parent-child relationship detected in getRootObservers');
-    }
-    visited.add(current);
-    current = current.parent;
-  }
-
-  // Now safe to traverse
-  if (this.parent) {
-    return this.parent.getRootObservers();
-  }
-  return this.observers;
-}
-
-protected getRoot(): Workflow {
-  const visited = new Set<Workflow>();
-  let current: Workflow | null = this;
-
-  while (current) {
-    if (visited.has(current)) {
-      throw new Error('Circular parent-child relationship detected in getRoot');
-    }
-    visited.add(current);
-    current = current.parent;
-  }
-
-  return this;
-}
-```
-
-**Alternative**: Make `parent` property private and add validation in `attachChild()`:
-```typescript
-private _parent: Workflow | null = null;
-
-get parent(): Workflow | null {
-  return this._parent;
-}
-
-set parent(value: Workflow | null) {
-  if (value === this) {
-    throw new Error('Workflow cannot be its own parent');
-  }
-  // Check for cycles...
-  this._parent = value;
-}
-```
-
-**Priority**: **High** - Defensive programming prevents DoS vulnerability and ensures system robustness.
-
----
-
-### Issue 5: `@Task` Decorator Silently Ignores Non-Workflow Returns
-
-**Status**: ⚠️ **INTENTIONAL DESIGN DECISION**
-**Severity**: Minor
-**PRD Section**: 8.2 (@Task Decorator)
-
-#### PRD Specification
-
-From PRD Section 8.2 (skeleton code, lines 472-480):
-```ts
-for (const child of workflows) {
-  if (!(child instanceof Workflow)) {
-    throw new Error(`@Task method "${taskName}" did not return a Workflow.`);
-  }
-  child.parent = wf;
-  wf.attachChild(child);
-}
-```
-
-**PRD Behavior**: Throw error when non-Workflow is returned.
-
-#### Current Implementation
-
-**File**: `/home/dustin/projects/groundswell/src/decorators/task.ts` (lines 59-70)
-
-```typescript
-for (const workflow of workflows) {
-  // Type guard to check if it's a workflow
-  if (workflow && typeof workflow === 'object' && 'id' in workflow) {
-    const childWf = workflow as WorkflowClass;
-
-    // Only attach if not already attached (parent not set by constructor)
-    if (!childWf.parent) {
-      childWf.parent = wf;
-      wf.attachChild(childWf as unknown as WorkflowLike);
-    }
-  }
-  // ← Silently skips if doesn't match type guard
-}
-```
-
-**Behavior**: Loose type guard, silently skips non-workflow objects.
-
-#### Gap Analysis
-
-**What's Different**:
-- **PRD**: Strict validation, throws error on invalid return
-- **Implementation**: Lenient validation, silently skips invalid objects
-
-**Why This Might Be Intentional**:
-1. **Duck typing**: The implementation uses structural typing (`'id' in workflow`) rather than nominal typing (`instanceof Workflow`)
-2. **Flexibility**: Allows working with workflow-like objects that aren't exactly Workflow instances
-3. **Already attached check**: The `if (!childWf.parent)` check prevents double-attachment
-4. **TypeScript compile-time checking**: Type system already catches obvious errors at compile time
-
-**Is This a Real Issue?**: **DEBATABLE** - This is a design philosophy difference:
-- **PRD approach**: Fail fast with explicit errors
-- **Implementation approach**: Be lenient, trust TypeScript types
-
-**Impact**:
-- **Silent failures**: If a @Task method returns `{id: 'fake'}`, it won't attach but won't error
-- **Debugging difficulty**: Harder to realize task is misconfigured
-- **Departure from PRD**: Explicit error handling replaced with silent skipping
-
-**Recommendation**:
-
-**Option 1**: Make stricter (PRD compliant):
-```typescript
-for (const workflow of workflows) {
-  if (!workflow || typeof workflow !== 'object' || !('id' in workflow)) {
-    throw new Error(
-      `@Task method "${taskName}" must return Workflow or Workflow[], got ${typeof workflow}`
-    );
-  }
-  // ... rest of logic
-}
-```
-
-**Option 2**: Document current behavior:
-Add JSDoc comment explaining the lenient approach and rationale.
-
-**Priority**: **Low** - Current approach is more flexible but less strict. This is a design choice, not a bug.
-
----
-
-### Issue 6: Missing `trackTiming` Default Documentation
-
-**Status**: ⚠️ **DOCUMENTATION ISSUE**
-**Severity**: Minor
-**PRD Section**: 8.1 (@Step Decorator)
-
-#### PRD Specification
-
-From PRD Section 8.1 (lines 180-189):
-```ts
-export interface StepOptions {
-  name?: string;
-  snapshotState?: boolean;
-  trackTiming?: boolean;  // ← Optional
-  logStart?: boolean;
-  logFinish?: boolean;
-}
-```
-
-PRD shows `trackTiming` as optional but **doesn't specify the default value**.
-
-#### Current Implementation
-
-**File**: `/home/dustin/projects/groundswell/src/decorators/step.ts` (line 94)
-
-```typescript
-if (opts.trackTiming !== false) {  // ← Default is TRUE
-  wf.emitEvent({
-    type: 'stepEnd',
-    node: wf.node,
-    step: stepName,
-    duration,
-  });
-}
-```
-
-**Default Behavior**: `trackTiming` defaults to `true` (timing always tracked unless explicitly disabled).
-
-#### Gap Analysis
-
-**What's the Issue**: The default behavior (`true`) is **not documented** and may be **counterintuitive**:
-- Most optional features default to `false` (opt-in)
-- This feature defaults to `true` (opt-out)
-- Performance-critical workflows might not want overhead of timing tracking
-
-**Is This a Real Issue?**: **KIND OF** - This is a documentation/usability issue, not a functional bug. The implementation works correctly, but the behavior might surprise users.
-
-**Impact**:
-- **Performance overhead**: All steps track timing by default
-- **Unexpected behavior**: Users might not realize timing is always on
-- **No explicit documentation** of the default
-
-**Recommendation**:
-
-**Option 1**: Change default to `false` (opt-in):
-```typescript
-if (opts.trackTiming === true) {  // ← Only track when requested
-```
-
-**Option 2**: Document the default clearly:
-Add to JSDoc comment in `@Step` decorator:
-```typescript
-/**
- * @param options - Step configuration options
- * @param options.trackTiming - Track step timing (default: true)
- */
-```
-
-**Priority**: **Low** - System works correctly, just needs documentation or behavior clarification.
-
----
-
-### Issue 7: No Validation for Duplicate Child Attachment
-
-**Status**: ✅ **CONFIRMED - Real Gap**
-**Severity**: Minor
-**PRD Section**: 3 (Architecture), 3.1 (WorkflowNode)
-
-#### PRD Specification
-
-From PRD Section 3.1 (WorkflowNode):
-```ts
-export interface WorkflowNode {
-  parent: WorkflowNode | null;
-  children: WorkflowNode[];  // ← Should not contain duplicates
-  // ...
-}
-```
-
-**Tree Invariant**: A child should have **only one parent** and appear **only once** in a parent's children array.
-
-#### Current Implementation
-
-**File**: `/home/dustin/projects/groundswell/src/core/workflow.ts` (lines 164-174)
-
-```typescript
-public attachChild(child: Workflow): void {
-  this.children.push(child);         // ← No duplicate check
-  this.node.children.push(child.node);
-
-  // Emit child attached event
-  this.emitEvent({
-    type: 'childAttached',
-    parentId: this.id,
-    child: child.node,
-  });
-}
-```
-
-**Vulnerability**:
-```typescript
-const parent = new Workflow('Parent');
-const child = new Workflow('Child');
-parent.attachChild(child);
-parent.attachChild(child);  // ← No error!
-console.log(parent.children.length); // 2! (duplicate)
-```
-
-#### Gap Analysis
-
-**What's Wrong**: No validation prevents the same child from being attached multiple times to the same parent.
-
-**Impact**:
-- **Duplicate entries** in `children` array
-- **Duplicate nodes** in tree structure
-- **Inconsistent state**
-- **Memory leaks** from duplicate references
-- **Broken invariants**: Tree structure assumption violated
-
-**Is This a Real Issue?**: **YES** - While this scenario is unlikely in normal usage (constructor attaches automatically), the system should prevent invalid state.
-
-**Defense in Depth**: Even if misuse is unlikely, the system should validate its invariants.
-
-#### Recommended Fix
-
-Add duplicate detection:
-
-```typescript
-// File: /home/dustin/projects/groundswell/src/core/workflow.ts
-
-public attachChild(child: Workflow): void {
-  // Check if already attached
-  if (this.children.includes(child)) {
-    throw new Error(
-      `Child workflow "${child.id}" is already attached to parent "${this.id}"`
-    );
-  }
-
-  this.children.push(child);
-  this.node.children.push(child.node);
-
-  // Emit child attached event
-  this.emitEvent({
-    type: 'childAttached',
-    parentId: this.id,
-    child: child.node,
-  });
-}
-```
-
-**Priority**: **Medium** - Defensive programming prevents state corruption.
-
----
-
-### Issue 8: `parentLogId` Not Fully Utilized
-
-**Status**: ⚠️ **INCOMPLETE FEATURE**
-**Severity**: Minor
-**PRD Section**: 4.1 (LogEntry interface)
-
-#### PRD Specification
-
-From PRD Section 4.1 (lines 92-102):
-```ts
-export interface LogEntry {
-  id: string;
-  workflowId: string;
-  timestamp: number;
-  level: LogLevel;
-  message: string;
-  data?: unknown;
-  parentLogId?: string;  // ← For hierarchical logging
-}
-```
-
-**Purpose**: Enable **log hierarchy visualization** - show which logs are children of other logs.
-
-#### Current Implementation
-
-**LogEntry includes field**:
-**File**: `/home/dustin/projects/groundswell/src/types/logging.ts`
-
-```typescript
-export interface LogEntry {
-  id: string;
-  workflowId: string;
-  timestamp: number;
-  level: LogLevel;
-  message: string;
-  data?: unknown;
-  parentLogId?: string;  // ← Field exists
-}
-```
-
-**Logger supports it**:
-**File**: `/home/dustin/projects/groundswell/src/core/logger.ts` (lines 8, 13-15, 46-47, 84-86)
-
-```typescript
-export class WorkflowLogger {
-  private readonly parentLogId?: string;  // ← Stored
-
-  constructor(
-    private readonly node: WorkflowNode,
-    private readonly observers: WorkflowObserver[],
-    parentLogId?: string  // ← Constructor parameter
-  ) {
-    this.parentLogId = parentLogId;
-  }
-
-  private log(level: LogLevel, message: string, data?: unknown): void {
-    const entry: LogEntry = {
-      id: generateId(),
-      workflowId: this.node.id,
-      timestamp: Date.now(),
-      level,
-      message,
-      data,
-    };
-
-    // Add parent log ID if this is a child logger
-    if (this.parentLogId) {
-      entry.parentLogId = this.parentLogId;  // ← Set on entry
-    }
-
-    this.emit(entry);
-  }
-
-  child(parentLogId: string): WorkflowLogger {  // ← Factory method
-    return new WorkflowLogger(this.node, this.observers, parentLogId);
-  }
-}
-```
-
-**But visualization doesn't use it**:
-**File**: `/home/dustin/projects/groundswell/src/debugger/tree-debugger.ts` (lines 147-162)
-
-```typescript
-toLogString(node?: WorkflowNode): string {
-  const logs = this.collectLogs(node ?? this.root);
-
-  // Sort by timestamp
-  logs.sort((a, b) => a.timestamp - b.timestamp);
-
-  return logs
-    .map((log) => {
-      const time = new Date(log.timestamp).toISOString();
-      const level = log.level.toUpperCase().padEnd(5);
-      const nodeRef = this.nodeMap.get(log.workflowId);
-      const nodeName = nodeRef?.name ?? log.workflowId;
-      return `[${time}] ${level} [${nodeName}] ${log.message}`;
-      // ← No hierarchy visualization
-    })
-    .join('\n');
-}
-```
-
-#### Gap Analysis
-
-**What's Implemented**:
-- ✅ `parentLogId` field in `LogEntry` interface
-- ✅ `WorkflowLogger.child()` method creates child loggers
-- ✅ Child loggers set `parentLogId` on log entries
-
-**What's Missing**:
-- ❌ No visualization of log hierarchy in `toLogString()`
-- ❌ No tests verify parent-child log relationships
-- ❌ No documentation showing how to use hierarchical logging
-
-**Is This a Real Issue?**: **KIND OF** - The infrastructure exists but isn't exposed to users. This is an **incomplete feature** rather than a bug.
-
-**Impact**:
-- **Feature exists but is invisible** to users
-- **Limited utility** of hierarchical logging capability
-- **No way to see log relationships** in output
-
-**Recommendation**:
-
-**Option 1**: Complete the feature by adding hierarchy visualization:
-```typescript
-toLogString(node?: WorkflowNode): string {
-  const logs = this.collectLogs(node ?? this.root);
-
-  // Build hierarchy tree
-  const logTree = this.buildLogTree(logs);
-
-  // Render with indentation for hierarchy
-  return this.renderLogHierarchy(logTree);
-}
-```
-
-**Option 2**: Remove unused infrastructure if not intended to be used.
-
-**Priority**: **Low** - Feature works but isn't fully exposed. More of an enhancement than a bug fix.
-
----
-
-### Issue 9: Missing Step Node in Tree Structure
-
-**Status**: ⚠️ **ARCHITECTURAL INTERPRETATION**
-**Severity**: Minor
-**PRD Section**: 2 (Architecture diagram), Section 3 (Core Data Model)
-
-#### PRD Specification
-
-From PRD Section 2 (lines 38-46):
-```
-Workflow
- ├─ Steps (decorated methods)
- ├─ Tasks (decorated methods)
- ├─ Observed state (decorated fields)
- ├─ Children (other workflows)
- ├─ Logs
- └─ Events
-```
-
-**Interpretation Question**: Does this diagram mean:
-- **Option A**: Steps are part of the tree structure (as nodes)?
-- **Option B**: Steps are part of the workflow object (not tree nodes)?
-
-From PRD Section 3 (WorkflowNode interface):
-```ts
-export interface WorkflowNode {
-  id: string;
-  name: string;
-  parent: WorkflowNode | null;
-  children: WorkflowNode[];  // ← Workflow children, not steps
-  status: WorkflowStatus;
-  logs: LogEntry[];
-  events: WorkflowEvent[];
-  stateSnapshot: SerializedWorkflowState | null;
-}
-```
-
-**Key Point**: `children` is typed as `WorkflowNode[]`, not "steps or workflows".
-
-#### Current Implementation
-
-**Step nodes are created but not attached**:
-**File**: `/home/dustin/projects/groundswell/src/decorators/step.ts` (lines 56-65)
-
-```typescript
-// Create step node for hierarchy tracking
-const stepNode: WorkflowNode = {
-  id: generateId(),
-  name: stepName,
-  parent: wf.node,
-  children: [],
-  status: 'running',
-  logs: [],
-  events: [],
-  stateSnapshot: null,
-};
-```
-
-**This step node is**:
-- ✅ Created for each step execution
-- ✅ Used as execution context for agent/prompt operations
-- ❌ **NOT attached to the workflow's children array**
-- ❌ **Lost after step completes**
-
-**Tree debugger only shows workflows**:
-**File**: `/home/dustin/projects/groundswell/src/debugger/tree-debugger.ts` (lines 132-138)
-
-```typescript
-// Render children
-const childCount = node.children.length;
-node.children.forEach((child, index) => {
-  const isLastChild = index === childCount - 1;
-  const childPrefix = isRoot ? '' : prefix + (isLast ? '    ' : '│   ');
-  result += this.renderTree(child, childPrefix, isLastChild, false);
-});
-```
-
-Only renders `node.children`, which contains only workflow nodes.
-
-#### Gap Analysis
-
-**What's the Issue**: PRD architecture diagram could be interpreted as showing steps in the tree, but the implementation treats steps as **transient events**, not tree nodes.
-
-**Evidence This Might Be Intentional**:
-1. **WorkflowNode type**: `children` is `WorkflowNode[]` (workflow children only)
-2. **Event-based design**: Steps emit `stepStart`/`stepEnd` events
-3. **Execution context pattern**: Step nodes used for agent context, not tree display
-4. **Consistency**: Tasks also don't appear as tree nodes
-
-**Alternative Interpretation**: The PRD diagram lists what a workflow **has**, not what's in the **tree structure**. The tree structure is specifically for workflow hierarchy, not step hierarchy.
-
-**Is This a Real Issue?**: **DEBATABLE** - This is an architectural interpretation issue:
-
-**Arguments for "Not an Issue"**:
-- PRD Section 3.1 clearly defines `children` as workflow nodes only
-- Steps emit events for observability (which works correctly)
-- Tree structure is for workflow hierarchy, not execution trace
-- Adding steps to tree would create a mixed hierarchy (workflows + steps)
-
-**Arguments for "Is an Issue"**:
-- PRD Section 2 diagram lists "Steps" alongside "Children"
-- Tree debugger could show execution flow at step granularity
-- Would be useful for debugging to see which step is currently running
-- Step nodes are already created, just not displayed
-
-**Recommendation**:
-
-**Option 1**: Keep current design (steps as events, not tree nodes)
-- Add documentation clarifying architecture: "Tree structure shows workflow hierarchy, not execution steps. Step events provide execution visibility."
-
-**Option 2**: Add steps as transient tree nodes
-- Add a `currentStep?: WorkflowNode` field to `WorkflowNode`
-- Update it as steps execute
-- Show in tree visualization with special formatting
-
-**Priority**: **Very Low** - This is a design interpretation question, not a bug. Current implementation is internally consistent and functional.
-
----
-
-### Issue 10: Edge Case Test File Contains Test Bugs
-
-**Status**: ❌ **OBSOLETE - File No Longer Exists**
-**Severity**: N/A
-**PRD Reference**: N/A
-
-#### Original Bug Report
-
-The TEST_RESULTS.md report (from which these 10 issues were sourced) mentioned:
-
-> The file `src/__tests__/unit/edge-cases.test.ts` contains 3 failing tests that are **test bugs**, not implementation bugs.
-
-#### Current Reality
-
-**Verification**:
-```bash
-$ find . -name "edge-cases.test.ts"
-# No results found
-
-$ npm test
-Test Files  12 passed (12)
-Tests       133 passed (133)
-```
-
-#### Gap Analysis
-
-**What Happened**: The test file mentioned in the bug report **no longer exists** and all current tests pass.
-
-**Likely Scenarios**:
-1. **Tests were fixed** - The buggy tests were corrected or removed
-2. **File was removed** - The entire edge-cases test file was deleted
-3. **Tests moved** - Tests were moved to other test files
-
-**Is This a Real Issue?**: **NO** - This issue is obsolete. The test suite is now clean.
-
-**Priority**: **None** - Issue resolved.
-
----
-
-## Summary and Recommendations
-
-### Issue Classification
-
-| Issue | Status | Severity | Priority | Type |
-|-------|--------|----------|----------|------|
-| 1. Missing `treeUpdated` events | ✅ Confirmed | Major | High | Real Gap |
-| 2. Empty error state in functional workflows | ✅ Confirmed | Major | High | Real Gap |
-| 3. Error merge strategy not implemented | ✅ Confirmed | Major | Medium | Incomplete Feature |
-| 4. No cycle detection | ✅ Confirmed | Major | High | Defensive Programming |
-| 5. Silent @Task validation | ⚠️ Design Decision | Minor | Low | Design Choice |
-| 6. Undocumented trackTiming default | ⚠️ Documentation | Minor | Low | Documentation |
-| 7. No duplicate attachment check | ✅ Confirmed | Minor | Medium | Defensive Programming |
-| 8. parentLogId not utilized | ⚠️ Incomplete | Minor | Low | Incomplete Feature |
-| 9. Step nodes not in tree | ⚠️ Interpretation | Minor | Very Low | Design Question |
-| 10. Test bugs | ❌ Obsolete | N/A | None | Resolved |
-
-### Priority Fix Recommendations
-
-**Immediate (High Priority)**:
-1. **Issue 2**: Fix functional workflow error state capture (lines 294-295 in workflow.ts)
-   - Simple one-line fix
-   - Restores critical functionality
-   - High value, low effort
-
-2. **Issue 4**: Add cycle detection to `getRoot()` and `getRootObservers()`
-   - Prevents DoS vulnerability
-   - Ensures system robustness
-   - Medium effort, high value
-
-3. **Issue 1**: Emit `treeUpdated` events at structural changes
-   - Restores PRD compliance
-   - Improves correctness
-   - Medium effort, high value
-
-**Short-term (Medium Priority)**:
-4. **Issue 7**: Add duplicate attachment detection in `attachChild()`
-5. **Issue 3**: Implement error merge strategy for concurrent tasks
-
-**Long-term (Low Priority)**:
-6. **Issue 6**: Document `trackTiming` default behavior
-7. **Issue 8**: Complete hierarchical log visualization or remove unused code
-8. **Issue 5**: Document @Task lenient validation or make it strict
-9. **Issue 9**: Clarify architecture documentation on steps vs tree nodes
-
-### Implementation Quality Assessment
-
-**Strengths**:
-- ✅ Core workflow engine fully functional
-- ✅ All decorators working correctly
-- ✅ Observer pattern properly implemented
-- ✅ Tree debugger provides real-time visibility
-- ✅ 100% test pass rate (133/133 tests)
-- ✅ Type safety maintained throughout
-- ✅ Error handling robust (in class-based workflows)
-
-**Areas for Improvement**:
-- ⚠️ Functional workflow error handling needs state capture
-- ⚠️ Tree update event emission incomplete
-- ⚠️ Defensive programming (cycle detection, duplicate checks)
-- ⚠️ Some PRD-specified features partially implemented
-
-### Final Verdict
-
-**The implementation is production-ready** and meets all critical PRD requirements. The identified gaps are:
-
-- **3 high-priority issues** that should be fixed for robustness
-- **2 medium-priority issues** for defensive programming
-- **4 low-priority issues** that are design choices or documentation
-- **1 obsolete issue** already resolved
-
-**Recommendation**: Implement the 3 high-priority fixes (Issues 1, 2, 4) before considering the implementation fully PRD-compliant. The medium and low priority issues can be addressed incrementally.
-
----
-
-## Appendix: File References
-
-### PRD
-- **Location**: `/home/dustin/projects/groundswell/PRPs/PRDs/001-hierarchical-workflow-engine.md`
-- **Version**: 1.0
-- **Status**: Implementation-ready
-
-### Implementation Files
-- **Core**: `/home/dustin/projects/groundswell/src/core/workflow.ts`
-- **Decorators**: `/home/dustin/projects/groundswell/src/decorators/step.ts`, `/home/dustin/projects/groundswell/src/decorators/task.ts`
-- **Types**: `/home/dustin/projects/groundswell/src/types/events.ts`, `/home/dustin/projects/groundswell/src/types/workflow.ts`
-- **Logger**: `/home/dustin/projects/groundswell/src/core/logger.ts`
-- **Debugger**: `/home/dustin/projects/groundswell/src/debugger/tree-debugger.ts`
-
-### Test Results
-- **Location**: `/home/dustin/projects/groundswell/TEST_RESULTS.md`
-- **Test Status**: 133/133 passing (as of 2026-01-10)