ring%3apre-dev-dependency-map（ring%3apre 开发依赖关系图）

Dependency Map - Explicit Technology Choices

Foundational Principle

Every technology choice must be explicit, versioned, validated against Ring Standards, and justified.

Using vague or "latest" dependencies creates:

• Unreproducible builds across environments
• Hidden incompatibilities discovered during implementation
• Security vulnerabilities from unvetted versions

The Dependency Map answers: WHAT specific products, versions, packages, and infrastructure we'll use. The Dependency Map never answers: HOW to implement features (that's Tasks/Subtasks).

⛔ HARD BLOCK: Standards Loading (Step 0)

This is a HARD GATE. Do NOT proceed without loading Ring Standards and TRD decisions.

Step 0.1: Read Technology Decisions from TRD

Read docs/pre-dev/{feature-name}/trd.md and extract: deployment.model, tech_stack.primary, project_technologies[]

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

Step 0.2: Load Ring Standards via WebFetch

Ring Standards = coding patterns, observability, logging, error handling (shared across ALL projects) PROJECT_RULES.md = specific technologies, versions, database choices (specific to THIS project)

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.

Pressure Resistance for Step 0

Mandatory Workflow

Explicit Rules

✅ DO Include

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, how to use dependencies, task breakdowns, setup instructions, architectural patterns (TRD), business requirements (PRD)

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

Rationalization Table

Red Flags - STOP

If you catch yourself writing any of these in a Dependency Map, STOP:

• Version placeholders: @latest, @next, ^X.Y.Z without justification
• Vague descriptions: "latest stable", "current version", "newest"
• Missing version numbers: Just package names without versions
• Unchecked compatibility: Not verifying version conflicts
• Unvetted security: Not checking vulnerability databases
• Unknown licenses: Not documenting license types
• Estimated costs as "TBD" or "unknown"
• "We'll use whatever is default" (no default without analysis)

When you catch yourself: Stop and specify the exact version after proper analysis.

Gate 6 Validation Checklist

Gate Result: ✅ PASS (all checked) → Task Breakdown | ⚠️ CONDITIONAL (standards not loaded) → Complete Step 0 | ❌ FAIL (critical CVEs, incompatibilities, standards not loaded)

Common Violations

Dependency Resolution Patterns

Standards-Driven Validation

If language cannot be auto-detected, use AskUserQuestion with tech stack options (Go Backend, TypeScript Backend, TypeScript Frontend, Full-Stack TypeScript).

Validation Flow: Standards loaded → Extract mandatory/prohibited/constraints → Check PROJECT_RULES.md → Validate each selection → Document compliance or justified deviations

Best Practices

Prefer: Semantic versioned packages, well-maintained (commits within 6 months), minimal dependency trees, standard library when sufficient Avoid: Deprecated packages (>1 year unmaintained), single-maintainer critical deps, >100 transitive deps, GPL unless compliance certain

Authentication Dependencies (Mandatory for Auth Features)

If TRD specifies authentication/authorization requirements, include these dependencies:

For Go services, the dependency entry MUST include:

### Authentication

**Package:** `github.com/LerianStudio/lib-auth/v2@vX.Y.Z`
**Purpose:** Integration with Lerian Access Manager (plugin-auth + identity)
**Rationale:** Standard authentication library for all Lerian Go services
**Environment Variables:** PLUGIN_AUTH_ADDRESS, PLUGIN_AUTH_ENABLED
**Additional (if S2S):** CLIENT_ID, CLIENT_SECRET
**Reference:** See `golang.md` → Access Manager Integration for implementation patterns

CRITICAL: Go services MUST use lib-auth for authentication. Direct integration with plugin-auth is FORBIDDEN.

Implementation Requirement (from TRD):

• Every protected endpoint MUST have route middleware: auth.Authorize(applicationName, resource, action)
• Middleware is applied per-route, not globally
• See golang.md → Access Manager Integration → Router Setup for patterns

Licensing Dependencies (Mandatory for Licensed Products)

If TRD specifies this is a licensed product/plugin, include these dependencies:

For Go services, the dependency entry MUST include:

### Licensing

**Package:** `github.com/LerianStudio/lib-license-go/v2/middleware@vX.Y.Z`
**Purpose:** Integration with Lerian License Manager for product licensing
**Rationale:** Standard licensing library for all Lerian licensed Go services
**Environment Variables:** LICENSE_KEY, ORGANIZATION_IDS
**Mode:** Global (ORGANIZATION_IDS=global) or Multi-org (comma-separated org IDs)
**Reference:** See `golang.md` → License Manager Integration for implementation patterns

CRITICAL: Go services MUST use lib-license-go for licensing. Custom license validation is FORBIDDEN.

Implementation Requirement (from TRD):

• License middleware applied GLOBALLY: f.Use(lc.Middleware())
• Middleware applied early in chain (first after Fiber creation)
• Graceful shutdown MUST include: licenseClient.GetLicenseManagerShutdown()
• See golang.md → License Manager Integration → Router Setup for patterns

License & Cost Templates

License Summary: Document count by type (MIT, Apache 2.0, BSD-3-Clause, Commercial), compliance actions (attribution file, legal notification, GPL verification)

Cost Analysis: Monthly breakdown by category (Compute: containers × cost, Storage: managed DB + cache + object, Network: transfer + load balancer, Third-Party: auth + email + monitoring), grand total, scaling cost per additional users, budget validation

Confidence Scoring

Action: 80+ autonomous generation | 50-79 present alternatives | <50 ask about expertise/constraints

Output & After Approval

Output to: docs/pre-dev/{feature-name}/dependency-map.md

1. ✅ Lock all versions - update only with documented justification
2. 🎯 Create lock files (go.mod, package-lock.json, etc.)
3. 🔒 Set up Dependabot or equivalent for security updates
4. 📋 Proceed to task breakdown with full stack context

The Bottom Line

If you skipped loading Ring Standards, STOP and go back to Step 0.

If you wrote a Dependency Map without explicit versions, add them now or start over.

Two non-negotiable requirements:

1. Ring Standards MUST be loaded - Technology choices validated against organizational baseline
2. Every dependency MUST be explicit - No @latest, no vague versions, no "we'll figure it out"

Load standards first. Be explicit. Be specific. Lock your versions.

Blocker Criteria - STOP and Report

Cannot Be Overridden

These requirements are NON-NEGOTIABLE:

• MUST complete Step 0 (Standards Loading) before selecting technologies
• MUST NOT use @latest, @next, or vague version ranges
• MUST specify exact versions for ALL dependencies
• MUST scan for CVEs before finalizing selections
• MUST verify license compatibility for commercial use
• MUST include lib-auth for Go services requiring authentication
• MUST include lib-license-go for Go services requiring licensing
• CANNOT proceed to Gate 7 with missing versions or unresolved CVEs

Severity Calibration

Pressure Resistance

When This Skill Is Not Needed

• Small Track workflow (skip to Task Breakdown)
• Technologies already locked and validated
• Data Model (Gate 5) not validated → complete Gate 5 first
• Dependency Map already exists and versions are current
• No new technology decisions needed for this feature