groundswell 0.0.1 → 0.0.2

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

@@ -0,0 +1,1134 @@
+# 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)