groundswell 0.0.2 → 1.0.0

package/plan/001_d3bb02af4886/bugfix/P1M1T1S1/PRP.md

@@ -1,457 +0,0 @@
-name: "PRP: P1.M1.T1.S1 - Research PRD specification for child() signature"
-description: |
-
----
-
-## Goal
-
-**Feature Goal**: Document the PRD specification for WorkflowLogger.child() signature and create a comprehensive analysis comparing it with the current implementation.
-
-**Deliverable**: Analysis document `plan/bugfix/architecture/logger_child_signature_analysis.md` containing:
-- PRD specification details for child(meta: Partial<LogEntry>)
-- Current implementation analysis of child(parentLogId: string)
-- Detailed comparison of differences
-- Migration recommendations and approach
-- All existing call sites cataloged for impact analysis
-
-**Success Definition**:
-- Analysis document exists at specified path with all required sections
-- All existing child() call sites are documented with their usage patterns
-- Clear migration path is defined for future implementation work
-- Document passes "No Prior Knowledge" test - enables implementer to understand complete context
-
-## User Persona (if applicable)
-
-**Target User**: Developer/Implementer (Subtask P1.M1.T1.S2 executor)
-
-**Use Case**: Research phase before implementing the signature change migration
-
-**User Journey**:
-1. Read this PRP to understand the research scope
-2. Use provided context files to understand PRD vs implementation
-3. Catalog existing call sites and usage patterns
-4. Document findings for implementation team
-5. Create migration recommendations
-
-**Pain Points Addressed**:
-- Fragmented understanding of PRD requirements across multiple documents
-- Unclear impact of signature change on existing code
-- Need for comprehensive context before implementing breaking changes
-
-## Why
-
-- **Critical Bug Fix Foundation**: This research enables the critical signature mismatch fix (P1.M1.T1) which violates the public API contract
-- **Impact Analysis**: Understanding all call sites is essential before implementing a breaking change
-- **Migration Safety**: Proper research prevents unintended breaking of existing functionality
-- **Documentation Alignment**: Ensures implementation matches PRD specification for long-term maintainability
-
-## What
-
-Research task to analyze and document the PRD specification for WorkflowLogger.child() method signature.
-
-### Success Criteria
-
-- [ ] Analysis document created at `plan/bugfix/architecture/logger_child_signature_analysis.md`
-- [ ] PRD Section 12.1 specification documented with exact signature requirements
-- [ ] Current implementation documented from src/core/logger.ts:84-86
-- [ ] All existing child() call sites cataloged with file paths and line numbers
-- [ ] Migration recommendations provided for backward compatibility
-- [ ] Document passes "No Prior Knowledge" validation
-
-## All Needed Context
-
-### Context Completeness Check
-
-_Before writing this PRP, I validated: "If someone knew nothing about this codebase, would they have everything needed to implement this successfully?"_
-
-### Documentation & References
-
-```yaml
-# MUST READ - PRD Specification
-- url: file:///home/dustin/projects/groundswell/PRPs/PRDs/001-hierarchical-workflow-engine.md
-  section: "Section 12.1 (lines 286-308)"
-  why: PRD specification for child() signature - defines required API contract
-  critical: PRD specifies `child(meta: Partial<LogEntry>): WorkflowLogger` which differs from current implementation
-
-# MUST READ - Current Implementation
-- file: src/core/logger.ts
-  lines: "1-88 (complete file)"
-  why: Complete WorkflowLogger implementation including child() method at lines 84-86
-  pattern: Current signature is `child(parentLogId: string): WorkflowLogger`
-  gotcha: Current implementation passes parentLogId to constructor but PRD shows constructor without it
-
-# MUST READ - Type Definitions
-- file: src/types/logging.ts
-  lines: "1-25"
-  why: LogEntry interface definition - required to understand Partial<LogEntry> type
-  pattern: LogEntry has fields: id, workflowId, timestamp, level, message, data?, parentLogId?
-
-# MUST READ - Architecture Documentation
-- docfile: plan/bugfix/architecture/codebase_structure.md
-  why: Documents WorkflowLogger location and current implementation details
-  section: "WorkflowLogger class at src/core/logger.ts:84"
-
-# MUST READ - Existing Test Patterns
-- file: src/__tests__/adversarial/edge-case.test.ts
-  lines: "90-110"
-  why: Example of current child() usage pattern: `logger.child('parent-id-123')`
-  pattern: String argument passed to child() method
-
-# MUST READ - Test Framework Configuration
-- file: package.json
-  section: "scripts: test, test:watch"
-  why: Verification commands - vitest is the testing framework used
-  command: `npm test` runs `vitest run`
-
-# MUST READ - Partial<> Usage Patterns
-- file: src/types/reflection.ts
-  lines: "100-120"
-  why: Example of Partial<> pattern with default merging using spread operator
-  pattern: `{ ...DEFAULT_CONFIG, ...partial }` for merging Partial objects
-
-# MUST READ - Migration Context
-- docfile: plan/bugfix/RESEARCH_SUMMARY.md
-  why: Contains research notes about the signature mismatch issue
-  section: "Signature Mismatch: child() method"
-```
-
-### Current Codebase Tree
-
-```bash
-/home/dustin/projects/groundswell
-├── package.json                    # Test commands: npm test, npm run test:watch
-├── PRPs/
-│   └── PRDs/
-│       └── 001-hierarchical-workflow-engine.md    # PRD Section 12.1 (lines 286-308)
-├── plan/
-│   └── bugfix/
-│       ├── architecture/
-│       │   ├── codebase_structure.md              # WorkflowLogger documentation
-│       │   ├── concurrent_execution_best_practices.md
-│       │   └── error_handling_patterns.md
-│       ├── P1M1T1S1/                               # THIS WORK ITEM
-│       │   └── research/                           # Research output directory
-│       └── RESEARCH_SUMMARY.md                     # Existing research notes
-├── src/
-│   ├── core/
-│   │   └── logger.ts                               # WorkflowLogger class (lines 84-86: child())
-│   ├── types/
-│   │   └── logging.ts                              # LogEntry interface
-│   ├── __tests__/
-│   │   ├── unit/                                   # Unit tests
-│   │   └── adversarial/
-│   │       ├── edge-case.test.ts                   # child() usage at line ~96
-│   │       └── deep-analysis.test.ts               # child() usage at line ~61
-│   └── utils/
-│       └── id.ts                                   # generateId() utility
-├── vitest.config.ts                # Vitest configuration
-└── tsconfig.json                    # TypeScript configuration
-```
-
-### Desired Codebase Tree (After This Research Task)
-
-```bash
-plan/bugfix/
-├── architecture/
-│   └── logger_child_signature_analysis.md    # NEW: Main analysis output document
-└── P1M1T1S1/
-    ├── PRP.md                                 # THIS FILE: Product Requirement Prompt
-    └── research/
-        ├──prd_specification.md                # NEW: Extracted PRD Section 12.1 details
-        ├──current_implementation.md           # NEW: Current implementation analysis
-        ├──call_site_catalog.md                # NEW: All existing child() call sites
-        └──migration_recommendations.md        # NEW: Recommended migration approach
-```
-
-### Known Gotchas of our codebase & Library Quirks
-
-```typescript
-// CRITICAL: TypeScript Partial<> type requires proper default merging
-// Pattern from src/types/reflection.ts: { ...DEFAULT_CONFIG, ...partial }
-// Wrong: direct assignment may leave undefined values
-// Right: spread operator merging with defaults
-
-// CRITICAL: PRD constructor differs from current implementation
-// Current: new WorkflowLogger(node, observers, parentLogId?)
-// PRD: new WorkflowLogger(node, observers) - no parentLogId parameter
-// Migration must handle this discrepancy
-
-// CRITICAL: Existing child() call sites use string argument
-// Found in src/__tests__/adversarial/edge-case.test.ts:96
-// Found in src/__tests__/adversarial/deep-analysis.test.ts:61
-// Backward compatibility must be maintained
-
-// CRITICAL: LogEntry.parentLogId is optional (undefined for root logs)
-// Child logger entries MUST have parentLogId set
-// This is how hierarchical logging is implemented
-
-// CRITICAL: Vitest test framework uses import pattern
-// import { describe, it, expect, beforeEach, afterEach } from 'vitest'
-// Not jest - different mocking APIs (vi.spyOn, vi.fn, not jest.spyOn, jest.fn)
-```
-
-## Implementation Blueprint
-
-### Research Output Structure
-
-Create structured research documents under plan/bugfix/P1M1T1S1/research/:
-
-```markdown
-research/
-├── prd_specification.md          # PRD Section 12.1 content
-├── current_implementation.md     # src/core/logger.ts analysis
-├── call_site_catalog.md          # All child() usage sites
-└── migration_recommendations.md  # Proposed approach
-```
-
-### Implementation Tasks (ordered by dependencies)
-
-```yaml
-Task 1: CREATE plan/bugfix/P1M1T1S1/research/prd_specification.md
-  - EXTRACT: Complete PRD Section 12.1 content from PRPs/PRDs/001-hierarchical-workflow-engine.md:286-308
-  - DOCUMENT: Exact signature: child(meta: Partial<LogEntry>): WorkflowLogger
-  - DOCUMENT: Constructor signature from PRD: new WorkflowLogger(node, observers)
-  - DOCUMENT: LogEntry interface fields that can be partially specified
-  - FORMAT: Markdown with code blocks for clarity
-  - PLACEMENT: plan/bugfix/P1M1T1S1/research/
-
-Task 2: CREATE plan/bugfix/P1M1T1S1/research/current_implementation.md
-  - EXTRACT: Complete WorkflowLogger class from src/core/logger.ts:1-88
-  - DOCUMENT: Current signature: child(parentLogId: string): WorkflowLogger
-  - DOCUMENT: Current constructor: new WorkflowLogger(node, observers, parentLogId?)
-  - DOCUMENT: How parentLogId flows through the log() method (lines 35-51)
-  - DOCUMENT: The private emit() method pattern (lines 21-30)
-  - FORMAT: Markdown with line number references
-  - PLACEMENT: plan/bugfix/P1M1T1S1/research/
-
-Task 3: CREATE plan/bugfix/P1M1T1S1/research/call_site_catalog.md
-  - SEARCH: All occurrences of `.child(` in the codebase
-  - DOCUMENT: Each call site with file path, line number, and usage pattern
-  - CATEGORIZE: Test usage vs production usage
-  - ANALYZE: How each call site would be affected by signature change
-  - IDENTIFY: Backward compatibility requirements
-  - FORMAT: Table format for easy reference
-  - PLACEMENT: plan/bugfix/P1M1T1S1/research/
-
-Task 4: CREATE plan/bugfix/P1M1T1S1/research/migration_recommendations.md
-  - ANALYZE: Differences between PRD and implementation
-  - PROPOSE: Backward compatibility approach (string shorthand for parentLogId)
-  - REFERENCE: Partial<> usage patterns from src/types/reflection.ts
-  - DOCUMENT: Recommended function signature using TypeScript overloads
-  - IDENTIFY: Risks and mitigation strategies
-  - PLACEMENT: plan/bugfix/P1M1T1S1/research/
-
-Task 5: CREATE plan/bugfix/architecture/logger_child_signature_analysis.md
-  - COMPILE: Consolidated analysis from all research documents
-  - INCLUDE: Executive summary of findings
-  - INCLUDE: PRD vs Implementation comparison table
-  - INCLUDE: Complete call site catalog
-  - INCLUDE: Migration recommendations
-  - REFERENCE: All individual research documents
-  - PLACEMENT: plan/bugfix/architecture/
-
-Task 6: VERIFY plan/bugfix/P1M1T1S1/PRP.md completeness
-  - VALIDATE: All context references are accurate and accessible
-  - VALIDATE: File paths are correct
-  - VALIDATE: "No Prior Knowledge" test would pass
-  - UPDATE: Any missing context or unclear references
-  - PLACEMENT: plan/bugfix/P1M1T1S1/
-```
-
-### Research Patterns & Key Details
-
-```typescript
-// Pattern 1: PRD Specification Extraction
-// From PRPs/PRDs/001-hierarchical-workflow-engine.md:303-305
-child(meta: Partial<LogEntry>): WorkflowLogger {
-  return new WorkflowLogger(this.node, this.observers);
-}
-// NOTE: PRD constructor does NOT include parentLogId parameter
-
-// Pattern 2: Current Implementation
-// From src/core/logger.ts:84-86
-child(parentLogId: string): WorkflowLogger {
-  return new WorkflowLogger(this.node, this.observers, parentLogId);
-}
-// NOTE: Constructor receives parentLogId as third parameter
-
-// Pattern 3: parentLogId Flow in LogEntry
-// From src/core/logger.ts:45-48
-if (this.parentLogId) {
-  entry.parentLogId = this.parentLogId;
-}
-// CRITICAL: This is how hierarchical logging is implemented
-
-// Pattern 4: Partial<> Merging Pattern (from codebase)
-// From src/types/reflection.ts - createReflectionConfig function
-export function createReflectionConfig(
-  partial?: Partial<ReflectionConfig>
-): ReflectionConfig {
-  return {
-    ...DEFAULT_REFLECTION_CONFIG,
-    ...partial,
-  };
-}
-// RECOMMENDED: Use this pattern for handling Partial<LogEntry>
-
-// Pattern 5: Existing Call Site Pattern
-// From src/__tests__/adversarial/edge-case.test.ts:96
-const childLogger = this.logger.child('parent-id-123');
-// BACKWARD COMPATIBILITY: Must support string argument as shorthand
-```
-
-### Integration Points
-
-```yaml
-PRD_DOCUMENT:
-  - location: PRPs/PRDs/001-hierarchical-workflow-engine.md
-  - section: "12.1 WorkflowLogger Skeleton"
-  - lines: 286-308
-
-TYPE_DEFINITIONS:
-  - file: src/types/logging.ts
-  - interface: LogEntry (lines 9-24)
-  - fields: id, workflowId, timestamp, level, message, data?, parentLogId?
-
-TEST_SITES:
-  - src/__tests__/adversarial/edge-case.test.ts:96
-  - src/__tests__/adversarial/deep-analysis.test.ts:61
-  - dist/__tests__/unit/logging.test.js (HierarchicalLogger tests - different class)
-
-ARCHITECTURE_DOCS:
-  - plan/bugfix/architecture/codebase_structure.md
-  - plan/bugfix/RESEARCH_SUMMARY.md
-```
-
-## Validation Loop
-
-### Level 1: Syntax & Style (Immediate Feedback)
-
-```bash
-# Not applicable - this is a research task producing documentation
-# No code compilation needed
-
-# Verify markdown syntax if using linting tools
-npx markdownlint plan/bugfix/P1M1T1S1/research/*.md --fix
-
-# Expected: Zero markdown syntax errors
-```
-
-### Level 2: Document Completeness (Content Validation)
-
-```bash
-# Verify all required documents exist
-ls -la plan/bugfix/P1M1T1S1/research/
-# Expected output: prd_specification.md, current_implementation.md,
-#                  call_site_catalog.md, migration_recommendations.md
-
-# Verify main analysis document exists
-ls -la plan/bugfix/architecture/logger_child_signature_analysis.md
-# Expected: File exists
-
-# Count words in each document (minimum thresholds)
-wc -w plan/bugfix/P1M1T1S1/research/*.md
-# Expected: Each document should have substantial content (>100 words)
-
-# Verify document contains required sections
-grep -E "### (PRD Specification|Current Implementation|Call Sites|Migration)" plan/bugfix/architecture/logger_child_signature_analysis.md
-# Expected: All section headers found
-```
-
-### Level 3: Research Quality Validation (Accuracy Check)
-
-```bash
-# Verify PRD reference is accurate
-grep -A 5 "child(meta: Partial" PRPs/PRDs/001-hierarchical-workflow-engine.md
-# Expected: Shows child(meta: Partial<LogEntry>): WorkflowLogger
-
-# Verify current implementation reference is accurate
-grep -A 2 "child(parentLogId" src/core/logger.ts
-# Expected: Shows child(parentLogId: string): WorkflowLogger
-
-# Verify call sites are documented correctly
-grep -r "\.child(" src/__tests__/ --include="*.ts"
-# Expected: Matches documented call sites
-
-# Verify LogEntry interface reference
-grep -A 15 "interface LogEntry" src/types/logging.ts
-# Expected: Shows all LogEntry fields including parentLogId
-```
-
-### Level 4: Context Completeness Validation ("No Prior Knowledge" Test)
-
-```bash
-# Test: Can someone new to the project understand the issue?
-# Validation questions to answer:
-
-# 1. What is the PRD specification?
-cat plan/bugfix/P1M1T1S1/research/prd_specification.md
-# Should clearly state: child(meta: Partial<LogEntry>): WorkflowLogger
-
-# 2. What is the current implementation?
-cat plan/bugfix/P1M1T1S1/research/current_implementation.md
-# Should clearly state: child(parentLogId: string): WorkflowLogger
-
-# 3. What code will be affected?
-cat plan/bugfix/P1M1T1S1/research/call_site_catalog.md
-# Should list all files and line numbers
-
-# 4. How should migration be handled?
-cat plan/bugfix/P1M1T1S1/research/migration_recommendations.md
-# Should provide clear approach with backward compatibility
-
-# 5. Is there a single comprehensive document?
-cat plan/bugfix/architecture/logger_child_signature_analysis.md
-# Should consolidate all findings with clear summary
-```
-
-## Final Validation Checklist
-
-### Technical Validation
-
-- [ ] All 4 research documents exist in plan/bugfix/P1M1T1S1/research/
-- [ ] Main analysis document exists at plan/bugfix/architecture/logger_child_signature_analysis.md
-- [ ] All file references in documents are accurate and accessible
-- [ ] PRD specification is correctly extracted with line numbers
-- [ ] Current implementation is correctly documented with line numbers
-- [ ] All child() call sites are catalogued
-- [ ] Migration recommendations include backward compatibility approach
-
-### Research Quality Validation
-
-- [ ] PRD specification section includes exact signature from Section 12.1
-- [ ] Current implementation section includes complete child() method and constructor
-- [ ] Call site catalog includes file paths, line numbers, and usage patterns
-- [ ] Migration recommendations reference codebase patterns (Partial<> usage)
-- [ ] Main analysis document consolidates all findings with executive summary
-- [ ] Documents pass "No Prior Knowledge" test
-
-### Documentation & Formatting
-
-- [ ] All markdown files are properly formatted
-- [ ] Code blocks have language identifiers (typescript, bash, etc.)
-- [ ] File paths use absolute paths or clear relative paths from project root
-- [ ] Line number references are accurate
-- [ ] Tables (if any) are properly formatted
-
-### Success Criteria Validation
-
-- [ ] Analysis document exists at specified path
-- [ ] PRD specification documented with exact signature requirements
-- [ ] Current implementation documented from src/core/logger.ts
-- [ ] All existing child() call sites cataloged
-- [ ] Migration recommendations provided
-- [ ] Document enables implementation without additional context
-
----
-
-## Anti-Patterns to Avoid
-
-- ❌ Don't assume prior knowledge - be explicit about all file locations and line numbers
-- ❌ Don't skip cataloging call sites - every usage matters for migration planning
-- ❌ Don't ignore backward compatibility - existing code must continue to work
-- ❌ Don't omit line numbers - references must be precise
-- ❌ Don't create research documents without cross-referencing - link related sections
-- ❌ Don't forget the "No Prior Knowledge" test - imagine explaining to someone new
-- ❌ Don't mix PRD content with implementation analysis - keep them separate
-- ❌ Don't propose migration without understanding existing patterns - reference Partial<> usage from codebase