Cfn Loop Validation

CFN Loop Validation Skill

APPLIES TO CLI MODE ONLY. In Task Mode (/cfn-loop-task), agents return output directly; never call redis-cli or invoke-waiting-mode.sh.

MISSING ON DISK: the redis-coordination skill referenced below does not exist. All redis-coordination script calls in this file are ASPIRATIONAL; do not invoke them. CLI mode currently has no working Redis signaling path.

Purpose: Implement multi-layer validation and quality gates for CFN Loop workflows with clean agent exit patterns.

Version: 2.3.0 Confidence: 0.98 Status: CLI mode aspirational; Task Mode does not use this file's protocol.

Core Architecture

Clean Agent Exit Protocol

Critical Principle: Agents MUST exit immediately after reporting confidence. No waiting mode for implementers/validators.

# ✅ CORRECT - Agent completion protocol (ASPIRATIONAL: redis-coordination skill missing on disk; do not invoke)
# Step 1: Complete work
# Step 2: Signal completion
redis-cli lpush "swarm:${TASK_ID}:${AGENT_ID}:done" "complete"

# Step 3: Report confidence
./.claude/skills/redis-coordination/invoke-waiting-mode.sh report \
  --task-id "$TASK_ID" \
  --agent-id "$AGENT_ID" \
  --confidence 0.85 \
  --iteration 1

# Step 4: EXIT CLEANLY (no waiting mode)
# Agent process terminates here

# ❌ FORBIDDEN - Agents entering waiting mode (ASPIRATIONAL: redis-coordination skill missing on disk)
./.claude/skills/redis-coordination/invoke-waiting-mode.sh enter \
  --task-id "$TASK_ID" \
  --agent-id "${AGENT_ID}" \
  --context "iteration-complete"

Why Clean Exit Matters:

• Prevents orchestrator blocking on wait $PID
• Enables adaptive agent specialization (different agents per iteration)
• Eliminates indefinite blocking scenarios
• Supports true parallel execution

Validation Layers

Layer 1: Gate Validation (Loop 3 Self-Validation)

• Threshold: Mode-dependent (0.70-0.85)
• Purpose: Implementers self-assess work quality
• Blocking: Prevents validators from reviewing incomplete work

Layer 2: Consensus Validation (Loop 2 Validators)

• Threshold: Mode-dependent (0.80-0.95)
• Purpose: Independent quality assessment
• Requirement: Minimum 2 validators for robust consensus

Layer 3: Product Owner Decision

• Purpose: Strategic validation and scope enforcement
• Options: PROCEED/ITERATE/ABORT
• Anti-Pattern Prevention: Prevents "consensus on vapor"

Dependency Enforcement

Mandatory Flow:

1. Loop 3 agents complete work
2. Gate check validates Loop 3 quality
3. IF gate passes → Signal swarm:${TASK_ID}:gate-passed
4. Loop 2 validators wait for gate signal via blpop
5. Loop 2 validators review and report consensus
6. Product Owner makes final decision

Redis Coordination:

# Loop 2 agents wait for gate signal
redis-cli blpop "swarm:${TASK_ID}:gate-passed" 0

# Gate signal sent by orchestrator
redis-cli lpush "swarm:${TASK_ID}:gate-passed" "true"

Mode Configurations

Single source of truth: .claude/skills/cfn-loop-orchestration-v2/THRESHOLDS.md. Do not restate numeric values here. The confidence values this skill gates on are the confidence_gate column (CLI mode only: mvp 0.70, standard 0.75, enterprise 0.85 as decimals); consensus and max_iter also come from that table. Validator counts: mvp 2, standard 3-4, enterprise 5.

Agent Lifecycle Management

Coordinator Responsibilities

• Spawn agents via CLI (cost optimization)
• Manage Redis coordination
• Handle iteration logic
• Collect confidence scores
• Enforce dependency blocking

Agent Responsibilities

• Complete assigned work
• Signal completion via Redis
• Report confidence score
• Exit immediately (no waiting mode) - MANDATORY

Updated Agent Completion Protocol (v2.3)

# ✅ NEW MANDATORY PROTOCOL - All agents MUST follow (ASPIRATIONAL: redis-coordination skill missing on disk; do not invoke)
# Step 1: Complete work
# Step 2: Signal completion
redis-cli lpush "swarm:${TASK_ID}:${AGENT_ID}:done" "complete"

# Step 3: Report confidence score
./.claude/skills/redis-coordination/invoke-waiting-mode.sh report \
  --task-id "$TASK_ID" \
  --agent-id "$AGENT_ID" \
  --confidence 0.92 \
  --iteration 1

# Step 4: EXIT CLEANLY (no waiting mode - agents MUST NOT enter waiting mode)
# Agent process terminates here - orchestrator uses wait $PID
exit 0

Clean Exit Benefits

1. No Blocking: Orchestrator uses wait $PID successfully
2. Adaptive Specialization: Different agents per iteration
3. Resource Efficiency: No idle agent processes
4. Simplified Debugging: Clear agent lifecycle
5. Prevents Orchestration Deadlock: Eliminates indefinite agent blocking
6. Enables True Parallelism: Multiple agents can complete independently

Forbidden Patterns (Critical Anti-Patterns)

# ❌ FORBIDDEN - Agents MUST NOT enter waiting mode (ASPIRATIONAL: redis-coordination skill missing on disk)
./.claude/skills/redis-coordination/invoke-waiting-mode.sh enter \
  --task-id "$TASK_ID" \
  --agent-id "${AGENT_ID}" \
  --context "iteration-complete"

# ❌ FORBIDDEN - Only coordinators use waiting mode
if [[ "$AGENT_TYPE" != "coordinator" ]]; then
  echo "ERROR: Non-coordinator agents cannot use waiting mode"
  exit 1
fi

Context Injection Patterns

Multi-Layer Context Flow

Coordinator → Redis Storage → Orchestrator → Agent Spawning → Agent Context

Critical Requirement: Context must flow through ALL layers.

Context Components

• Epic Context: High-level goals and scope
• Phase Context: Sprint-specific requirements
• Success Criteria: Acceptance criteria and deliverables
• Thresholds: Gate and consensus values

Context Validation

1. Coordinator: Validates context has deliverables before spawning
2. Orchestrator: Validates Redis retrieval before agent spawning
3. Agents: Validate received context has required fields

Anti-Pattern Prevention: Avoid generic context when specifics exist in Redis.

Quality Gates Implementation

Deliverable Verification (STRAT-020)

Mandatory check: Validate actual file creation for implementation tasks.

# Check for deliverable creation
git_status=$(git status --porcelain 2>/dev/null || echo "")
if [[ -z "$git_status" ]] && [[ "$task_type" == "implementation" ]]; then
    # Force iteration - no files created
    consensus=0.0
    feedback="No deliverable files created. Must implement actual changes."
fi

Confidence Scoring (mechanical rubric, MANDATORY)

Agents do NOT estimate confidence freely. Compute it with this arithmetic and report the work:

1. Start at 1.0
2. Subtract 0.3 if any scoped test fails
3. Subtract 0.2 if there are typecheck errors in owned files
4. Subtract 0.2 if any planned deliverable file was not created
5. Subtract 0.1 if any acceptance criterion has no test
6. Subtract 0.1 if a workaround marked with a cfn: comment was used
7. Floor at 0.0

Report the arithmetic, not just the result. Example: confidence: 1.0 - 0.3 (2 scoped tests failing) - 0.1 (AC-4 has no test) = 0.6

Reporting format: explicit decimal (confidence: 0.60). Percentages and qualitative words (high/medium/low) are forbidden in new output; the parser fallbacks below exist only to recover from malformed legacy output.

Multi-Pattern Parsing (PATTERN-009, recovery-only fallback)

# Extract confidence with fallback strategies
confidence=$(echo "$output" | grep -o "confidence: [0-9.]*" | tail -1 | cut -d' ' -f2)
if [[ -z "$confidence" ]]; then
    confidence=$(echo "$output" | grep -o "[0-9]*%" | tail -1 | sed 's/%//')
    if [[ -n "$confidence" ]]; then
        confidence=$(echo "scale=2; $confidence/100" | bc -l)
    fi
fi

Testing and Validation

Test Suite Requirements

• Validate clean agent exit
• Test dependency enforcement
• Verify context injection
• Check timeout handling
• Validate consensus calculations

Key Test Cases

1. Clean Exit Test: Agents exit without waiting mode
2. Blocking Test: Loop 2 waits for Loop 3 gate signal
3. Context Test: Deliverables flow through all layers
4. Iteration Test: Quality gate triggers iteration
5. Timeout Test: Agents respect phase timeouts

Integration Points

Redis Coordination Skill (MISSING ON DISK; this integration is aspirational)

• Uses invoke-waiting-mode.sh report for confidence reporting
• No enter calls for implementers/validators
• Blocking via blpop for dependency enforcement

Agent Spawning Skill

• CLI spawning for cost optimization
• Agent ID assignment and tracking
• Background process management

Product Owner Decision Skill

• Structured decision parsing
• Deliverable validation
• Scope enforcement

Error Handling and Recovery

Timeout Scenarios

• Phase-specific timeouts: Based on work complexity
• Agent timeout: timeout command wrapper
• Orchestrator timeout: Background execution with monitoring

Failure Recovery

• Redis state cleanup: Clear iteration data
• Agent PID tracking: Monitor and cleanup stuck processes
• Context validation: Fail-fast on missing context

Performance Optimization

Cost Savings

• CLI Spawning: 95-98% cost reduction vs Task()
• Zero-Token Waiting: Redis BLPOP for coordination
• Parallel Execution: Background agent spawning

Resource Management

• Clean Exit: No idle agent processes
• Timeout Enforcement: Prevent resource leaks
• Redis Cleanup: Automatic state management

Usage Examples

Standard CFN Loop Execution (ASPIRATIONAL: orchestrate-cfn-loop.sh missing on disk; do not invoke)

./.claude/skills/redis-coordination/orchestrate-cfn-loop.sh \
  --task-id "feature-auth-123" \
  --mode standard \
  --loop3-agents "backend-dev,security-specialist" \
  --loop2-agents "reviewer,tester,architect" \
  --product-owner "product-owner" \
  --phase-id "phase-2" \
  --epic-context '{"epicGoal":"Build auth system","inScope":["JWT","OAuth"]}' \
  --phase-context '{"deliverables":["auth.js","tests/auth.test.js"]}' \
  --success-criteria '{"acceptanceCriteria":["JWT tokens work","Tests pass"]}'

Agent Implementation Protocol (ASPIRATIONAL: redis-coordination skill missing on disk; do not invoke)

# Agent receives task context
# Completes implementation work

# Signal completion
redis-cli lpush "swarm:${TASK_ID}:${AGENT_ID}:done" "complete"

# Report confidence
./.claude/skills/redis-coordination/invoke-waiting-mode.sh report \
  --task-id "$TASK_ID" \
  --agent-id "$AGENT_ID" \
  --confidence 0.92 \
  --iteration 1

# EXIT CLEANLY - no waiting mode

Monitoring and Debugging

Key Redis Keys

• swarm:${TASK_ID}:${AGENT_ID}:done - Completion signal
• swarm:${TASK_ID}:${AGENT_ID}:confidence - Confidence score
• swarm:${TASK_ID}:gate-passed - Gate signal
• swarm:${TASK_ID}:epic-context - Epic context
• swarm:${TASK_ID}:success-criteria - Acceptance criteria

Debug Commands

# Check agent completion
redis-cli lrange "swarm:${TASK_ID}:${AGENT_ID}:done" 0 -1

# Check confidence scores
redis-cli get "swarm:${TASK_ID}:${AGENT_ID}:confidence"

# Monitor gate signals
redis-cli blpop "swarm:${TASK_ID}:gate-passed" 1

Maintenance: Regular validation of clean exit patterns and dependency enforcement. Test suite should validate all lifecycle scenarios.

⚠️ Bash Deprecation Notice

The bash implementation of this skill is deprecated as of 2025-11-20.

Deprecation Date: 2025-11-20
Removal Date: 2026-02-20 (90 days)
TypeScript Implementation: dist/validator.js and dist/cli/validate-*.js (MISSING ON DISK: no dist/ directory exists in lib/validation; the TypeScript migration target was never compiled here. Do not set USE_TYPESCRIPT=true expecting it to work.)
Migration Guide: SKILL_TYPESCRIPT.md (in this directory)

Why Migrate to TypeScript?

• Type Safety: Zero runtime type errors with compile-time validation
• Better Performance: 5-10ms faster execution, optimized Redis operations
• Comprehensive Testing: 90%+ test coverage with unit, integration, and E2E tests
• Modern Tooling: Full IDE support, autocomplete, and inline documentation
• Maintainability: Single source of truth, easier debugging

Automatic Migration

Set environment variable to automatically use TypeScript:

export USE_TYPESCRIPT=true

All coordinators and orchestrators will automatically prefer TypeScript implementations.

Rollback

If issues arise:

export USE_TYPESCRIPT=false

Bash scripts will continue working for the 90-day deprecation period.

See Also

• Complete Deprecation List: docs/BASH_DEPRECATION_NOTICE.md
• TypeScript Benefits: See individual migration guides
• Test Coverage: Run npm test to verify TypeScript implementation