@tea-agent/loop-agent 0.25.5 → 0.26.0

package/skills/systematic-debugging/condition-based-waiting.md

@@ -1,115 +1,115 @@
-# Condition-Based Waiting
-
-## Overview
-
-Flaky tests 常用 arbitrary delays 猜 timing。这制造 race conditions：fast machines 上 pass，load 或 CI 下 fail。
-
-**Core principle：** Wait for 你真正关心的 actual condition，不是猜需要多久。
-
-## 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 有 arbitrary delays（`setTimeout`、`sleep`、`time.sleep()`）
-- Tests flaky（有时 pass，load 下 fail）
-- Parallel 运行时 timeout
-- 等待 async operations 完成
-
-**Don't use when：**
-- 测试 actual timing behavior（debounce、throttle intervals）
-- 若用 arbitrary timeout，ALWAYS document WHY
-
-## 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
-  }
-}
-```
-
-完整实现及 domain-specific helpers（`waitForEvent`、`waitForEventCount`、`waitForEventMatch`）见本目录 `condition-based-waiting-example.ts`，来自 actual debugging session。
-
-## Common Mistakes
-
-**❌ Polling too fast:** `setTimeout(check, 1)` — wastes CPU
-**✅ Fix:** Poll every 10ms
-
-**❌ No timeout:** 条件永不满足则 loop forever
-**✅ Fix:** Always include timeout with clear error
-
-**❌ Stale data:** Loop 前 cache state
-**✅ Fix:** Loop 内 call getter 取 fresh data
-
-## When Arbitrary Timeout IS Correct
-
-```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:**
-1. First wait for triggering condition
-2. Based on known timing（not guessing）
-3. Comment explaining WHY
-
-## Real-World Impact
-
-来自 debugging session (2025-10-03)：
-- 修复 3 个文件中 15 个 flaky tests
-- Pass rate：60% → 100%
-- Execution time：40% faster
-- No more race conditions
+# Condition-Based Waiting
+
+## Overview
+
+Flaky tests 常用 arbitrary delays 猜 timing。这制造 race conditions：fast machines 上 pass，load 或 CI 下 fail。
+
+**Core principle：** Wait for 你真正关心的 actual condition，不是猜需要多久。
+
+## 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 有 arbitrary delays（`setTimeout`、`sleep`、`time.sleep()`）
+- Tests flaky（有时 pass，load 下 fail）
+- Parallel 运行时 timeout
+- 等待 async operations 完成
+
+**Don't use when：**
+- 测试 actual timing behavior（debounce、throttle intervals）
+- 若用 arbitrary timeout，ALWAYS document WHY
+
+## 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
+  }
+}
+```
+
+完整实现及 domain-specific helpers（`waitForEvent`、`waitForEventCount`、`waitForEventMatch`）见本目录 `condition-based-waiting-example.ts`，来自 actual debugging session。
+
+## Common Mistakes
+
+**❌ Polling too fast:** `setTimeout(check, 1)` — wastes CPU
+**✅ Fix:** Poll every 10ms
+
+**❌ No timeout:** 条件永不满足则 loop forever
+**✅ Fix:** Always include timeout with clear error
+
+**❌ Stale data:** Loop 前 cache state
+**✅ Fix:** Loop 内 call getter 取 fresh data
+
+## When Arbitrary Timeout IS Correct
+
+```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:**
+1. First wait for triggering condition
+2. Based on known timing（not guessing）
+3. Comment explaining WHY
+
+## Real-World Impact
+
+来自 debugging session (2025-10-03)：
+- 修复 3 个文件中 15 个 flaky tests
+- Pass rate：60% → 100%
+- Execution time：40% faster
+- No more race conditions

package/skills/systematic-debugging/defense-in-depth.md

@@ -1,122 +1,122 @@
-# Defense-in-Depth Validation
-
-## Overview
-
-Bug 由 invalid data 引起时，在一处加 validation 感觉足够。但 single check 可被不同 code paths、refactoring 或 mocks 绕过。
-
-**Core principle：** 在 data 经过的 EVERY layer 验证。使 bug structurally impossible。
-
-## Why Multiple Layers
-
-Single validation："We fixed the bug"
-Multiple layers："We made the bug impossible"
-
-不同 layers 捕获不同 cases：
-- Entry validation 捕获 most bugs
-- Business logic 捕获 edge cases
-- Environment guards 防止 context-specific dangers
-- Debug logging 在其他 layers fail 时帮助 forensics
-
-## The Four Layers
-
-### Layer 1: Entry Point Validation
-**Purpose：** 在 API boundary 拒绝 obviously invalid input
-
-```typescript
-function createProject(name: string, workingDirectory: string) {
-  if (!workingDirectory || workingDirectory.trim() === '') {
-    throw new Error('workingDirectory cannot be empty');
-  }
-  if (!existsSync(workingDirectory)) {
-    throw new Error(`workingDirectory does not exist: ${workingDirectory}`);
-  }
-  if (!statSync(workingDirectory).isDirectory()) {
-    throw new Error(`workingDirectory is not a directory: ${workingDirectory}`);
-  }
-  // ... proceed
-}
-```
-
-### Layer 2: Business Logic Validation
-**Purpose：** 确保 data 对此 operation 有意义
-
-```typescript
-function initializeWorkspace(projectDir: string, sessionId: string) {
-  if (!projectDir) {
-    throw new Error('projectDir required for workspace initialization');
-  }
-  // ... proceed
-}
-```
-
-### Layer 3: Environment Guards
-**Purpose：** 在特定 contexts 阻止 dangerous operations
-
-```typescript
-async function gitInit(directory: string) {
-  // In tests, refuse git init outside temp directories
-  if (process.env.NODE_ENV === 'test') {
-    const normalized = normalize(resolve(directory));
-    const tmpDir = normalize(resolve(tmpdir()));
-
-    if (!normalized.startsWith(tmpDir)) {
-      throw new Error(
-        `Refusing git init outside temp dir during tests: ${directory}`
-      );
-    }
-  }
-  // ... proceed
-}
-```
-
-### Layer 4: Debug Instrumentation
-**Purpose：** 捕获 forensics context
-
-```typescript
-async function gitInit(directory: string) {
-  const stack = new Error().stack;
-  logger.debug('About to git init', {
-    directory,
-    cwd: process.cwd(),
-    stack,
-  });
-  // ... proceed
-}
-```
-
-## Applying the Pattern
-
-找到 bug 时：
-
-1. **Trace the data flow** — Bad value 从哪 originate？在哪使用？
-2. **Map all checkpoints** — 列出 data 经过的 every point
-3. **Add validation at each layer** — Entry、business、environment、debug
-4. **Test each layer** — 尝试 bypass layer 1，verify layer 2 捕获
-
-## Example from Session
-
-Bug：Empty `projectDir` 导致 `git init` 在 source code
-
-**Data flow:**
-1. Test setup → empty string
-2. `Project.create(name, '')`
-3. `WorkspaceManager.createWorkspace('')`
-4. `git init` 在 `process.cwd()` 运行
-
-**Four layers added:**
-- Layer 1: `Project.create()` validates not empty/exists/writable
-- Layer 2: `WorkspaceManager` validates projectDir not empty
-- Layer 3: `WorktreeManager` refuses git init outside tmpdir in tests
-- Layer 4: Stack trace logging before git init
-
-**Result:** All 1847 tests passed，bug impossible to reproduce
-
-## Key Insight
-
-四层都必要。Testing 中每层捕获 others 遗漏的 bugs：
-- 不同 code paths 绕过 entry validation
-- Mocks 绕过 business logic checks
-- 不同 platforms 的 edge cases 需要 environment guards
-- Debug logging 识别 structural misuse
-
-**Don't stop at one validation point.** 在 every layer 加 checks。
+# Defense-in-Depth Validation
+
+## Overview
+
+Bug 由 invalid data 引起时，在一处加 validation 感觉足够。但 single check 可被不同 code paths、refactoring 或 mocks 绕过。
+
+**Core principle：** 在 data 经过的 EVERY layer 验证。使 bug structurally impossible。
+
+## Why Multiple Layers
+
+Single validation："We fixed the bug"
+Multiple layers："We made the bug impossible"
+
+不同 layers 捕获不同 cases：
+- Entry validation 捕获 most bugs
+- Business logic 捕获 edge cases
+- Environment guards 防止 context-specific dangers
+- Debug logging 在其他 layers fail 时帮助 forensics
+
+## The Four Layers
+
+### Layer 1: Entry Point Validation
+**Purpose：** 在 API boundary 拒绝 obviously invalid input
+
+```typescript
+function createProject(name: string, workingDirectory: string) {
+  if (!workingDirectory || workingDirectory.trim() === '') {
+    throw new Error('workingDirectory cannot be empty');
+  }
+  if (!existsSync(workingDirectory)) {
+    throw new Error(`workingDirectory does not exist: ${workingDirectory}`);
+  }
+  if (!statSync(workingDirectory).isDirectory()) {
+    throw new Error(`workingDirectory is not a directory: ${workingDirectory}`);
+  }
+  // ... proceed
+}
+```
+
+### Layer 2: Business Logic Validation
+**Purpose：** 确保 data 对此 operation 有意义
+
+```typescript
+function initializeWorkspace(projectDir: string, sessionId: string) {
+  if (!projectDir) {
+    throw new Error('projectDir required for workspace initialization');
+  }
+  // ... proceed
+}
+```
+
+### Layer 3: Environment Guards
+**Purpose：** 在特定 contexts 阻止 dangerous operations
+
+```typescript
+async function gitInit(directory: string) {
+  // In tests, refuse git init outside temp directories
+  if (process.env.NODE_ENV === 'test') {
+    const normalized = normalize(resolve(directory));
+    const tmpDir = normalize(resolve(tmpdir()));
+
+    if (!normalized.startsWith(tmpDir)) {
+      throw new Error(
+        `Refusing git init outside temp dir during tests: ${directory}`
+      );
+    }
+  }
+  // ... proceed
+}
+```
+
+### Layer 4: Debug Instrumentation
+**Purpose：** 捕获 forensics context
+
+```typescript
+async function gitInit(directory: string) {
+  const stack = new Error().stack;
+  logger.debug('About to git init', {
+    directory,
+    cwd: process.cwd(),
+    stack,
+  });
+  // ... proceed
+}
+```
+
+## Applying the Pattern
+
+找到 bug 时：
+
+1. **Trace the data flow** — Bad value 从哪 originate？在哪使用？
+2. **Map all checkpoints** — 列出 data 经过的 every point
+3. **Add validation at each layer** — Entry、business、environment、debug
+4. **Test each layer** — 尝试 bypass layer 1，verify layer 2 捕获
+
+## Example from Session
+
+Bug：Empty `projectDir` 导致 `git init` 在 source code
+
+**Data flow:**
+1. Test setup → empty string
+2. `Project.create(name, '')`
+3. `WorkspaceManager.createWorkspace('')`
+4. `git init` 在 `process.cwd()` 运行
+
+**Four layers added:**
+- Layer 1: `Project.create()` validates not empty/exists/writable
+- Layer 2: `WorkspaceManager` validates projectDir not empty
+- Layer 3: `WorktreeManager` refuses git init outside tmpdir in tests
+- Layer 4: Stack trace logging before git init
+
+**Result:** All 1847 tests passed，bug impossible to reproduce
+
+## Key Insight
+
+四层都必要。Testing 中每层捕获 others 遗漏的 bugs：
+- 不同 code paths 绕过 entry validation
+- Mocks 绕过 business logic checks
+- 不同 platforms 的 edge cases 需要 environment guards
+- Debug logging 识别 structural misuse
+
+**Don't stop at one validation point.** 在 every layer 加 checks。

package/skills/systematic-debugging/find-polluter.sh

@@ -1,63 +1,63 @@
-#!/usr/bin/env bash
-# Bisection script to find which test creates unwanted files/state
-# Usage: ./find-polluter.sh <file_or_dir_to_check> <test_pattern>
-# Example: ./find-polluter.sh '.git' 'src/**/*.test.ts'
-
-set -e
-
-if [ $# -ne 2 ]; then
-  echo "Usage: $0 <file_to_check> <test_pattern>"
-  echo "Example: $0 '.git' 'src/**/*.test.ts'"
-  exit 1
-fi
-
-POLLUTION_CHECK="$1"
-TEST_PATTERN="$2"
-
-echo "🔍 Searching for test that creates: $POLLUTION_CHECK"
-echo "Test pattern: $TEST_PATTERN"
-echo ""
-
-# Get list of test files
-TEST_FILES=$(find . -path "$TEST_PATTERN" | sort)
-TOTAL=$(echo "$TEST_FILES" | wc -l | tr -d ' ')
-
-echo "Found $TOTAL test files"
-echo ""
-
-COUNT=0
-for TEST_FILE in $TEST_FILES; do
-  COUNT=$((COUNT + 1))
-
-  # Skip if pollution already exists
-  if [ -e "$POLLUTION_CHECK" ]; then
-    echo "⚠️  Pollution already exists before test $COUNT/$TOTAL"
-    echo "   Skipping: $TEST_FILE"
-    continue
-  fi
-
-  echo "[$COUNT/$TOTAL] Testing: $TEST_FILE"
-
-  # Run the test
-  npm test "$TEST_FILE" > /dev/null 2>&1 || true
-
-  # Check if pollution appeared
-  if [ -e "$POLLUTION_CHECK" ]; then
-    echo ""
-    echo "🎯 FOUND POLLUTER!"
-    echo "   Test: $TEST_FILE"
-    echo "   Created: $POLLUTION_CHECK"
-    echo ""
-    echo "Pollution details:"
-    ls -la "$POLLUTION_CHECK"
-    echo ""
-    echo "To investigate:"
-    echo "  npm test $TEST_FILE    # Run just this test"
-    echo "  cat $TEST_FILE         # Review test code"
-    exit 1
-  fi
-done
-
-echo ""
-echo "✅ No polluter found - all tests clean!"
-exit 0
+#!/usr/bin/env bash
+# Bisection script to find which test creates unwanted files/state
+# Usage: ./find-polluter.sh <file_or_dir_to_check> <test_pattern>
+# Example: ./find-polluter.sh '.git' 'src/**/*.test.ts'
+
+set -e
+
+if [ $# -ne 2 ]; then
+  echo "Usage: $0 <file_to_check> <test_pattern>"
+  echo "Example: $0 '.git' 'src/**/*.test.ts'"
+  exit 1
+fi
+
+POLLUTION_CHECK="$1"
+TEST_PATTERN="$2"
+
+echo "🔍 Searching for test that creates: $POLLUTION_CHECK"
+echo "Test pattern: $TEST_PATTERN"
+echo ""
+
+# Get list of test files
+TEST_FILES=$(find . -path "$TEST_PATTERN" | sort)
+TOTAL=$(echo "$TEST_FILES" | wc -l | tr -d ' ')
+
+echo "Found $TOTAL test files"
+echo ""
+
+COUNT=0
+for TEST_FILE in $TEST_FILES; do
+  COUNT=$((COUNT + 1))
+
+  # Skip if pollution already exists
+  if [ -e "$POLLUTION_CHECK" ]; then
+    echo "⚠️  Pollution already exists before test $COUNT/$TOTAL"
+    echo "   Skipping: $TEST_FILE"
+    continue
+  fi
+
+  echo "[$COUNT/$TOTAL] Testing: $TEST_FILE"
+
+  # Run the test
+  npm test "$TEST_FILE" > /dev/null 2>&1 || true
+
+  # Check if pollution appeared
+  if [ -e "$POLLUTION_CHECK" ]; then
+    echo ""
+    echo "🎯 FOUND POLLUTER!"
+    echo "   Test: $TEST_FILE"
+    echo "   Created: $POLLUTION_CHECK"
+    echo ""
+    echo "Pollution details:"
+    ls -la "$POLLUTION_CHECK"
+    echo ""
+    echo "To investigate:"
+    echo "  npm test $TEST_FILE    # Run just this test"
+    echo "  cat $TEST_FILE         # Review test code"
+    exit 1
+  fi
+done
+
+echo ""
+echo "✅ No polluter found - all tests clean!"
+exit 0