System Zależności (Dependency System)

Przegląd

System zależności w orkiestrze team umożliwia precyzyjne kontrolowanie kolejności wykonywania subtasków. Wykorzystuje dependency graph z wsparciem dla wildcard patterns.

---

Podstawy

Deklaracja Zależności

Każdy subtask może zdefiniować listę zależności w task.json:

{
  "task_id": "frontend_abc123",
  "dependencies": ["init_workspace", "plan_task"]
}

Subtask frontend_abc123 nie zostanie uruchomiony dopóki:

• init_workspace nie będzie w stanie done
• plan_task nie będzie w stanie done

---

Wildcard Patterns

System wspiera wzorce wildcard (*) dla elastycznego zarządzania zależnościami.

Podstawowe Wzorce

1. Konkretny ID

{
  "dependencies": ["init_workspace"]
}

Zachowanie: Czeka na konkretny subtask o ID init_workspace_xyz123

2. Prefix Wildcard

{
  "dependencies": ["frontend_*"]
}

Zachowanie: Czeka na dowolny subtask zaczynający się od frontend_

• Może to być: frontend_component, frontend_service, frontend_styles
• Warunek: Przynajmniej jeden subtask matching pattern musi być done

3. Suffix Wildcard

{
  "dependencies": ["*_tests"]
}

Zachowanie: Czeka na dowolny subtask kończący się na _tests

4. Middle Wildcard

{
  "dependencies": ["test_*_unit"]
}

Zachowanie: Czeka na dowolny subtask pasujący do wzorca

---

Przykłady Użycia

Przykład 1: Deploy po wszystkich testach

{
  "id": "deploy_production",
  "dependencies": [
    "test_unit_*",          // Dowolny test jednostkowy
    "test_integration_*",   // Dowolny test integracyjny
    "build_production"      // Konkretny build
  ]
}

Wymagania:

• ✅ Przynajmniej jeden test jednostkowy ukończony (np. test_unit_auth)
• ✅ Przynajmniej jeden test integracyjny ukończony (np. test_integration_api)
• ✅ Build produkcyjny ukończony (build_production_xyz)

Przykład 2: Review po całym froncie i backu

{
  "id": "reviewer_product_final",
  "dependencies": [
    "frontend_*",    // Wszystkie taski frontendowe
    "backend_*",     // Wszystkie taski backendowe
    "test_*"         // Wszystkie testy
  ]
}

Wymagania:

• ✅ Przynajmniej jeden frontend task done
• ✅ Przynajmniej jeden backend task done
• ✅ Przynajmniej jeden test done

Przykład 3: Konkretne zależności

{
  "id": "test_authentication_flow",
  "dependencies": [
    "frontend_login_form",       // Konkretny task
    "backend_auth_api",          // Konkretny task
    "database_migration_users"   // Konkretny task
  ]
}

Wymagania:

• ✅ frontend_login_form_abc123 done
• ✅ backend_auth_api_def456 done
• ✅ database_migration_users_ghi789 done

---

Implementacja

Algorytm Dependency Resolution

def can_execute_subtask(subtask, completed_subtasks):
    """
    Sprawdza czy subtask może zostać wykonany
    na podstawie jego dependencies.
    """
    for dependency_pattern in subtask.dependencies:
        if is_wildcard(dependency_pattern):
            # Wildcard - sprawdź czy jakikolwiek task pasuje
            if not any_matches(dependency_pattern, completed_subtasks):
                return False
        else:
            # Concrete ID - sprawdź dokładne dopasowanie
            if not exact_match(dependency_pattern, completed_subtasks):
                return False

    return True

def any_matches(pattern, completed_subtasks):
    """
    Sprawdza czy jakikolwiek completed subtask
    pasuje do wzorca wildcard.
    """
    for subtask_id in completed_subtasks:
        if fnmatch(subtask_id, pattern):
            return True
    return False

Bash Implementation (orchestrator_team.yaml)

# Check if dependency is satisfied
check_dependency() {
  local dependency_pattern=$1
  local done_dir=$2

  if [[ "$dependency_pattern" == *"*"* ]]; then
    # Wildcard pattern - check if any subtask matches
    find "$done_dir" -maxdepth 2 -type d -name "${dependency_pattern}" | grep -q .
    return $?
  else
    # Concrete ID - check exact match
    find "$done_dir" -maxdepth 2 -type d -name "${dependency_pattern}_*" | grep -q .
    return $?
  fi
}

# Example usage
if check_dependency "frontend_*" "$SUBTASKS_DIR/P1/done"; then
  echo "✅ Frontend dependency satisfied"
else
  echo "⏳ Waiting for frontend tasks..."
fi

---

Zasady i Best Practices

1. Używaj wildcard dla grup zadań

❌ Źle:

{
  "dependencies": [
    "frontend_component_a",
    "frontend_component_b",
    "frontend_component_c",
    "frontend_service_x",
    "frontend_service_y"
  ]
}

✅ Dobrze:

{
  "dependencies": ["frontend_*"]
}

2. Kombinuj concrete i wildcard

{
  "dependencies": [
    "init_workspace",     // Konkretny - musi być
    "test_*",            // Wildcard - dowolny test
    "build_production"   // Konkretny - musi być
  ]
}

3. Priorytety i dependencies

Zasada: Dependencies mogą wskazywać na taski z wyższych lub tego samego poziomu priorytetu.

❌ Błąd:

// P1 task
{
  "id": "frontend_component",
  "priority": "P1",
  "dependencies": ["test_e2e"]  // test_e2e jest w P2 (niższy priorytet)
}

✅ Poprawnie:

// P2 task
{
  "id": "test_e2e",
  "priority": "P2",
  "dependencies": ["frontend_component"]  // frontend_component w P1 (wyższy)
}

4. Dependency Chains

System automatycznie rozwiązuje łańcuchy zależności:

A → B → C → D

Task D dependencies: ["C"]
Task C dependencies: ["B"]
Task B dependencies: ["A"]
Task A dependencies: []

Kolejność wykonania: A → B → C → D

---

Zaawansowane Przypadki

Circular Dependencies Detection

System wykrywa i blokuje cykliczne zależności:

// ❌ BŁĄD: Circular dependency
{
  "id": "task_a",
  "dependencies": ["task_b"]
}
{
  "id": "task_b",
  "dependencies": ["task_a"]
}

Rezultat: Task zostanie przeniesiony do failed/ z błędem dependency resolution.

Optional Dependencies

Jeśli chcesz aby task wykonał się nawet jeśli dependency nie istnieje:

{
  "id": "deploy",
  "dependencies": ["test_*"],  // Jeśli brak testów - i tak wykonaj
  "optional_dependencies": true
}

Uwaga: Feature optional_dependencies jest planowany (nie zaimplementowany).

---

Monitoring Dependencies

Sprawdzanie statusu zależności

# Dla konkretnego subtaska
cat tasks/in_progress/DEV-7315/subtasks/P1/todo/frontend_abc123/task.json | jq '.dependencies'

# Lista wszystkich done subtasków (potencjalne dependencies)
ls tasks/in_progress/DEV-7315/subtasks/*/done/

Debugging dependency issues

# Sprawdź orchestration log
cat tasks/in_progress/DEV-7315/artifacts/logs/orchestration.log | grep "dependency"

# Przykładowy output:
# ⏳ Waiting for dependencies: frontend_*, backend_api
# ✅ Dependency satisfied: frontend_component_xyz
# ⚠️ Still waiting for: backend_api

---

Changelog

v2.0 - Wildcard Support

• ✅ Dodano wsparcie dla wildcard patterns (*)
• ✅ Implementacja fnmatch dla bash
• ✅ Dokumentacja i przykłady

v1.0 - Initial Release

• ✅ Podstawowy system dependencies
• ✅ Concrete ID matching
• ✅ Dependency graph resolution