claude-flow-novice 2.18.22 → 2.18.24

package/.claude/CLAUDE.md

@@ -0,0 +1,17 @@
+# CFN Coordination and Namespace Guide
+
+## Coordination Patterns and Namespace Isolation
+
+- Coordination patterns: see `.claude/skills/cfn-coordination/SKILL.md` (chain, broadcast, mesh, consensus collection).
+- Namespace structure: agents `.claude/agents/cfn-dev-team/`; skills `.claude/skills/cfn-*/`; hooks `.claude/hooks/cfn-*`; commands `.claude/commands/cfn/`.
+- Enhanced orchestrator v3.0: `./.claude/skills/cfn-loop-orchestration/orchestrate.sh`
+- Orchestration flow: Loop 3 executes and tests -> gate check -> Loop 2 validators -> Product Owner decision (PROCEED/ITERATE/ABORT) -> iterate or finish.
+- Task mode agents: return output directly; no Redis signaling.
+
+### Coordination Anti-Patterns (avoid)
+
+- Skipping gate check before spawning Loop 2.
+- Validators reviewing without tests/logs.
+- Product Owner decision without deliverable paths.
+- Mixing service and container names inside Docker networks.
+- Manual cleanup instead of orchestrator controls.

package/.claude/cfn-scripts/check-memory.sh

@@ -0,0 +1,150 @@
+#!/bin/bash
+# Memory Leak Prevention Script (ANTI-024)
+# Detects and kills orphaned test processes (jest, vitest, node test runners)
+#
+# Usage:
+#   ./scripts/check-memory.sh           # Report only
+#   ./scripts/check-memory.sh --kill    # Kill orphans
+#   ./scripts/check-memory.sh --kill 500  # Kill if total MB > 500
+
+set -euo pipefail
+
+KILL_MODE=false
+THRESHOLD_MB=0
+
+# Parse arguments
+while [[ $# -gt 0 ]]; do
+    case "$1" in
+        --kill)
+            KILL_MODE=true
+            shift
+            if [[ "${1:-}" =~ ^[0-9]+$ ]]; then
+                THRESHOLD_MB="$1"
+                shift
+            fi
+            ;;
+        --help|-h)
+            echo "Usage: $0 [--kill [threshold_mb]]"
+            echo "  --kill        Kill orphaned test processes"
+            echo "  --kill 500    Only kill if total memory > 500MB"
+            exit 0
+            ;;
+        *)
+            shift
+            ;;
+    esac
+done
+
+# Find test-related processes
+find_test_processes() {
+    # Jest, Vitest, and generic node test runners
+    pgrep -af "(jest|vitest|node.*test)" 2>/dev/null || true
+}
+
+# Calculate memory usage of test processes (in MB)
+get_test_memory_mb() {
+    ps aux 2>/dev/null | grep -E "(jest|vitest|node.*test)" | grep -v grep | \
+        awk '{sum+=$6} END {print int(sum/1024)}' || echo "0"
+}
+
+# Find orphaned processes (parent PID = 1 or parent dead)
+find_orphans() {
+    local orphans=()
+
+    while IFS= read -r line; do
+        local pid=$(echo "$line" | awk '{print $1}')
+        if [[ -z "$pid" ]]; then continue; fi
+
+        local ppid=$(ps -o ppid= -p "$pid" 2>/dev/null | tr -d ' ' || echo "")
+        if [[ -z "$ppid" ]]; then continue; fi
+
+        # Check if parent is init (1) or parent process doesn't exist
+        if [[ "$ppid" == "1" ]] || ! ps -p "$ppid" > /dev/null 2>&1; then
+            orphans+=("$pid")
+        fi
+    done < <(find_test_processes)
+
+    echo "${orphans[@]:-}"
+}
+
+# Kill processes gracefully
+kill_processes() {
+    local pids=("$@")
+
+    for pid in "${pids[@]}"; do
+        if [[ -z "$pid" ]]; then continue; fi
+
+        echo "Killing orphaned process: $pid"
+
+        # Try SIGTERM first
+        kill -TERM "$pid" 2>/dev/null || continue
+
+        # Wait up to 5 seconds for graceful shutdown
+        local count=0
+        while ps -p "$pid" > /dev/null 2>&1 && [[ $count -lt 5 ]]; do
+            sleep 1
+            ((count++))
+        done
+
+        # Force kill if still running
+        if ps -p "$pid" > /dev/null 2>&1; then
+            echo "Force killing: $pid"
+            kill -KILL "$pid" 2>/dev/null || true
+        fi
+    done
+}
+
+# Main
+main() {
+    local total_mb=$(get_test_memory_mb)
+    local orphans=($(find_orphans))
+    local orphan_count=${#orphans[@]}
+
+    echo "=== Memory Check (ANTI-024) ==="
+    echo "Test process memory: ${total_mb}MB"
+    echo "Orphaned processes: ${orphan_count}"
+
+    if [[ $orphan_count -gt 0 ]]; then
+        echo ""
+        echo "Orphan PIDs: ${orphans[*]}"
+
+        if $KILL_MODE; then
+            if [[ $THRESHOLD_MB -gt 0 ]] && [[ $total_mb -lt $THRESHOLD_MB ]]; then
+                echo "Memory ($total_mb MB) below threshold ($THRESHOLD_MB MB), skipping kill"
+                exit 0
+            fi
+
+            echo ""
+            echo "Killing orphaned processes..."
+            kill_processes "${orphans[@]}"
+
+            # Verify cleanup
+            sleep 1
+            local remaining=$(find_orphans | wc -w)
+            echo "Remaining orphans: $remaining"
+
+            if [[ $remaining -gt 0 ]]; then
+                echo "WARNING: Some processes could not be killed"
+                exit 1
+            fi
+        else
+            echo ""
+            echo "Run with --kill to terminate orphaned processes"
+        fi
+    else
+        echo "No orphaned test processes found"
+    fi
+
+    # Report current test processes
+    local running=$(find_test_processes | wc -l)
+    if [[ $running -gt 0 ]]; then
+        echo ""
+        echo "Running test processes: $running"
+        find_test_processes | head -5
+        if [[ $running -gt 5 ]]; then
+            echo "... and $((running - 5)) more"
+        fi
+    fi
+}
+
+main "$@"

package/.claude/cfn-scripts/run-with-memory-limit.sh

@@ -0,0 +1,91 @@
+#!/bin/bash
+# Run command with memory limit enforcement (ANTI-024)
+# Uses systemd-run when available, falls back to ulimit
+#
+# Usage:
+#   ./scripts/run-with-memory-limit.sh <memory_limit> <command...>
+#   ./scripts/run-with-memory-limit.sh 6G npm test
+#   ./scripts/run-with-memory-limit.sh 2G npm run test:unit
+
+set -euo pipefail
+
+MEMORY_LIMIT="${1:-6G}"
+shift
+
+if [[ $# -eq 0 ]]; then
+    echo "Usage: $0 <memory_limit> <command...>"
+    echo "Example: $0 6G npm test"
+    exit 1
+fi
+
+# Parse memory limit to bytes for ulimit fallback
+parse_memory_to_kb() {
+    local mem="$1"
+    local num="${mem%[GgMmKk]*}"
+    local unit="${mem: -1}"
+
+    case "$unit" in
+        G|g) echo $((num * 1024 * 1024)) ;;
+        M|m) echo $((num * 1024)) ;;
+        K|k) echo "$num" ;;
+        *)   echo "$mem" ;;  # Assume KB if no unit
+    esac
+}
+
+# Check systemd availability
+use_systemd() {
+    # Check if systemd-run exists and user session is available
+    command -v systemd-run >/dev/null 2>&1 && \
+    systemctl --user is-system-running >/dev/null 2>&1
+}
+
+# Check if running in WSL (systemd support varies)
+is_wsl() {
+    grep -qi microsoft /proc/version 2>/dev/null
+}
+
+echo "=== Memory-Limited Execution (ANTI-024) ==="
+echo "Limit: $MEMORY_LIMIT"
+echo "Command: $*"
+echo ""
+
+if use_systemd; then
+    echo "Using: systemd-run (cgroups v2)"
+    echo ""
+
+    # Run with systemd memory limit
+    # --user: run as current user
+    # --scope: transient scope (not a service)
+    # -p MemoryMax: hard memory limit
+    # -p MemorySwapMax=0: disable swap so OOM killer triggers at limit
+    exec systemd-run --user --scope \
+        -p MemoryMax="$MEMORY_LIMIT" \
+        -p MemorySwapMax=0 \
+        --description="CFN test run with memory limit" \
+        "$@"
+
+elif is_wsl; then
+    # WSL may not have full systemd support
+    echo "Using: ulimit (WSL detected, systemd unavailable)"
+    echo ""
+
+    MEM_KB=$(parse_memory_to_kb "$MEMORY_LIMIT")
+
+    # Set virtual memory limit (soft enforcement)
+    ulimit -v "$MEM_KB" 2>/dev/null || true
+
+    # Also set resident set size limit
+    ulimit -m "$MEM_KB" 2>/dev/null || true
+
+    exec "$@"
+
+else
+    echo "Using: ulimit (systemd unavailable)"
+    echo ""
+
+    MEM_KB=$(parse_memory_to_kb "$MEMORY_LIMIT")
+    ulimit -v "$MEM_KB" 2>/dev/null || true
+    ulimit -m "$MEM_KB" 2>/dev/null || true
+
+    exec "$@"
+fi

package/.claude/commands/cfn-loop/cfn-loop-cli.md

@@ -265,6 +265,15 @@ The orchestrator returns structured results:
 }
 ```
 
+## Validation Flow Summary
+
+1. **Loop 3 Gate:** Test pass rate must meet mode threshold before validators start
+2. **Loop 2 Validators:** Need access to Loop 3 outputs, tests, and logs
+3. **Product Owner Decision:** Parsed via `.claude/skills/product-owner-decision/execute-decision.sh`
+4. **Gate Failure:** Iterate Loop 3 only
+5. **Gate Pass:** Proceed to validators
+6. **Decision Outcomes:** PROCEED (done), ITERATE (repeat), ABORT (stop with error)
+
 This simplified architecture provides:
 - ✅ **Zero external dependencies** - runs anywhere Node.js is available
 - ✅ **Fast execution** - parallel decomposition and implementation

package/.claude/commands/cfn-loop-task.md

@@ -249,6 +249,17 @@ fi
 
 ---
 
+## Validation Flow Summary
+
+1. **Loop 3 Gate:** Test pass rate must meet mode threshold before validators start
+2. **Loop 2 Validators:** Need access to Loop 3 outputs, tests, and logs
+3. **Product Owner Decision:** Parsed via `.claude/skills/product-owner-decision/execute-decision.sh`
+4. **Gate Failure:** Iterate Loop 3 only
+5. **Gate Pass:** Proceed to validators
+6. **Decision Outcomes:** PROCEED (done), ITERATE (repeat), ABORT (stop with error)
+
+---
+
 ## Related Documentation
 
 - **Full Task Mode Guide**: `.claude/commands/cfn-loop/cfn-loop-task.md`

package/.claude/commands/cfn-ruvector/cfn-codebase-reindex.md

@@ -17,20 +17,39 @@ Add `--force` flag for complete reindex:
 - Major restructuring
 - Index issues
 
-**Prerequisites:**
-- OPENAI_API_KEY must be set: `export OPENAI_API_KEY="sk-..."`
+**Log file:** `/tmp/ruvector-index.log` - tail this for progress monitoring.
 
 ---
 
 Execute reindex:
 
 ```bash
+# --- FAIL-FAST: Validate OpenAI API Key ---
+# Always load from .env if current key is invalid (placeholder or missing)
+if [[ ! "$OPENAI_API_KEY" =~ ^sk- ]] && [[ -f ".env" ]]; then
+    export OPENAI_API_KEY=$(grep "^OPENAI_API_KEY=" .env | cut -d'=' -f2- | tr -d '"' | tr -d "'")
+fi
+
+# Final validation
+if [[ ! "$OPENAI_API_KEY" =~ ^sk- ]]; then
+    echo "❌ FATAL: Valid OPENAI_API_KEY not found." >&2
+    echo "   Add to .env: OPENAI_API_KEY=sk-..." >&2
+    exit 1
+fi
+
+echo "✅ OpenAI key: ${OPENAI_API_KEY:0:12}..."
+
+# --- Setup ---
 RUVECTOR_BIN="${HOME}/.local/bin/local-ruvector"
 [ ! -f "$RUVECTOR_BIN" ] && RUVECTOR_BIN="./.claude/skills/cfn-local-ruvector-accelerator/target/release/local-ruvector"
+LOG_FILE="/tmp/ruvector-index.log"
+
+echo "📝 Logging to: $LOG_FILE"
+echo "   Monitor with: tail -f $LOG_FILE"
 
 # Incremental (default - only changed files)
-"$RUVECTOR_BIN" index --path . --types rs,ts,js,py,sh,md
+"$RUVECTOR_BIN" index --path . --types rs,ts,js,py,sh,md 2>&1 | tee "$LOG_FILE"
 
 # Full rebuild (when needed)
-# "$RUVECTOR_BIN" index --path . --types rs,ts,js,py,sh,md --force
+# "$RUVECTOR_BIN" index --path . --types rs,ts,js,py,sh,md --force 2>&1 | tee "$LOG_FILE"
 ```

package/.claude/commands/cfn-ruvector/cfn-codebase-search.md

@@ -19,7 +19,7 @@ Search your indexed codebase using RuVector. Uses SQLite index for fast lookups.
 - `/cfn-ruvector:cfn-codebase-search database migration`
 
 **Prerequisites:**
-- Codebase must be indexed: `./local-ruvector index --path . --force`
+- Codebase must be indexed: `/cfn-codebase-reindex`
 - OPENAI_API_KEY must be set for indexing
 
 ---
@@ -27,7 +27,15 @@ Search your indexed codebase using RuVector. Uses SQLite index for fast lookups.
 Execute the search:
 
 ```bash
+# Load from .env if current key is invalid
+if [[ ! "$OPENAI_API_KEY" =~ ^sk- ]] && [[ -f ".env" ]]; then
+    export OPENAI_API_KEY=$(grep "^OPENAI_API_KEY=" .env | cut -d'=' -f2- | tr -d '"' | tr -d "'")
+fi
+[[ ! "$OPENAI_API_KEY" =~ ^sk- ]] && { echo "❌ OPENAI_API_KEY invalid. Add to .env" >&2; exit 1; }
+
 RUVECTOR_BIN="${HOME}/.local/bin/local-ruvector"
 [ ! -f "$RUVECTOR_BIN" ] && RUVECTOR_BIN="./.claude/skills/cfn-local-ruvector-accelerator/target/release/local-ruvector"
-"$RUVECTOR_BIN" query "{{query}}" --max-results {{#if top}}{{top}}{{else}}10{{/if}}
+
+# Use threshold 0.1 for better results (default 0.3 is too strict)
+"$RUVECTOR_BIN" query "{{query}}" --max-results {{#if top}}{{top}}{{else}}10{{/if}} --threshold 0.1
 ```

package/.claude/commands/cfn-ruvector/cfn-detect-stale-docs.md

@@ -29,13 +29,31 @@ Analyzes all `.md` files in the codebase to detect legacy/outdated documentation
 - Score 2-4: **POSSIBLY STALE** (minor issues)
 
 **Prerequisites:**
-- Codebase must be indexed first (`/codebase-reindex`)
-- ZAI_API_KEY must be set (for semantic search)
+- Codebase must be indexed first (`/cfn-codebase-reindex`)
+- OPENAI_API_KEY must be set (for semantic search)
 
 ---
 
-Run the stale documentation detector:
+**Note:** This is a planned feature. Currently use these manual queries:
 
 ```bash
-./.claude/skills/cfn-ruvector-codebase-index/detect-stale-docs.sh
+# Find docs older than 90 days with no recent code references
+sqlite3 ~/.local/share/ruvector/index_v2.db "
+SELECT e.file_path, e.name,
+       datetime(e.created_at, 'unixepoch') as indexed_at
+FROM entities e
+WHERE e.file_path LIKE '%.md'
+  AND e.project_root LIKE '%$(pwd)%'
+  AND (e.name LIKE '%legacy%' OR e.name LIKE '%deprecated%' OR e.name LIKE '%old%')
+LIMIT 20;"
+
+# Find orphan docs (no references)
+sqlite3 ~/.local/share/ruvector/index_v2.db "
+SELECT DISTINCT e.file_path
+FROM entities e
+LEFT JOIN refs r ON e.id = r.source_entity_id OR e.id = r.target_entity_id
+WHERE e.file_path LIKE '%.md'
+  AND e.project_root LIKE '%$(pwd)%'
+  AND r.id IS NULL
+LIMIT 20;"
 ```