aiox-core 5.0.4 → 5.0.5

package/pro/squads/squad-creator-pro/scripts/squad_utils.py

@@ -1,261 +0,0 @@
-#!/usr/bin/env python3
-"""
-Squad Utilities - Shared functions for squad management scripts.
-
-Contains deterministic logic for:
-- Maturity calculation (DRAFT → DEVELOPING → OPERATIONAL)
-- Usage signal detection
-- Consistency rules for maturity/validated fields
-
-CRITICAL RULE - Maturity/Validated Consistency:
-- validated=True MUST mean maturity=OPERATIONAL
-- validated=False EXPLICIT (via validated_explicit=True) BLOCKS auto-promotion
-- validated=False DEFAULT allows auto-promotion based on evidence
-
-Usage:
-    from squad_utils import calculate_maturity, detect_squad_usage, MATURITY_*
-"""
-
-from pathlib import Path
-from typing import Dict, Any, Optional
-
-
-# =============================================================================
-# MATURITY CONSTANTS (ALWAYS at top of file)
-# =============================================================================
-
-MATURITY_DRAFT = "DRAFT"           # Missing essential components (tasks=0 or tasks<3 and workflows=0)
-MATURITY_DEVELOPING = "DEVELOPING" # Has components but no validated usage
-MATURITY_OPERATIONAL = "OPERATIONAL"  # Validated usage detected (outputs exist or manually validated)
-
-
-# =============================================================================
-# USAGE DETECTION
-# =============================================================================
-
-def detect_squad_usage(squad_name: str, project_root: Path) -> Dict[str, Any]:
-    """
-    Detect signals of real squad usage (AI-first, no forms).
-
-    Signals checked:
-    1. outputs/{squad}/ - outputs generated by squad
-    2. squads/{squad}/artifacts/ - artifacts inside squad folder
-    3. squads/{squad}/.validation/ - validation evidence
-
-    Args:
-        squad_name: Name of the squad to check
-        project_root: Path to project root (parent of squads/)
-
-    Returns:
-        Dict with detection results:
-        - outputs_found: int - number of output files
-        - artifacts_found: int - number of artifact files
-        - validation_exists: bool - whether .validation/ folder exists
-        - total_evidence: int - outputs + artifacts count
-    """
-    signals = {
-        "outputs_found": 0,
-        "artifacts_found": 0,
-        "validation_exists": False,
-        "total_evidence": 0,
-    }
-
-    # 1. Check outputs/{squad}/
-    outputs_path = project_root / "outputs" / squad_name
-    if outputs_path.exists():
-        try:
-            files = [f for f in outputs_path.rglob("*") if f.is_file()]
-            signals["outputs_found"] = len(files)
-        except (OSError, IOError) as e:
-            # Log but don't fail
-            pass
-
-    # 2. Check squads/{squad}/artifacts/
-    artifacts_path = project_root / "squads" / squad_name / "artifacts"
-    if artifacts_path.exists():
-        try:
-            files = [f for f in artifacts_path.rglob("*") if f.is_file()]
-            signals["artifacts_found"] = len(files)
-        except (OSError, IOError) as e:
-            # Log but don't fail
-            pass
-
-    # 3. Check squads/{squad}/.validation/
-    validation_path = project_root / "squads" / squad_name / ".validation"
-    if validation_path.exists():
-        signals["validation_exists"] = True
-
-    signals["total_evidence"] = signals["outputs_found"] + signals["artifacts_found"]
-
-    return signals
-
-
-# =============================================================================
-# MATURITY CALCULATION
-# =============================================================================
-
-def calculate_maturity(
-    counts: Dict[str, int],
-    usage_signals: Optional[Dict[str, Any]] = None,
-    existing_validated: bool = False,
-    validated_explicit: bool = False
-) -> str:
-    """
-    Calculate squad maturity level (deterministic).
-
-    Levels:
-    - DRAFT: Missing essential components (tasks=0 or tasks<3 and workflows=0)
-    - DEVELOPING: Has components but no validated usage
-    - OPERATIONAL: Validated usage (outputs detected OR manually validated in registry)
-
-    CRITICAL CONSISTENCY RULE:
-    - If validated_explicit=True AND existing_validated=False, do NOT auto-promote to OPERATIONAL
-    - This prevents the bug where maturity=OPERATIONAL but validated=false
-
-    Args:
-        counts: Component counts dict with 'tasks' and 'workflows' keys
-        usage_signals: Results from detect_squad_usage(), optional
-        existing_validated: True if registry has validated=true for this squad
-        validated_explicit: True if validated was EXPLICITLY set (not just default)
-                           When True and existing_validated=False, blocks auto-promotion
-
-    Returns:
-        Maturity level string: DRAFT, DEVELOPING, or OPERATIONAL
-    """
-    tasks = counts.get("tasks", 0) if counts else 0
-    workflows = counts.get("workflows", 0) if counts else 0
-
-    # DRAFT: Missing essential components
-    if tasks == 0:
-        return MATURITY_DRAFT
-    if tasks < 3 and workflows == 0:
-        return MATURITY_DRAFT
-
-    # OPERATIONAL: Human validated (always trust explicit human validation)
-    if existing_validated:
-        return MATURITY_OPERATIONAL
-
-    # CRITICAL: If human EXPLICITLY set validated=false, respect it
-    # Do NOT auto-promote based on evidence
-    if validated_explicit:
-        return MATURITY_DEVELOPING
-
-    # Auto-detection: promote to OPERATIONAL if enough evidence
-    if usage_signals:
-        if usage_signals.get("total_evidence", 0) >= 3:
-            return MATURITY_OPERATIONAL
-
-        if usage_signals.get("validation_exists", False):
-            return MATURITY_OPERATIONAL
-
-    # DEVELOPING: Has components but not validated
-    return MATURITY_DEVELOPING
-
-
-def is_maturity_validated_consistent(maturity: str, validated: bool) -> bool:
-    """
-    Check if maturity and validated fields are consistent.
-
-    Rules:
-    - If validated=True, maturity MUST be OPERATIONAL
-    - If maturity=OPERATIONAL, validated SHOULD be True (warning if false)
-    - Other combinations are valid
-
-    Args:
-        maturity: Current maturity level
-        validated: Current validated flag
-
-    Returns:
-        True if consistent, False if inconsistent
-    """
-    # If validated=True but not OPERATIONAL, that's a problem
-    if validated and maturity != MATURITY_OPERATIONAL:
-        return False
-
-    # Note: maturity=OPERATIONAL with validated=False is allowed
-    # (can happen during auto-detection before human validation)
-    # But we return True with a softer check
-
-    return True
-
-
-def resolve_maturity_validated(
-    counts: Dict[str, int],
-    usage_signals: Optional[Dict[str, Any]],
-    existing_validated: bool,
-    validated_explicit: bool
-) -> Dict[str, Any]:
-    """
-    Calculate maturity AND validated together to ensure consistency.
-
-    This is the RECOMMENDED function to use instead of calculate_maturity()
-    when you need both fields, as it guarantees they will be consistent.
-
-    Args:
-        counts: Component counts dict
-        usage_signals: Results from detect_squad_usage()
-        existing_validated: Current validated value from registry
-        validated_explicit: Whether validated was explicitly set
-
-    Returns:
-        Dict with:
-        - maturity: str - calculated maturity level
-        - validated: bool - consistent validated flag
-        - auto_promoted: bool - True if maturity was auto-promoted from evidence
-    """
-    maturity = calculate_maturity(
-        counts=counts,
-        usage_signals=usage_signals,
-        existing_validated=existing_validated,
-        validated_explicit=validated_explicit
-    )
-
-    # Determine validated flag
-    if existing_validated:
-        # Human said it's validated, keep it
-        validated = True
-        auto_promoted = False
-    elif validated_explicit:
-        # Human explicitly said NOT validated, respect it
-        validated = False
-        auto_promoted = False
-    else:
-        # Auto-detection mode
-        validated = (maturity == MATURITY_OPERATIONAL)
-        auto_promoted = validated
-
-    return {
-        "maturity": maturity,
-        "validated": validated,
-        "auto_promoted": auto_promoted
-    }
-
-
-# =============================================================================
-# HELPER FUNCTIONS
-# =============================================================================
-
-def get_project_root_from_squads_path(squads_path: Path) -> Path:
-    """
-    Get project root from squads/ directory path.
-
-    Args:
-        squads_path: Path to squads/ directory
-
-    Returns:
-        Path to project root (parent of squads/)
-    """
-    return squads_path.parent
-
-
-def get_project_root_from_squad_path(squad_path: Path) -> Path:
-    """
-    Get project root from a specific squad's directory path.
-
-    Args:
-        squad_path: Path to squads/{squad-name}/ directory
-
-    Returns:
-        Path to project root (grandparent of squad path)
-    """
-    return squad_path.parent.parent