SOP-007: External Dependency Blockers

Purpose

Detect, document, escalate, and track external dependency blockers that prevent a service from progressing through the ADLC pipeline. External blockers are resources that require human action (API keys, infrastructure provisioning, third-party accounts).

Scope

Applies to all services and all pipeline stages. Covers credential blockers, infrastructure blockers, deployment blockers, external API blockers, network blockers, and permission blockers.

Prerequisites

• External dependencies registry: ~/dev/ops/external-deps.md
• Slack credentials: source ~/.env.adlc
• External blockers log: ~/dev/ops/outputs/external-blockers.log

Procedure

1. Detect the blocker

External blockers manifest as: | Signal | Category | Example | |——–|———-|———| | Missing env var | Credentials | .env.example has RESEND_API_KEY but .env does not | | 401/403 from external API | Credentials | curl to CinetPay returns 401 | | Connection refused/timeout | Infrastructure | Cannot reach external host | | Missing Coolify config | Deployment | ~/dev/ops/coolify/{service}.json has no app_uuid | | Spec references non-existent resource | Infrastructure | S3 bucket not provisioned | | Build fails on missing arg | Credentials | Docker build needs GHCR_TOKEN | | Audit finding requiring upgrade | Human decision | CVE requires manual review |

2. Check the external dependencies registry

grep "{service}" ~/dev/ops/external-deps.md

If the dependency is already tracked with status NOT_CONFIGURED or BLOCKED, check if it has been resolved since last check.

3. Escalate to Slack DM

Post immediately – do not retry indefinitely:

source ~/.env.adlc
curl -sf -X POST "https://slack.com/api/chat.postMessage" \
  -H "Authorization: Bearer $SLACK_BOT_TOKEN" \
  -H "Content-Type: application/json" \
  -d "$(python3 -c "
import json
msg = {
    'channel': 'D0AGRAVEC1K',
    'text': ':key: EXTERNAL BLOCKER -- {service}/{task}\nCategory: {category}\nMissing: {specific_resource}\nSpec reference: {spec_section}\nImpact: {what_cannot_proceed}\nAction needed: {exact_steps_for_human}'
}
print(json.dumps(msg))
")"

4. Mark as BLOCKED_EXTERNAL

CLI="$HOME/dev/ops/adlc-v2/scripts/cli"
bash $CLI/write-status.sh {service} dev BLOCKED_EXTERNAL "{missing_resource}"
bash $CLI/write-pipeline-state.sh {project} {service} BLOCKED_EXTERNAL "{missing_resource}"

5. Log to external blockers file

echo "$(date -Iseconds) | {service} | {category} | {missing_resource} | OPEN" >> ~/dev/ops/outputs/external-blockers.log

6. Update external dependencies registry

Add or update the entry in ~/dev/ops/external-deps.md:

| {service} | {dependency} | {type} | NOT_CONFIGURED | {env_vars} | {notes} |

7. Move to next task

Do NOT wait for resolution. Continue working on other tasks/services. When the human responds in Slack with the missing credentials/config: 1. Update .env or config file with the provided values 2. Clear the BLOCKED_EXTERNAL status 3. Resume the blocked task 4. Update the registry entry to AVAILABLE

8. Check for one-shot/CLI services before deploying

Before triggering DevOps deploy (lesson from 2026-03-23):

# Does it have a Dockerfile?
ls ~/dev/projects/{service}/Dockerfile 2>/dev/null

# Does it have an HTTP server/health endpoint?
grep -r "health\|listen\|serve" ~/dev/projects/{service}/src/ 2>/dev/null | head -5

If no to both: it is a CLI tool. Escalate for deployment model decision (run on agents server, Coolify job, or GitHub Actions).

Verification

• Blocker logged: grep "{service}" ~/dev/ops/outputs/external-blockers.log
• Status file set: cat ~/dev/ops/outputs/{service}-dev.status shows BLOCKED_EXTERNAL
• Pipeline state updated: grep "{service}" ~/.claude/agent-memory/pipeline/state.md shows BLOCKED_EXTERNAL
• Slack DM posted with actionable steps
• External deps registry updated: grep "{service}" ~/dev/ops/external-deps.md

Rollback

External blockers do not have a rollback per se. If a blocker is resolved: 1. Update the status: bash $CLI/write-status.sh {service} dev RUNNING "blocker resolved" 2. Update the registry: change status from NOT_CONFIGURED to AVAILABLE 3. Close the log entry: append RESOLVED to the blockers log 4. Resume pipeline for the service

References

• External deps registry: ~/dev/ops/external-deps.md
• Blockers log: ~/dev/ops/outputs/external-blockers.log
• Slack DM channel: D0AGRAVEC1K
• ADLC rules: ~/dev/CLAUDE.md (External Dependency Blockers section)
• Lesson: One-shot CLI script deployment (2026-03-23) – check for Dockerfile and HTTP server first
• Lesson: Coolify public hostname unreachable (2026-03-23) – use $COOLIFY_API_URL
• Lesson: Missing data file is same as absent (2026-03-23) – check content, not just existence

Current known blockers (as of 2026-03-30)