Pipeline Guards

---
name: pipeline-guards
description: Safety constraints and quality gates for pipeline and workflow execution
scope: core
user-invocable: false
---

# Pipeline Guards Skill

Defines mandatory safety constraints for all pipeline, workflow, and iterative execution within the oh-my-customcode system. Prevents infinite loops, enforces timeouts, and establishes quality gates.

**System-wide** — these guards apply to dag-orchestration, worker-reviewer-pipeline, and any iterative process.

## Guard Limits

| Guard | Default | Hard Cap | Applies To |
|-------|---------|----------|------------|
| Max iterations | 3 | 5 | worker-reviewer-pipeline |
| Max DAG nodes | 20 | 30 | dag-orchestration |
| Max parallel agents | 4 | 5 | R009 (all pipelines) |
| Max parallel steps   | 4        | 4        | pipeline parallel blocks |
| Timeout per node | 300s | 600s | dag-orchestration nodes |
| Timeout per pipeline | 900s | 1800s | worker-reviewer-pipeline |
| Max retry count | 2 | 3 | Failure retry strategies |
| Max PR improvement items | 20 | 50 | pr-auto-improve |
| Max auto-improve items | 20 | 50 | omcustom-auto-improve |
| Max files per agent | 10 | 15 | All agent spawns (advisory) |

## Enforcement

Guards are enforced at two levels:

### Level 1: Skill-Level (Soft)
Each skill checks guard limits before execution:

```
Before starting pipeline:
  1. Check max_iterations ≤ hard cap
  2. Check timeout ≤ hard cap
  3. Check node count ≤ hard cap
  If any exceeded → warn user, use hard cap value
```

### Level 2: Hook-Level (Hard)
The stuck-detector hook monitors for guard violations:

```
PostToolUse → check:
  - Iteration count > max_iterations?
  - Elapsed time > timeout?
  - Same error repeated > max_retry?
  If any → emit advisory to stderr
```

## Quality Gates

### Pipeline Quality Gate
```
[Quality Gate Check]
├── Critical issues: {count} (must be 0)
├── Major issues: {count} (must be ≤ threshold)
├── Minor issues: {count} (informational)
└── Gate: PASS | FAIL
```

### DAG Completion Gate
```
[DAG Completion Gate]
├── Nodes completed: {n}/{total}
├── Nodes failed: {count}
├── Nodes skipped: {count}
└── Gate: PASS | PARTIAL | FAIL
```

## Manifest Integrity Gate

Guards `templates/manifest.json` against structure loss — e.g. a `source-hash.sh` path→hash map overwriting the versioned manifest (#1423 incident). The correct source-hash target is `wiki/.source-hashes.json`, never `templates/manifest.json`.

```
[Manifest Integrity Gate]
- File: templates/manifest.json (staged)
- Structure: {version, lastUpdated, omcustomMinClaudeCode, components[]} present?
- .version field: present?
- Gate: PASS | FAIL
```

| Signal | Action | Enforcement |
|--------|--------|-------------|
| `.version` missing in staged templates/manifest.json | Block stage, surface recovery hint | Advisory (skill-level, run jq check before commit) |
| Staged content is a path→hash map (no `{version,…}` keys) | Block stage, surface recovery hint | Advisory (skill-level) |
| `.version` present + structure intact | Pass gate, proceed | Commit allowed |

Deterministic check before staging: `jq -e '.version and .components' templates/manifest.json` must succeed.

```
[Guard] OK templates/manifest.json — structure validated (.version present)
[Guard] BLOCK templates/manifest.json — structure lost (path→hash map) — recover: git show HEAD:templates/manifest.json | jq '.version="<NEW>"'
```

## Escalation Integration

When guards are triggered, they integrate with existing advisory systems:

| Event | Action |
|-------|--------|
| Max iterations reached | → stuck-recovery advisory |
| Repeated failures | → model-escalation advisory |
| Timeout approaching (80%) | → warn user, suggest early termination |
| Hard cap hit | → force stop, report to user |

## Task Granularity Guard

Advisory guard for agent task scope. When a single agent is assigned too many files, it becomes a bottleneck in parallel execution.

| Signal | Default | Action |
|--------|---------|--------|
| Files per agent > 10 | Advisory warning | Suggest splitting by layer/domain |
| Files per agent > 15 | Hard warning | Require explicit user override |

Display:
```
[Guard] ⚠ Agent assigned {n} files (> 10) — consider splitting by layer
[Guard] 🛑 Agent assigned {n} files (> 15) — requires explicit override
```

This integrates with R009 Adaptive Parallel Splitting: if a stalled agent is detected AND it was assigned > 10 files, the splitting recommendation is stronger.

## Guard Configuration

Pipelines can override defaults (within hard caps):

```yaml
# In pipeline/workflow spec
guards:
  max_iterations: 4          # Override default 3, cannot exceed 5
  timeout_per_node: 120      # Override default 300s
  timeout_pipeline: 600      # Override default 900s
  quality_gate: all_pass     # all_pass | majority_pass
```

## Kill Switch

When a pipeline or workflow must be terminated:

```
[Kill Switch] Activated
├── Reason: {max_iterations | timeout | user_request | stuck_detected}
├── Pipeline: {name}
├── Progress: {completed}/{total} steps
├── Preserved state: /tmp/.claude-pipeline-$PPID.json
└── Action: Stopped gracefully, state saved for resume
```

The kill switch:
1. Signals all running agents to complete current operation
2. Does NOT terminate mid-write (waits for current tool call)
3. Saves pipeline state for potential resume
4. Reports final status to user

## State Preservation

On guard-triggered termination:

```json
{
  "pipeline": "feature-review",
  "terminated_at": "2026-03-07T10:15:00Z",
  "reason": "max_iterations_reached",
  "completed_iterations": 3,
  "last_verdict": "FAIL",
  "remaining_issues": [
    {"severity": "major", "file": "src/auth.ts", "line": 42, "description": "..."}
  ],
  "worker_last_output": "...",
  "resumable": true
}
```

## Display Format

Guard warnings appear inline:

```
[Guard] ⚠ Iteration 3/3 — final attempt
[Guard] ⚠ Timeout 80% (240s/300s) — consider early termination
[Guard] 🛑 Max iterations reached — pipeline stopped
[Guard] 🛑 Hard timeout (600s) — force stop
```

## Integration

| Rule/Skill | Integration |
|------------|-------------|
| R009 | Max parallel agents enforced (hard cap: 5, soft default: 4) |
| R010 | Guards run in orchestrator only |
| R015 | Guard warnings displayed transparently |
| dag-orchestration | Node count and timeout limits |
| worker-reviewer-pipeline | Iteration and pipeline timeout limits |
| pr-auto-improve | Improvement item count limits |
| omcustom-auto-improve | Auto-improve item count limits |
| stuck-recovery | Guard triggers feed into stuck detection |
| model-escalation | Repeated failures trigger escalation advisory |
| task-decomposition | Subtask file counts validated against granularity guard thresholds |

## Checkpoint Gate Integration

각 guard 통과/실패 시 `tracker-checkpoint` 에이전트로 gate state 기록.

### Flow

1. Guard 진입 → tracker-checkpoint에 gate state: running 기록
2. Guard 통과 → tracker-checkpoint에 gate state: passed + metrics 기록
3. Guard 실패 → tracker-checkpoint에 gate state: failed + failure reason freeze
4. 다음 단계는 checkpoint state 참조하여 재개/중단 판단

### Benefits

- 긴 파이프라인에서 guard 지점마다 복원점 확보
- 부분 실패 시 직전 guard 지점부터 재시도 가능 (비용 절감)
- guard metrics 축적으로 품질 추이 관찰 가능

See `.claude/agents/tracker-checkpoint.md` for the tracker spec.

## Override Policy

- Defaults can be overridden in pipeline spec (within hard caps)
- Hard caps can ONLY be changed by modifying this skill file
- User cannot bypass hard caps at runtime
- All overrides are logged and displayed (R015)

## Limitations

- Guards are advisory at skill level, hard at hook level
- Cannot prevent infinite loops in agent reasoning (only tool call patterns)
- State preservation is best-effort (process crash = state loss)
- Resume from saved state requires user confirmation