cokit-cli 1.0.1 → 1.0.3

package/skills/ck-debugging/references/root-cause-tracing.md

@@ -1,65 +1,122 @@
 # Root Cause Tracing
 
-Technique for finding where bugs originate, not where they manifest.
+Systematically trace bugs backward through call stack to find original trigger.
 
-## Core Concept
+## Core Principle
 
-Bugs often appear deep in execution but originate elsewhere. Trace backward through the call stack to find the original source.
+**Trace backward through call chain until finding original trigger, then fix at source.**
 
-## The Backward Trace
+Bugs often manifest deep in call stack (git init in wrong directory, file created in wrong location). Instinct is to fix where error appears, but that's treating symptom.
 
-When you see an error:
+## When to Use
 
-1. **Note the error location**
-   - Where did it crash/fail?
-   - This is the symptom, not cause
+**Use when:**
+- Error happens deep in execution (not at entry point)
+- Stack trace shows long call chain
+- Unclear where invalid data originated
+- Need to find which test/code triggers problem
 
-2. **Ask: Where did this data come from?**
-   - What function called this?
-   - What set this variable?
+## The Tracing Process
 
-3. **Trace one level back**
-   - Check the caller
-   - Verify data at that point
+### 1. Observe the Symptom
+```
+Error: git init failed in /Users/jesse/project/packages/core
+```
 
-4. **Repeat until source found**
-   - Keep asking "where from?"
-   - Stop when you find invalid data entry point
+### 2. Find Immediate Cause
+What code directly causes this?
+```typescript
+await execFileAsync('git', ['init'], { cwd: projectDir });
+```
 
-## Example
+### 3. Ask: What Called This?
+```typescript
+WorktreeManager.createSessionWorktree(projectDir, sessionId)
+  → called by Session.initializeWorkspace()
+  → called by Session.create()
+  → called by test at Project.create()
+```
 
+### 4. Keep Tracing Up
+What value was passed?
+- `projectDir = ''` (empty string!)
+- Empty string as `cwd` resolves to `process.cwd()`
+- That's the source code directory!
+
+### 5. Find Original Trigger
+Where did empty string come from?
+```typescript
+const context = setupCoreTest(); // Returns { tempDir: '' }
+Project.create('name', context.tempDir); // Accessed before beforeEach!
 ```
-Error: Cannot read property 'name' of undefined
-  at renderUser (line 50)
-  at processUsers (line 30)
-  at handleResponse (line 15)
-  at fetchUsers (line 5)
+
+## Adding Stack Traces
+
+When can't trace manually, add instrumentation:
+
+```typescript
+async function gitInit(directory: string) {
+  const stack = new Error().stack;
+  console.error('DEBUG git init:', {
+    directory,
+    cwd: process.cwd(),
+    stack,
+  });
+
+  await execFileAsync('git', ['init'], { cwd: directory });
+}
 ```
 
-**Bad approach:** Fix at line 50 with null check
-**Good approach:** Trace back - why is user undefined at line 30? Where did it come from?
+**Critical:** Use `console.error()` in tests (not logger - may not show)
+
+**Run and capture:**
+```bash
+npm test 2>&1 | grep 'DEBUG git init'
+```
+
+**Analyze stack traces:**
+- Look for test file names
+- Find line number triggering call
+- Identify pattern (same test? same parameter?)
+
+## Finding Which Test Causes Pollution
+
+If something appears during tests but don't know which test:
+
+Use bisection script: `scripts/find-polluter.sh`
+
+```bash
+./scripts/find-polluter.sh '.git' 'src/**/*.test.ts'
+```
+
+Runs tests one-by-one, stops at first polluter.
+
+## Key Principle
+
+**NEVER fix just where error appears.** Trace back to find original trigger.
 
-## Questions to Ask
+When found immediate cause:
+- Can trace one level up? → Trace backwards
+- Is this the source? → Fix at source
+- Then add validation at each layer (see defense-in-depth.md)
 
-At each level:
-- What is the value here?
-- Is it what I expect?
-- Who set it / passed it?
-- Was it validated?
+## Real Example
 
-## Finding the Root
+**Symptom:** `.git` created in `packages/core/` (source code)
 
-Root cause is found when:
-- You find where invalid data first entered
-- Or where a valid value became invalid
-- Or where an assumption was violated
+**Trace chain:**
+1. `git init` runs in `process.cwd()` ← empty cwd parameter
+2. WorktreeManager called with empty projectDir
+3. Session.create() passed empty string
+4. Test accessed `context.tempDir` before beforeEach
+5. setupCoreTest() returns `{ tempDir: '' }` initially
 
-Fix at that point, not downstream.
+**Root cause:** Top-level variable initialization accessing empty value
 
-## Common Root Causes
+**Fix:** Made tempDir a getter that throws if accessed before beforeEach
 
-- Missing input validation
-- Incorrect API response handling
-- Race condition
-- State mutation
-- Incorrect assumption about data shape
+**Also added defense-in-depth:**
+- Layer 1: Project.create() validates directory
+- Layer 2: WorkspaceManager validates not empty
+- Layer 3: NODE_ENV guard refuses git init outside tmpdir
+- Layer 4: Stack trace logging before git init

package/skills/ck-debugging/references/systematic-debugging.md

@@ -1,74 +1,102 @@
 # Systematic Debugging
 
-Four-phase framework ensuring proper investigation before fixes.
+Four-phase debugging framework that ensures root cause investigation before attempting fixes.
 
-## Phase 1: Root Cause Investigation
+## The Iron Law
 
-Before ANY fix attempt:
+```
+NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST
+```
 
-1. **Read the full error**
-   - Stack trace, line numbers, error type
-   - Don't skim - read word by word
+If haven't completed Phase 1, cannot propose fixes.
 
-2. **Reproduce consistently**
-   - Can you trigger it reliably?
-   - What are the exact steps?
+## The Four Phases
 
-3. **Check recent changes**
-   - What changed since it last worked?
-   - git diff, recent commits
+Must complete each phase before proceeding to next.
 
-4. **Gather evidence**
-   - Add logging if needed
-   - Check inputs and outputs
-   - Don't guess - observe
+### Phase 1: Root Cause Investigation
 
-## Phase 2: Pattern Analysis
+**BEFORE attempting ANY fix:**
 
-1. **Find working example**
-   - Similar code that works
-   - Previous version that worked
+1. **Read Error Messages Carefully** - Don't skip past errors/warnings, read stack traces completely
+2. **Reproduce Consistently** - Can trigger reliably? Exact steps? If not reproducible → gather more data
+3. **Check Recent Changes** - What changed? Git diff, recent commits, new dependencies, config changes
+4. **Gather Evidence in Multi-Component Systems**
+   - For EACH component boundary: log data entering/exiting, verify environment propagation
+   - Run once to gather evidence showing WHERE it breaks
+   - THEN analyze to identify failing component
+5. **Trace Data Flow** - Where does bad value originate? Trace up call stack until finding source (see root-cause-tracing.md)
 
-2. **Compare systematically**
-   - Line by line comparison
-   - What's different?
+### Phase 2: Pattern Analysis
 
-3. **Identify key difference**
-   - What's the minimal difference?
-   - What assumption changed?
+**Find pattern before fixing:**
 
-## Phase 3: Hypothesis and Testing
+1. **Find Working Examples** - Locate similar working code in same codebase
+2. **Compare Against References** - Read reference implementation COMPLETELY, understand fully before applying
+3. **Identify Differences** - List every difference however small, don't assume "that can't matter"
+4. **Understand Dependencies** - What other components, settings, config, environment needed?
 
-1. **Form specific theory**
-   - "The bug is caused by X because Y"
-   - Must be testable
+### Phase 3: Hypothesis and Testing
 
-2. **Test minimally**
-   - Smallest change to prove/disprove
-   - Don't fix yet - just test theory
+**Scientific method:**
 
-3. **Verify theory**
-   - Did prediction match result?
-   - If not, return to Phase 1
+1. **Form Single Hypothesis** - "I think X is root cause because Y", be specific not vague
+2. **Test Minimally** - SMALLEST possible change to test hypothesis, one variable at a time
+3. **Verify Before Continuing** - Worked? → Phase 4. Didn't work? → NEW hypothesis. DON'T add more fixes
+4. **When Don't Know** - Say "I don't understand X", don't pretend, ask for help
 
-## Phase 4: Implementation
+### Phase 4: Implementation
 
-1. **Write failing test first**
-   - Test should fail before fix
-   - Proves you understand bug
+**Fix root cause, not symptom:**
 
-2. **Make minimal fix**
-   - Fix at root cause
-   - Don't add workarounds
+1. **Create Failing Test Case** - Simplest reproduction, automated if possible, MUST have before fixing
+2. **Implement Single Fix** - Address root cause identified, ONE change, no "while I'm here" improvements
+3. **Verify Fix** - Test passes? No other tests broken? Issue actually resolved?
+4. **If Fix Doesn't Work**
+   - STOP. Count: How many fixes tried?
+   - If < 3: Return to Phase 1, re-analyze with new information
+   - **If ≥ 3: STOP and question architecture**
+5. **If 3+ Fixes Failed: Question Architecture**
+   - Pattern: Each fix reveals new shared state/coupling problem elsewhere
+   - STOP and question fundamentals: Is pattern sound? Wrong architecture?
+   - Discuss with human partner before more fixes
 
-3. **Verify fix works**
-   - Test passes now
-   - No regressions
-   - Fresh run, not cached
+## Red Flags - STOP and Follow Process
 
-## Key Rules
+If catch yourself thinking:
+- "Quick fix for now, investigate later"
+- "Just try changing X and see if it works"
+- "Add multiple changes, run tests"
+- "Skip the test, I'll manually verify"
+- "It's probably X, let me fix that"
+- "I don't fully understand but this might work"
+- "One more fix attempt" (when already tried 2+)
 
-- Complete each phase before proceeding
-- No fixes without Phase 1 evidence
-- Theory must be testable
-- Verify every claim
+**ALL mean:** STOP. Return to Phase 1.
+
+## Human Partner Signals You're Doing It Wrong
+
+- "Is that not happening?" - Assumed without verifying
+- "Will it show us...?" - Should have added evidence gathering
+- "Stop guessing" - Proposing fixes without understanding
+- "Ultrathink this" - Question fundamentals, not just symptoms
+- "We're stuck?" (frustrated) - Approach isn't working
+
+**When see these:** STOP. Return to Phase 1.
+
+## Common Rationalizations
+
+| Excuse | Reality |
+|--------|---------|
+| "Issue is simple, don't need process" | Simple issues have root causes too |
+| "Emergency, no time for process" | Systematic is FASTER than guess-and-check |
+| "Just try this first, then investigate" | First fix sets pattern. Do right from start |
+| "One more fix attempt" (after 2+ failures) | 3+ failures = architectural problem |
+
+## Real-World Impact
+
+From debugging sessions:
+- Systematic approach: 15-30 minutes to fix
+- Random fixes approach: 2-3 hours of thrashing
+- First-time fix rate: 95% vs 40%
+- New bugs introduced: Near zero vs common

package/skills/ck-debugging/references/verification.md

@@ -1,74 +1,123 @@
-# Verification Protocol
+# Verification Before Completion
 
 Run verification commands and confirm output before claiming success.
 
-## Core Rule
+## Core Principle
 
-**NO COMPLETION CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE**
+**Evidence before claims, always.**
 
-"Should work" is not evidence. Run it. Read the output. Then claim.
+Claiming work complete without verification is dishonesty, not efficiency.
 
-## Verification Steps
+## The Iron Law
 
-### 1. Run Fresh
+```
+NO COMPLETION CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE
+```
 
-- Clear cache if applicable
-- Run from clean state
-- Don't rely on previous runs
+If haven't run verification command in this message, cannot claim it passes.
 
-### 2. Read Output
+## The Gate Function
 
-- Read the actual output
-- Don't assume it passed
-- Check for warnings too
+```
+BEFORE claiming any status or expressing satisfaction:
 
-### 3. Confirm Expectations
+1. IDENTIFY: What command proves this claim?
+2. RUN: Execute FULL command (fresh, complete)
+3. READ: Full output, check exit code, count failures
+4. VERIFY: Does output confirm claim?
+   - If NO: State actual status with evidence
+   - If YES: State claim WITH evidence
+5. ONLY THEN: Make claim
+
+Skip any step = lying, not verifying
+```
 
-- Did it do what you expected?
-- All tests pass (not just most)?
-- No new warnings/errors?
+## Common Failures
+
+| Claim | Requires | Not Sufficient |
+|-------|----------|----------------|
+| Tests pass | Test command output: 0 failures | Previous run, "should pass" |
+| Linter clean | Linter output: 0 errors | Partial check, extrapolation |
+| Build succeeds | Build command: exit 0 | Linter passing, logs look good |
+| Bug fixed | Test original symptom: passes | Code changed, assumed fixed |
+| Regression test works | Red-green cycle verified | Test passes once |
+| Agent completed | VCS diff shows changes | Agent reports "success" |
+| Requirements met | Line-by-line checklist | Tests passing |
+
+## Red Flags - STOP
+
+- Using "should", "probably", "seems to"
+- Expressing satisfaction before verification ("Great!", "Perfect!", "Done!")
+- About to commit/push/PR without verification
+- Trusting agent success reports
+- Relying on partial verification
+- Thinking "just this once"
+- Tired and wanting work over
+- **ANY wording implying success without having run verification**
+
+## Rationalization Prevention
+
+| Excuse | Reality |
+|--------|---------|
+| "Should work now" | RUN verification |
+| "I'm confident" | Confidence ≠ evidence |
+| "Just this once" | No exceptions |
+| "Linter passed" | Linter ≠ compiler |
+| "Agent said success" | Verify independently |
+| "Partial check is enough" | Partial proves nothing |
+
+## Key Patterns
+
+**Tests:**
+```
+✅ [Run test command] [See: 34/34 pass] "All tests pass"
+❌ "Should pass now" / "Looks correct"
+```
+
+**Regression tests (TDD Red-Green):**
+```
+✅ Write → Run (pass) → Revert fix → Run (MUST FAIL) → Restore → Run (pass)
+❌ "I've written regression test" (without red-green verification)
+```
 
-### 4. Document Evidence
+**Build:**
+```
+✅ [Run build] [See: exit 0] "Build passes"
+❌ "Linter passed" (linter doesn't check compilation)
+```
 
-- Copy relevant output
-- Note what was verified
-- Timestamp if needed
+**Requirements:**
+```
+✅ Re-read plan → Create checklist → Verify each → Report gaps or completion
+❌ "Tests pass, phase complete"
+```
 
-## What to Verify
+**Agent delegation:**
+```
+✅ Agent reports success → Check VCS diff → Verify changes → Report actual state
+❌ Trust agent report
+```
 
-Before claiming "fixed":
-- [ ] Tests pass (fresh run)
-- [ ] No new errors in logs
-- [ ] Feature works manually
-- [ ] Edge cases handled
+## When To Apply
 
-Before claiming "complete":
-- [ ] All acceptance criteria met
-- [ ] Tests cover new code
-- [ ] No regressions
-- [ ] Documentation updated
+**ALWAYS before:**
+- ANY variation of success/completion claims
+- ANY expression of satisfaction
+- ANY positive statement about work state
+- Committing, PR creation, task completion
+- Moving to next task
+- Delegating to agents
 
-## Anti-Patterns
+**Rule applies to:**
+- Exact phrases
+- Paraphrases and synonyms
+- Implications of success
+- ANY communication suggesting completion/correctness
 
-**Don't do:**
-- "Tests passed earlier"
-- "It worked on my machine"
-- "Should be fine now"
-- Skipping verification because confident
+## The Bottom Line
 
-**Do instead:**
-- Run fresh every time
-- Read actual output
-- Verify on clean state
-- Question assumptions
+**No shortcuts for verification.**
 
-## Verification Checklist
+Run command. Read output. THEN claim result.
 
-```
-[ ] Ran command fresh (not cached)
-[ ] Read full output (not skimmed)
-[ ] Output matches expectations
-[ ] No warnings or errors
-[ ] Tested edge case
-[ ] Documented result
-```
+Non-negotiable.

package/skills/ck-debugging/scripts/find-polluter.sh

@@ -0,0 +1,63 @@
+#!/bin/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

package/skills/ck-debugging/scripts/find-polluter.test.md

@@ -0,0 +1,102 @@
+# find-polluter.sh Test Documentation
+
+## Purpose
+Bisection script to find which test creates unwanted files or state pollution.
+
+## Manual Test Procedure
+
+### Setup Test Scenario
+```bash
+# Create test directory
+mkdir -p /tmp/polluter-test && cd /tmp/polluter-test
+
+# Create clean test
+cat > test1.test.js << 'EOF'
+console.log('Test 1: clean');
+EOF
+
+# Create polluter test
+cat > test2.test.js << 'EOF'
+const fs = require('fs');
+fs.mkdirSync('.git', { recursive: true });
+console.log('Test 2: creates pollution');
+EOF
+
+# Create another clean test
+cat > test3.test.js << 'EOF'
+console.log('Test 3: clean');
+EOF
+```
+
+### Run Script
+```bash
+# For projects with npm test
+/path/to/find-polluter.sh '.git' 'src/**/*.test.ts'
+
+# For node-only tests (modify script to use 'node' instead of 'npm test')
+./find-polluter.sh '.git' '*.test.js'
+```
+
+### Expected Output
+```
+🔍 Searching for test that creates: .git
+Test pattern: *.test.js
+
+Found 3 test files
+
+[1/3] Testing: ./test1.test.js
+[2/3] Testing: ./test2.test.js
+
+🎯 FOUND POLLUTER!
+   Test: ./test2.test.js
+   Created: .git
+```
+
+### Cleanup
+```bash
+rm -rf /tmp/polluter-test
+```
+
+## Test Results
+
+✅ Script logic verified (2025-11-11)
+- Correctly iterates through test files
+- Detects pollution creation
+- Reports the polluting test file
+- Exits early when polluter found
+
+## Usage Notes
+
+**Prerequisites:**
+- Test runner (npm test) must be configured in project
+- Test pattern must match actual test files
+- Pollution path must be accurate
+
+**Customization:**
+If your project doesn't use `npm test`, modify line 42:
+```bash
+# Replace
+npm test "$TEST_FILE" > /dev/null 2>&1 || true
+
+# With your test command
+node "$TEST_FILE" > /dev/null 2>&1 || true
+# Or
+jest "$TEST_FILE" > /dev/null 2>&1 || true
+```
+
+## Common Use Cases
+
+1. **Find test creating .git directory:**
+   ```bash
+   ./find-polluter.sh '.git' 'src/**/*.test.ts'
+   ```
+
+2. **Find test creating node_modules:**
+   ```bash
+   ./find-polluter.sh 'node_modules' 'test/**/*.spec.js'
+   ```
+
+3. **Find test creating specific file:**
+   ```bash
+   ./find-polluter.sh 'unwanted-file.txt' '**/*.test.js'
+   ```