claude-flow-novice 2.6.0 → 2.9.0

package/.claude/skills/redis-coordination/HEARTBEAT_MONITORING.md

@@ -1,267 +0,0 @@
-# Heartbeat Monitoring for CFN Loop Orchestration
-
-## Overview
-
-The orchestrator includes built-in heartbeat monitoring to detect hung or unresponsive agents during BLPOP waiting periods. This feature provides early warning of agent failures and enables quorum-aware decision making.
-
-## Features
-
-- **Periodic Health Checks**: Monitors agent heartbeats every 30 seconds
-- **Missed Beat Tracking**: Tracks consecutive missed heartbeats per agent
-- **Quorum-Aware Decisions**: Determines if the loop can continue without hung agents
-- **Automatic Recovery**: Resets counters when agents recover
-- **Graceful Shutdown**: Monitors stop cleanly when orchestrator shuts down
-
-## Architecture
-
-### Components
-
-1. **Heartbeat Check Function** (`check_agent_heartbeat`)
-   - Checks Redis key: `swarm:{task_id}:{agent_id}:heartbeat`
-   - Returns 0 if heartbeat exists, 1 if missing
-
-2. **Loop Health Check** (`check_heartbeats_loop`)
-   - Checks all agents in a loop
-   - Increments missed heartbeat counter
-   - Warns after 2 consecutive misses (60 seconds)
-   - Evaluates quorum impact
-
-3. **Background Monitor** (`start_heartbeat_monitor`)
-   - Runs in background subprocess
-   - Checks every 30 seconds
-   - Stops via marker file removal
-   - Respects SHUTDOWN_REQUESTED flag
-
-4. **Monitor Cleanup** (`stop_heartbeat_monitor`)
-   - Removes marker file
-   - Terminates background process
-   - Called during shutdown
-
-### Heartbeat Data Format
-
-```json
-{
-  "timestamp": 1760898665,
-  "status": "working",
-  "iteration": 1,
-  "task": "implementing feature X"
-}
-```
-
-## Usage
-
-### Agent Side (Publishing Heartbeats)
-
-Agents should publish heartbeats every 20-30 seconds:
-
-```bash
-# Set heartbeat with 60s TTL
-HEARTBEAT=$(jq -n \
-  --arg ts "$(date +%s)" \
-  --arg status "working" \
-  --arg iteration "1" \
-  '{timestamp: ($ts | tonumber), status: $status, iteration: ($iteration | tonumber)}')
-
-redis-cli SET "swarm:${TASK_ID}:${AGENT_ID}:heartbeat" "$HEARTBEAT" EX 60
-```
-
-### Orchestrator Side (Monitoring)
-
-The orchestrator automatically starts/stops monitors during each loop:
-
-```bash
-# Loop 3 monitoring
-LOOP3_HEARTBEAT_MONITOR_PID=$(start_heartbeat_monitor "$TASK_ID" "loop3" "${LOOP3_AGENTS[@]}")
-
-# ... wait for agents ...
-
-stop_heartbeat_monitor "$TASK_ID" "loop3" "$LOOP3_HEARTBEAT_MONITOR_PID"
-```
-
-## Monitoring Output
-
-### Normal Operation
-
-```
-[Loop 3] Starting heartbeat monitor (checking every 30s)...
-```
-
-### Agent Appears Hung
-
-```
-[2025-10-19T18:30:00Z] [loop3] ⚠️ agent-1 appears hung (no heartbeat for 60s)
-[2025-10-19T18:30:00Z] [loop3] ℹ️ Continuing with quorum (2/2 agents)
-```
-
-### Quorum at Risk
-
-```
-[2025-10-19T18:30:00Z] [loop3] ⚠️ agent-2 appears hung (no heartbeat for 60s)
-[2025-10-19T18:30:00Z] [loop3] ⚠️ Cannot meet quorum without agent-2 (1/2)
-```
-
-## Configuration
-
-### Monitoring Interval
-
-Default: 30 seconds
-
-To change, edit the `sleep` duration in `start_heartbeat_monitor`:
-
-```bash
-sleep 30  # Check every 30s
-```
-
-### Missed Heartbeat Threshold
-
-Default: 2 consecutive misses (60 seconds)
-
-To change, edit the threshold in `check_heartbeats_loop`:
-
-```bash
-if [ ${MISSED_HEARTBEATS["$AGENT"]} -ge 2 ]; then
-```
-
-### Heartbeat TTL
-
-Default: 60 seconds
-
-Agents should set TTL when publishing:
-
-```bash
-redis-cli SET "swarm:${TASK_ID}:${AGENT_ID}:heartbeat" "$DATA" EX 60
-```
-
-## Integration Points
-
-### Cleanup Handler
-
-Monitors are automatically stopped during shutdown:
-
-```bash
-function cleanup_and_exit() {
-  # Stop heartbeat monitors if running
-  if [ -n "${LOOP3_HEARTBEAT_MONITOR_PID:-}" ]; then
-    stop_heartbeat_monitor "$TASK_ID" "loop3" "$LOOP3_HEARTBEAT_MONITOR_PID"
-  fi
-  if [ -n "${LOOP2_HEARTBEAT_MONITOR_PID:-}" ]; then
-    stop_heartbeat_monitor "$TASK_ID" "loop2" "$LOOP2_HEARTBEAT_MONITOR_PID"
-  fi
-}
-```
-
-### Global Variables
-
-```bash
-LOOP3_HEARTBEAT_MONITOR_PID=""
-LOOP2_HEARTBEAT_MONITOR_PID=""
-declare -A MISSED_HEARTBEATS
-```
-
-## Testing
-
-### Unit Tests
-
-```bash
-./.claude/skills/redis-coordination/tests/test-heartbeat-simple.sh
-```
-
-Tests:
-1. Active heartbeat detection
-2. Missing heartbeat detection
-3. Missed heartbeat counter increment
-4. Counter reset on recovery
-
-### Manual Testing
-
-```bash
-# Set up test heartbeat
-redis-cli SET "swarm:test-task:test-agent:heartbeat" '{"timestamp": 1234567890}' EX 60
-
-# Source functions
-source ./.claude/skills/redis-coordination/heartbeat-functions.sh
-
-# Check heartbeat
-check_agent_heartbeat "test-agent" "test-task"
-echo $?  # Should be 0 (success)
-```
-
-## Best Practices
-
-### For Agents
-
-1. **Publish regularly**: Every 20-30 seconds
-2. **Use appropriate TTL**: 60 seconds (2x publish interval)
-3. **Include metadata**: Status, iteration, current task
-4. **Handle errors**: Continue if Redis unavailable
-
-### For Orchestrators
-
-1. **Start monitors early**: Before waiting for agents
-2. **Stop monitors promptly**: After agents complete
-3. **Check quorum impact**: Before making decisions
-4. **Log appropriately**: Warn for hung agents, not for normal timeouts
-
-## Troubleshooting
-
-### Monitor Not Detecting Hung Agents
-
-**Symptoms**: Agents appear hung but no warnings
-
-**Causes**:
-1. Monitor not started
-2. Heartbeat check interval too long
-3. Missed heartbeat threshold too high
-
-**Solutions**:
-- Verify monitor PID is set
-- Check monitor marker file exists
-- Review threshold values
-
-### False Positives
-
-**Symptoms**: Warnings for healthy agents
-
-**Causes**:
-1. Heartbeat publish interval too long
-2. Heartbeat TTL too short
-3. Network latency issues
-
-**Solutions**:
-- Reduce heartbeat interval (e.g., 15s)
-- Increase TTL (e.g., 90s)
-- Increase missed heartbeat threshold
-
-### Monitor Not Stopping
-
-**Symptoms**: Background processes remain after completion
-
-**Causes**:
-1. Marker file not removed
-2. Process not killed
-3. Cleanup not called
-
-**Solutions**:
-- Check for marker files: `ls /tmp/heartbeat-monitor-*.active`
-- Kill processes: `pkill -f heartbeat-monitor`
-- Verify cleanup handler is registered
-
-## Performance Impact
-
-- **CPU**: Negligible (~0.01% per monitor)
-- **Network**: ~1 Redis GET per agent per 30s
-- **Memory**: ~1KB per agent for tracking state
-
-## Future Enhancements
-
-1. **Adaptive Intervals**: Reduce check frequency for stable agents
-2. **Health Scores**: Track reliability over time
-3. **Auto-Retry**: Wake hung agents with lower priority
-4. **Metrics Export**: Publish heartbeat stats to monitoring system
-5. **Dead Letter Queue Integration**: Automatic DLQ writes for consistently hung agents
-
-## Related Documentation
-
-- [Redis Coordination Skill](./SKILL.md)
-- [CFN Loop Orchestration](./orchestrate-cfn-loop.sh)
-- [Waiting Mode Documentation](../../CLAUDE.md#redis-waiting-mode-zero-token-agent-coordination)

package/.claude/skills/redis-coordination/README.md

@@ -1,64 +0,0 @@
-# Redis Coordination Skill
-
-## Quick Start
-
-### Prerequisites
-- Redis 5.0+
-- bash
-- jq
-- redis-cli
-
-### Installation
-1. Ensure Redis is running
-2. Configure Redis connection in `config.json`
-3. Make scripts executable:
-```bash
-chmod +x invoke-redis-pattern.sh test-waiting-mode.sh
-```
-
-### Basic Usage
-
-#### Waiting Mode
-```bash
-# Agent enters waiting mode
-./invoke-redis-pattern.sh wait \
-  --task-id "my-task" \
-  --agent-id "agent-1" \
-  --context "iteration-1"
-
-# Coordinator wakes agent
-./invoke-redis-pattern.sh wake \
-  --task-id "my-task" \
-  --agent-id "agent-1" \
-  --payload '{"instruction": "proceed"}'
-```
-
-#### Consensus Collection
-```bash
-# Multiple agents report results
-./invoke-redis-pattern.sh report \
-  --task-id "my-task" \
-  --agent-id "agent-1" \
-  --confidence 0.95 \
-  --result '{"status": "completed"}'
-
-# Collect and evaluate consensus
-./invoke-redis-pattern.sh collect \
-  --task-id "my-task" \
-  --agent-ids "agent-1,agent-2,agent-3"
-```
-
-## Testing
-Run comprehensive tests:
-```bash
-./test-waiting-mode.sh
-```
-
-## Configuration Options
-See `SKILL.md` for detailed configuration and usage instructions.
-
-## Performance
-- Zero-token waiting
-- Sub-100ms wake-up latency
-- Supports 10+ concurrent agents
-- Configurable consensus thresholds

package/.claude/skills/redis-coordination/SECURITY_REVIEW.md

@@ -1,25 +0,0 @@
-# Security Review: Metrics Export System (Phase 7)
-
-## Overview
-Security review conducted by security-specialist-3 for Redis Coordination metrics export functionality.
-
-## Confidence Score: 0.92 (High)
-
-### Key Findings
-- ✅ Robust input validation
-- ✅ Secure file handling
-- ✅ Minimal data exposure
-- ⚠️ Recommended ACL improvements
-
-### Recommendations
-1. Implement optional PII sanitization
-2. Enhance Redis key access controls
-3. Create metrics export audit logging
-4. Add optional export encryption
-
-### Compliance
-- NIST SP 800-53 Alignment: Moderate Impact
-- SOC 2 Type II Ready
-- GDPR Data Minimization Compliant
-
-Full detailed report available in source code comments.

package/.claude/skills/redis-coordination/SHUTDOWN_HANDLING.md

@@ -1,164 +0,0 @@
-# Shutdown Handling for Waiting Agents
-
-## Overview
-
-Agents in waiting mode can now listen for shutdown signals and exit gracefully with proper cleanup. This enables coordinators to terminate long-running tasks without leaving orphaned agents in the system.
-
-## Implementation Details
-
-### Multi-Key Monitoring
-
-Agents in waiting mode now monitor **two** Redis keys simultaneously:
-1. **Wake Queue**: `swarm:{task-id}:{agent-id}:wake-queue` (priority queue for wake signals)
-2. **Shutdown Key**: `swarm:{task-id}:shutdown` (broadcast shutdown signal)
-
-### Polling Strategy
-
-Since Redis `BZPOPMIN` doesn't support multiple keys, we implement a polling loop:
-
-```bash
-while true; do
-    # Check shutdown first (highest priority)
-    SHUTDOWN_CHECK=$(redis-cli LPOP "swarm:${TASK_ID}:shutdown")
-
-    if shutdown_detected; then
-        exit 130  # SIGINT code for graceful shutdown
-    fi
-
-    # Block on wake queue with 1-second timeout
-    WAKE_RESULT=$(redis-cli BZPOPMIN "$WAKE_QUEUE" 1)
-
-    if wake_received; then
-        process_wake_signal
-        break
-    fi
-done
-```
-
-### Exit Code Convention
-
-- **Exit Code 130**: Graceful shutdown via shutdown signal (SIGINT equivalent)
-- **Exit Code 0**: Normal completion after wake signal
-
-## Usage
-
-### Coordinator Broadcasts Shutdown
-
-```bash
-./invoke-waiting-mode.sh shutdown \
-  --task-id "auth-system" \
-  --reason "task_complete"
-```
-
-**Broadcast Behavior:**
-- Shutdown signal is added to `swarm:{task-id}:shutdown` key
-- All agents monitoring this task will receive the signal on their next poll cycle (max 1 second latency)
-- Multiple agents can be shutdown with a single broadcast
-
-### Agent Enters Waiting Mode
-
-```bash
-./invoke-waiting-mode.sh enter \
-  --task-id "auth-system" \
-  --agent-id "coder-1" \
-  --context "iteration-1"
-```
-
-**Agent will:**
-1. Publish ready status to Redis
-2. Enter polling loop monitoring both wake queue and shutdown key
-3. Check shutdown key first (highest priority)
-4. Block on wake queue with 1-second timeout
-5. Exit with code 130 if shutdown signal received
-6. Continue normally if wake signal received
-
-## Priority Behavior
-
-**Shutdown signals have HIGHEST priority:**
-- Checked **before** wake queue on every poll cycle
-- Even if wake signals are in the queue, shutdown is processed first
-- Ensures clean task termination
-
-## Performance Characteristics
-
-- **Latency**: Max 1 second to detect shutdown (BZPOPMIN timeout)
-- **Cost**: Still zero tokens during waiting (BZPOPMIN blocks, LPOP is instant)
-- **Overhead**: Minimal - one LPOP per second for shutdown check
-
-## Test Results
-
-```bash
-bash .claude/skills/redis-coordination/test-shutdown.sh
-```
-
-**Test Coverage:**
-1. ✅ Agent enters waiting mode successfully
-2. ✅ Agent receives shutdown signal and exits with code 130
-3. ✅ Shutdown signal is broadcasted properly
-4. ✅ Agent terminates gracefully within 1-2 seconds
-
-## Integration Examples
-
-### CFN Loop Coordinator
-
-```bash
-# After consensus reached or max iterations
-./invoke-waiting-mode.sh shutdown \
-  --task-id "$TASK_ID" \
-  --reason "cfn_loop_complete"
-
-echo "All agents notified of task completion"
-```
-
-### Emergency Shutdown
-
-```bash
-# Abort all agents in a task
-./invoke-waiting-mode.sh shutdown \
-  --task-id "$TASK_ID" \
-  --reason "emergency_abort"
-```
-
-### Timeout Management
-
-```bash
-# Coordinator timeout
-timeout 300 ./my-coordination-script.sh || {
-  echo "Coordinator timeout - sending shutdown to all agents"
-  ./invoke-waiting-mode.sh shutdown \
-    --task-id "$TASK_ID" \
-    --reason "coordinator_timeout"
-}
-```
-
-## File Changes
-
-**Modified:**
-- `/mnt/c/Users/masha/Documents/claude-flow-novice/.claude/skills/redis-coordination/invoke-waiting-mode.sh`
-
-**Added:**
-- `shutdown` command for broadcasting shutdown signals
-- Multi-key monitoring in `enter` command
-- Polling loop with shutdown priority
-- Exit code 130 convention for graceful shutdown
-
-**Test Suite:**
-- `/mnt/c/Users/masha/Documents/claude-flow-novice/.claude/skills/redis-coordination/test-shutdown.sh`
-
-## Benefits
-
-1. **Graceful Cleanup**: Agents exit cleanly instead of hanging indefinitely
-2. **Broadcast Efficiency**: Single shutdown command affects all agents
-3. **Priority Handling**: Shutdown always takes precedence over wake signals
-4. **Zero Token Cost**: Still maintains efficient blocking while waiting
-5. **Fast Response**: Max 1 second latency to detect shutdown
-
-## Future Enhancements
-
-Potential improvements for future iterations:
-
-1. **Agent-Specific Shutdown**: Target individual agents instead of broadcast
-2. **Shutdown Acknowledgement**: Agents report shutdown receipt before exiting
-3. **Lua Script Optimization**: Atomic shutdown check + wake queue pop
-4. **Timeout Configuration**: Configurable poll timeout instead of hardcoded 1 second
-5. **Shutdown Reason Logging**: Persist shutdown events to Redis for audit trail

package/.claude/skills/redis-coordination/SKILL.md

@@ -1,118 +0,0 @@
-# Redis Coordination Skill
-
-[... previous content ...]
-
-## Metrics & Observability (v2.0.0)
-
-### Overview
-
-The Redis Coordination Skill provides comprehensive metrics and observability features to monitor distributed coordination performance, track system health, and enable advanced analytics.
-
-### Metrics Configuration
-
-```json
-{
-  "metrics": {
-    "enabled": true,
-    "retention": 604800,          // 7 days of metric retention
-    "export_formats": [
-      "json",                     // Lightweight JSON export
-      "prometheus"                // Prometheus-compatible metrics
-    ]
-  }
-}
-```
-
-### Collected Metrics
-
-#### System Performance Metrics
-- `redis_coordination_task_latency`: Latency for task coordination
-  - Labels: `task_id`, `agent_id`, `operation_type`
-  - Unit: Milliseconds
-  - Description: Time taken to complete coordination operations
-
-- `redis_coordination_waiting_mode_duration`: Duration of agent waiting mode
-  - Labels: `task_id`, `agent_id`, `iteration`
-  - Unit: Seconds
-  - Description: Time agents spend in waiting state
-
-#### Coordination Metrics
-- `redis_coordination_consensus_score`: Consensus calculation metrics
-  - Labels: `task_id`, `loop_stage`
-  - Range: 0.0 - 1.0
-  - Description: Real-time consensus calculation progress
-
-- `redis_coordination_retry_count`: Retry mechanism tracking
-  - Labels: `task_id`, `operation`, `reason`
-  - Unit: Count
-  - Description: Number of retries for different coordination operations
-
-#### Agent Health Metrics
-- `redis_agent_heartbeat_status`: Agent heartbeat status
-  - Labels: `task_id`, `agent_id`, `status`
-  - Values: 0 (Failed), 1 (Active)
-  - Description: Tracks individual agent health
-
-- `redis_agent_replacement_count`: Agent replacement tracking
-  - Labels: `task_id`, `original_agent_id`, `replacement_agent_id`
-  - Unit: Count
-  - Description: Tracks automatic agent replacements
-
-### Export Examples
-
-#### JSON Export
-```bash
-# Export metrics to JSON
-./.claude/skills/redis-coordination/export-metrics.sh \
-  --format json \
-  --output /var/log/claude-flow/metrics-$(date +%Y%m%d).json \
-  --retention 7 \
-  --compress
-```
-
-#### Prometheus Export
-```bash
-# Export metrics for Prometheus scraping
-./.claude/skills/redis-coordination/export-metrics.sh \
-  --format prometheus \
-  --output /var/lib/prometheus/redis_coordination_metrics.prom
-```
-
-### Grafana Dashboard Integration
-
-**Dashboard URL:** `https://grafana.claude-flow.ai/dashboards/redis-coordination`
-
-**Key Visualization Panels:**
-1. Task Latency Heatmap
-2. Consensus Score Trends
-3. Agent Health Overview
-4. Retry and Fallback Analysis
-
-### Monitoring Best Practices
-
-1. Set up real-time alerting for:
-   - Consensus score below threshold
-   - High retry rates
-   - Repeated agent replacements
-
-2. Use retention and rotation to manage metric storage
-3. Implement secure, read-only metric access
-4. Correlate metrics with logs for deep insights
-
-### Security Considerations
-- Metrics do not expose sensitive task details
-- Anonymized agent tracking
-- Configurable metric retention
-
-### Performance Impact
-- Minimal overhead (<1% CPU)
-- Configurable metric collection
-- Zero-token metric tracking
-
-### Version Information
-- **Version:** 2.0.0
-- **Metrics Support:** Full
-- **Export Formats:** JSON, Prometheus
-- **Last Updated:** 2025-10-19
-
-[... rest of the previous content remains the same ...]