Pinning Dependency Versions

---
name: ring:pinning-dependency-versions
description: "Pinning an explicit versioned dependency manifest (dependencies.md plus PROJECT_RULES.md): exact package versions, CVE and license checks, compatibility matrices, and per-component cost analysis against Ring Standards. Gate 6 of ring:planning-large-features; runs after ring:designing-data-model, before ring:writing-plans. Use when the schema is validated and you are about to lock products and versions. Skip for Small Track or when versions are already locked."
---

# Dependency Map — Explicit Technology Choices

## When to use

- Schema (schema.sql / schema.prisma) passed Gate 5 validation
- About to select specific technologies
- Large Track workflow (2+ day features)

## Skip when

- Small Track workflow → skip to ring:writing-plans
- Technologies already locked → skip to ring:writing-plans
- Schema not validated → complete Gate 5 first

## Sequence

**Runs before:** ring:writing-plans
**Runs after:** ring:designing-data-model


Every technology choice must be explicit, versioned, validated against Ring Standards, and justified. The Dependency Map answers WHAT specific products, versions, packages, and infrastructure will be used.

## Step 0: Standards Loading (HARD GATE)

### Step 0.1: Read Technology Decisions from TRD
Read `docs/pre-dev/{feature}/trd.md` — extract: `deployment.model`, `tech_stack.primary`, `project_technologies[]`.

If TRD metadata missing → STOP: "Go back to TRD (Gate 3) and complete Step 0.4."

### Step 0.2: Load Ring Standards via WebFetch

| Standard | URL |
|----------|-----|
| golang/index.md | `https://raw.githubusercontent.com/LerianStudio/ring/main/dev-team/docs/standards/golang/index.md` |
| typescript.md | `https://raw.githubusercontent.com/LerianStudio/ring/main/dev-team/docs/standards/typescript.md` |
| frontend.md | `https://raw.githubusercontent.com/LerianStudio/ring/main/dev-team/docs/standards/frontend.md` |
| devops.md | `https://raw.githubusercontent.com/LerianStudio/ring/main/dev-team/docs/standards/devops.md` |
| sre.md | `https://raw.githubusercontent.com/LerianStudio/ring/main/dev-team/docs/standards/sre.md` |

### Step 0.3: Generate PROJECT_RULES.md (OUTPUT)
Using TRD `project_technologies[]`, create `docs/PROJECT_RULES.md` with: deployment model, tech stack, per-category decisions (PRD requirement, technology, version, rationale, cloud service, on-premise alternative), version matrix, security/compliance notes.

## Mandatory Workflow

| Phase | Activities |
|-------|------------|
| **1. Evaluation** | Ring Standards loaded; map TRD components to tech candidates; validate against Ring Standards; map the schema file (schema.sql / schema.prisma) to storage; map openapi.yaml contracts to protocols; check team expertise; estimate costs |
| **2. Selection** | Per technology: check Ring Standards (mandatory/prohibited), specify exact version, list alternatives with trade-offs, verify compatibility, check security (CVEs), validate licenses, calculate costs |
| **3. Gate 6 Validation** | All dependencies explicit; no conflicts; no critical CVEs; licenses compliant; costs documented; all components mapped |

## Version Rules

1. **Explicit**: `@v1.27.0` not `@latest` or `^1.0.0`
2. **Justified ranges**: If using `>=`, document why
3. **Lock file referenced**: `go.mod`, `package-lock.json`, etc.
4. **Upgrade constraints**: Document why locked/capped
5. **Compatibility**: Document known conflicts

## Include in Dependency Map

- Exact package names with versions (`go.uber.org/zap@v1.27.0`)
- Tech stack with constraints (`Go 1.24+, PostgreSQL 16`)
- Infrastructure specs (`Valkey 8, MinIO`)
- External SDKs, dev tools, security deps, monitoring tools
- Compatibility matrices
- License summary
- Cost analysis

## Never Include

- Implementation code or how to use dependencies
- Task breakdowns or setup instructions
- Architectural patterns (→ TRD)
- Business requirements (→ PRD)

## Output Format

**File:** `docs/PROJECT_RULES.md`
**File:** `docs/pre-dev/{feature}/dependencies.md`

```markdown
# Dependency Map: {Feature Name}

## Technology Decisions

| Category | PRD Requirement | Choice | Version | Rationale | Alternatives Considered |
|----------|----------------|--------|---------|-----------|------------------------|
| Relational DB | Persistent user data | PostgreSQL | 16.2 | Ring standard; team expertise; ACID | MySQL (less preferred), SQLite (no concurrent writes) |
| Cache | Session storage | Valkey | 8.0 | Ring standard; Redis-compatible | Redis (licensing change) |
| Message Queue | Async processing | RabbitMQ | 3.13 | Ring standard; existing infra | Kafka (overkill for volume) |

## Version Matrix

| Package | Version | Lock File | Upgrade Constraint |
|---------|---------|-----------|-------------------|
| go.uber.org/zap | v1.27.0 | go.sum | Stable API; no breaking changes in minor |

## Security & Licenses

| Package | License | CVE Status | Risk |
|---------|---------|-----------|------|
| github.com/jackc/pgx/v5 | MIT | None | Low |

## Cost Analysis

| Component | Shared/Dedicated | Monthly Cost | Notes |
|-----------|-----------------|-------------|-------|
| PostgreSQL (RDS) | Dedicated | R$ 1,490 | 2 vCPU, 8GB RAM |
```

## Gate 6 Validation Checklist

| Category | Requirements |
|----------|--------------|
| **Completeness** | All TRD components have specific technology choices; all dependencies explicit |
| **Versioning** | Exact versions specified; no `@latest`; lock files referenced |
| **Standards Compliance** | Choices validated against Ring Standards; prohibited packages avoided |
| **Security** | No critical CVEs; licenses compliant; security deps included |
| **Costs** | Cost per component documented; shared vs dedicated decisions made |

**Gate Result:** ✅ PASS → Plan (ring:writing-plans) | ⚠️ CONDITIONAL (version gaps or cost estimates missing) | ❌ FAIL (unresolved conflicts or CVEs)