claude-flow-novice 2.8.1 → 2.9.0

package/.claude/skills/loop3-output-processing/AGENT_COMPLETION_PROTOCOL.md

@@ -1,206 +0,0 @@
-# Agent Completion Protocol Implementation
-
-## Overview
-
-This implementation adds robust timeout handling and process monitoring to the Redis Coordination orchestrator, preventing indefinite blocking when agents crash or fail to signal completion.
-
-## Problem Solved
-
-**Issue:** If an agent doesn't execute `redis-cli lpush "swarm:${TASK_ID}:${AGENT_ID}:done" "complete"`, the orchestrator blocks forever on BLPOP.
-
-**Root Causes:**
-- Agent process crashes without cleanup
-- Bash script errors before reaching done signal
-- Agent gets stuck in infinite loop
-- Network issues preventing Redis communication
-
-## Implementation
-
-### Files Modified
-
-1. **orchestrate-cfn-loop.sh** - Core orchestration script
-   - Added `monitor_agent_process()` function (lines ~498-529)
-   - Enhanced `blpop_with_retry()` with PID tracking (lines ~534-620)
-   - Updated Loop 3 spawning to track PIDs and start monitors (lines ~751-775)
-   - Updated Loop 2 spawning to track PIDs and start monitors (lines ~1032-1056)
-   - Modified BLPOP calls to include PID parameter (lines ~805, ~1086)
-
-2. **send-heartbeat.sh** - Heartbeat utility
-   - Added start/stop/once modes for continuous heartbeat
-   - Backward compatible with original one-shot behavior
-   - Supports custom intervals and TTLs
-
-3. **SKILL.md** - Documentation
-   - Added "Agent Completion Protocol (v2.1.0)" section
-   - Comprehensive usage examples
-   - Metrics and test coverage documentation
-
-### Files Created
-
-1. **test-agent-timeout.sh** - Test suite
-   - Test 1: Normal agent completion
-   - Test 2: Agent exits with error (auto-completion)
-   - Test 3: Agent stuck without heartbeat (timeout kill)
-   - Test 4: Agent with continuous heartbeat (no timeout)
-
-## Three-Layer Protection
-
-### Layer 1: Process-Based Completion Detection
-
-**What it does:**
-- Monitors agent process in background
-- Auto-signals completion when process exits
-- Captures exit code for debugging
-
-**Implementation:**
-```bash
-monitor_agent_process "$AGENT_ID" "$AGENT_PID" "$TASK_ID" "$DONE_KEY"
-```
-
-**Auto-completion signals:**
-- Exit code 0: `auto-completed-success`
-- Exit code non-zero: `auto-completed-error:<code>`
-
-### Layer 2: BLPOP with Process Status Checks
-
-**What it does:**
-- Enhanced BLPOP retry logic
-- Checks if process is still alive on timeout
-- Retrieves auto-completion signals from dead processes
-
-**Implementation:**
-```bash
-blpop_with_retry "$AGENT_ID" "$DONE_KEY" "$TIMEOUT" "$RETRY_COUNT" "$RETRY_DELAY" "$AGENT_PID"
-```
-
-**Behavior on timeout:**
-1. BLPOP times out (no signal)
-2. Check: `kill -0 $AGENT_PID`
-3. If dead: Check for auto-completion signal
-4. If alive: Continue retry logic
-
-### Layer 3: Heartbeat Monitoring (Optional)
-
-**What it does:**
-- Agents send periodic heartbeats
-- Orchestrator checks heartbeat on timeout
-- Kills stuck processes with no heartbeat
-
-**Agent usage:**
-```bash
-# Start heartbeat
-./.claude/skills/redis-coordination/send-heartbeat.sh start \
-  --task-id "$TASK_ID" \
-  --agent-id "$AGENT_ID" \
-  --interval 30 &
-HEARTBEAT_PID=$!
-
-# ... do work ...
-
-# Stop heartbeat
-./.claude/skills/redis-coordination/send-heartbeat.sh stop \
-  --task-id "$TASK_ID" \
-  --agent-id "$AGENT_ID" \
-  --pid "$HEARTBEAT_PID"
-```
-
-**Orchestrator behavior:**
-- No heartbeat for 2 intervals (60s) → Consider agent stuck
-- Stuck + alive → Kill process with SIGTERM/SIGKILL
-
-## Metrics
-
-New metrics collected:
-
-- `swarm:{TASK_ID}:metrics:agent_errors` - Agents that exited with errors
-- `swarm:{TASK_ID}:metrics:agent_killed` - Stuck agents killed by timeout
-- `swarm:{TASK_ID}:metrics:timeout_count` - BLPOP timeouts
-- `swarm:{TASK_ID}:metrics:retry_count` - Retry attempts
-
-## Testing
-
-Run the test suite:
-
-```bash
-./.claude/skills/loop3-output-processing/test-agent-timeout.sh
-```
-
-**Expected output:**
-```
-=== Agent Completion Protocol Test ===
-Task ID: test-timeout-1729517234
-
-[Test 1] Agent completes successfully and signals done
-  ✅ PASS: Agent signaled completion
-
-[Test 2] Agent exits with error - process monitor auto-completes
-  ✅ PASS: Process monitor auto-completed with error
-
-[Test 3] Agent stuck without heartbeat - orchestrator kills process
-  ✅ PASS: Stuck process was killed by timeout logic
-
-[Test 4] Agent with continuous heartbeat - no timeout
-  ✅ PASS: Heartbeat active after 5 seconds
-
-=== Test Summary ===
-Passed: 4
-Failed: 0
-✅ ALL TESTS PASSED
-```
-
-## Benefits
-
-1. **No indefinite blocking** - Orchestrator never hangs on dead agents
-2. **Automatic cleanup** - Dead processes auto-complete without intervention
-3. **Graceful degradation** - System continues with quorum if some agents fail
-4. **Debugging support** - Exit codes and metrics identify failure patterns
-5. **Zero token waste** - No API calls for stuck agents
-6. **Backward compatible** - Agents work without heartbeats
-7. **Optional enhancement** - Heartbeats only for long-running agents
-
-## Migration Guide
-
-### For Agent Developers
-
-**No changes required!** The protocol works automatically with existing agents.
-
-**Optional enhancement** (for long-running agents >5 minutes):
-
-```bash
-# Add heartbeat at start of agent script
-./.claude/skills/redis-coordination/send-heartbeat.sh start \
-  --task-id "$TASK_ID" \
-  --agent-id "$AGENT_ID" \
-  --interval 30 &
-HEARTBEAT_PID=$!
-
-# Add cleanup at end
-./.claude/skills/redis-coordination/send-heartbeat.sh stop \
-  --task-id "$TASK_ID" \
-  --agent-id "$AGENT_ID" \
-  --pid "$HEARTBEAT_PID"
-```
-
-### For Orchestrator Operators
-
-**No changes required!** Process monitoring is automatic for all CLI-spawned agents.
-
-**Monitoring:**
-- Check metrics for `agent_errors` and `agent_killed` counts
-- High kill rates may indicate agent bugs or resource issues
-
-## Version History
-
-- **v2.1.0** (2025-10-20) - Agent Completion Protocol implementation
-  - Process-based completion detection
-  - Enhanced BLPOP with PID tracking
-  - Continuous heartbeat support
-  - Comprehensive test suite
-
-## References
-
-- Implementation: `.claude/skills/redis-coordination/orchestrate-cfn-loop.sh`
-- Documentation: `.claude/skills/redis-coordination/SKILL.md`
-- Tests: `.claude/skills/loop3-output-processing/test-agent-timeout.sh`
-- Heartbeat: `.claude/skills/redis-coordination/send-heartbeat.sh`
-- Requirements: `docs/SKILL_ENFORCEMENT_OPPORTUNITIES.md` (Section 4)

package/.claude/skills/loop3-output-processing/SKILL.md

@@ -1,421 +0,0 @@
-# Loop 3 Output Processing Skill
-
-**Version:** 1.0.0
-**Status:** Production
-**Purpose:** Guaranteed confidence extraction from Loop 3 implementer agents
-
----
-
-## Overview
-
-**Problem Solved:** Loop 3 agents (coders, researchers, developers) might document bash commands instead of executing them, leading to missing confidence scores.
-
-**Solution:** Orchestrator-controlled output processing with:
-- Multi-pattern confidence extraction
-- Git-based deliverable verification
-- Calculated confidence fallback
-- Guaranteed Redis reporting
-
----
-
-## Core Principle
-
-```
-Loop 3 Agents → Focus on implementation
-This Skill → Extract confidence + verify deliverables
-Orchestrator → Report to Redis + gate check
-```
-
-**Why This Works:**
-- ✅ Agents implement features (what they do best)
-- ✅ Skill extracts confidence (robust parsing)
-- ✅ Orchestrator controls coordination (Redis state)
-- ✅ No reliance on agent bash execution
-
----
-
-## Architecture
-
-### Processing Flow
-
-```
-1. Orchestrator spawns Loop 3 agent
-2. Skill captures agent stdout/stderr
-3. Skill parses confidence (multi-pattern)
-4. Skill verifies deliverables (git status)
-5. Skill calculates fallback confidence
-6. Skill reports to Redis
-7. Orchestrator uses for gate check
-```
-
-### Skill Components
-
-```
-.claude/skills/loop3-output-processing/
-├── SKILL.md                        # This file
-├── execute-and-extract.sh          # Main wrapper script
-├── parse-confidence.sh             # Confidence pattern matching
-├── verify-deliverables.sh          # Git-based verification
-├── calculate-confidence.sh         # Fallback calculation
-└── test-loop3-processing.sh        # Integration tests
-```
-
----
-
-## Confidence Extraction Patterns
-
-### Priority 1: Explicit Confidence Statement
-```
-Confidence: 0.85
-confidence: 0.92
-Confidence Score: 0.78
-```
-
-### Priority 2: Percentage Format
-```
-I'm 85% confident
-Confidence: 92%
-```
-
-### Priority 3: Natural Language
-```
-I'm very confident (0.9)
-High confidence: 0.85
-```
-
-### Priority 4: Calculated from Deliverables
-```bash
-# If no confidence found, calculate based on:
-- Files created/modified (git status)
-- Tests passing (if applicable)
-- Build success (if applicable)
-```
-
-**Fallback Logic:**
-- 0 files changed → 0.0
-- 1-2 files, no tests → 0.50
-- 3+ files, tests pass → 0.85
-- Complete deliverables → 0.90
-
----
-
-## Usage
-
-### From Orchestrator
-
-```bash
-# Spawn Loop 3 agent with output processing
-RESULT=$(./.claude/skills/loop3-output-processing/execute-and-extract.sh \
-  --agent-type "coder" \
-  --task-id "$TASK_ID" \
-  --agent-id "coder-1" \
-  --context "Implement authentication" \
-  --iteration 1)
-
-CONFIDENCE=$(echo "$RESULT" | jq -r '.confidence')
-FILES_CHANGED=$(echo "$RESULT" | jq -r '.files_changed')
-DELIVERABLES=$(echo "$RESULT" | jq -r '.deliverables[]')
-
-# Report to Redis (orchestrator does this, not agent)
-redis-cli LPUSH "swarm:${TASK_ID}:coder-1:confidence" "$CONFIDENCE"
-redis-cli LPUSH "swarm:${TASK_ID}:coder-1:done" "complete"
-```
-
-### Output Format
-
-```json
-{
-  "agent_id": "coder-1",
-  "confidence": 0.85,
-  "confidence_source": "explicit|calculated|fallback",
-  "files_changed": 5,
-  "deliverables": [
-    "src/auth/login.ts (A)",
-    "src/auth/register.ts (A)",
-    "tests/auth.test.ts (A)"
-  ],
-  "tests_passed": true,
-  "iteration": 1,
-  "timestamp": "2025-10-20T15:30:00Z"
-}
-```
-
----
-
-## Implementation
-
-### execute-and-extract.sh
-
-```bash
-#!/bin/bash
-set -euo pipefail
-
-# Parse arguments
-AGENT_TYPE=""
-TASK_ID=""
-AGENT_ID=""
-CONTEXT=""
-ITERATION=1
-TIMEOUT=900
-
-while [[ $# -gt 0 ]]; do
-  case $1 in
-    --agent-type) AGENT_TYPE="$2"; shift 2 ;;
-    --task-id) TASK_ID="$2"; shift 2 ;;
-    --agent-id) AGENT_ID="$2"; shift 2 ;;
-    --context) CONTEXT="$2"; shift 2 ;;
-    --iteration) ITERATION="$2"; shift 2 ;;
-    --timeout) TIMEOUT="$2"; shift 2 ;;
-    *) echo "Unknown: $1"; exit 1 ;;
-  esac
-done
-
-SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-
-# Capture git state before agent runs
-BEFORE_GIT=$(git status --short)
-
-# Spawn agent and capture output
-AGENT_OUTPUT=$(timeout "$TIMEOUT" npx claude-flow-novice agent "$AGENT_TYPE" \
-  --task-id "$TASK_ID" \
-  --agent-id "$AGENT_ID" \
-  --context "$CONTEXT" 2>&1 || true)
-
-# Capture git state after agent runs
-AFTER_GIT=$(git status --short)
-
-# Parse confidence from output
-CONFIDENCE=$("$SCRIPT_DIR/parse-confidence.sh" "$AGENT_OUTPUT")
-
-# Verify deliverables
-DELIVERABLE_CHECK=$("$SCRIPT_DIR/verify-deliverables.sh" \
-  --before "$BEFORE_GIT" \
-  --after "$AFTER_GIT")
-
-FILES_CHANGED=$(echo "$DELIVERABLE_CHECK" | jq -r '.files_changed')
-DELIVERABLES=$(echo "$DELIVERABLE_CHECK" | jq -r '.deliverables')
-
-# If confidence not found or too low, calculate fallback
-if (( $(echo "$CONFIDENCE == 0.0" | bc -l) )) || [ -z "$CONFIDENCE" ]; then
-  CONFIDENCE=$("$SCRIPT_DIR/calculate-confidence.sh" \
-    --files-changed "$FILES_CHANGED" \
-    --deliverables "$DELIVERABLES")
-  CONFIDENCE_SOURCE="calculated"
-elif (( $(echo "$CONFIDENCE > 0.0" | bc -l) )); then
-  CONFIDENCE_SOURCE="explicit"
-else
-  CONFIDENCE_SOURCE="fallback"
-fi
-
-# Build output JSON
-cat <<EOF
-{
-  "agent_id": "$AGENT_ID",
-  "confidence": $CONFIDENCE,
-  "confidence_source": "$CONFIDENCE_SOURCE",
-  "files_changed": $FILES_CHANGED,
-  "deliverables": $DELIVERABLES,
-  "iteration": $ITERATION,
-  "timestamp": "$(date -u +%Y-%m-%dT%H:%M:%SZ)"
-}
-EOF
-```
-
-### parse-confidence.sh
-
-```bash
-#!/bin/bash
-set -euo pipefail
-
-OUTPUT="$1"
-
-# Pattern 1: Explicit confidence (0.0-1.0)
-if echo "$OUTPUT" | grep -oP '[Cc]onfidence[:\s]*([0-9.]+)' | grep -oP '([0-9.]+)' | head -1; then
-  exit 0
-fi
-
-# Pattern 2: Percentage (85%)
-if PERCENT=$(echo "$OUTPUT" | grep -oP '([0-9]{1,3})%' | grep -oP '[0-9]+' | head -1); then
-  echo "scale=2; $PERCENT / 100" | bc
-  exit 0
-fi
-
-# Pattern 3: Natural language with score
-if echo "$OUTPUT" | grep -oP '\(([0-9.]+)\)' | grep -oP '[0-9.]+' | head -1; then
-  exit 0
-fi
-
-# No confidence found
-echo "0.0"
-```
-
-### verify-deliverables.sh
-
-```bash
-#!/bin/bash
-set -euo pipefail
-
-BEFORE=""
-AFTER=""
-
-while [[ $# -gt 0 ]]; do
-  case $1 in
-    --before) BEFORE="$2"; shift 2 ;;
-    --after) AFTER="$2"; shift 2 ;;
-    *) echo "Unknown: $1"; exit 1 ;;
-  esac
-done
-
-# Find new/modified files
-CHANGED_FILES=$(comm -13 <(echo "$BEFORE" | sort) <(echo "$AFTER" | sort) || true)
-FILE_COUNT=$(echo "$CHANGED_FILES" | grep -c '^' || echo "0")
-
-# Build deliverables array
-DELIVERABLES="["
-FIRST=true
-while IFS= read -r line; do
-  if [ -n "$line" ]; then
-    if [ "$FIRST" = true ]; then
-      FIRST=false
-    else
-      DELIVERABLES+=","
-    fi
-    DELIVERABLES+="\"$line\""
-  fi
-done <<< "$CHANGED_FILES"
-DELIVERABLES+="]"
-
-# Output JSON
-cat <<EOF
-{
-  "files_changed": $FILE_COUNT,
-  "deliverables": $DELIVERABLES
-}
-EOF
-```
-
-### calculate-confidence.sh
-
-```bash
-#!/bin/bash
-set -euo pipefail
-
-FILES_CHANGED=0
-DELIVERABLES="[]"
-
-while [[ $# -gt 0 ]]; do
-  case $1 in
-    --files-changed) FILES_CHANGED="$2"; shift 2 ;;
-    --deliverables) DELIVERABLES="$2"; shift 2 ;;
-    *) echo "Unknown: $1"; exit 1 ;;
-  esac
-done
-
-# Calculate confidence based on deliverables
-if (( FILES_CHANGED == 0 )); then
-  echo "0.0"
-elif (( FILES_CHANGED <= 2 )); then
-  echo "0.50"
-elif (( FILES_CHANGED <= 5 )); then
-  echo "0.75"
-else
-  echo "0.85"
-fi
-```
-
----
-
-## Benefits
-
-| Aspect | Before (Template-Based) | After (Skill-Based) |
-|--------|------------------------|---------------------|
-| **Confidence Guarantee** | ❌ 0.0 if agent doesn't execute | ✅ Always calculated |
-| **Deliverable Verification** | ❌ Agent-dependent | ✅ Git-based proof |
-| **Parsing Robustness** | ❌ None | ✅ 4 fallback patterns |
-| **Redis Coordination** | ❌ Agent reports (maybe) | ✅ Orchestrator reports |
-| **Race Conditions** | ❌ Polling wait needed | ✅ Synchronous processing |
-| **Testability** | ❌ Hard to test | ✅ Unit testable |
-
----
-
-## Testing
-
-### Unit Tests
-
-```bash
-# Test confidence parsing
-./test-parse-confidence.sh
-
-# Test deliverable verification
-./test-verify-deliverables.sh
-
-# Test confidence calculation
-./test-calculate-confidence.sh
-```
-
-### Integration Test
-
-```bash
-# Test full Loop 3 processing
-./test-loop3-processing.sh
-```
-
-**Expected Results:**
-- ✅ Explicit confidence extracted correctly
-- ✅ Percentage converted to decimal
-- ✅ Fallback calculation works
-- ✅ Deliverables verified via git
-- ✅ JSON output valid
-
----
-
-## Integration with Orchestrator
-
-### Before (BUG #10 Pattern)
-
-```bash
-# Spawn agents, wait, poll for confidence
-spawn_all_loop3_agents
-sleep 5  # Hope agents report in time
-CONFIDENCE=$(redis-cli LRANGE "swarm:${TASK_ID}:${AGENT_ID}:confidence" 0 0)
-# Often 0.0 due to race condition
-```
-
-### After (Skill-Based)
-
-```bash
-# Process each agent with guaranteed extraction
-for AGENT in $LOOP3_AGENTS; do
-  RESULT=$(./.claude/skills/loop3-output-processing/execute-and-extract.sh \
-    --agent-type "$AGENT" \
-    --task-id "$TASK_ID" \
-    --agent-id "${AGENT}-1")
-
-  CONFIDENCE=$(echo "$RESULT" | jq -r '.confidence')
-  redis-cli LPUSH "swarm:${TASK_ID}:${AGENT}-1:confidence" "$CONFIDENCE"
-  redis-cli LPUSH "swarm:${TASK_ID}:${AGENT}-1:done" "complete"
-done
-```
-
----
-
-## Related Skills
-
-- **Agent Output Processing** (`.claude/skills/agent-output-processing/SKILL.md`) - Universal pattern
-- **Loop 2 Output Processing** (`.claude/skills/loop2-output-processing/SKILL.md`) - Validator skill
-- **Redis Coordination** (`.claude/skills/redis-coordination/SKILL.md`) - State management
-
----
-
-## Version History
-
-### 1.0.0 (2025-10-20)
-- Initial implementation
-- Multi-pattern confidence extraction
-- Git-based deliverable verification
-- Fallback confidence calculation
-- Integration with orchestrator
-
----
-
-**Summary:** This skill guarantees confidence extraction from Loop 3 implementers by processing agent output with robust parsing, git-based verification, and fallback calculation. Eliminates BUG #10 race conditions.

package/.claude/skills/loop3-output-processing/calculate-confidence.sh

@@ -1,28 +0,0 @@
-#!/bin/bash
-set -euo pipefail
-
-FILES_CHANGED=0
-DELIVERABLES="[]"
-
-while [[ $# -gt 0 ]]; do
-  case $1 in
-    --files-changed) FILES_CHANGED="$2"; shift 2 ;;
-    --deliverables) DELIVERABLES="$2"; shift 2 ;;
-    *) echo "ERROR: Unknown parameter: $1" >&2; exit 1 ;;
-  esac
-done
-
-# Calculate confidence based on deliverables
-if (( FILES_CHANGED == 0 )); then
-  # No files changed - agent did not deliver
-  echo "0.0"
-elif (( FILES_CHANGED <= 2 )); then
-  # Minimal changes - low confidence
-  echo "0.50"
-elif (( FILES_CHANGED <= 5 )); then
-  # Moderate changes - medium confidence
-  echo "0.75"
-else
-  # Significant changes - high confidence
-  echo "0.85"
-fi