/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`

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