claude-mpm 4.25.10__py3-none-any.whl → 5.1.8__py3-none-any.whl

claude_mpm/skills/bundled/testing/condition-based-waiting/SKILL.md

@@ -1,119 +0,0 @@
----
-name: Condition-Based Waiting
-description: Replace arbitrary timeouts with condition polling for reliable async tests
-when_to_use: when tests have race conditions, timing dependencies, or inconsistent pass/fail behavior
-version: 1.1.0
-languages: all
-progressive_disclosure:
-  entry_point:
-    summary: "Replace arbitrary timeouts with condition polling for reliable async tests"
-    when_to_use: "Tests with setTimeout/sleep, flaky tests, or timing-dependent async operations"
-    quick_start: |
-      1. Identify arbitrary delays in tests (setTimeout, sleep, time.sleep())
-      2. Replace with condition-based waiting (waitFor pattern)
-      3. Use domain-specific helpers for common scenarios
-      See @example.ts for complete working implementation
-    core_pattern: |
-      // ❌ Guessing at timing
-      await new Promise(r => setTimeout(r, 50));
-
-      // ✅ Waiting for condition
-      await waitFor(() => getResult() !== undefined);
-  references:
-    - path: references/patterns-and-implementation.md
-      purpose: Detailed waiting patterns, implementation guide, and common mistakes
-      when_to_read: When implementing waitFor or debugging timing issues
----
-
-# Condition-Based Waiting
-
-## Overview
-
-Flaky tests often guess at timing with arbitrary delays. This creates race conditions where tests pass on fast machines but fail under load or in CI.
-
-**Core principle:** Wait for the actual condition you care about, not a guess about how long it takes.
-
-## When to Use
-
-```dot
-digraph when_to_use {
-    "Test uses setTimeout/sleep?" [shape=diamond];
-    "Testing timing behavior?" [shape=diamond];
-    "Document WHY timeout needed" [shape=box];
-    "Use condition-based waiting" [shape=box];
-
-    "Test uses setTimeout/sleep?" -> "Testing timing behavior?" [label="yes"];
-    "Testing timing behavior?" -> "Document WHY timeout needed" [label="yes"];
-    "Testing timing behavior?" -> "Use condition-based waiting" [label="no"];
-}
-```
-
-**Use when:**
-- Tests have arbitrary delays (`setTimeout`, `sleep`, `time.sleep()`)
-- Tests are flaky (pass sometimes, fail under load)
-- Tests timeout when run in parallel
-- Waiting for async operations to complete
-
-**Don't use when:**
-- Testing actual timing behavior (debounce, throttle intervals)
-- Always document WHY if using arbitrary timeout
-
-## Core Pattern
-
-```typescript
-// ❌ BEFORE: Guessing at timing
-await new Promise(r => setTimeout(r, 50));
-const result = getResult();
-expect(result).toBeDefined();
-
-// ✅ AFTER: Waiting for condition
-await waitFor(() => getResult() !== undefined);
-const result = getResult();
-expect(result).toBeDefined();
-```
-
-## Quick Patterns
-
-| Scenario | Pattern |
-|----------|---------|
-| Wait for event | `waitFor(() => events.find(e => e.type === 'DONE'))` |
-| Wait for state | `waitFor(() => machine.state === 'ready')` |
-| Wait for count | `waitFor(() => items.length >= 5)` |
-| Wait for file | `waitFor(() => fs.existsSync(path))` |
-| Complex condition | `waitFor(() => obj.ready && obj.value > 10)` |
-
-## Implementation
-
-Generic polling function:
-```typescript
-async function waitFor<T>(
-  condition: () => T | undefined | null | false,
-  description: string,
-  timeoutMs = 5000
-): Promise<T> {
-  const startTime = Date.now();
-
-  while (true) {
-    const result = condition();
-    if (result) return result;
-
-    if (Date.now() - startTime > timeoutMs) {
-      throw new Error(`Timeout waiting for ${description} after ${timeoutMs}ms`);
-    }
-
-    await new Promise(r => setTimeout(r, 10)); // Poll every 10ms
-  }
-}
-```
-
-See @example.ts for complete implementation with domain-specific helpers (`waitForEvent`, `waitForEventCount`, `waitForEventMatch`).
-
-For detailed patterns, implementation guide, and common mistakes, see @references/patterns-and-implementation.md
-
-## Real-World Impact
-
-From debugging session (2025-10-03):
-- Fixed 15 flaky tests across 3 files
-- Pass rate: 60% → 100%
-- Execution time: 40% faster
-- No more race conditions

claude_mpm/skills/bundled/testing/condition-based-waiting/example.ts

@@ -1,158 +0,0 @@
-// Complete implementation of condition-based waiting utilities
-// From: Lace test infrastructure improvements (2025-10-03)
-// Context: Fixed 15 flaky tests by replacing arbitrary timeouts
-
-import type { ThreadManager } from '~/threads/thread-manager';
-import type { LaceEvent, LaceEventType } from '~/threads/types';
-
-/**
- * Wait for a specific event type to appear in thread
- *
- * @param threadManager - The thread manager to query
- * @param threadId - Thread to check for events
- * @param eventType - Type of event to wait for
- * @param timeoutMs - Maximum time to wait (default 5000ms)
- * @returns Promise resolving to the first matching event
- *
- * Example:
- *   await waitForEvent(threadManager, agentThreadId, 'TOOL_RESULT');
- */
-export function waitForEvent(
-  threadManager: ThreadManager,
-  threadId: string,
-  eventType: LaceEventType,
-  timeoutMs = 5000
-): Promise<LaceEvent> {
-  return new Promise((resolve, reject) => {
-    const startTime = Date.now();
-
-    const check = () => {
-      const events = threadManager.getEvents(threadId);
-      const event = events.find((e) => e.type === eventType);
-
-      if (event) {
-        resolve(event);
-      } else if (Date.now() - startTime > timeoutMs) {
-        reject(new Error(`Timeout waiting for ${eventType} event after ${timeoutMs}ms`));
-      } else {
-        setTimeout(check, 10); // Poll every 10ms for efficiency
-      }
-    };
-
-    check();
-  });
-}
-
-/**
- * Wait for a specific number of events of a given type
- *
- * @param threadManager - The thread manager to query
- * @param threadId - Thread to check for events
- * @param eventType - Type of event to wait for
- * @param count - Number of events to wait for
- * @param timeoutMs - Maximum time to wait (default 5000ms)
- * @returns Promise resolving to all matching events once count is reached
- *
- * Example:
- *   // Wait for 2 AGENT_MESSAGE events (initial response + continuation)
- *   await waitForEventCount(threadManager, agentThreadId, 'AGENT_MESSAGE', 2);
- */
-export function waitForEventCount(
-  threadManager: ThreadManager,
-  threadId: string,
-  eventType: LaceEventType,
-  count: number,
-  timeoutMs = 5000
-): Promise<LaceEvent[]> {
-  return new Promise((resolve, reject) => {
-    const startTime = Date.now();
-
-    const check = () => {
-      const events = threadManager.getEvents(threadId);
-      const matchingEvents = events.filter((e) => e.type === eventType);
-
-      if (matchingEvents.length >= count) {
-        resolve(matchingEvents);
-      } else if (Date.now() - startTime > timeoutMs) {
-        reject(
-          new Error(
-            `Timeout waiting for ${count} ${eventType} events after ${timeoutMs}ms (got ${matchingEvents.length})`
-          )
-        );
-      } else {
-        setTimeout(check, 10);
-      }
-    };
-
-    check();
-  });
-}
-
-/**
- * Wait for an event matching a custom predicate
- * Useful when you need to check event data, not just type
- *
- * @param threadManager - The thread manager to query
- * @param threadId - Thread to check for events
- * @param predicate - Function that returns true when event matches
- * @param description - Human-readable description for error messages
- * @param timeoutMs - Maximum time to wait (default 5000ms)
- * @returns Promise resolving to the first matching event
- *
- * Example:
- *   // Wait for TOOL_RESULT with specific ID
- *   await waitForEventMatch(
- *     threadManager,
- *     agentThreadId,
- *     (e) => e.type === 'TOOL_RESULT' && e.data.id === 'call_123',
- *     'TOOL_RESULT with id=call_123'
- *   );
- */
-export function waitForEventMatch(
-  threadManager: ThreadManager,
-  threadId: string,
-  predicate: (event: LaceEvent) => boolean,
-  description: string,
-  timeoutMs = 5000
-): Promise<LaceEvent> {
-  return new Promise((resolve, reject) => {
-    const startTime = Date.now();
-
-    const check = () => {
-      const events = threadManager.getEvents(threadId);
-      const event = events.find(predicate);
-
-      if (event) {
-        resolve(event);
-      } else if (Date.now() - startTime > timeoutMs) {
-        reject(new Error(`Timeout waiting for ${description} after ${timeoutMs}ms`));
-      } else {
-        setTimeout(check, 10);
-      }
-    };
-
-    check();
-  });
-}
-
-// Usage example from actual debugging session:
-//
-// BEFORE (flaky):
-// ---------------
-// const messagePromise = agent.sendMessage('Execute tools');
-// await new Promise(r => setTimeout(r, 300)); // Hope tools start in 300ms
-// agent.abort();
-// await messagePromise;
-// await new Promise(r => setTimeout(r, 50));  // Hope results arrive in 50ms
-// expect(toolResults.length).toBe(2);         // Fails randomly
-//
-// AFTER (reliable):
-// ----------------
-// const messagePromise = agent.sendMessage('Execute tools');
-// await waitForEventCount(threadManager, threadId, 'TOOL_CALL', 2); // Wait for tools to start
-// agent.abort();
-// await messagePromise;
-// await waitForEventCount(threadManager, threadId, 'TOOL_RESULT', 2); // Wait for results
-// expect(toolResults.length).toBe(2); // Always succeeds
-//
-// Result: 60% pass rate → 100%, 40% faster execution

claude_mpm/skills/bundled/testing/condition-based-waiting/references/patterns-and-implementation.md

@@ -1,253 +0,0 @@
-# Detailed Patterns and Implementation Guide
-
-This reference provides detailed implementation patterns, common mistakes, and edge cases for condition-based waiting.
-
-## Common Mistakes
-
-### ❌ Polling too fast
-```typescript
-// BAD: Wastes CPU
-await new Promise(r => setTimeout(r, 1));
-```
-
-**✅ Fix:** Poll every 10ms
-```typescript
-await new Promise(r => setTimeout(r, 10)); // Balanced interval
-```
-
-### ❌ No timeout
-```typescript
-// BAD: Loop forever if condition never met
-while (true) {
-  const result = condition();
-  if (result) return result;
-  await new Promise(r => setTimeout(r, 10));
-}
-```
-
-**✅ Fix:** Always include timeout with clear error
-```typescript
-const startTime = Date.now();
-while (true) {
-  const result = condition();
-  if (result) return result;
-
-  if (Date.now() - startTime > timeoutMs) {
-    throw new Error(`Timeout waiting for ${description} after ${timeoutMs}ms`);
-  }
-
-  await new Promise(r => setTimeout(r, 10));
-}
-```
-
-### ❌ Stale data
-```typescript
-// BAD: Cache state before loop
-const state = machine.getState();
-await waitFor(() => state === 'ready'); // state never updates!
-```
-
-**✅ Fix:** Call getter inside loop for fresh data
-```typescript
-await waitFor(() => machine.getState() === 'ready'); // Fresh on each poll
-```
-
-## When Arbitrary Timeout IS Correct
-
-There are legitimate cases where a fixed timeout is the right approach:
-
-```typescript
-// Tool ticks every 100ms - need 2 ticks to verify partial output
-await waitForEvent(manager, 'TOOL_STARTED'); // First: wait for condition
-await new Promise(r => setTimeout(r, 200));   // Then: wait for timed behavior
-// 200ms = 2 ticks at 100ms intervals - documented and justified
-```
-
-**Requirements for justified arbitrary timeouts:**
-1. First wait for triggering condition (condition-based wait comes first)
-2. Based on known timing (not guessing - actual system tick rate)
-3. Comment explaining WHY timeout is necessary
-
-## Advanced Patterns
-
-### Waiting with transformation
-```typescript
-// Wait for event and return transformed data
-const userId = await waitFor(
-  () => events.find(e => e.type === 'USER_CREATED')?.data.id,
-  'user creation event'
-);
-```
-
-### Waiting with complex conditions
-```typescript
-// Multiple conditions must be met
-await waitFor(
-  () => {
-    const user = getUser();
-    return user?.verified && user?.credits > 0 ? user : undefined;
-  },
-  'verified user with credits'
-);
-```
-
-### Waiting with side effects
-```typescript
-// Log attempts while waiting
-let attempts = 0;
-await waitFor(
-  () => {
-    attempts++;
-    if (attempts % 10 === 0) {
-      console.log(`Still waiting after ${attempts} attempts...`);
-    }
-    return isReady() || undefined;
-  },
-  'system ready'
-);
-```
-
-### Waiting with custom timeouts per condition
-```typescript
-// Different timeouts for different scenarios
-async function waitForDeploy(environment: string) {
-  const timeout = environment === 'prod' ? 30000 : 5000;
-  return waitFor(
-    () => checkDeployStatus(environment),
-    `${environment} deployment`,
-    timeout
-  );
-}
-```
-
-## Domain-Specific Helpers
-
-When you have common waiting scenarios, create domain-specific helpers:
-
-```typescript
-// Event-based waiting
-async function waitForEvent(
-  manager: EventManager,
-  eventType: string,
-  timeoutMs = 5000
-) {
-  return waitFor(
-    () => manager.getEvents().find(e => e.type === eventType),
-    `event ${eventType}`,
-    timeoutMs
-  );
-}
-
-// Count-based waiting
-async function waitForEventCount(
-  manager: EventManager,
-  minCount: number,
-  timeoutMs = 5000
-) {
-  return waitFor(
-    () => {
-      const events = manager.getEvents();
-      return events.length >= minCount ? events : undefined;
-    },
-    `at least ${minCount} events`,
-    timeoutMs
-  );
-}
-
-// Pattern matching waiting
-async function waitForEventMatch(
-  manager: EventManager,
-  matcher: (event: Event) => boolean,
-  timeoutMs = 5000
-) {
-  return waitFor(
-    () => manager.getEvents().find(matcher),
-    'event matching predicate',
-    timeoutMs
-  );
-}
-```
-
-See @example.ts for complete working implementations from real debugging session.
-
-## Debugging Tips
-
-### Add descriptive error messages
-```typescript
-// GOOD: Clear what failed
-await waitFor(
-  () => orders.find(o => o.status === 'SHIPPED'),
-  'order to be shipped',
-  5000
-);
-// Error: "Timeout waiting for order to be shipped after 5000ms"
-
-// BETTER: Include context
-await waitFor(
-  () => orders.find(o => o.id === orderId && o.status === 'SHIPPED'),
-  `order ${orderId} to be shipped`,
-  5000
-);
-// Error: "Timeout waiting for order abc-123 to be shipped after 5000ms"
-```
-
-### Log current state on timeout
-```typescript
-async function waitForWithDebug<T>(
-  condition: () => T | undefined | null | false,
-  description: string,
-  getCurrentState: () => any,
-  timeoutMs = 5000
-): Promise<T> {
-  const startTime = Date.now();
-
-  while (true) {
-    const result = condition();
-    if (result) return result;
-
-    if (Date.now() - startTime > timeoutMs) {
-      const state = getCurrentState();
-      throw new Error(
-        `Timeout waiting for ${description} after ${timeoutMs}ms. ` +
-        `Current state: ${JSON.stringify(state)}`
-      );
-    }
-
-    await new Promise(r => setTimeout(r, 10));
-  }
-}
-```
-
-## Performance Considerations
-
-### Poll interval trade-offs
-- **1ms**: Too fast, wastes CPU (10,000 checks/second)
-- **10ms**: Good default, responsive (100 checks/second)
-- **50ms**: Acceptable for slow operations (20 checks/second)
-- **100ms+**: Only for very slow operations or known timing
-
-### Choose appropriate timeout values
-```typescript
-// Fast operations - short timeout
-await waitFor(() => cache.get(key), 'cache hit', 1000);
-
-// Network operations - medium timeout
-await waitFor(() => fetchStatus(), 'API response', 5000);
-
-// External systems - long timeout
-await waitFor(() => checkDeployment(), 'deployment complete', 30000);
-```
-
-### Avoid expensive condition checks
-```typescript
-// BAD: Expensive regex on every poll
-await waitFor(() => /complex.*regex.*pattern/.test(getLargeString()), ...);
-
-// GOOD: Cache expensive computations
-let parsed;
-await waitFor(() => {
-  const str = getString();
-  parsed = parsed || expensiveParse(str);
-  return parsed.isReady;
-}, ...);
-```

claude_mpm/skills/bundled/testing/test-driven-development/SKILL.md

@@ -1,145 +0,0 @@
----
-name: test-driven-development
-description: Write the test first, watch it fail, write minimal code to pass
-version: 3.2.0
-category: testing
-author: Jesse Vincent
-license: MIT
-source: https://github.com/obra/superpowers-skills/tree/main/skills/testing/test-driven-development
-progressive_disclosure:
-  entry_point:
-    summary: "Enforce test-first development with strict RED/GREEN/REFACTOR cycle. Never write implementation before failing test."
-    when_to_use: "When implementing any feature or bugfix, before writing implementation code. Always for new features, bug fixes, refactoring, and behavior changes."
-    quick_start: "1. Write failing test 2. Watch it fail (verify) 3. Write minimal code to pass 4. Watch it pass (verify) 5. Refactor if needed 6. Repeat"
-  references:
-    - workflow.md
-    - examples.md
-    - philosophy.md
-    - anti-patterns.md
-    - integration.md
-context_limit: 800
-tags:
-  - tdd
-  - testing
-  - red-green-refactor
-  - test-first
----
-
-# Test-Driven Development (TDD)
-
-## Overview
-
-Write the test first. Watch it fail. Write minimal code to pass.
-
-**Core principle:** If you didn't watch the test fail, you don't know if it tests the right thing.
-
-This skill enforces strict test-first development following the RED/GREEN/REFACTOR cycle. Violating the letter of the rules is violating the spirit of the rules.
-
-## When to Use This Skill
-
-**Always:**
-- New features
-- Bug fixes
-- Refactoring
-- Behavior changes
-
-**Exceptions (ask human partner):**
-- Throwaway prototypes
-- Generated code
-- Configuration files
-
-Thinking "skip TDD just this once"? Stop. That's rationalization.
-
-## The Iron Law
-
-```
-NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST
-```
-
-Write code before the test? Delete it. Start over.
-
-**No exceptions:**
-- Don't keep it as "reference"
-- Don't "adapt" it while writing tests
-- Delete means delete
-
-## Core Principles
-
-1. **RED**: Write a failing test first
-2. **GREEN**: Write minimal code to make test pass
-3. **REFACTOR**: Improve code while keeping tests green
-4. **NEVER**: Write implementation before tests
-
-## Quick Start
-
-### The RED/GREEN/REFACTOR Cycle
-
-```
-RED → Verify RED → GREEN → Verify GREEN → REFACTOR → Repeat
-```
-
-1. **RED**: Write one minimal test showing desired behavior
-2. **Verify RED**: Run test, confirm it fails for right reason
-3. **GREEN**: Write simplest code to pass test
-4. **Verify GREEN**: Run test, confirm it passes
-5. **REFACTOR**: Clean up while keeping tests green
-6. **Repeat**: Next test for next feature
-
-## Cycle Details
-
-**RED**: Write one minimal test (one behavior, clear name, real code)
-**Verify RED**: MANDATORY - watch it fail for right reason
-**GREEN**: Write simplest code to pass (no extras)
-**Verify GREEN**: MANDATORY - watch it pass, all tests pass
-**REFACTOR**: Clean up while keeping tests green (optional)
-
-## Navigation
-
-For detailed information:
-- **[Workflow](references/workflow.md)**: Complete RED/GREEN/REFACTOR workflow with detailed examples
-- **[Examples](references/examples.md)**: Real-world TDD scenarios with step-by-step walkthroughs
-- **[Philosophy](references/philosophy.md)**: Why order matters and why tests-after don't work
-- **[Anti-patterns](references/anti-patterns.md)**: Common mistakes, rationalizations, and red flags
-- **[Integration](references/integration.md)**: Using TDD with debugging and other skills
-
-## Key Reminders
-
-- ALWAYS write the test BEFORE implementation
-- Make each test fail FIRST to verify it's testing something
-- Keep implementation minimal - just enough to pass tests
-- Refactor only when tests are green
-- One cycle at a time - small steps
-- If test passes immediately, it's not testing new behavior
-
-## Red Flags - STOP and Start Over
-
-If you catch yourself:
-- Writing code before test
-- Test passes immediately
-- Can't explain why test failed
-- "I'll test after"
-- "Keep as reference"
-- "Already spent X hours, deleting is wasteful"
-- "Tests after achieve the same purpose"
-
-**ALL of these mean: Delete code. Start over with TDD.**
-
-## Why Order Matters
-
-Tests-after pass immediately (proves nothing), test-first fail then pass (proves it works). See [Philosophy](references/philosophy.md) for detailed explanation.
-
-## Integration with Other Skills
-
-- **systematic-debugging**: Create failing test in Phase 4 (bug reproduction)
-- **verification-before-completion**: Verify tests exist and watched them fail
-- **defense-in-depth**: Add validation tests after implementing feature
-
-## Real-World Impact
-
-From TDD practice:
-- Test-first: 95%+ first-time correctness
-- Test-after: 40% first-time correctness
-- TDD time: 25-45 minutes per feature (including tests)
-- Non-TDD time: 15 minutes coding + 60-120 minutes debugging
-
-**TDD is pragmatic** - finds bugs before commit, prevents regressions, documents behavior, enables refactoring.