# Cfn Loop Validation

> Multi-layer validation and quality gates for CFN Loop workflows. Use when implementing gate checks, consensus validation, or enforcing clean agent exit patterns.

- Skill: `masharratt/cfn-loop-validation` (Agent Skill, multi-file: 31 files)
- Install (CLI): `npx skillmds@latest add masharratt/cfn-loop-validation`
- Raw SKILL.md: https://api.skillmd.com/api/skills/masharratt/cfn-loop-validation/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: masharratt (https://skillmd.com/u/masharratt)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/masharratt/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.

```bash
# ✅ 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
```

```bash
# ❌ 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:**
```bash
# 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)
```bash
# ✅ 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)
```bash
# ❌ 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.

```bash
# 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)
```bash
# 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)
```bash
./.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)
```bash
# 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
```bash
# 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:

```bash
export USE_TYPESCRIPT=true
```

All coordinators and orchestrators will automatically prefer TypeScript implementations.

### Rollback

If issues arise:

```bash
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](../../../docs/BASH_DEPRECATION_NOTICE.md)
- **TypeScript Benefits:** See individual migration guides
- **Test Coverage:** Run `npm test` to verify TypeScript implementation

---