safeword 0.6.9 → 0.7.1

package/templates/scripts/bisect-test-pollution.sh

@@ -0,0 +1,87 @@
+#!/bin/bash
+# Bisect test pollution: Find which test creates unwanted files or shared state
+#
+# Use when: Tests pass individually but fail together, tests leave files behind,
+# tests affect each other, test isolation problems, shared state between tests
+#
+# Usage: ./bisect-test-pollution.sh <file_to_check> <name_pattern> [search_dir]
+# Example: ./bisect-test-pollution.sh '.git' '*.test.ts' src
+# Example: ./bisect-test-pollution.sh '.git' '*.test.ts'  (searches current dir)
+
+set -e
+
+if [ $# -lt 2 ]; then
+  echo "Usage: $0 <file_to_check> <name_pattern> [search_dir]"
+  echo "Example: $0 '.git' '*.test.ts' src"
+  echo "Example: $0 '.git' '*.test.ts'"
+  echo ""
+  echo "Runs tests one-by-one to find which creates <file_to_check>"
+  echo "Override test command: TEST_CMD='pnpm test' $0 ..."
+  exit 1
+fi
+
+# Detect package manager from lockfile
+detect_runner() {
+  if [ -f "pnpm-lock.yaml" ]; then echo "pnpm"
+  elif [ -f "yarn.lock" ]; then echo "yarn"
+  elif [ -f "bun.lockb" ]; then echo "bun"
+  else echo "npm"
+  fi
+}
+
+# Allow override via environment variable
+RUNNER="${TEST_CMD:-$(detect_runner) test}"
+
+POLLUTION_CHECK="$1"
+NAME_PATTERN="$2"
+SEARCH_DIR="${3:-.}"
+
+echo "Searching for test that creates: $POLLUTION_CHECK"
+echo "Test pattern: $NAME_PATTERN in $SEARCH_DIR"
+echo ""
+
+# Get list of test files using find (portable across bash versions)
+TEST_FILES=$(find "$SEARCH_DIR" -type f -name "$NAME_PATTERN" 2>/dev/null | sort)
+TOTAL=$(echo "$TEST_FILES" | grep -c . || echo 0)
+
+if [ "$TOTAL" -eq 0 ]; then
+  echo "No test files found matching: $NAME_PATTERN in $SEARCH_DIR"
+  exit 1
+fi
+
+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 "Clean it up first: rm -rf $POLLUTION_CHECK"
+    exit 1
+  fi
+
+  echo "[$COUNT/$TOTAL] Testing: $TEST_FILE"
+
+  # Run the test
+  $RUNNER "$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 "To investigate:"
+    echo "  $RUNNER $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/templates/scripts/bisect-zombie-processes.sh

@@ -0,0 +1,129 @@
+#!/bin/bash
+# Bisect zombie processes: Find which test leaves processes behind
+#
+# Use when: Tests leave processes running, playwright browsers not cleaned up,
+# port stays in use after tests, zombie node processes after test suite,
+# can't find which test is leaving processes behind, chromium processes accumulate
+#
+# Usage: ./bisect-zombie-processes.sh <process_pattern> <name_pattern> [search_dir]
+# Example: ./bisect-zombie-processes.sh 'chromium' '*.test.ts' tests
+# Example: ./bisect-zombie-processes.sh 'node.*:3000' '*.spec.ts' e2e
+# Example: ./bisect-zombie-processes.sh 'playwright' '*.test.ts'
+
+set -e
+
+if [ $# -lt 2 ]; then
+  echo "Usage: $0 <process_pattern> <name_pattern> [search_dir]"
+  echo "Example: $0 'chromium' '*.test.ts' tests"
+  echo "Example: $0 'playwright' '*.test.ts'"
+  echo ""
+  echo "Runs tests one-by-one to find which leaves <process_pattern> running"
+  echo "Override test command: TEST_CMD='pnpm test' $0 ..."
+  exit 1
+fi
+
+# Detect package manager from lockfile
+detect_runner() {
+  if [ -f "pnpm-lock.yaml" ]; then echo "pnpm"
+  elif [ -f "yarn.lock" ]; then echo "yarn"
+  elif [ -f "bun.lockb" ]; then echo "bun"
+  else echo "npm"
+  fi
+}
+
+# Allow override via environment variable
+RUNNER="${TEST_CMD:-$(detect_runner) test}"
+
+PROCESS_PATTERN="$1"
+NAME_PATTERN="$2"
+SEARCH_DIR="${3:-.}"
+
+echo "Searching for test that leaves process behind: $PROCESS_PATTERN"
+echo "Test pattern: $NAME_PATTERN in $SEARCH_DIR"
+echo ""
+
+# Function to count matching processes
+count_procs() {
+  pgrep -f "$PROCESS_PATTERN" 2>/dev/null | wc -l | tr -d ' '
+}
+
+# Function to kill matching processes
+kill_procs() {
+  pkill -9 -f "$PROCESS_PATTERN" 2>/dev/null || true
+}
+
+# Get list of test files using find (portable across bash versions)
+TEST_FILES=$(find "$SEARCH_DIR" -type f -name "$NAME_PATTERN" 2>/dev/null | sort)
+TOTAL=$(echo "$TEST_FILES" | grep -c . || echo 0)
+
+if [ "$TOTAL" -eq 0 ]; then
+  echo "No test files found matching: $NAME_PATTERN in $SEARCH_DIR"
+  exit 1
+fi
+
+echo "Found $TOTAL test files"
+echo ""
+
+# Clean up any existing matching processes first
+INITIAL_COUNT=$(count_procs)
+if [ "$INITIAL_COUNT" -gt 0 ]; then
+  echo "Found $INITIAL_COUNT existing '$PROCESS_PATTERN' processes - cleaning up first..."
+  kill_procs
+  sleep 2
+
+  REMAINING=$(count_procs)
+  if [ "$REMAINING" -gt 0 ]; then
+    echo "WARNING: Could not kill all processes. $REMAINING still running."
+    echo "You may need to manually kill them first."
+    exit 1
+  fi
+  echo "Cleanup complete."
+  echo ""
+fi
+
+COUNT=0
+for TEST_FILE in $TEST_FILES; do
+  COUNT=$((COUNT + 1))
+
+  # Get baseline process count
+  BEFORE=$(count_procs)
+
+  if [ "$BEFORE" -gt 0 ]; then
+    echo "Zombie process found before test $COUNT/$TOTAL"
+    echo "Clean up first or check previous test"
+    exit 1
+  fi
+
+  echo "[$COUNT/$TOTAL] Testing: $TEST_FILE"
+
+  # Run the test
+  $RUNNER "$TEST_FILE" > /dev/null 2>&1 || true
+
+  # Small delay for processes to settle
+  sleep 1
+
+  # Check if zombie processes appeared
+  AFTER=$(count_procs)
+  if [ "$AFTER" -gt 0 ]; then
+    echo ""
+    echo "FOUND ZOMBIE SPAWNER!"
+    echo "  Test: $TEST_FILE"
+    echo "  Process pattern: $PROCESS_PATTERN"
+    echo "  Processes left behind: $AFTER"
+    echo ""
+    echo "Running processes:"
+    pgrep -f "$PROCESS_PATTERN" | head -5 | while read -r pid; do
+      ps -p "$pid" -o pid,command= 2>/dev/null | head -c 100
+      echo ""
+    done
+    echo ""
+    echo "To investigate:"
+    echo "  $RUNNER $TEST_FILE    # Run just this test"
+    echo "  cat $TEST_FILE         # Review test code for missing cleanup"
+    exit 1
+  fi
+done
+
+echo ""
+echo "No zombie spawner found - all tests clean up properly!"
+exit 0

package/templates/scripts/lint-md.sh

@@ -0,0 +1,16 @@
+#!/bin/bash
+# Markdown linter wrapper with helpful hints for MD040 errors
+# Usage: ./lint-md.sh [markdownlint-cli2 args]
+
+set -euo pipefail
+
+# Run markdownlint and add context to MD040 errors
+pnpm markdownlint-cli2 "$@" 2>&1 | while IFS= read -r line; do
+  echo "$line"
+  if [[ "$line" == *"MD040"* ]]; then
+    echo "    💡 Language hints: typescript|bash|json|yaml for code, 'text' for templates/pseudocode, 'plaintext' for directory trees"
+  fi
+done
+
+# Preserve exit code from markdownlint
+exit "${PIPESTATUS[0]}"

package/templates/skills/safeword-quality-reviewer/SKILL.md

@@ -96,7 +96,7 @@ Read relevant standards:
 
 **CRITICAL**: This is your main differentiator from automatic hook. ALWAYS check versions.
 
-```
+```text
 WebSearch: "[library name] latest stable version 2025"
 WebSearch: "[library name] security vulnerabilities"
 ```
@@ -116,7 +116,7 @@ WebSearch: "[library name] security vulnerabilities"
 
 **CRITICAL**: This is your main differentiator from automatic hook. ALWAYS verify against current docs.
 
-```
+```text
 WebFetch: https://react.dev (for React)
 WebFetch: https://vitejs.dev (for Vite)
 WebFetch: https://www.electronjs.org/docs (for Electron)
@@ -134,7 +134,7 @@ WebFetch: https://www.electronjs.org/docs (for Electron)
 
 **Simple question** ("is it correct?"):
 
-```
+```text
 **Correctness:** ✓ Logic is sound, edge cases handled, no obvious errors.
 ```
 

package/templates/skills/safeword-systematic-debugger/SKILL.md

@@ -0,0 +1,246 @@
+---
+name: systematic-debugger
+description: Four-phase debugging framework that ensures root cause identification before fixes. Use when encountering bugs, test failures, unexpected behavior, or when previous fix attempts failed. Enforces investigate-first discipline ('debug this', 'fix this error', 'test is failing', 'not working').
+allowed-tools: '*'
+---
+
+# Systematic Debugger
+
+Find root cause before fixing. Symptom fixes are failure.
+
+**Iron Law:** NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST
+
+## When to Use
+
+Answer IN ORDER. Stop at first match:
+
+1. Bug, error, or test failure? → Use this skill
+2. Unexpected behavior? → Use this skill
+3. Previous fix didn't work? → Use this skill (especially important)
+4. Performance problem? → Use this skill
+5. None of above? → Skip this skill
+
+**Use especially when:**
+
+- Under time pressure (emergencies make guessing tempting)
+- "Quick fix" seems obvious (red flag)
+- Already tried 1+ fixes that didn't work
+
+## The Four Phases
+
+Complete each phase before proceeding.
+
+### Phase 1: Root Cause Investigation
+
+**BEFORE attempting ANY fix:**
+
+**1. Read Error Messages Completely**
+
+```text
+Don't skip past errors. They often contain the exact solution.
+- Full stack trace (note line numbers, file paths)
+- Error codes and messages
+- Warnings that preceded the error
+```
+
+**2. Reproduce Consistently**
+
+| Can reproduce?  | Action                                               |
+| --------------- | ---------------------------------------------------- |
+| Yes, every time | Proceed to step 3                                    |
+| Sometimes       | Gather more data - when does it happen vs not?       |
+| Never           | Cannot debug what you cannot reproduce - gather logs |
+
+**3. Check Recent Changes**
+
+```bash
+git diff HEAD~5          # Recent code changes
+git log --oneline -10    # Recent commits
+```
+
+What changed that could cause this? Dependencies? Config? Environment?
+
+**4. Trace Data Flow (Root Cause Tracing)**
+
+When error is deep in call stack:
+
+```text
+Symptom: Error at line 50 in utils.js
+    ↑ Called by handler.js:120
+    ↑ Called by router.js:45
+    ↑ Called by app.js:10 ← ROOT CAUSE: bad input here
+```
+
+**Technique:**
+
+1. Find where error occurs (symptom)
+2. Ask: "What called this with bad data?"
+3. Trace up until you find the SOURCE
+4. Fix at source, not at symptom
+
+**5. Multi-Component Systems**
+
+When system has multiple layers (API → service → database):
+
+```bash
+# Log at EACH boundary before proposing fixes
+echo "=== Layer 1 (API): request=$REQUEST ==="
+echo "=== Layer 2 (Service): input=$INPUT ==="
+echo "=== Layer 3 (DB): query=$QUERY ==="
+```
+
+Run once to find WHERE it breaks. Then investigate that layer.
+
+### Phase 2: Pattern Analysis
+
+**1. Find Working Examples**
+
+Locate similar working code in same codebase. What works that's similar?
+
+**2. Identify Differences**
+
+| Working code     | Broken code    | Could this matter? |
+| ---------------- | -------------- | ------------------ |
+| Uses async/await | Uses callbacks | Yes - timing       |
+| Validates input  | No validation  | Yes - bad data     |
+
+List ALL differences. Don't assume "that can't matter."
+
+### Phase 3: Hypothesis Testing
+
+**1. Form Single Hypothesis**
+
+Write it down: "I think X is the root cause because Y"
+
+Be specific:
+
+- ❌ "Something's wrong with the database"
+- ✅ "Connection pool exhausted because connections aren't released in error path"
+
+**2. Test Minimally**
+
+| Rule                     | Why                    |
+| ------------------------ | ---------------------- |
+| ONE change at a time     | Isolate what works     |
+| Smallest possible change | Avoid side effects     |
+| Don't bundle fixes       | Can't tell what helped |
+
+**3. Evaluate Result**
+
+| Result          | Action                                  |
+| --------------- | --------------------------------------- |
+| Fixed           | Phase 4 (verify)                        |
+| Not fixed       | NEW hypothesis (return to 3.1)          |
+| Partially fixed | Found one issue, continue investigating |
+
+### Phase 4: Implementation
+
+**1. Create Failing Test**
+
+Before fixing, write test that fails due to the bug:
+
+```javascript
+it('handles empty input without crashing', () => {
+  // This test should FAIL before fix, PASS after
+  expect(() => processData('')).not.toThrow();
+});
+```
+
+**2. Implement Fix**
+
+- Address ROOT CAUSE identified in Phase 1
+- ONE change
+- No "while I'm here" improvements
+
+**3. Verify**
+
+- [ ] New test passes
+- [ ] Existing tests still pass
+- [ ] Issue actually resolved (not just test passing)
+
+**4. If Fix Doesn't Work**
+
+| Fix attempts | Action                                   |
+| ------------ | ---------------------------------------- |
+| 1-2          | Return to Phase 1 with new information   |
+| 3+           | STOP - Question architecture (see below) |
+
+**5. After 3+ Failed Fixes: Question Architecture**
+
+Pattern indicating architectural problem:
+
+- Each fix reveals new coupling/shared state
+- Fixes require "massive refactoring"
+- Each fix creates new symptoms elsewhere
+
+**STOP and ask:**
+
+- Is this pattern fundamentally sound?
+- Should we refactor vs. continue patching?
+- Discuss with user before more fix attempts
+
+## Red Flags - STOP Immediately
+
+If you catch yourself thinking:
+
+| Thought                                        | Reality                           |
+| ---------------------------------------------- | --------------------------------- |
+| "Quick fix for now, investigate later"         | Investigate NOW or you never will |
+| "Just try changing X"                          | That's guessing, not debugging    |
+| "I'll add multiple fixes and test"             | Can't isolate what worked         |
+| "I don't fully understand but this might work" | You need to understand first      |
+| "One more fix attempt" (after 2+ failures)     | 3+ failures = wrong approach      |
+
+**ALL mean: STOP. Return to Phase 1.**
+
+## Finding Test Pollution
+
+When tests pass individually but fail together (test isolation problem, tests affect each other, tests leave files behind), use bisection:
+
+```bash
+./.safeword/scripts/bisect-test-pollution.sh '.git' '*.test.ts' src
+```
+
+See: @./.safeword/scripts/bisect-test-pollution.sh
+
+## Debug Logging
+
+When adding diagnostic logging:
+
+```javascript
+// ❌ BAD
+console.log('here');
+console.log(data);
+
+// ✅ GOOD
+console.log('validateUser', { expected: 'admin', actual: user.role });
+console.log('processOrder', JSON.stringify({ input, output }, null, 2));
+```
+
+Log **expected vs actual**. Remove after fixing.
+
+## Quick Reference
+
+| Phase             | Key Question                          | Success Criteria                   |
+| ----------------- | ------------------------------------- | ---------------------------------- |
+| 1. Root Cause     | "WHY is this happening?"              | Understand cause, not just symptom |
+| 2. Pattern        | "What's different from working code?" | Identified key differences         |
+| 3. Hypothesis     | "Is my theory correct?"               | Confirmed or formed new theory     |
+| 4. Implementation | "Does the fix work?"                  | Test passes, issue resolved        |
+
+## Finding Zombie Process Spawners
+
+When tests leave processes behind (playwright browsers not cleaned up, port stays in use, zombie node processes, chromium accumulating), use bisection to find the culprit:
+
+```bash
+./.safeword/scripts/bisect-zombie-processes.sh 'chromium' '*.test.ts' tests
+./.safeword/scripts/bisect-zombie-processes.sh 'playwright' '*.spec.ts' e2e
+```
+
+See: @./.safeword/scripts/bisect-zombie-processes.sh
+
+## Related Resources
+
+- Process cleanup guide: @./.safeword/guides/zombie-process-cleanup.md
+- Debug logging style: @./.safeword/guides/code-philosophy.md
+- TDD for fix verification: @./.safeword/guides/tdd-best-practices.md