groundswell 0.0.2 → 1.0.0

package/plan/001_d3bb02af4886/docs/TEST_RESULTS.md

@@ -1,230 +0,0 @@
-# Bug Fix Requirements
-
-## Overview
-
-This document reports findings from comprehensive end-to-end testing of the hierarchical workflow engine implementation against the PRD specifications. The testing methodology included:
-
-- **240 existing unit tests** - All passing
-- **Creative end-to-end testing** - PRD example workflows and edge cases
-- **Adversarial testing** - Unexpected inputs, boundary conditions, and stress scenarios
-- **PRD compliance verification** - Validation against all PRD requirements
-
-**Overall Assessment**: The implementation is robust and well-tested. One critical bug was discovered that could lead to inconsistent tree state under certain conditions.
-
----
-
-## Critical Issues (Must Fix)
-
-### Issue 1: `attachChild()` Allows Creating Inconsistent Tree State
-
-**Severity**: Critical
-**PRD Reference**: Section 12.2 - Workflow Base Class, `attachChild` method
-**Location**: `src/core/workflow.ts:187-201`
-
-#### Expected Behavior
-
-The workflow tree should maintain consistency:
-- A child workflow should have exactly one parent
-- The `child.parent` property should always match the parent that contains it
-- A child should only appear in one parent's `children` array
-
-#### Actual Behavior
-
-The `attachChild()` method does not validate if the child workflow already has a parent. This allows:
-
-1. A child to be added to multiple parents' `children` arrays
-2. The `child.parent` property to point to only the original parent
-3. Inconsistent tree state that breaks observer propagation and tree debugging
-
-#### Steps to Reproduce
-
-```typescript
-import { Workflow } from './src/index.js';
-
-const parent1 = new Workflow('Parent1');
-const parent2 = new Workflow('Parent2');
-
-// Create child with parent1 - child is automatically attached
-const child = new Workflow('Child', parent1);
-
-// BUG: attachChild doesn't check if child already has a parent
-parent2.attachChild(child);
-
-// Result: INCONSISTENT STATE
-// - child.parent === parent1 (original parent)
-// - parent1.children.includes(child) === true
-// - parent2.children.includes(child) === true
-// - Child appears in TWO trees but only links to one
-```
-
-#### Impact
-
-1. **Observer Event Propagation**: Events from the shared child only propagate to the original parent's observers, not all parents that contain the child.
-
-2. **Tree Debugger Output**: The tree debugger shows the child in both trees, but navigation via parent/child links is inconsistent.
-
-3. **getRoot() Behavior**: The `getRoot()` method only follows the `child.parent` chain, so it will always return the original parent even though the child is in multiple trees.
-
-4. **Data Integrity**: The "1:1 tree mirror" requirement from the PRD is violated - the in-memory tree structure becomes inconsistent.
-
-#### Suggested Fix
-
-Update the `attachChild()` method in `src/core/workflow.ts` to validate the child's parent state:
-
-```typescript
-public attachChild(child: Workflow): void {
-  // Check if already attached to THIS workflow
-  if (this.children.includes(child)) {
-    throw new Error('Child already attached to this workflow');
-  }
-
-  // NEW: Check if child already has a different parent
-  if (child.parent && child.parent !== this) {
-    throw new Error(
-      `Child '${child.node.name}' already has a parent '${child.parent.node.name}'. ` +
-      `A workflow can only have one parent.`
-    );
-  }
-
-  // NEW: Update child's parent if it's currently null
-  if (!child.parent) {
-    child.parent = this;
-  }
-
-  this.children.push(child);
-  this.node.children.push(child.node);
-
-  this.emitEvent({
-    type: 'childAttached',
-    parentId: this.id,
-    child: child.node,
-  });
-}
-```
-
-**Note**: The fix should also consider whether to update `child.node.parent` similarly for consistency with the node tree structure.
-
-#### Test Coverage
-
-Add the following test to `src/__tests__/adversarial/edge-case.test.ts`:
-
-```typescript
-it('should prevent attaching a child that already has a different parent', async () => {
-  class ChildWorkflow extends Workflow {
-    async run() {
-      return 'child';
-    }
-  }
-
-  class ParentWorkflow extends Workflow {
-    async run() {
-      return 'parent';
-    }
-  }
-
-  const parent1 = new ParentWorkflow('Parent1');
-  const parent2 = new ParentWorkflow('Parent2');
-
-  // Create child with parent1
-  const child = new ChildWorkflow('Child', parent1);
-
-  // Should throw because child already has parent1 as parent
-  expect(() => {
-    parent2.attachChild(child);
-  }).toThrow(/already has a parent/);
-});
-```
-
----
-
-## Major Issues (Should Fix)
-
-*None discovered*
-
----
-
-## Minor Issues (Nice to Fix)
-
-### Issue 1: Manual Parent Property Mutation Not Validated
-
-**Severity**: Minor
-**PRD Reference**: Implicit - data integrity expectation
-
-#### Description
-
-The `parent` property on `Workflow` is public and can be manually mutated to create inconsistent tree state. While this requires intentional misuse (not normal API usage), making it private or adding validation could improve robustness.
-
-#### Suggested Fix
-
-Consider making `parent` private with a getter, or add validation in setter to ensure consistency with `children` arrays.
-
----
-
-## Testing Summary
-
-### Total Tests Performed
-- **Existing test suite**: 240 tests (all passing)
-- **Custom e2e tests**: 20+ additional scenarios
-- **Adversarial scenarios**: 15+ edge cases
-- **PRD compliance checks**: 7+ verification tests
-
-### Passing
-- All 240 existing tests pass
-- All custom end-to-end tests pass
-- All PRD compliance checks pass
-
-### Failing
-- **1 critical bug**: `attachChild()` allows inconsistent tree state
-
-### Areas with Good Coverage
-- ✅ PRD Section 3: Core data model (WorkflowNode, WorkflowStatus)
-- ✅ PRD Section 4: Logging and events model
-- ✅ PRD Section 5: Error model with state snapshots
-- ✅ PRD Section 6: Snapshot system with @ObservedState
-- ✅ PRD Section 7: Observer pattern and event propagation
-- ✅ PRD Section 8: Decorators (@Step, @Task, @ObservedState)
-- ✅ PRD Section 11: Tree debugger API
-- ✅ PRD Section 12: Base class implementation
-- ✅ Edge cases: Unicode, empty values, deep hierarchies, concurrent execution
-- ✅ Adversarial scenarios: Circular references, observer errors, state transitions
-
-### Areas Needing More Attention
-- ⚠️ **Tree integrity validation**: The `attachChild()` method needs parent validation (see Critical Issue 1)
-- ℹ️ **Functional workflows**: Good coverage but could test more complex functional workflow scenarios
-- ℹ️ **Concurrent task error handling**: Current implementation throws on first error; could document this behavior more clearly
-
----
-
-## Additional Notes
-
-### Positive Findings
-
-1. **Strong Type Safety**: TypeScript types are comprehensive and align well with the PRD
-2. **Robust Error Handling**: @Step decorator properly wraps errors with full context
-3. **Good Observer Pattern**: Observers receive events correctly and errors in observers don't crash the system
-4. **Complete PRD Compliance**: Aside from the identified bug, all PRD requirements are met
-5. **Excellent Test Coverage**: 240 tests covering unit, integration, and adversarial scenarios
-
-### PRD Requirements Fully Satisfied
-
-- ✅ Hierarchical workflows with parent/child relationships
-- ✅ All 5 workflow status values supported
-- ✅ Complete Logging with 4 log levels
-- ✅ All 7 WorkflowEvent types properly emitted
-- ✅ WorkflowError includes all required fields (message, original, workflowId, stack, state, logs)
-- ✅ @Step decorator with all options (name, snapshotState, trackTiming, logStart, logFinish)
-- ✅ @Task decorator with concurrent execution support
-- ✅ @ObservedState with redact and hidden options
-- ✅ WorkflowTreeDebugger implements all required methods (getTree, getNode, events, toTreeString, toLogString)
-- ✅ Perfect 1:1 tree mirror in logs and events
-- ✅ Root-only observer restriction enforced
-- ✅ State snapshot captured AFTER step completion
-- ✅ Circular reference detection in getRoot() (works for direct cycles)
-
----
-
-## Conclusion
-
-The hierarchical workflow engine implementation is of high quality and nearly fully compliant with the PRD. The critical bug in `attachChild()` should be fixed before production use, as it can lead to subtle data integrity issues that are difficult to debug.
-
-Once the `attachChild()` validation is added, the implementation will be production-ready for the use cases described in the PRD.

package/plan/001_d3bb02af4886/docs/architecture/external_deps.md

@@ -1,358 +0,0 @@
-# External Dependencies - Research Findings
-
-## Document Purpose
-This document records verified external dependencies, SDK patterns, and integration requirements for the Agent/Prompt layer implementation.
-
----
-
-## 1. Anthropic SDK (@anthropic-ai/sdk)
-
-### Package Information
-- **NPM Package**: `@anthropic-ai/sdk`
-- **Verified Version**: `0.71.1` (already in node_modules)
-- **Node.js Requirement**: 18+
-- **Module Type**: ESM compatible
-
-### Key Interfaces for Integration
-
-```typescript
-// Core types to import from SDK
-import Anthropic from '@anthropic-ai/sdk';
-
-// Message types
-interface MessageCreateParams {
-  model: string;
-  max_tokens: number;
-  messages: MessageParam[];
-  system?: string;
-  tools?: Tool[];
-  temperature?: number;
-  stop_sequences?: string[];
-}
-
-interface MessageParam {
-  role: 'user' | 'assistant';
-  content: ContentBlock[] | string;
-}
-
-// Tool definition
-interface Tool {
-  name: string;
-  description: string;
-  input_schema: {
-    type: 'object';
-    properties: Record<string, unknown>;
-    required?: string[];
-  };
-}
-
-// Response types
-interface Message {
-  id: string;
-  type: 'message';
-  role: 'assistant';
-  content: ContentBlock[];
-  model: string;
-  stop_reason: 'end_turn' | 'max_tokens' | 'stop_sequence' | 'tool_use';
-  stop_sequence: string | null;
-  usage: Usage;
-}
-
-interface Usage {
-  input_tokens: number;
-  output_tokens: number;
-}
-
-// Content blocks
-type ContentBlock = TextBlock | ToolUseBlock;
-
-interface TextBlock {
-  type: 'text';
-  text: string;
-}
-
-interface ToolUseBlock {
-  type: 'tool_use';
-  id: string;
-  name: string;
-  input: Record<string, unknown>;
-}
-```
-
-### Streaming Support
-```typescript
-// Streaming iteration
-const stream = await anthropic.messages.stream({
-  model: 'claude-sonnet-4-20250514',
-  max_tokens: 1024,
-  messages: [{ role: 'user', content: 'Hello' }],
-});
-
-for await (const event of stream) {
-  // event types: message_start, content_block_start, content_block_delta,
-  // content_block_stop, message_delta, message_stop
-}
-```
-
-### Tool Use Pattern
-```typescript
-// Define tools
-const tools: Tool[] = [{
-  name: 'get_weather',
-  description: 'Get the weather for a location',
-  input_schema: {
-    type: 'object',
-    properties: {
-      location: { type: 'string', description: 'City name' }
-    },
-    required: ['location']
-  }
-}];
-
-// Send message with tools
-const response = await anthropic.messages.create({
-  model: 'claude-sonnet-4-20250514',
-  max_tokens: 1024,
-  tools,
-  messages: [{ role: 'user', content: 'What is the weather in SF?' }]
-});
-
-// Handle tool_use response
-if (response.stop_reason === 'tool_use') {
-  const toolUse = response.content.find(b => b.type === 'tool_use');
-  // Execute tool, send result back
-}
-```
-
-### Environment Variables
-```bash
-ANTHROPIC_API_KEY=sk-ant-...  # Required
-ANTHROPIC_BASE_URL=...         # Optional, for proxies
-```
-
----
-
-## 2. Zod Schema Validation
-
-### Package Information
-- **NPM Package**: `zod`
-- **Recommended Version**: `^3.23.0` (v3 stable)
-- **In node_modules**: `4.1.13` (v4 beta - consider downgrade for stability)
-
-### Key Patterns for Prompt Response Validation
-
-```typescript
-import { z } from 'zod';
-
-// Define response schema
-const ReviewResponseSchema = z.object({
-  approved: z.boolean(),
-  comments: z.array(z.object({
-    file: z.string(),
-    line: z.number(),
-    message: z.string(),
-    severity: z.enum(['error', 'warning', 'info']),
-  })),
-  summary: z.string(),
-});
-
-type ReviewResponse = z.infer<typeof ReviewResponseSchema>;
-
-// In Prompt class
-class Prompt<T> {
-  constructor(config: PromptConfig<T>) {
-    this.responseFormat = config.responseFormat; // ZodSchema<T>
-  }
-
-  // Validation method
-  validateResponse(data: unknown): T {
-    return this.responseFormat.parse(data);
-  }
-}
-```
-
-### Schema to JSON Schema (for cache key hashing)
-```typescript
-import { z } from 'zod';
-
-// Get deterministic representation for hashing
-function schemaToHashable(schema: z.ZodType): string {
-  // Zod doesn't have built-in JSON schema export
-  // Use schema._def for internal representation
-  return JSON.stringify(schema._def);
-}
-```
-
----
-
-## 3. Node.js Crypto API (SHA-256 Cache Keys)
-
-### Available in Node 18+
-```typescript
-import { createHash } from 'crypto';
-
-function generateCacheKey(inputs: CacheKeyInputs): string {
-  const hash = createHash('sha256');
-
-  // Deterministic JSON encoding
-  const canonical = JSON.stringify({
-    user: inputs.user,
-    data: inputs.data,
-    system: inputs.system,
-    model: inputs.model,
-    temperature: inputs.temperature,
-    tools: inputs.tools?.map(t => t.name).sort(),
-    mcps: inputs.mcps?.map(m => m.name).sort(),
-    skills: inputs.skills?.map(s => s.name).sort(),
-    schemaHash: inputs.schemaHash,
-  }, Object.keys(inputs).sort());
-
-  hash.update(canonical);
-  return hash.digest('hex');
-}
-```
-
----
-
-## 4. MCP (Model Context Protocol) Integration
-
-### SDK MCP Server Pattern
-From research, MCP servers can be:
-1. **In-process**: Faster, no subprocess overhead
-2. **External (stdio)**: Separate process
-
-### In-Process MCP Server (Recommended)
-```typescript
-// Pattern from Anthropic docs
-import { createSdkMcpServer, tool } from '@anthropic-ai/claude-agent-sdk';
-
-const server = createSdkMcpServer({
-  name: 'my-tools',
-  version: '1.0.0',
-  tools: [
-    tool('get_data', 'Fetch data', { id: z.string() }, async (args) => {
-      return { content: [{ type: 'text', text: '...' }] };
-    })
-  ]
-});
-```
-
-### MCPServer Interface for Groundswell
-```typescript
-interface MCPServer {
-  name: string;
-  version?: string;
-  transport: 'stdio' | 'inprocess';
-  command?: string;        // For stdio
-  args?: string[];         // For stdio
-  tools?: Tool[];          // For inprocess
-}
-```
-
----
-
-## 5. Hooks (Anthropic SDK)
-
-### Hook Types Available
-```typescript
-// From SDK
-type HookType = 'PreToolUse' | 'PostToolUse' | 'SessionStart' | 'SessionEnd';
-
-interface AgentHooks {
-  PreToolUse?: HookHandler[];
-  PostToolUse?: HookHandler[];
-  SessionStart?: HookHandler[];
-  SessionEnd?: HookHandler[];
-}
-
-type HookHandler = (
-  input: HookInput,
-  toolUseId: string,
-  context: HookContext
-) => Promise<HookOutput>;
-```
-
-### Pass-Through Strategy
-Hooks MUST be passed through unchanged to Anthropic SDK. Groundswell does NOT add custom hook types.
-
----
-
-## 6. Skills Integration
-
-### Skill Structure
-```
-.claude/skills/
-└── my-skill/
-    ├── SKILL.md (required)
-    ├── /scripts (optional)
-    └── /references (optional)
-```
-
-### Skills in AgentConfig
-```typescript
-interface Skill {
-  name: string;
-  path: string;  // Path to skill directory
-}
-
-interface AgentConfig {
-  skills?: Skill[];
-}
-```
-
----
-
-## 7. Verified Compatibility Matrix
-
-| Dependency | Version | Node.js | ESM | Status |
-|------------|---------|---------|-----|--------|
-| @anthropic-ai/sdk | 0.71.1 | 18+ | Yes | In node_modules |
-| zod | 3.23.x | 16+ | Yes | Install needed |
-| typescript | 5.2+ | 18+ | Yes | In devDependencies |
-| vitest | 1.0+ | 18+ | Yes | In devDependencies |
-
----
-
-## 8. API Endpoint Reference
-
-### Anthropic Messages API
-```
-POST https://api.anthropic.com/v1/messages
-Headers:
-  x-api-key: $ANTHROPIC_API_KEY
-  anthropic-version: 2023-06-01
-  content-type: application/json
-```
-
-### Models Available
-- `claude-sonnet-4-20250514` (recommended)
-- `claude-3-5-sonnet-20241022`
-- `claude-3-5-haiku-20241022`
-- `claude-3-opus-20240229`
-
----
-
-## 9. Breaking Changes & Deprecations
-
-### SDK Migration (v0.1.0)
-- Package renamed: `@anthropic-ai/claude-code` -> `@anthropic-ai/claude-agent-sdk`
-- Class renamed: `ClaudeCodeOptions` -> `ClaudeAgentOptions`
-- These changes apply to the AGENT SDK, not the base SDK we're using
-
-### Zod v4 Breaking Changes
-- v4 is in beta; recommend using v3.x for production
-- Schema internals changed; cache key hashing needs testing
-
----
-
-## 10. Integration Checklist
-
-- [ ] Add `@anthropic-ai/sdk` to package.json dependencies
-- [ ] Add `zod@^3.23.0` to package.json dependencies
-- [ ] Verify ANTHROPIC_API_KEY environment variable handling
-- [ ] Test streaming iteration pattern
-- [ ] Test tool use response handling
-- [ ] Implement cache key SHA-256 generation
-- [ ] Test Zod schema validation
-- [ ] Create MCP server wrapper (if needed)
-- [ ] Pass through hooks unchanged