groundswell 0.0.2 → 0.0.3

package/plan/001_d3bb02af4886/bugfix/001_e8e04329daf3/P1M3T3S2/PRP.md

@@ -1,460 +0,0 @@
-name: "P1.M3.T3.S2 - Implement Workflow Name Validation in Constructor"
-description: |
-
----
-
-## Goal
-
-**Feature Goal**: Add validation to the Workflow constructor to reject empty and whitespace-only workflow names while preserving existing behavior for undefined/null names.
-
-**Deliverable**: Updated `src/core/workflow.ts` constructor with name validation logic that throws descriptive errors for invalid names.
-
-**Success Definition**:
-- Workflow constructor throws `Error` when name is empty string or whitespace-only
-- Workflow constructor throws `Error` when name exceeds 100 characters
-- Workflow constructor preserves existing fallback behavior when name is `undefined` or `null` (uses class name)
-- TypeScript compiles without errors
-- All tests pass including updated edge-case test
-
-## User Persona (if applicable)
-
-**Target User**: Developer using the Groundswell workflow engine
-
-**Use Case**: Creating Workflow instances with custom or default names for identification in tree debugger and logging
-
-**User Journey**:
-1. Developer creates a `new Workflow('MyWorkflowName')` or extends Workflow class
-2. If the name is invalid (empty/whitespace), they receive immediate, clear error feedback
-3. If the name is valid or omitted, the workflow is created successfully
-
-**Pain Points Addressed**:
-- Empty workflow names appear as blank entries in tree debugger, causing confusion
-- No validation feedback when developers accidentally use empty strings
-- Inconsistent with industry best practices (all major workflow engines validate names)
-
-## Why
-
-- **User Experience**: Empty workflow names provide no useful information and create confusion in the tree debugger
-- **Bug Fix**: Issue 8 explicitly frames empty names as a bug ("should probably be non-empty")
-- **Industry Alignment**: All major workflow engines (Kubernetes, Airflow, AWS Step Functions) require non-empty names
-- **Consistency**: Codebase already validates other critical inputs (circular references, duplicate registrations)
-- **PRD Compliance**: PRD specifies name as "Human-readable name" - empty string is not human-readable
-
-## What
-
-Add validation logic to the Workflow constructor that:
-1. Rejects empty strings (`''`)
-2. Rejects whitespace-only strings (`'   '`, `'\t\n'`)
-3. Rejects names exceeding 100 characters
-4. Preserves existing fallback behavior for `undefined`/`null` (uses class name)
-5. Does NOT auto-trim leading/trailing whitespace (preserves user intent)
-
-### Success Criteria
-
-- [ ] Empty string names throw `Error` with message: "Workflow name cannot be empty or whitespace only"
-- [ ] Whitespace-only names throw `Error` with message: "Workflow name cannot be empty or whitespace only"
-- [ ] Names exceeding 100 characters throw `Error` with message: "Workflow name cannot exceed 100 characters"
-- [ ] `undefined`/`null` names still use class name (existing behavior preserved)
-- [ ] Valid names with leading/trailing whitespace are accepted as-is
-- [ ] Both constructor patterns (class-based and functional) are validated
-
-## All Needed Context
-
-### Context Completeness Check
-
-_Before writing this PRP, validate: "If someone knew nothing about this codebase, would they have everything needed to implement this successfully?"_
-
-✅ **YES** - This PRP includes:
-- Exact file path and line numbers for the modification
-- Complete validation rules from S1 decision document
-- Existing constructor code patterns to follow
-- Error handling patterns used throughout codebase
-- Test file that needs updating with specific line numbers
-- Both constructor patterns that must be validated
-- TypeScript compilation validation steps
-
-### Documentation & References
-
-```yaml
-# MUST READ - Include these in your context window
-- url: file:///home/dustin/projects/groundswell/plan/001_d3bb02af4886/bugfix/001_e8e04329daf3/docs/P1M3T3S1/DECISION.md
-  why: Contains complete validation rules decided in S1 (5 rules with examples)
-  critical: Implementation location specified as line ~98, after config normalization, before node creation
-
-- file: src/core/workflow.ts
-  why: Contains the Workflow class constructor that needs modification
-  pattern: Constructor uses overloaded parameters (class-based: name, parent | functional: config, executor)
-  gotcha: Validation MUST apply to both constructor patterns - name comes from different sources
-
-- file: src/core/workflow.ts:94
-  why: Line where `this.config = { name: name ?? this.constructor.name }` is set (class-based pattern)
-  pattern: Nullish coalescing preserves undefined fallback - must NOT break this
-
-- file: src/core/workflow.ts:98-117
-  why: Constructor body - validation must be added AFTER line 94 (config set), BEFORE line 101 (node created)
-  pattern: Existing validation patterns in codebase use standard `Error` with descriptive messages
-
-- file: src/__tests__/adversarial/edge-case.test.ts:107-117
-  why: This test currently EXPECTS empty names to work - must be updated to expect error thrown
-  pattern: Uses `expect(workflow.node.name).toBe('')` - needs `expect(() => new TestWorkflow('')).toThrow()`
-
-- file: src/__tests__/unit/workflow.test.ts
-  why: Contains existing constructor test patterns to follow for new validation tests
-  pattern: Uses SimpleWorkflow class, `expect().toThrow()` for error testing
-
-- docfile: plan/001_d3bb02af4886/bugfix/001_e8e04329daf3/docs/P1M3T3S1/DECISION.md
-  why: Complete validation rules with examples and anti-patterns to avoid
-  section: Rules 1-5 specify exact validation behavior required
-```
-
-### Current Codebase tree (run `tree` in the root of the project) to get an overview of the codebase
-
-```bash
-/home/dustin/projects/groundswell
-├── src/
-│   ├── core/
-│   │   ├── workflow.ts          # MODIFICATION TARGET (constructor at lines 83-117)
-│   │   ├── agent.ts
-│   │   ├── context.ts
-│   │   └── ...
-│   ├── types/
-│   │   ├── workflow.ts          # WorkflowConfig interface (name?: string)
-│   │   └── ...
-│   └── __tests__/
-│       ├── adversarial/
-│       │   └── edge-case.test.ts   # UPDATE REQUIRED (line 107-117)
-│       └── unit/
-│           └── workflow.test.ts     # REFERENCE for test patterns
-```
-
-### Desired Codebase tree with files to be added and responsibility of file
-
-```bash
-# No new files to be added
-# Modifications only:
-├── src/
-│   ├── core/
-│   │   └── workflow.ts          # MODIFY: Add validation to constructor (~line 98-100)
-└── __tests__/
-    ├── adversarial/
-    │   └── edge-case.test.ts    # MODIFY: Update test at lines 107-117 to expect error
-    └── unit/
-        └── workflow.test.ts     # MODIFY: Add new validation test suite
-```
-
-### Known Gotchas of our codebase & Library Quirks
-
-```typescript
-// CRITICAL: The Workflow constructor has TWO patterns - validation must work for both
-// Pattern 1: Class-based - new Workflow(name?, parent?)
-// Pattern 2: Functional - new Workflow(config, executor)
-// The name parameter comes from different sources in each pattern!
-
-// Pattern 1 (lines 88-94):
-// this.config = { name: name ?? this.constructor.name };
-// If name is string, use it. If undefined/null, use class name.
-
-// Pattern 2 (lines 96-101):
-// if (typeof name === 'object') { this.config = name; } else { ... }
-// name is actually a WorkflowConfig object with name property
-
-// GOTCHA: The parameter named "name" in the constructor signature
-// can be either: string | WorkflowConfig | undefined
-// After config normalization, always check: this.config.name
-
-// VALIDATION LOCATION: After line 94, this.config.name is always defined
-// Check if it's a string and validate. If undefined, class name was used (valid).
-
-// GOTCHA: Don't use custom error classes - codebase uses standard Error throughout
-// Examples from codebase:
-// throw new Error('Circular parent-child relationship detected');
-// throw new Error('Child already attached to this workflow');
-
-// GOTCHA: The test at edge-case.test.ts:107-117 expects empty names to work
-// This test MUST be updated or it will fail after implementation
-
-// GOTCHA: TypeScript compilation is a validation gate - code must compile without errors
-// Run: npx tsc --noEmit
-```
-
-## Implementation Blueprint
-
-### Data models and structure
-
-No new data models needed. This is a pure validation enhancement to existing constructor.
-
-```typescript
-// Existing models (no changes needed):
-// - WorkflowConfig interface: { name?: string; ... }
-// - Workflow class extends WorkflowNodeBase
-```
-
-### Implementation Tasks (ordered by dependencies)
-
-```yaml
-Task 1: MODIFY src/core/workflow.ts constructor
-  - LOCATION: After line 94 (this.config assignment), before line 98 (conditional logic)
-  - IMPLEMENT: Name validation using this.config.name
-  - VALIDATION RULE 1 (Empty/Whitespace): if (typeof this.config.name === 'string' && this.config.name.trim().length === 0) throw new Error('Workflow name cannot be empty or whitespace only')
-  - VALIDATION RULE 2 (Max Length): if (typeof this.config.name === 'string' && this.config.name.length > 100) throw new Error('Workflow name cannot exceed 100 characters')
-  - PRESERVE: undefined/null fallback to class name (don't validate if this.config.name is undefined)
-  - PATTERN: Follow existing error throwing pattern in codebase (standard Error, descriptive message)
-  - GOTCHA: Only validate when this.config.name is explicitly a string - undefined means class name was used (valid)
-
-Task 2: UPDATE src/__tests__/adversarial/edge-case.test.ts
-  - LOCATION: Lines 107-117 (test "should handle empty string workflow name")
-  - CHANGE: Modify test to expect error to be thrown
-  - PATTERN: expect(() => new TestWorkflow('')).toThrow('Workflow name cannot be empty or whitespace only')
-  - PRESERVE: Test structure and description, only change expectation
-
-Task 3: CREATE new test suite in src/__tests__/unit/workflow.test.ts
-  - LOCATION: Add new describe block: 'Workflow Name Validation'
-  - IMPLEMENT: Comprehensive tests for all validation rules
-  - TEST CASES:
-    - Empty string should throw
-    - Whitespace-only (spaces) should throw
-    - Whitespace-only (tabs/newlines) should throw
-    - Name exceeding 100 characters should throw
-    - Exactly 100 characters should work
-    - Valid names should work
-    - Undefined should use class name (existing behavior)
-    - Null should use class name (existing behavior)
-    - Name with leading/trailing whitespace should be accepted as-is
-    - Both constructor patterns should be validated
-  - PATTERN: Follow existing test patterns in workflow.test.ts (SimpleWorkflow class, expect().toThrow())
-
-Task 4: VERIFY TypeScript compilation
-  - RUN: npx tsc --noEmit
-  - EXPECT: Zero type errors
-  - FIX: Any type errors that arise from validation logic
-
-Task 5: RUN full test suite
-  - RUN: npm test
-  - EXPECT: All tests pass
-  - FIX: Any failing tests (should only be the updated edge-case test now passing)
-```
-
-### Implementation Patterns & Key Details
-
-```typescript
-// EXACT CODE TO INSERT at src/core/workflow.ts after line 94:
-
-// Location: src/core/workflow.ts:94 (after this.config = { name: name ?? this.constructor.name })
-// PATTERN: Only validate when name is explicitly provided as a string
-// CRITICAL: undefined means class name was used - this is valid behavior
-
-// Validate workflow name (after config is normalized)
-if (typeof this.config.name === 'string') {
-  const trimmedName = this.config.name.trim();
-  if (trimmedName.length === 0) {
-    throw new Error('Workflow name cannot be empty or whitespace only');
-  }
-  if (this.config.name.length > 100) {
-    throw new Error('Workflow name cannot exceed 100 characters');
-  }
-}
-
-// GOTCHA: We check this.config.name.length (not trimmed) for max length
-// This matches the decision document Rule 2 exactly
-
-// GOTCHA: We check trimmedName.length === 0 for whitespace-only detection
-// This matches the decision document Rule 1 exactly
-
-// GOTCHA: We DON'T auto-trim - we only reject if entirely whitespace
-// This matches the decision document Rule 4 exactly
-
-// Existing constructor structure for reference (lines 83-101):
-constructor(name?: string | WorkflowConfig, parentOrExecutor?: Workflow | WorkflowExecutor<T>) {
-  this.id = generateId();
-  this.status = 'idle';
-  this.observers = [];
-  this.children = [];
-  this.parent = null;
-
-  // Class-based pattern: new Workflow(name?, parent?)
-  if (typeof name !== 'object' || name === null) {
-    this.config = { name: name ?? this.constructor.name };
-    this.parent = parentOrExecutor as Workflow | null;
-  }
-  // Functional pattern: new Workflow(config, executor)
-  else {
-    this.config = name;
-    this.executor = parentOrExecutor as WorkflowExecutor<T>;
-  }
-
-  // *** INSERT VALIDATION HERE *** (after line 94, before line 98)
-  // After this point, this.config.name is set for both patterns
-
-  this.node = new WorkflowNode({
-    id: this.id,
-    name: this.config.name ?? this.constructor.name,
-    // ... rest of node creation
-  });
-}
-```
-
-### Integration Points
-
-```yaml
-VALIDATION:
-  - location: "src/core/workflow.ts constructor"
-  - line: "~94-97 (after config assignment, before node creation)"
-  - pattern: "Standard Error throwing with descriptive messages"
-
-TESTS:
-  - update: "src/__tests__/adversarial/edge-case.test.ts:107-117"
-  - add: "src/__tests__/unit/workflow.test.ts (new describe block)"
-  - pattern: "expect(() => new Workflow('')).toThrow()"
-
-COMPATIBILITY:
-  - breaking: "Yes - empty names will now throw errors"
-  - rationale: "Empty names provide no value and are bugs (Issue 8)"
-  - migration: "Provide meaningful names instead of empty strings"
-```
-
-## Validation Loop
-
-### Level 1: Syntax & Style (Immediate Feedback)
-
-```bash
-# Run after file modification - fix before proceeding
-npx tsc --noEmit                    # TypeScript type checking
-npm run lint                        # ESLint checking (if configured)
-npm run format                      # Prettier formatting (if configured)
-
-# Expected: Zero errors. If errors exist, READ output and fix before proceeding.
-```
-
-### Level 2: Unit Tests (Component Validation)
-
-```bash
-# Test the specific validation functionality
-npm test -- workflow.test.ts        # Run workflow unit tests
-npm test -- edge-case.test.ts       # Run adversarial edge case tests
-
-# Full test suite for affected areas
-npm test                            # Run all tests
-
-# Expected: All tests pass. The edge-case test should now pass with the updated expectation.
-```
-
-### Level 3: Integration Testing (System Validation)
-
-```bash
-# Verify workflow creation still works for valid names
-node -e "
-const { Workflow } = require('./dist/index.js');
-class TestWF extends Workflow { async run() { return 'done'; } }
-
-// Valid names should work
-const wf1 = new TestWF('ValidName');
-console.log('Valid name:', wf1.node.name);
-
-// Undefined should use class name
-const wf2 = new TestWF();
-console.log('Undefined uses class name:', wf2.node.name);
-
-// Empty should throw
-try {
-  new TestWF('');
-  console.log('ERROR: Empty name should have thrown!');
-} catch (e) {
-  console.log('Empty name correctly throws:', e.message);
-}
-"
-
-# Expected: Valid names work, empty names throw with correct error message
-```
-
-### Level 4: Creative & Domain-Specific Validation
-
-```bash
-# Test both constructor patterns
-node -e "
-const { Workflow } = require('./dist/index.js');
-
-// Pattern 1: Class-based
-try {
-  const wf1 = new Workflow('   ');  // Whitespace only
-  console.log('ERROR: Whitespace should have thrown!');
-} catch (e) {
-  console.log('Class-based pattern validation:', e.message);
-}
-
-// Pattern 2: Functional
-try {
-  const wf2 = new Workflow({ name: '' }, async () => {});
-  console.log('ERROR: Empty should have thrown!');
-} catch (e) {
-  console.log('Functional pattern validation:', e.message);
-}
-"
-
-# Test max length validation
-node -e "
-const { Workflow } = require('./dist/index.js');
-class TestWF extends Workflow { async run() { return 'done'; } }
-
-const longName = 'a'.repeat(101);
-try {
-  new TestWF(longName);
-  console.log('ERROR: 101 chars should have thrown!');
-} catch (e) {
-  console.log('Max length validation:', e.message);
-}
-
-const exactly100 = 'a'.repeat(100);
-const wf3 = new TestWF(exactly100);
-console.log('Exactly 100 chars works:', wf3.node.name.length === 100);
-"
-
-# Expected: All validation rules work correctly for both constructor patterns
-```
-
-## Final Validation Checklist
-
-### Technical Validation
-
-- [ ] TypeScript compiles without errors: `npx tsc --noEmit`
-- [ ] All tests pass: `npm test`
-- [ ] Empty string names throw error with correct message
-- [ ] Whitespace-only names throw error with correct message
-- [ ] Names > 100 chars throw error with correct message
-- [ ] Exactly 100 chars works
-- [ ] Undefined/null names use class name (existing behavior)
-- [ ] Both constructor patterns are validated
-
-### Feature Validation
-
-- [ ] Validation location: after config assignment, before node creation
-- [ ] Error messages match decision document exactly
-- [ ] No auto-trimming of whitespace (user intent preserved)
-- [ ] Edge-case test updated and passing
-- [ ] New validation tests added and passing
-
-### Code Quality Validation
-
-- [ ] Follows existing error throwing patterns (standard Error, descriptive messages)
-- [ ] No custom error classes created
-- [ ] Code is self-documenting with clear variable names
-- [ ] Breaking change is documented (test expectations updated)
-
-### Documentation & Deployment
-
-- [ ] Code changes are minimal and focused
-- [ ] No new dependencies added
-- [ ] No new files created (modifications only)
-- [ ] Backward compatibility handled (undefined preserved)
-
----
-
-## Anti-Patterns to Avoid
-
-- ❌ Don't auto-trim names - preserve user intent, only reject whitespace-only
-- ❌ Don't use custom error classes - codebase uses standard `Error`
-- ❌ Don't forget both constructor patterns - validation must work for class-based AND functional
-- ❌ Don't break the undefined fallback - preserve class name default behavior
-- ❌ Don't validate when this.config.name is undefined - this means class name was used (valid)
-- ❌ Don't check trimmed length for max length - check original length per decision document
-- ❌ Don't update the edge-case test description - only change the expectation
-- ❌ Don't skip testing both constructor patterns - they handle name differently