groundswell 0.0.1 → 0.0.2

package/.claude/commands/subtask-planning/prp-base-create.md

@@ -0,0 +1,120 @@
+# Create BASE PRP
+
+## Feature: $ARGUMENTS or $(tsk next) subtask
+
+## PRP Creation Mission
+
+Create a comprehensive PRP that enables **one-pass implementation success** through systematic research and context curation.
+
+
+**Critical Understanding**:
+You must start by reading and understanding the prp concepts plan/README.md
+Be aware that the executing AI agent only receives:
+- The PRP content you create
+- Its training data knowledge
+- Access to codebase files (but needs guidance on which ones)
+
+
+**Therefore**: Your research and context curation directly determines implementation success. Incomplete context = implementation failure.
+
+## Research Process
+
+> During the research process, create clear tasks and spawn as many agents and subagents as needed using the batch tools. The deeper research we do here the better the PRP will be. We optimize for chance of success, not for speed.
+
+1. **Codebase Analysis in depth**
+   - Create clear todos and spawn subagents to search the codebase for similar features/patterns. Think hard and plan your approach
+   - Identify all the necessary files to reference in the PRP
+   - Note all existing conventions to follow
+   - Check existing test patterns for validation approach, if none are found plan to find a new one
+   - Use the batch tools to spawn subagents to search the codebase for similar features/patterns
+
+2. **Internal Research at scale**
+   - Use relevant research and plan information in the `plan/M#P#T#S#` directory according to the current subtask
+   - Consider the scope of the subtask within the overall PRD. Respect the boundaries of scope of implementation for this task. Ensure cohesion across
+   previously completed tasks and guard against harming future task completion in your plan
+
+2. **External Research at scale**
+   - Create clear todos and spawn subagents with instructions to do deep research for similar features/patterns online and include urls to documentation and examples
+   - Library documentation (include specific URLs)
+   - Store all research in plans/\[M#P#T#S#]/research according to the current task and reference critical pieces of documentation in the PRP with clear
+   reasoning and instructions
+   - Implementation examples (GitHub/StackOverflow/blogs)
+   - New validation approach none found in existing codebase and user confirms they would like one added
+   - Best practices and common pitfalls found during research
+   - Use the batch tools to spawn subagents to search for similar features/patterns online and include urls to documentation and examples
+
+3. **User Clarification**
+   - Ask for clarification if you need it
+   - If no testing framework is found, ask the user if they would like to set one up
+   - If a fundamental misalignemnt of objectives across tasks is detected, halt and produce a thorough explanation of the problem at a 10th grade level
+
+## PRP Generation Process
+
+### Step 1: Choose Template
+
+Use `plan/templates/prp_base.md` as your template structure - it contains all necessary sections and formatting.
+
+### Step 2: Context Completeness Validation
+
+Before writing, apply the **"No Prior Knowledge" test** from the template:
+_"If someone knew nothing about this codebase, would they have everything needed to implement this successfully?"_
+
+### Step 3: Research Integration
+
+Transform your research findings into the template sections:
+
+**Goal Section**: Use research to define specific, measurable Feature Goal and concrete Deliverable
+**Context Section**: Populate YAML structure with your research findings - specific URLs, file patterns, gotchas
+**Implementation Tasks**: Create dependency-ordered tasks using information-dense keywords from codebase analysis
+**Validation Gates**: Use project-specific validation commands that you've verified work in this codebase
+
+### Step 4: Information Density Standards
+
+Ensure every reference is **specific and actionable**:
+
+- URLs include section anchors, not just domain names
+- File references include specific patterns to follow, not generic mentions
+- Task specifications include exact naming conventions and placement
+- Validation commands are project-specific and executable
+
+### Step 5: ULTRATHINK Before Writing
+
+After research completion, create comprehensive PRP writing plan using TodoWrite tool:
+
+- Plan how to structure each template section with your research findings
+- Identify gaps that need additional research
+- Create systematic approach to filling template with actionable context
+
+## Output
+
+Store the PRP at `plan/M#P#T#S#/PRP.md`
+Store documentation at `plan/M#P#T#S#/research/`
+
+## PRP Quality Gates
+
+### Context Completeness Check
+
+- [ ] Passes "No Prior Knowledge" test from template
+- [ ] All YAML references are specific and accessible
+- [ ] Implementation tasks include exact naming and placement guidance
+- [ ] Validation commands are project-specific and verified working
+
+### Template Structure Compliance
+
+- [ ] All required template sections completed
+- [ ] Goal section has specific Feature Goal, Deliverable, Success Definition
+- [ ] Implementation Tasks follow dependency ordering
+- [ ] Final Validation Checklist is comprehensive
+
+### Information Density Standards
+
+- [ ] No generic references - all are specific and actionable
+- [ ] File patterns point at specific examples to follow
+- [ ] URLs include section anchors for exact guidance
+- [ ] Task specifications use information-dense keywords from codebase
+
+## Success Metrics
+
+**Confidence Score**: Rate 1-10 for one-pass implementation success likelihood
+
+**Validation**: The completed PRP should enable an AI agent unfamiliar with the codebase to implement the feature successfully using only the PRP content and codebase access.

package/.claude/commands/subtask-planning/prp-base-execute.md

@@ -0,0 +1,65 @@
+# Execute BASE PRP
+
+## PRP File: $ARGUMENTS or $(tsk next) subtask information located at plans/M#P#T#S#/PRP.md
+
+## Mission: One-Pass Implementation Success
+
+PRPs enable working code on the first attempt through:
+
+- **Context Completeness**: Everything needed, nothing guessed
+- **Progressive Validation**: 4-level gates catch errors early
+- **Pattern Consistency**: Follow existing codebase approaches
+- Read PRPs/README.md to understand PRP concepts
+
+**Your Goal**: Transform the PRP into working code that passes all validation gates.
+
+## Execution Process
+
+1. **Load PRP**
+   - Read the specified PRP file completely
+   - Absorb all context, patterns, requirements and gather codebase intelligence
+   - Use the provided documentation references and file patterns, consume the right documentation before the appropriate todo/task
+   - Trust the PRP's context and guidance - it's designed for one-pass success
+   - If needed do additional codebase exploration and research as needed
+
+2. **ULTRATHINK & Plan**
+   - Create comprehensive implementation plan following the PRP's task order
+   - Break down into clear todos using TodoWrite tool
+   - Use subagents for parallel work when beneficial (always create prp inspired prompts for subagents when used)
+   - Follow the patterns referenced in the PRP
+   - Use specific file paths, class names, and method signatures from PRP context
+   - Never guess - always verify the codebase patterns and examples referenced in the PRP yourself
+
+3. **Execute Implementation**
+   - Follow the PRP's Implementation Tasks sequence, add more detail as needed, especially when using subagents
+   - Use the patterns and examples referenced in the PRP
+   - Create files in locations specified by the desired codebase tree
+   - Apply naming conventions from the task specifications and CLAUDE.md
+
+4. **Progressive Validation**
+
+   **Execute the level validation system from the PRP:**
+   - **Level 1**: Run syntax & style validation commands from PRP
+   - **Level 2**: Execute unit test validation from PRP
+   - **Level 3**: Run integration testing commands from PRP
+   - **Level 4**: Execute specified validation from PRP
+
+   **Each level must pass before proceeding to the next.**
+
+5. **Completion Verification**
+   - Work through the Final Validation Checklist in the PRP
+   - Verify all Success Criteria from the "What" section are met
+   - Confirm all Anti-Patterns were avoided
+   - Implementation is ready and working
+
+**Failure Protocol**: When validation fails, use the patterns and gotchas from the PRP to fix issues, then re-run validation until passing.
+
+If a fundamental issue with the plan is found, halt and produce a thorough explanation of the problem at a 10th grade level.
+
+Strictly output your results in this JSON format:
+
+```json
+{
+   "result": "success" | "error" | "issue",
+   "message": "Detailed explanation of the issue"
+}

package/.claude/commands/task-breakdown.md

@@ -0,0 +1,94 @@
+Act as a Lead Technical Architect and Project Management Synthesizer. You have already convened a panel of senior specialists (Security, DevOps, Backend, Frontend, and QA) who hold adversarial views on scope and complexity. Your job is not to output their debate, but to output their rigorous, unified consensus on how to decompose the attached PRD.
+
+Your Primary Goal: Assess the PRD to determine its hierarchy (Phase > Milestone > Task > Subtask) and decompose it into atomic, coherent work units.
+
+Hierarchy Definitions:
+
+Phase: Project-scope goals (e.g., MVP, V1.0). Weeks to months of effort.
+
+Milestone: Key objectives within a Phase. 1 to 12 weeks of effort.
+
+Task: Complete features within a Milestone. Days to weeks of effort.
+
+Subtask: Atomic implementation steps. 0.5, 1, or 2 Story Points (SP). Max 2 SP per subtask.
+
+Critical Constraints & Standard of Work (SOW):
+
+Coherence & Continuity (Priority):
+
+You must ensure architectural flow. Subtasks must not exist in a vacuum.
+
+If Subtask A defines a data schema, Subtask B must explicitly be told to consume that specific schema.
+
+Reference specific file paths, variable names, or API endpoints within the context_scope to ensure the implementing agent follows the chain of logic.
+
+Implicit TDD & Quality:
+
+Do not create subtasks for "Write Tests."
+
+Assume every subtask implies: "Write the failing test, implement the code, pass the test."
+
+Code is not complete without tests.
+
+The "Context Scope" Blinder:
+
+For every Subtask, the context_scope must be a strict set of instructions for a developer who cannot see the rest of the project.
+
+It must define Inputs (what data/interfaces are available from previous subtasks) and Outputs (what exact interface this subtask exposes).
+
+It must explicitly state Mocking Strategies to keep the subtask isolated.
+
+Process:
+
+Analyze the attached or referenced PRD.
+
+Determine the highest level of scope (Phase, Milestone, or Task) this PRD represents.
+
+Decompose strictly downwards to the Subtask level.
+
+Output Format:
+Output only a JSON object. No conversational text.
+
+```json
+{
+  "backlog": [
+    {
+      "type": "Phase",
+      "id": "P[#]",
+      "title": "Phase Title",
+      "status": "Planned | Researching | Ready | Implementing | Complete | Failed",
+      "description": "High level goal.",
+      "milestones": [
+        {
+          "type": "Milestone",
+          "id": "P[#].M[#]",
+          "title": "Milestone Title",
+          "status": "Planned",
+          "description": "Key objective.",
+          "tasks": [
+            {
+              "type": "Task",
+              "id": "P[#].M[#].T[#]",
+              "title": "Task Title",
+              "status": "Planned",
+              "description": "Feature definition.",
+              "subtasks": [
+                {
+                  "type": "Subtask",
+                  "id": "P[#].M[#].T[#].S[#]",
+                  "title": "Subtask Title",
+                  "status": "Planned",
+                  "story_points": 1,
+                  "dependencies": ["ID of prerequisite subtask"],
+                  "context_scope": "CONTRACT DEFINITION:\n1. INPUT: [Specific data structure/variable] from [Dependency ID].\n2. LOGIC: Implement [PRD Section X] logic. Mock [Service Y] for isolation.\n3. OUTPUT: Return [Result Object/Interface] for consumption by [Next Subtask ID]."
+                }
+              ]
+            }
+          ]
+        }
+      ]
+    }
+  ]
+}
+```
+

package/.claude/system_prompts/task-breakdown.md

@@ -98,3 +98,4 @@ For every Subtask, the `context_scope` must be a **strict set of instructions**
     }
   ]
 }
+```

package/CHANGELOG.md

@@ -0,0 +1,188 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.0.3] - 2026-01-12
+
+### Fixed
+
+- **WorkflowLogger.child() signature** (Critical): Updated to accept `Partial<LogEntry>` parameter matching PRD specification, while maintaining backward compatibility with string-based API via function overloads.
+  - Implementation: [src/core/logger.ts:98-111](src/core/logger.ts#L98-L111)
+- **Promise.allSettled for concurrent tasks** (Major): Replaced `Promise.all()` with `Promise.allSettled()` for comprehensive error collection when multiple concurrent workflows fail, enabling aggregate error reporting.
+  - Implementation: [src/decorators/task.ts:112-142](src/decorators/task.ts#L112-L142)
+- **ErrorMergeStrategy implementation** (Major): Added error merge strategy for concurrent task failures with configurable custom combinators, enabling aggregation of all concurrent errors into a single WorkflowError.
+  - Implementation: [src/types/decorators.ts:25-32](src/types/decorators.ts#L25-L32), [src/utils/workflow-error-utils.ts:23-56](src/utils/workflow-error-utils.ts#L23-L56)
+- **Console.error to logger replacement** (Minor): Replaced `console.error()` with workflow logger for observer error handling, ensuring consistent structured logging throughout the codebase.
+  - Implementation: [src/core/workflow.ts:426, 444](src/core/workflow.ts#L426)
+- **Tree debugger optimization** (Minor): Implemented incremental node map updates for childDetached events using BFS traversal, avoiding O(n) full map rebuilds and improving performance on large workflow trees.
+  - Implementation: [src/debugger/tree-debugger.ts:65-84, 92-117](src/debugger/tree-debugger.ts#L65-L84)
+- **Workflow name validation** (Minor): Added validation for empty, whitespace-only, and overly long (>100 chars) workflow names to prevent invalid configurations.
+  - Implementation: [src/core/workflow.ts:98-107](src/core/workflow.ts#L98-L107)
+- **trackTiming default documentation** (Major): Clarified documentation that `trackTiming` in `@Step` decorator defaults to `true` via `!== false` check, improving API discoverability.
+  - Implementation: [src/decorators/step.ts:94-101](src/decorators/step.ts#L94-L101)
+- **isDescendantOf public API** (Minor): Made previously private `isDescendantOf()` helper method public with comprehensive JSDoc documentation, enabling workflow hierarchy validation and topology checking.
+  - Implementation: [src/core/workflow.ts:201-219](src/core/workflow.ts#L201-L219)
+
+### Added
+
+- **Public isDescendantOf() method**: Made the previously private `isDescendantOf()` helper method public for workflow hierarchy validation, circular reference prevention, and topology checking.
+  - Implementation: [src/core/workflow.ts:201-219](src/core/workflow.ts#L201-L219)
+
+### Test Coverage
+
+**New Test Files Added** (12 files):
+- `src/__tests__/unit/logger.test.ts` - WorkflowLogger.child() signature tests (294 lines)
+- `src/__tests__/adversarial/concurrent-task-failures.test.ts` - Concurrent task failure scenarios
+- `src/__tests__/adversarial/error-merge-strategy.test.ts` - Error merge strategy functionality
+- `src/__tests__/unit/tree-debugger-incremental.test.ts` - Incremental node map updates
+- `src/__tests__/adversarial/node-map-update-benchmarks.test.ts` - Performance benchmarks
+- `src/__tests__/integration/observer-logging.test.ts` - Observer logging tests
+- `src/__tests__/unit/workflow.test.ts` - Workflow name validation
+- `src/__tests__/unit/workflow-isDescendantOf.test.ts` - Public isDescendantOf API
+- `src/__tests__/adversarial/parent-validation.test.ts` - Parent validation edge cases
+- `src/__tests__/adversarial/circular-reference.test.ts` - Circular reference detection
+- `src/__tests__/adversarial/complex-circular-reference.test.ts` - Deep circular reference scenarios
+- `src/__tests__/integration/workflow-reparenting.test.ts` - Reparenting workflow tests
+
+**Test Count Increase**: +50+ new test cases
+**Regression Tests**: All existing tests continue to pass (100% pass rate maintained)
+
+### Implementation Details
+
+- **WorkflowLogger.child() signature fix**: [src/core/logger.ts:98-111](src/core/logger.ts#L98-L111)
+  - Function overloads for type safety with both string and Partial<LogEntry> parameters
+  - Backward compatible with existing string-based API
+  - Follows PRD specification exactly
+- **Promise.allSettled for concurrent tasks**: [src/decorators/task.ts:112-142](src/decorators/task.ts#L112-L142)
+  - Captures all concurrent errors using Promise.allSettled()
+  - Optional error merge strategy for aggregate error reporting
+  - Backward compatible: throws first error by default
+- **ErrorMergeStrategy implementation**: [src/types/decorators.ts:25-32](src/types/decorators.ts#L25-L32), [src/utils/workflow-error-utils.ts:23-56](src/utils/workflow-error-utils.ts#L23-L56)
+  - New TaskOptions.errorMergeStrategy property
+  - Default merger aggregates all error messages, logs, and workflow IDs
+  - Custom combine function support for specialized error handling
+- **Console.error to logger replacement**: [src/core/workflow.ts:426, 444](src/core/workflow.ts#L426)
+  - Observer onEvent errors now logged with structured context
+  - Observer onStateUpdated errors now logged with node context
+- **Tree debugger optimization**: [src/debugger/tree-debugger.ts:65-84, 92-117](src/debugger/tree-debugger.ts#L65-L84)
+  - Incremental subtree removal using BFS traversal
+  - O(k) complexity for subtree operations instead of O(n)
+  - Prevents stack overflow on deep trees with iterative BFS
+- **Workflow name validation**: [src/core/workflow.ts:98-107](src/core/workflow.ts#L98-L107)
+  - Rejects empty and whitespace-only names
+  - Rejects names exceeding 100 characters
+  - Fail-fast validation during construction
+- **trackTiming default documentation**: [src/decorators/step.ts:94-101](src/decorators/step.ts#L94-L101)
+  - Clarified that trackTiming defaults to true via !== false check
+  - Explicit false disables timing, undefined/true enables timing
+- **isDescendantOf public API**: [src/core/workflow.ts:201-219](src/core/workflow.ts#L201-L219)
+  - Cycle detection during parent chain traversal
+  - Comprehensive JSDoc with security warning and usage examples
+  - Time/space complexity documentation
+
+## [0.0.2] - 2026-01-12
+
+### Fixed
+
+- **attachChild() parent validation**: `attachChild()` now throws an Error if you attempt to attach a child that already has a different parent. Previously, this would silently create an inconsistent tree state where the child appeared in multiple parents' `children` arrays while only linking to one parent via its `parent` property.
+- **Circular reference detection**: `attachChild()` now detects and prevents attaching an ancestor as a child, which would create a circular reference in the tree.
+- **Observer event propagation**: Observer events now propagate correctly after reparenting operations. Previously, events from a shared child would only reach the original parent's observers, not any new parents.
+
+### Added
+
+- **New `detachChild()` method**: Enables proper reparenting workflow by removing a child from both the workflow tree (`this.children`) and the node tree (`this.node.children`), clearing the child's parent reference, and emitting a `childDetached` event.
+  - Implementation: [src/core/workflow.ts:329-358](src/core/workflow.ts#L329-L358)
+- **New `childDetached` event type**: Discriminated union member for detachment notifications, following the existing event pattern with `type`, `parentId`, and `childId` properties.
+  - Implementation: [src/types/events.ts:11](src/types/events.ts#L11)
+- **New `isDescendantOf()` helper**: Private method for circular reference detection that traverses the parent chain upward with cycle detection.
+  - Implementation: [src/core/workflow.ts:151-169](src/core/workflow.ts#L151-L169)
+
+### Migration Guide for attachChild() Behavior Change
+
+**What Changed**:
+The `attachChild()` method now throws an Error if you attempt to attach a child that already has a different parent. Previously, this would silently create an inconsistent tree state that broke observer propagation and violated the PRD's single-parent requirement.
+
+**Before (Buggy Pattern)**:
+```typescript
+// This would silently create inconsistent state
+const parent1 = new Workflow({ name: 'parent1' });
+const parent2 = new Workflow({ name: 'parent2' });
+const child = new Workflow({ name: 'child' });
+
+parent1.attachChild(child);  // child.parent = parent1
+parent2.attachChild(child);  // BUG: child still has parent1, but parent2 thinks it's attached
+// Result: child.parent === parent1, but parent2.children.includes(child) === true
+```
+
+**After (Correct Pattern)**:
+```typescript
+// Use detachChild() before reattaching
+const parent1 = new Workflow({ name: 'parent1' });
+const parent2 = new Workflow({ name: 'parent2' });
+const child = new Workflow({ name: 'child' });
+
+parent1.attachChild(child);
+parent1.detachChild(child);  // Explicitly detach first
+parent2.attachChild(child);  // Now works correctly
+// Result: child.parent === parent2, parent1.children does NOT include child
+```
+
+**Migration Steps**:
+1. Search your code for patterns of attaching the same child to multiple parents
+2. Add `detachChild()` calls before reattaching to a new parent
+3. Test that your workflow tree operations complete without errors
+4. Verify observer events propagate correctly after reparenting
+
+### Test Coverage
+
+**New Test Files Added** (12 files):
+- `src/__tests__/unit/workflow-detachChild.test.ts` - `detachChild()` method tests
+- `src/__tests__/unit/workflow-emitEvent-childDetached.test.ts` - `childDetached` event tests
+- `src/__tests__/adversarial/parent-validation.test.ts` - Parent validation edge cases
+- `src/__tests__/adversarial/circular-reference.test.ts` - Circular reference detection
+- `src/__tests__/adversarial/complex-circular-reference.test.ts` - Deep circular reference scenarios
+- `src/__tests__/adversarial/attachChild-performance.test.ts` - Performance validation
+- `src/__tests__/adversarial/deep-hierarchy-stress.test.ts` - Deep nesting tests (1000+ levels)
+- `src/__tests__/adversarial/bidirectional-consistency.test.ts` - Tree consistency tests
+- `src/__tests__/adversarial/edge-case.test.ts` - Edge case coverage
+- `src/__tests__/adversarial/observer-propagation.test.ts` - Observer propagation validation
+- `src/__tests__/adversarial/deep-analysis.test.ts` - Comprehensive deep tree analysis
+- `src/__tests__/integration/workflow-reparenting.test.ts` - Reparenting workflow tests
+
+**Test Count Increase**: +25 new test cases
+**Regression Tests**: All existing tests continue to pass (100% pass rate maintained)
+
+### Implementation Details
+
+- **attachChild() validation**: [src/core/workflow.ts:266-305](src/core/workflow.ts#L266-L305)
+  - Validates child is not already attached to this workflow
+  - Validates child does not have a different parent (throws with helpful error message)
+  - Validates child is not an ancestor of this parent (circular reference detection)
+- **detachChild() method**: [src/core/workflow.ts:329-358](src/core/workflow.ts#L329-L358)
+  - Removes child from both workflow and node trees
+  - Clears child's parent reference
+  - Emits childDetached event for observer notification
+- **isDescendantOf() helper**: [src/core/workflow.ts:151-169](src/core/workflow.ts#L151-L169)
+  - Private helper method for circular reference detection
+  - Traverses parent chain with Set-based cycle detection
+- **childDetached event**: [src/types/events.ts:11](src/types/events.ts#L11)
+  - Follows existing discriminated union pattern
+  - Uses `childId` (string) instead of `child` (WorkflowNode) since child is no longer in tree
+
+## [0.0.1] - 2025-01-10
+
+### Added
+- Initial release with hierarchical workflow engine
+- `Workflow` base class with parent/child relationships
+- Observer pattern for event propagation
+- `WorkflowTreeDebugger` for real-time tree visualization
+- `@Step`, `@Task`, and `@ObservedState` decorators
+- Full TypeScript type definitions
+
+[Unreleased]: https://github.com/dustin/groundswell/compare/v0.0.3...HEAD
+[0.0.3]: https://github.com/dustin/groundswell/compare/v0.0.2...v0.0.3
+[0.0.2]: https://github.com/dustin/groundswell/compare/v0.0.1...v0.0.2
+[0.0.1]: https://github.com/dustin/groundswell/releases/tag/v0.0.1