Dev Readyz

---
name: ring:dev-readyz
description: |
  Readiness implementation orchestrator for Lerian services. Drives a 12-gate cycle that
  detects stack, audits existing /readyz compliance, dispatches language-specific engineers
  (Go / TypeScript / Next.js) to implement the canonical /readyz contract, ValidateSaaSTLS()
  enforcement, metrics emission, startup self-probe, graceful-drain coupling, circuit-breaker
  integration, and multi-tenant carve-out — then runs 13 parallel reviewers.
---

# Readyz & Self-Probe Development Cycle

## When to use
- New service being created
- Service has external dependencies (DB, cache, queue, HTTP upstreams)
- Service lacks /readyz or has incomplete dependency checks
- Service missing startup self-probe, SaaS TLS enforcement, or metrics

## Skip when
- Pure library package with no deployable service or HTTP server
- Task is documentation-only, configuration-only, or non-code
- Service has no external dependencies AND no network listeners
- CLI tool or batch job that does not serve HTTP traffic


You orchestrate. Agents implement. NEVER use Edit/Write/Bash on source files.
All code changes go through `Task(subagent_type="ring:backend-engineer-{language}")`.
TDD mandatory for all implementation gates (RED → GREEN → REFACTOR).

**Agents:**

| Who | Responsibility |
|-----|----------------|
| ring:backend-engineer-golang | Go services |
| ring:backend-engineer-typescript | TypeScript backend/BFF |
| ring:frontend-bff-engineer-typescript | Next.js BFF |
| ring:codebase-explorer | Gate 1 analysis |
| ring:visualize | Gate 1.5 HTML preview |
| 13 reviewers | Gate 9 |

## Readiness Architecture

`/readyz` — runtime dependency probe for K8s readinessProbe. `/health` — liveness probe gated by startup self-probe.

**Standards references (WebFetch by implementation agents):**

| Resource | URL |
|----------|-----|
| Ring SRE standards | `https://raw.githubusercontent.com/LerianStudio/ring/main/dev-team/docs/standards/sre.md` |
| Go bootstrap standards | `https://raw.githubusercontent.com/LerianStudio/ring/main/dev-team/docs/standards/golang/bootstrap.md` |
| This skill (authoritative) | `https://raw.githubusercontent.com/LerianStudio/ring/main/dev-team/skills/dev-readyz/SKILL.md` |

**Canonical response contract:**

```json
{
  "status": "healthy",
  "checks": {
    "postgres": { "status": "up", "latency_ms": 2, "tls": true },
    "redis":    { "status": "skipped", "reason": "REDIS_ENABLED=false" },
    "upstream_fees": { "status": "degraded", "breaker_state": "half-open", "latency_ms": 12 }
  },
  "version": "1.2.3",
  "deployment_mode": "saas"
}
```

**Status vocabulary:** `up` / `down` / `degraded` / `skipped` / `n/a` — no others.

**Aggregation rule:** top-level `"unhealthy"` + HTTP 503 if ANY check is `down` or `degraded`.

**Endpoint paths:**

| Stack | Readiness | Liveness |
|-------|-----------|----------|
| Go API | `/readyz` | `/health` |
| TypeScript API | `/readyz` | `/health` |
| Next.js | `/api/admin/health/readyz` | same |

**Forbidden anti-patterns** (block progression in Gate 0):
1. Response caching in front of /readyz
2. `/ready` alias (not `/readyz`)
3. `/health/live` + `/health/ready` split
4. `strings.Contains(uri, "tls=true")` — use `url.Parse`
5. Reflection on `*amqp.Connection` for TLS state
6. Inline TLS checks at each connection site — use `ValidateSaaSTLS()`
7. `process.exit()` in Next.js `instrumentation.ts` on probe failure

**Mandatory agent instruction (include in EVERY dispatch):**

> WebFetch `https://raw.githubusercontent.com/LerianStudio/ring/main/dev-team/skills/dev-readyz/SKILL.md` and `sre.md`.
> Follow the canonical response contract exactly. Five-value status vocabulary.
> Aggregation: 503 iff any check is `down` or `degraded`.
> Forbidden anti-patterns 1-7: MUST NOT introduce any.
> TDD: RED → GREEN → REFACTOR.

## Gate Overview

| Gate | Name | Condition | Agent |
|------|------|-----------|-------|
| 0 | Stack Detection + /readyz Compliance Audit | Always | Orchestrator |
| 1 | Codebase Analysis | Always | ring:codebase-explorer |
| 1.5 | Implementation Preview (HTML report) | Always | ring:visualize |
| 2 | /readyz Endpoint Implementation | Always | ring:backend-engineer-{language} |
| 3 | TLS Detection (url.Parse) | Always | ring:backend-engineer-{language} |
| 4 | SaaS TLS Enforcement (ValidateSaaSTLS) | Always | ring:backend-engineer-{language} |
| 5 | Metrics Emission | Always | ring:backend-engineer-{language} |
| 6 | Circuit Breaker + Multi-Tenant Carve-Out | Skip only if no breakers AND single-tenant | ring:backend-engineer-{language} |
| 7 | Startup Self-Probe + /health + Graceful Drain | Always — NEVER skippable | ring:backend-engineer-{language} |
| 8 | Tests | Always | ring:backend-engineer-{language} |
| 9 | Code Review | Always | 13 parallel reviewers |
| 10 | User Validation | Always | User |
| 11 | Activation Guide | Always | Orchestrator |

Gates execute sequentially. Existing /readyz code ≠ compliance. Gate 0 Phase 2 audit is mandatory.

## Gate 0: Stack Detection + Audit

Orchestrator executes directly. Three phases:

**Phase 1: Stack Detection**
```bash
grep -rn "postgresql\|pgx" internal/ go.mod
grep -rn "mongodb\|mongo" internal/ go.mod
grep -rn "redis\|valkey" internal/ go.mod
grep -rn "rabbitmq\|amqp" internal/ go.mod
grep -rn "http.Client\|upstream" internal/
grep -rn "circuitbreaker\|gobreaker" internal/
grep "DEPLOYMENT_MODE\|saas" .env* internal/
```

**Phase 2: Compliance Audit (S1-S9)** (if /readyz code detected)
- S1: Response contract shape (all required fields present)
- S2: Status vocabulary (only 5 valid values)
- S3: Aggregation rule (503 on down/degraded)
- S4: Endpoint path (exact `/readyz`, not `/ready`)
- S5: No response caching
- S6: TLS detection uses `url.Parse`, not `strings.Contains`
- S7: `ValidateSaaSTLS()` called at bootstrap for SaaS mode
- S8: Three readyz metrics emitted
- S9: Startup self-probe gates `/health`

**Phase 3: Anti-Pattern Detection**
Check for each of the 7 forbidden anti-patterns. Any match = COMPLIANT: false.

## Severity Reference

| Severity | Criteria |
|----------|----------|
| CRITICAL | `DEPLOYMENT_MODE=saas` without ValidateSaaSTLS; TLS reflection; response caching |
| HIGH | Wrong status vocabulary; aggregation rule wrong; metrics not emitted; self-probe missing |
| MEDIUM | Missing `reason` on skipped/n/a; drain grace too short |
| LOW | Missing per-dep description; inconsistent version string |