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):

# 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:

{
  "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