groundswell 0.0.2 → 1.0.0

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

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

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

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

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

@@ -1,49 +0,0 @@
-# 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');
-```