groundswell 0.0.1 → 0.0.2

package/plan/001_d3bb02af4886/docs/research/P1M2T1S4/INDEX.md

@@ -0,0 +1,213 @@
+# Decorator Documentation Research - Index
+
+**Research Date:** 2026-01-11
+**Purpose:** Best practices for documenting TypeScript decorator options in README.md files
+
+---
+
+## Research Documents
+
+### 1. Main Research Document
+**File:** [DECORATOR_DOCUMENTATION_BEST_PRACTICES.md](./DECORATOR_DOCUMENTATION_BEST_PRACTICES.md)
+**Size:** Comprehensive (500+ lines)
+**Contains:**
+- Executive summary of findings
+- Documentation structure patterns
+- Default value presentation methods
+- Table formatting best practices
+- Code example patterns
+- Real-world examples from Groundswell
+- Recommended templates
+- URLs and references
+- Action items for implementation
+
+**Use when:** You need comprehensive understanding of decorator documentation best practices
+
+### 2. Quick Reference Guide
+**File:** [DECORATOR_DOCUMENTATION_QUICK_REF.md](./DECORATOR_DOCUMENTATION_QUICK_REF.md)
+**Size:** Concise (150 lines)
+**Contains:**
+- Recommended table format
+- Code example patterns
+- Groundswell-specific improvements
+- Common default values
+- Validation checklist
+- PRP template sections
+
+**Use when:** You need fast reference while documenting decorators
+
+### 3. Concrete Examples
+**File:** [GROUNDSWELL_DECORATOR_EXAMPLES.md](./GROUNDSWELL_DECORATOR_EXAMPLES.md)
+**Size:** Detailed (400+ lines)
+**Contains:**
+- Current vs recommended documentation for all three decorators
+- Before/after comparisons
+- Implementation checklist
+- File references with line numbers
+
+**Use when:** You need to see exactly how to improve existing documentation
+
+---
+
+## Key Findings Summary
+
+### Top 3 Best Practices
+
+1. **Add a Dedicated Default Column**
+   ```markdown
+   | Option | Type | Default | Description |
+   ```
+   Makes defaults immediately visible, reduces cognitive load
+
+2. **Show Progressive Code Examples**
+   Start with defaults, then show overrides:
+   ```typescript
+   @Step()  // Default
+   @Step({ option: true })  // With option
+   ```
+
+3. **Document Default Behavior Explicitly**
+   Add a "Default Behavior" section before the options table
+
+### Recommended Table Structure
+
+```markdown
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `name` | `string` | method name | Custom name for logs |
+| `enabled` | `boolean` | `true` | Enable feature |
+```
+
+---
+
+## Groundswell Files to Update
+
+| File | Current Lines | Key Changes |
+|------|---------------|-------------|
+| `docs/workflow.md` | 114-244 | Add Default column to all 3 decorators |
+| `README.md` | 114-131 | Add inline comments explaining defaults |
+| `src/types/decorators.ts` | 1-26 | Ensure JSDoc comments match docs |
+
+---
+
+## URLs and External References
+
+### Groundswell Internal Files
+
+1. **Workflow Documentation**
+   - File: `/home/dustin/projects/groundswell/docs/workflow.md`
+   - Contains: @Step, @Task, @ObservedState documentation
+   - Status: Needs Default column added
+
+2. **Main README**
+   - File: `/home/dustin/projects/groundswell/README.md`
+   - Contains: Quick start decorator usage
+   - Status: Needs inline default comments
+
+3. **Type Definitions**
+   - File: `/home/dustin/projects/groundswell/src/types/decorators.ts`
+   - Contains: TypeScript interfaces
+   - Status: Reference for validation
+
+4. **Example Code**
+   - File: `/home/dustin/projects/groundswell/examples/examples/02-decorator-options.ts`
+   - Contains: Executable decorator examples
+   - Status: Needs default values documented
+
+### External Libraries (For Further Study)
+
+**Note:** These URLs were identified for reference but could not be accessed during research due to API rate limits. They represent excellent examples of decorator documentation to study:
+
+5. **class-validator**
+   - Repository: https://github.com/typestack/class-validator
+   - Known for: Extensive decorator options documentation
+   - Study focus: Table formatting, default value presentation
+
+6. **TypeORM**
+   - Repository: https://github.com/typeorm/typeorm
+   - Documentation: https://typeorm.io/#/decorator-reference
+   - Known for: Entity and column decorator options
+   - Study focus: Complex option configuration
+
+7. **NestJS**
+   - Repository: https://github.com/nestjs/nest
+   - Documentation: https://docs.nestjs.com/custom-decorators
+   - Known for: Clean decorator API design
+   - Study focus: Decorator composition patterns
+
+8. **Angular Style Guide**
+   - Repository: https://github.com/angular/angular
+   - Documentation: https://angular.io/guide/styleguide#style-05-12
+   - Known for: Consistent decorator documentation
+   - Study focus: Documentation style guide
+
+9. **InversifyJS**
+   - Repository: https://github.com/inversify/InversifyJS
+   - Known for: Dependency injection decorators
+   - Study focus: Optional vs required parameters
+
+### Documentation Standards
+
+10. **TypeScript Decorator Documentation**
+    - URL: https://www.typescriptlang.org/docs/handbook/decorators.html
+    - Official TypeScript handbook on decorators
+
+11. **TSDoc Standard**
+    - URL: https://tsdoc.org/
+    - Documentation comment standard for TypeScript
+
+12. **JSDoc Documentation**
+    - URL: https://jsdoc.app/
+    - Traditional JavaScript documentation tags
+
+---
+
+## Quick Actions
+
+### For PRP Creation
+
+```markdown
+## Documentation Update
+
+**Files to Update:**
+1. `docs/workflow.md` - Add Default column to decorator tables
+2. `README.md` - Add inline default value comments
+3. `examples/02-decorator-options.ts` - Document defaults in JSDoc
+
+**Reference:**
+- Best practices: `plan/docs/research/P1M2T1S4/DECORATOR_DOCUMENTATION_BEST_PRACTICES.md`
+- Examples: `plan/docs/research/P1M2T1S4/GROUNDSWELL_DECORATOR_EXAMPLES.md`
+- Quick ref: `plan/docs/research/P1M2T1S4/DECORATOR_DOCUMENTATION_QUICK_REF.md`
+```
+
+### For Implementation
+
+1. Read `GROUNDSWELL_DECORATOR_EXAMPLES.md` for specific changes
+2. Use `DECORATOR_DOCUMENTATION_QUICK_REF.md` for table format
+3. Reference `DECORATOR_DOCUMENTATION_BEST_PRACTICES.md` for rationale
+
+---
+
+## Related Research
+
+- `plan/docs/research/bugfix_typescript_patterns.md` - TypeScript patterns for error handling
+- `plan/docs/research/CYCLE_DETECTION_PATTERNS.md` - Cycle detection patterns
+- `plan/docs/research/error_handling_patterns.md` - Error handling best practices
+
+---
+
+## Confidence Score
+
+**Overall Confidence:** 9/10
+
+**Reasoning:**
+- Analyzed actual Groundswell codebase
+- Identified specific improvement areas
+- Provided actionable recommendations
+- External libraries identified but not accessed (rate limits)
+- Patterns based on established documentation best practices
+
+---
+
+**Research Complete:** 2026-01-11
+**Next Step:** Apply findings to improve Groundswell decorator documentation

package/plan/001_d3bb02af4886/docs/research/P1M2T1S4/codebase_structure.md

@@ -0,0 +1,30 @@
+# Codebase Structure for P1.M2.T1.S4
+
+## Relevant Source Files
+```
+/home/dustin/projects/groundswell/
+├── src/
+│   ├── core/
+│   │   └── workflow.ts          # Contains getRootObservers() (lines 124-139)
+│   ├── __tests__/
+│   │   └── unit/
+│   │       └── workflow.test.ts # Add test here (after line 223)
+│   └── index.js                 # Main exports
+└── plan/
+    └── bugfix/
+        └── P1M2T1S4/            # This subtask directory
+            ├── research/        # Research findings (this file)
+            └── PRP.md          # Target PRP location
+```
+
+## Key Files
+- **Implementation**: `/home/dustin/projects/groundswell/src/core/workflow.ts`
+- **Test File**: `/home/dustin/projects/groundswell/src/__tests__/unit/workflow.test.ts`
+- **PRP Location**: `/home/dustin/projects/groundswell/plan/bugfix/P1M2T1S4/PRP.md`
+
+## Existing Related Tests (workflow.test.ts)
+- Line 209-223: `should detect circular parent relationship` (getRoot() test)
+- P1.M2.T1.S2 test is the template to follow
+
+## Test Location for New Test
+Add after line 223 (within the same `describe('Workflow', ...)` block)

package/plan/001_d3bb02af4886/docs/research/P1M2T1S4/existing_test_pattern.md

@@ -0,0 +1,56 @@
+# Existing Test Pattern for Cycle Detection (P1.M2.T1.S2)
+
+## File Reference
+- **Test File**: `/home/dustin/projects/groundswell/src/__tests__/unit/workflow.test.ts`
+- **Test Location**: Lines 209-223
+
+## Complete Test Code (P1.M2.T1.S2)
+
+```typescript
+it('should detect circular parent relationship', () => {
+  // Arrange: Create parent and child workflows
+  const parent = new SimpleWorkflow('Parent');
+  const child = new SimpleWorkflow('Child', parent);
+
+  // Act: Create circular reference manually
+  // This simulates a bug or malicious input that creates a cycle
+  parent.parent = child;
+
+  // Assert: getRoot() should throw error for circular reference
+  // Note: getRoot() is protected, so we cast to any to access it
+  expect(() => (parent as any).getRoot()).toThrow(
+    'Circular parent-child relationship detected'
+  );
+});
+```
+
+## Key Patterns to Replicate
+
+### 1. Test Structure
+- **Arrange**: Create parent and child workflows with `new SimpleWorkflow('Name', parent)`
+- **Act**: Create circular reference by setting `parent.parent = child`
+- **Assert**: Use `expect(() => (workflow as any).method()).toThrow()` pattern
+
+### 2. Error Message
+- **Exact String**: `'Circular parent-child relationship detected'`
+- Must match exactly or use `toThrow(Error)` for type-only matching
+
+### 3. Test Utility Class
+```typescript
+class SimpleWorkflow extends Workflow {
+  async run(): Promise<string> {
+    this.setStatus('running');
+    this.logger.info('Running simple workflow');
+    this.setStatus('completed');
+    return 'done';
+  }
+}
+```
+
+### 4. Test Naming Convention
+- Use clear, descriptive test names like "should detect circular parent relationship"
+- Include comments explaining each step
+
+### 5. Accessibility Workaround
+- `getRoot()` is `protected` - accessed via `(parent as any).getRoot()`
+- `getRootObservers()` is `private` - may need different access method

package/plan/001_d3bb02af4886/docs/research/P1M2T1S4/getRootObservers_implementation.md

@@ -0,0 +1,53 @@
+# getRootObservers() Implementation Analysis (P1.M2.T1.S3)
+
+## File Reference
+- **Source File**: `/home/dustin/projects/groundswell/src/core/workflow.ts`
+- **Method Location**: Lines 124-139
+
+## Complete Implementation
+
+```typescript
+/**
+ * Get observers from the root workflow
+ * Traverses up the tree to find the root
+ * Uses cycle detection to prevent infinite loops from circular parent-child relationships
+ */
+private getRootObservers(): WorkflowObserver[] {
+  const visited = new Set<Workflow>();
+  let root: Workflow = this;
+  let current: Workflow | null = this;
+
+  while (current) {
+    if (visited.has(current)) {
+      throw new Error('Circular parent-child relationship detected');
+    }
+    visited.add(current);
+    root = current;
+    current = current.parent;
+  }
+
+  return root.observers;
+}
+```
+
+## Error Details
+- **Error Type**: `Error` (standard JavaScript Error)
+- **Error Message**: `"Circular parent-child relationship detected"`
+- **Error Trigger**: When a visited workflow is encountered during parent traversal
+
+## Comparison with getRoot()
+Both methods use **identical cycle detection logic**:
+- Same `Set<Workflow>` tracking approach
+- Same error message
+- Same traversal pattern
+- Only difference is return value (`WorkflowObserver[]` vs `Workflow`)
+
+## Accessibility Level
+- **`getRootObservers()`**: `private` method
+- **`getRoot()`**: `protected` method
+
+## Usage Context
+Called from:
+1. Constructor (line 111) - for logger creation
+2. `emitEvent()` method (line 205)
+3. `snapshotState()` method (line 228)

package/plan/001_d3bb02af4886/docs/research/P1M2T1S4/test_conventions.md

@@ -0,0 +1,49 @@
+# Test Conventions for Workflow Tests
+
+## Test Framework
+- **Framework**: Vitest
+- **Config File**: `vitest.config.ts`
+- **Test Pattern**: `src/__tests__/**/*.test.ts`
+
+## Running Tests
+```bash
+npm test              # Run all tests
+npm run test:watch    # Run in watch mode
+```
+
+## Test File Organization
+- **Unit Tests**: `src/__tests__/unit/*.test.ts`
+- **Integration Tests**: `src/__tests__/integration/*.test.ts`
+- Test file names match source: `workflow.ts` → `workflow.test.ts`
+
+## Standard Imports
+```typescript
+import { describe, it, expect } from 'vitest';
+import { Workflow, WorkflowObserver, /* ... */ } from '../../index.js';
+```
+
+## Test Structure Pattern
+```typescript
+describe('Workflow', () => {
+  it('should [expected behavior]', () => {
+    // Arrange: Set up test data
+    // Act: Execute the behavior
+    // Assert: Verify the result
+  });
+});
+```
+
+## Mock Observer Pattern
+```typescript
+const observer: WorkflowObserver = {
+  onLog: (entry) => logs.push(entry),
+  onEvent: (event) => events.push(event),
+  onStateUpdated: () => {},
+  onTreeChanged: () => {},
+};
+```
+
+## Error Testing Pattern
+```typescript
+expect(() => (workflow as any).privateMethod()).toThrow('Expected error message');
+```