claude-flow-novice 2.18.6 → 2.18.7

package/claude-assets/skills/cfn-docker-runtime/lib/logging/INTEGRATION.md

@@ -1,268 +0,0 @@
-# Hybrid Logging Integration Guide
-
-## Overview
-
-The hybrid logging system provides both **text files** (human-readable) and **SQLite database** (powerful queries) for CFN Docker mode execution.
-
-## Integration with spawn-agent.sh
-
-### Step 1: Initialize Logging at Task Start
-
-Add this to the coordinator/orchestrator that manages the task:
-
-```bash
-# At the start of task execution
-TASK_ID="your-task-id"
-LOG_DIR="logs/docker-mode/${TASK_ID}"
-DB_PATH="$LOG_DIR/logs.db"
-
-# Initialize hybrid logging
-./.claude/skills/cfn-docker-logging/init-hybrid-logging.sh "$TASK_ID"
-```
-
-### Step 2: Capture Logs for Each Container
-
-When spawning an agent container, add log capture:
-
-```bash
-# Spawn container (existing code)
-CONTAINER_ID=$(docker run -d \
-    --name "cfn-agent-${AGENT_ID}" \
-    --memory="${MEMORY_LIMIT}" \
-    -v "$WORKSPACE:/workspace:rw" \
-    -e AGENT_TYPE="$AGENT_TYPE" \
-    -e TASK_PROMPT="$TASK_PROMPT" \
-    cfn-agent:latest)
-
-# Capture logs to both text files and SQLite
-./.claude/skills/cfn-docker-logging/capture-container-logs.sh \
-    "$CONTAINER_ID" \
-    "$AGENT_ID" \
-    "$LOG_DIR" \
-    "$DB_PATH" \
-    "$TASK_ID" &
-
-LOG_CAPTURE_PID=$!
-echo "$LOG_CAPTURE_PID" > "$LOG_DIR/${AGENT_ID}-capture.pid"
-```
-
-### Step 3: Log Coordination Events
-
-When using coordination layer (Redis), log events to database:
-
-```bash
-source ./.claude/skills/cfn-docker-logging/sqlite-helpers.sh
-
-# Log gate check result
-log_gate_check "$DB_PATH" "$TASK_ID" "$ITERATION" "$PASS_RATE" "$THRESHOLD" "$PASSED" "$AGENT_COUNT" "$(date -u '+%Y-%m-%d %H:%M:%S')"
-
-# Log validator consensus
-log_validator_consensus "$DB_PATH" "$TASK_ID" "$ITERATION" "$VALIDATOR_ID" "$SCORE" "$FEEDBACK" "$(date -u '+%Y-%m-%d %H:%M:%S')"
-
-# Log product owner decision
-log_product_owner_decision "$DB_PATH" "$TASK_ID" "$ITERATION" "$DECISION" "$RATIONALE" "$DELIVERABLES_VALIDATED" "$(date -u '+%Y-%m-%d %H:%M:%S')"
-
-# Log coordination event
-log_coordination_event "$DB_PATH" "$TASK_ID" "$AGENT_ID" "$EVENT_TYPE" "$KEY" "$VALUE" "$(date -u '+%Y-%m-%d %H:%M:%S')"
-```
-
-### Step 4: Access Logs After Execution
-
-```bash
-# View text logs (human-readable)
-cat logs/docker-mode/${TASK_ID}/${AGENT_ID}-stdout.log
-cat logs/docker-mode/${TASK_ID}/${AGENT_ID}-stderr.log
-
-# Run SQL queries (powerful analysis)
-cd logs/docker-mode/${TASK_ID}
-
-# Analytics summary
-./queries/analytics-summary.sh logs.db $TASK_ID
-
-# Failed containers
-./queries/query-failed-containers.sh logs.db $TASK_ID
-
-# Gate check history
-./queries/query-gate-checks.sh logs.db $TASK_ID
-
-# Validator consensus
-./queries/query-consensus-history.sh logs.db $TASK_ID
-```
-
-## Complete Example: orchestrate.sh Integration
-
-```bash
-#!/bin/bash
-# Enhanced orchestrate.sh with hybrid logging
-
-set -euo pipefail
-
-TASK_ID=$1
-AGENT_LIST=$2
-LOG_DIR="logs/docker-mode/${TASK_ID}"
-DB_PATH="$LOG_DIR/logs.db"
-
-# Source helpers
-source ./.claude/skills/cfn-docker-logging/sqlite-helpers.sh
-
-# Initialize hybrid logging
-./.claude/skills/cfn-docker-logging/init-hybrid-logging.sh "$TASK_ID"
-
-echo "Hybrid logging initialized: $LOG_DIR"
-
-# Loop 3: Spawn implementers
-ITERATION=1
-for AGENT_TYPE in $AGENT_LIST; do
-    AGENT_ID="${AGENT_TYPE}-${ITERATION}-$$"
-
-    # Spawn container
-    CONTAINER_ID=$(docker run -d \
-        --name "cfn-${AGENT_ID}" \
-        --memory="1g" \
-        -e AGENT_TYPE="$AGENT_TYPE" \
-        -e TASK_ID="$TASK_ID" \
-        cfn-agent:latest)
-
-    # Capture logs (hybrid mode)
-    ./.claude/skills/cfn-docker-logging/capture-container-logs.sh \
-        "$CONTAINER_ID" "$AGENT_ID" "$LOG_DIR" "$DB_PATH" "$TASK_ID" &
-
-    echo "Spawned $AGENT_ID (container: $CONTAINER_ID)"
-done
-
-# Wait for completion
-echo "Waiting for agents to complete..."
-# (existing wait logic)
-
-# Execute tests
-TEST_PASS_RATE=$(npm test 2>&1 | grep -oP '\d+(?=% pass rate)' || echo "0")
-TEST_PASS_RATE_DECIMAL=$(echo "scale=2; $TEST_PASS_RATE / 100" | bc)
-
-# Log gate check result
-THRESHOLD=0.95
-PASSED=0
-[[ $(echo "$TEST_PASS_RATE_DECIMAL >= $THRESHOLD" | bc) -eq 1 ]] && PASSED=1
-
-log_gate_check "$DB_PATH" "$TASK_ID" "$ITERATION" "$TEST_PASS_RATE_DECIMAL" "$THRESHOLD" "$PASSED" "$(echo $AGENT_LIST | wc -w)" "$(date -u '+%Y-%m-%d %H:%M:%S')"
-
-if [[ $PASSED -eq 1 ]]; then
-    echo "Gate check PASSED: ${TEST_PASS_RATE}% >= ${THRESHOLD}"
-
-    # Loop 2: Spawn validators
-    for VALIDATOR in validator-1 validator-2 validator-3; do
-        AGENT_ID="${VALIDATOR}-${ITERATION}-$$"
-
-        CONTAINER_ID=$(docker run -d \
-            --name "cfn-${AGENT_ID}" \
-            --memory="512m" \
-            -e AGENT_TYPE="$VALIDATOR" \
-            -e TASK_ID="$TASK_ID" \
-            cfn-agent:latest)
-
-        ./.claude/skills/cfn-docker-logging/capture-container-logs.sh \
-            "$CONTAINER_ID" "$AGENT_ID" "$LOG_DIR" "$DB_PATH" "$TASK_ID" &
-
-        echo "Spawned validator: $AGENT_ID"
-    done
-
-    # Wait for validators
-    # (existing wait logic)
-
-    # Collect consensus scores
-    for VALIDATOR in validator-1 validator-2 validator-3; do
-        SCORE=$(cat "$LOG_DIR/${VALIDATOR}-${ITERATION}-$$-output.json" | jq -r '.confidence')
-        FEEDBACK=$(cat "$LOG_DIR/${VALIDATOR}-${ITERATION}-$$-output.json" | jq -r '.feedback')
-
-        log_validator_consensus "$DB_PATH" "$TASK_ID" "$ITERATION" "$VALIDATOR" "$SCORE" "$FEEDBACK" "$(date -u '+%Y-%m-%d %H:%M:%S')"
-    done
-
-    # Product owner decision
-    # (existing logic)
-    DECISION="PROCEED"
-    RATIONALE="All validators approved with high confidence"
-
-    log_product_owner_decision "$DB_PATH" "$TASK_ID" "$ITERATION" "$DECISION" "$RATIONALE" 1 "$(date -u '+%Y-%m-%d %H:%M:%S')"
-else
-    echo "Gate check FAILED: ${TEST_PASS_RATE}% < ${THRESHOLD}"
-    # Log failure and iterate
-fi
-
-# Generate analytics report
-echo ""
-echo "=== Execution Analytics ==="
-./queries/analytics-summary.sh "$DB_PATH" "$TASK_ID"
-```
-
-## Benefits
-
-### Text Files
-- **Human-readable**: Easy to tail, grep, less
-- **Backward compatible**: Existing tooling works
-- **Simple debugging**: No special tools required
-- **Real-time monitoring**: `tail -f agent-stdout.log`
-
-### SQLite Database
-- **Complex queries**: Joins, aggregations, subqueries
-- **Time-series analysis**: Gate checks over iterations
-- **Cross-agent correlation**: Find patterns across agents
-- **Performance metrics**: Duration, success rates, bottlenecks
-- **Audit trail**: Complete execution history
-- **Scalable**: Handles millions of log lines efficiently
-
-## Query Examples
-
-### Find All Failed Agents
-
-```bash
-sqlite3 logs.db "SELECT agent_id, exit_code, finished_at FROM container_events WHERE event_type='exit' AND exit_code != 0;"
-```
-
-### Show Gate Check Progression
-
-```bash
-sqlite3 logs.db "SELECT iteration, pass_rate, threshold, CASE WHEN passed=1 THEN 'PASS' ELSE 'FAIL' END FROM gate_checks WHERE task_id='$TASK_ID' ORDER BY iteration;"
-```
-
-### Find Consensus Disagreements
-
-```bash
-sqlite3 logs.db "SELECT iteration, MAX(score) - MIN(score) as variance FROM validator_consensus WHERE task_id='$TASK_ID' GROUP BY iteration HAVING variance > 0.2;"
-```
-
-### Analyze Agent Performance
-
-```bash
-sqlite3 logs.db "SELECT agent_id, AVG(duration_seconds) as avg_duration, COUNT(*) as executions FROM container_events WHERE event_type='exit' GROUP BY agent_id ORDER BY avg_duration DESC;"
-```
-
-### Error Pattern Analysis
-
-```bash
-sqlite3 logs.db "SELECT substr(log_line, 1, 80) as error_pattern, COUNT(*) as occurrences FROM container_logs WHERE stream='stderr' AND log_line LIKE '%error%' GROUP BY error_pattern ORDER BY occurrences DESC;"
-```
-
-## Performance Characteristics
-
-- **Text file overhead**: ~5% CPU during capture
-- **SQLite insert overhead**: ~2% CPU during capture
-- **Total overhead**: ~7% (negligible for most workloads)
-- **Storage**: SQLite adds ~30% to text file size
-- **Query speed**: Sub-second for most queries on 10k+ log lines
-- **Scalability**: Tested with 1M+ log lines, queries remain fast
-
-## Troubleshooting
-
-### Database locked error
-
-**Cause**: Multiple processes writing simultaneously
-**Fix**: SQLite handles this automatically with retry logic
-
-### Missing log lines in database
-
-**Cause**: Log capture process killed before flushing
-**Fix**: Ensure proper cleanup in spawn-agent.sh
-
-### Query scripts not found
-
-**Cause**: Query scripts not copied to log directory
-**Fix**: Run `init-hybrid-logging.sh` before spawning agents

package/claude-assets/skills/cfn-docker-runtime/lib/logging/SAMPLE_OUTPUTS.md

@@ -1,237 +0,0 @@
-# Sample Query Outputs
-
-This document shows example outputs from the hybrid logging system queries.
-
-## 1. Analytics Summary
-
-Command: `./queries/analytics-summary.sh logs.db demo-1763482064`
-
-```
-=== Task Execution Summary ===
-total_agents  total_containers  successful  failed  success_rate  oom_kills
-------------  ----------------  ----------  ------  ------------  ---------
-6             6                 5           1       41.67%        0
-
-=== Execution Duration ===
-avg_duration_sec  min_duration_sec  max_duration_sec  total_duration_sec
-----------------  ----------------  ----------------  ------------------
-0.00              0.00              0.00              0.00
-
-=== Log Volume ===
-stream  total_lines  avg_line_length  total_bytes
-------  -----------  ---------------  -----------
-stderr  1            28.00            28
-stdout  17           23.94            407
-
-=== Timeline Overview ===
-first_spawn          last_exit            total_runtime_sec
--------------------  -------------------  -----------------
-2025-11-18 16:07:45  2025-11-18 16:07:46  1.00
-```
-
-**Insights:**
-- 6 agents executed with 83% success rate
-- Total runtime: 1 second
-- No OOM kills detected
-- Log volume: 18 lines (407 bytes stdout, 28 bytes stderr)
-
----
-
-## 2. Gate Check Results
-
-Command: `./queries/query-gate-checks.sh logs.db demo-1763482064`
-
-```
-=== Gate Check Results ===
-iteration  pass_rate  threshold  result  agents  timestamp
----------  ---------  ---------  ------  ------  -------------------
-1          66.00%     95.00%     FAIL    3       2025-11-18 16:07:45
-2          100.00%    95.00%     PASS    3       2025-11-18 16:07:46
-
-=== Gate Check Summary ===
-total_checks  passed_count  failed_count  avg_pass_rate  max_pass_rate
-------------  ------------  ------------  -------------  -------------
-2             1             1             83.00%         100.00%
-```
-
-**Insights:**
-- Iteration 1 failed gate check (66% < 95% threshold)
-- Iteration 2 passed with 100% success rate
-- Average pass rate across iterations: 83%
-- Clear progression from failure to success
-
----
-
-## 3. Validator Consensus History
-
-Command: `./queries/query-consensus-history.sh logs.db demo-1763482064`
-
-```
-=== Validator Consensus History ===
-iteration  validator_id  score  feedback                timestamp
----------  ------------  -----  ----------------------  -------------------
-2          validator-1   0.85   Iteration 2 looks good  2025-11-18 16:07:46
-2          validator-2   0.85   Iteration 2 looks good  2025-11-18 16:07:46
-2          validator-3   0.85   Iteration 2 looks good  2025-11-18 16:07:46
-
-=== Consensus Trends by Iteration ===
-iteration  validator_count  avg_score  min_score  max_score  score_range
----------  ---------------  ---------  ---------  ---------  -----------
-2          3                0.85       0.85       0.85       0.00
-
-=== Validator Performance ===
-validator_id  reviews  avg_score  min_score  max_score
-------------  -------  ---------  ---------  ---------
-validator-1   1        0.85       0.85       0.85
-validator-2   1        0.85       0.85       0.85
-validator-3   1        0.85       0.85       0.85
-```
-
-**Insights:**
-- All validators agree (score range: 0.00)
-- Consistent confidence scores: 0.85 across all validators
-- No disagreements detected
-- Perfect consensus in iteration 2
-
----
-
-## 4. Custom Queries
-
-### Query: Success Rate by Iteration
-
-```sql
-SELECT
-    CAST(substr(agent_id, -1) as INTEGER) as iteration,
-    COUNT(*) as total,
-    SUM(CASE WHEN exit_code=0 THEN 1 ELSE 0 END) as successful,
-    printf('%.0f%%', AVG(CASE WHEN exit_code=0 THEN 100.0 ELSE 0.0 END)) as success_rate
-FROM container_events
-WHERE event_type='exit' AND task_id='demo-1763482064'
-GROUP BY iteration
-ORDER BY iteration;
-```
-
-**Output:**
-```
-iteration  total  successful  success_rate
----------  -----  ----------  ------------
-1          3      2           66%
-2          3      3           100%
-```
-
-**Insights:**
-- Clear improvement: 66% → 100%
-- Iteration 2 achieved perfect success rate
-- Validates iterative refinement approach
-
----
-
-### Query: Error Pattern Analysis
-
-```sql
-SELECT
-    substr(log_line, 1, 80) as error_pattern,
-    COUNT(*) as occurrences
-FROM container_logs
-WHERE stream='stderr' AND log_line LIKE '%error%' COLLATE NOCASE
-GROUP BY error_pattern
-ORDER BY occurrences DESC;
-```
-
-**Output:**
-```
-error_pattern                      occurrences
----------------------------------  -----------
-Error: Implementation failed       1
-```
-
-**Insights:**
-- Single error type detected
-- Occurred in iteration 1
-- Resolved in iteration 2
-
----
-
-## Real-World Use Cases
-
-### Use Case 1: Debug Agent Failure
-
-**Scenario:** Agent failed with exit code 137 (OOM killed)
-
-**Query Workflow:**
-1. Find failed containers: `./queries/query-failed-containers.sh logs.db TASK_ID`
-2. View agent timeline: `./queries/query-agent-timeline.sh logs.db AGENT_ID`
-3. Check stderr logs: `cat AGENT_ID-stderr.log`
-4. Analyze memory usage: Custom SQL query on performance_metrics table
-
----
-
-### Use Case 2: Optimize Iteration Count
-
-**Scenario:** Determine optimal iteration count based on historical data
-
-**Query:**
-```sql
-SELECT iteration, AVG(pass_rate) as avg_pass_rate
-FROM gate_checks
-WHERE task_id LIKE 'similar-task%'
-GROUP BY iteration
-ORDER BY iteration;
-```
-
-**Insight:** If pass rate plateaus after iteration 3, no need for iteration 4+
-
----
-
-### Use Case 3: Validator Disagreement Detection
-
-**Scenario:** Find iterations where validators strongly disagree
-
-**Query:**
-```sql
-SELECT
-    task_id,
-    iteration,
-    MAX(score) - MIN(score) as disagreement
-FROM validator_consensus
-GROUP BY task_id, iteration
-HAVING disagreement > 0.3
-ORDER BY disagreement DESC;
-```
-
-**Action:** Review these iterations for edge cases or unclear requirements
-
----
-
-## Benefits Comparison
-
-### Traditional Text File Approach
-
-**Command:** `grep -i error *-stderr.log`
-
-**Limitations:**
-- No aggregation (can't count by pattern)
-- No time-series analysis
-- No cross-agent correlation
-- Manual parsing required for statistics
-
----
-
-### SQLite Hybrid Approach
-
-**Advantages:**
-- Automatic aggregation (COUNT)
-- Pattern grouping
-- Sortable by frequency
-- Joinable with other tables (agent_id, iteration)
-- Structured data for dashboards
-
----
-
-## Conclusion
-
-The hybrid approach provides:
-- **Text files** for quick debugging and human readability
-- **SQLite** for complex analysis, trends, and optimization
-
-Both are generated simultaneously with minimal overhead (7% CPU).