Skip to content

REQ-O-031: Dependency Version Matrix Declaration

Tier: Opt-In | Priority: P1

Source: §38 Runtime Dependency Version Mismatch

Addresses: Severity: High / Token Spend: Medium / Time: High / Context: Low

Description

The framework MUST provide a mechanism for declaring all required runtime dependencies (external binaries, runtimes, and system libraries) with their minimum and maximum compatible version constraints. Each declared dependency MUST include: name, check_command (exact shell command to verify presence), version_regex (regex to extract the version string from check_command output), min_version, max_version (optional), and fix_command (exact shell command to install or upgrade). These declarations are automatically consumed by tool doctor (REQ-O-026) and emitted in --schema output.

Acceptance Criteria

  • A declared dependency with a version below min_version appears as a failed check in tool doctor
  • A declared dependency with a version above max_version appears as a compatibility warning in tool doctor
  • tool doctor --output json includes a dependencies array with all declared dependencies and their check results
  • The fix_command for each failed dependency is an executable shell command

Schema

Types: manifest-response.md · response-envelope.md

Declared dependencies appear in the manifest's dependencies field and in tool doctor output.

Wire Format

tool doctor --output json (dependencies section):

{
  "ok": false,
  "data": {
    "checks": [],
    "dependencies": [
      { "name": "node", "check_command": "node --version", "version_regex": "v(\\d+\\.\\d+)", "min_version": "18.0.0", "found_version": "20.11.0", "ok": true },
      { "name": "terraform", "check_command": "terraform version", "version_regex": "Terraform v(\\d+\\.\\d+)", "min_version": "1.5.0", "found_version": null, "ok": false, "fix_command": "brew install terraform" }
    ]
  },
  "error": null,
  "warnings": [],
  "meta": { "duration_ms": 412 }
}

Example

Opt-in: the framework provides a declare_dependency() registration API.

app = Framework("tool")

app.declare_dependency(
  name="terraform",
  check_command="terraform version",
  version_regex=r"Terraform v(\d+\.\d+)",
  min_version="1.5.0",
  fix_command="brew install terraform",
)

# Dependency checks run automatically in tool doctor:
$ tool doctor
→ FAIL terraform: not found (fix: brew install terraform)
Requirement Tier Relationship
REQ-O-026 O Consumes: declared dependencies as checks run by tool doctor
REQ-C-018 C Composes: per-command platform requirements augment the global dependency matrix