aiox-core 5.0.5 → 5.0.8

package/pro/squads/squad-creator/scripts/validate-squad-structure.py

@@ -0,0 +1,881 @@
+#!/usr/bin/env python3
+"""
+Validate Squad Structure - Worker Script (Deterministic)
+
+Phases 0-2 of validate-squad.md - 100% deterministic operations:
+- Phase 0: Type Detection (scan config, count agents, check patterns)
+- Phase 1: Structure Validation (files exist, YAML valid, required fields)
+- Phase 2: Coverage Analysis (checklist coverage, orphan detection, data usage)
+
+For full validation including quality analysis (Phases 3-6), use:
+  ./scripts/validate-squad.sh {squad-name}
+
+Usage:
+    python scripts/validate-squad-structure.py {squad-name}
+    python scripts/validate-squad-structure.py {squad-name} --output json
+    python scripts/validate-squad-structure.py {squad-name} --verbose
+    python scripts/validate-squad-structure.py /path/to/squad  (path mode)
+
+Output format (--output json):
+{
+  "phase": "structure",
+  "squad_type": "...",
+  "structure_valid": true/false,
+  "coverage": {"agents": N, "tasks": N, "workflows": N},
+  "issues": [],
+  "score": 0-100
+}
+
+Exit codes: 0 = pass, 1 = fail, 2 = error
+
+Pattern: EXEC-W-001 (Worker - Deterministic)
+"""
+
+import os
+import sys
+import yaml
+import json
+import re
+import argparse
+from pathlib import Path
+from datetime import datetime
+from typing import Dict, List, Any, Optional, Tuple
+
+
+# ============================================================================
+# CONFIGURATION
+# ============================================================================
+
+THRESHOLDS = {
+    "checklist_coverage_min": 0.30,  # 30%
+    "orphan_tasks_max": 2,
+    "data_usage_min": 0.50,  # 50%
+    "security_patterns": {
+        "api_key": r"(api[_-]?key|apikey)\s*[:=]\s*['\"][^'\"\$\{]{8,}",
+        "credential_secret": r"((client|api|app|access|jwt|signing|service)[_-]?secret|secret[_-]?key|password)\s*[:=]\s*['\"][^'\"\$\{]{8,}",
+        "aws_key": r"AKIA[A-Z0-9]{16}",
+        "private_key": r"-----BEGIN.*(PRIVATE|RSA|DSA|EC).*KEY-----",
+        "db_url": r"(postgres|mysql|mongodb|redis)://[^:]+:[^@]+@",
+    }
+}
+
+WORKSPACE_LEVELS = {"none", "read_only", "controlled_runtime_consumer", "workspace_first"}
+
+
+# ============================================================================
+# UTILITIES
+# ============================================================================
+
+def find_squads_root() -> Path:
+    """Find the squads/ directory"""
+    current = Path(__file__).parent.parent.parent  # scripts -> squad-creator -> squads
+    if current.name == "squads" or (current / "squad-creator").exists():
+        return current
+
+    # Try from cwd
+    cwd = Path.cwd()
+    if (cwd / "squads").exists():
+        return cwd / "squads"
+    if cwd.name == "squads":
+        return cwd
+
+    raise FileNotFoundError("Could not find squads/ directory")
+
+
+def has_workspace_governance_squad(squads_root: Path) -> bool:
+    return (squads_root / "c-level").exists()
+
+
+def count_files(directory: Path, patterns: List[str] = ["*.md", "*.yaml", "*.yml"]) -> int:
+    """Count files matching patterns"""
+    if not directory.exists():
+        return 0
+    count = 0
+    for pattern in patterns:
+        count += len(list(directory.glob(pattern)))
+    return count
+
+
+def read_yaml(file_path: Path) -> Optional[Dict]:
+    """Read and parse YAML file"""
+    if not file_path.exists():
+        return None
+    try:
+        with open(file_path, 'r', encoding='utf-8') as f:
+            return yaml.safe_load(f)
+    except Exception:
+        return None
+
+
+def grep_in_file(file_path: Path, pattern: str) -> List[str]:
+    """Search for pattern in file"""
+    if not file_path.exists():
+        return []
+    try:
+        with open(file_path, 'r', encoding='utf-8') as f:
+            content = f.read()
+        return re.findall(pattern, content, re.MULTILINE | re.IGNORECASE)
+    except Exception:
+        return []
+
+
+# ============================================================================
+# PHASE 0: TYPE DETECTION
+# ============================================================================
+
+def detect_squad_type(squad_path: Path) -> Dict[str, Any]:
+    """Detect squad type: expert, pipeline, or hybrid"""
+    result = {
+        "detected_type": "general",
+        "confidence": 0,
+        "signals": {},
+        "scoring": {
+            "expert": 0,
+            "pipeline": 0,
+            "hybrid": 0
+        }
+    }
+
+    agents_dir = squad_path / "agents"
+    tasks_dir = squad_path / "tasks"
+    workflows_dir = squad_path / "workflows"
+
+    # Count components
+    agent_count = count_files(agents_dir, ["*.md"])
+    task_count = count_files(tasks_dir, ["*.md"])
+    workflow_count = count_files(workflows_dir, ["*.yaml", "*.yml", "*.md"])
+
+    result["signals"]["agent_count"] = agent_count
+    result["signals"]["task_count"] = task_count
+    result["signals"]["workflow_count"] = workflow_count
+
+    # Expert signals
+    voice_dna_count = 0
+    if agents_dir.exists():
+        for agent_file in agents_dir.glob("*.md"):
+            content = agent_file.read_text(encoding='utf-8', errors='ignore')
+            if "voice_dna:" in content or "Voice DNA" in content:
+                voice_dna_count += 1
+
+    result["signals"]["voice_dna_count"] = voice_dna_count
+
+    # Expert scoring
+    if agent_count >= 5:
+        result["scoring"]["expert"] += 2
+    if voice_dna_count > 0:
+        result["scoring"]["expert"] += 3
+
+    # Pipeline scoring
+    if workflow_count > 0:
+        result["scoring"]["pipeline"] += 3
+    if task_count > 0 and agent_count > 0:
+        ratio = task_count / max(agent_count, 1)
+        result["signals"]["task_agent_ratio"] = round(ratio, 2)
+        if ratio > 3:
+            result["scoring"]["pipeline"] += 2
+
+    # Check for phase patterns
+    phase_count = 0
+    if tasks_dir.exists():
+        for task_file in tasks_dir.glob("*.md"):
+            content = task_file.read_text(encoding='utf-8', errors='ignore')
+            if re.search(r"phase|stage|step\s+\d", content, re.IGNORECASE):
+                phase_count += 1
+    result["signals"]["phase_pattern_files"] = phase_count
+    if phase_count > 3:
+        result["scoring"]["pipeline"] += 2
+
+    # Hybrid signals
+    human_refs = 0
+    for md_file in squad_path.rglob("*.md"):
+        content = md_file.read_text(encoding='utf-8', errors='ignore')
+        if re.search(r"human|manual|executor.*type", content, re.IGNORECASE):
+            human_refs += 1
+    result["signals"]["human_refs"] = human_refs
+    if human_refs > 2:
+        result["scoring"]["hybrid"] += 3
+
+    # Determine winner
+    max_score = max(result["scoring"].values())
+    if result["scoring"]["expert"] == max_score and max_score >= 4:
+        result["detected_type"] = "expert"
+        result["confidence"] = min(result["scoring"]["expert"], 10)
+    elif result["scoring"]["pipeline"] == max_score and max_score >= 4:
+        result["detected_type"] = "pipeline"
+        result["confidence"] = min(result["scoring"]["pipeline"], 10)
+    elif result["scoring"]["hybrid"] >= 3:
+        result["detected_type"] = "hybrid"
+        result["confidence"] = min(result["scoring"]["hybrid"], 10)
+    else:
+        result["detected_type"] = "general"
+        result["confidence"] = 5
+
+    return result
+
+
+# ============================================================================
+# PHASE 1: STRUCTURE VALIDATION
+# ============================================================================
+
+def validate_structure(squad_path: Path) -> Dict[str, Any]:
+    """Validate squad structure - Phase 1"""
+    squads_root = find_squads_root()
+    result = {
+        "passed": True,
+        "checks": [],
+        "blocking_issues": [],
+        "warnings": []
+    }
+
+    # T1-CFG-001: config.yaml exists
+    config_path = squad_path / "config.yaml"
+    if config_path.exists():
+        result["checks"].append({"id": "T1-CFG-001", "status": "pass", "message": "config.yaml exists"})
+
+        # T1-CFG-002: Valid YAML
+        config = read_yaml(config_path)
+        if config:
+            result["checks"].append({"id": "T1-CFG-002", "status": "pass", "message": "config.yaml is valid YAML"})
+
+            # CI-PAR-001: pack: section (mirrors CI validate-squads "Verify squad structure" step)
+            config_text = config_path.read_text(encoding='utf-8', errors='ignore')
+            if re.search(r'^pack:', config_text, re.MULTILINE):
+                result["checks"].append({"id": "CI-PAR-001", "status": "pass", "message": "config.yaml has 'pack:' section"})
+            else:
+                result["checks"].append({"id": "CI-PAR-001", "status": "fail", "message": "config.yaml missing 'pack:' section (CI hard-mandatory)"})
+                result["blocking_issues"].append("config.yaml missing 'pack:' section (CI hard-mandatory)")
+                result["passed"] = False
+
+            # T1-CFG-003: Required fields
+            required = ["name", "version"]
+            for field in required:
+                # Check top level or under squad_config/squad/pack (legacy)
+                found = False
+                if field in config:
+                    found = True
+                elif "squad_config" in config and field in config["squad_config"]:
+                    found = True
+                elif "squad" in config and field in config["squad"]:
+                    found = True
+                elif "pack" in config and field in config["pack"]:
+                    found = True
+
+                if found:
+                    result["checks"].append({"id": f"T1-CFG-003-{field}", "status": "pass", "message": f"Has '{field}' field"})
+                else:
+                    result["checks"].append({"id": f"T1-CFG-003-{field}", "status": "fail", "message": f"Missing '{field}' field"})
+                    result["blocking_issues"].append(f"config.yaml missing required field: {field}")
+                    result["passed"] = False
+
+            # T1-WSP-001: workspace integration level declared
+            workspace_level = None
+            if isinstance(config.get("workspace_integration"), dict):
+                workspace_level = config.get("workspace_integration", {}).get("level")
+            if workspace_level is None:
+                workspace_level = config.get("workspace_integration_level")
+
+            if not workspace_level:
+                result["checks"].append({
+                    "id": "T1-WSP-001",
+                    "status": "fail",
+                    "message": "Missing workspace integration level (workspace_integration.level)"
+                })
+                result["blocking_issues"].append("workspace integration level is required")
+                result["passed"] = False
+            elif workspace_level not in WORKSPACE_LEVELS:
+                result["checks"].append({
+                    "id": "T1-WSP-001",
+                    "status": "fail",
+                    "message": f"Invalid workspace integration level: {workspace_level}"
+                })
+                result["blocking_issues"].append(f"invalid workspace integration level: {workspace_level}")
+                result["passed"] = False
+            else:
+                result["checks"].append({
+                    "id": "T1-WSP-001",
+                    "status": "pass",
+                    "message": f"Workspace integration level: {workspace_level}"
+                })
+
+                if workspace_level != "none":
+                    refs_found = False
+                    for file in squad_path.rglob("*"):
+                        if file.suffix.lower() not in [".md", ".yaml", ".yml"]:
+                            continue
+                        content = file.read_text(encoding='utf-8', errors='ignore')
+                        if "workspace/" in content:
+                            refs_found = True
+                            break
+
+                    if refs_found:
+                        result["checks"].append({
+                            "id": "T1-WSP-002",
+                            "status": "pass",
+                            "message": "Workspace references found in squad artifacts"
+                        })
+                    else:
+                        result["checks"].append({
+                            "id": "T1-WSP-002",
+                            "status": "fail",
+                            "message": f"Level '{workspace_level}' requires workspace path references"
+                        })
+                        result["blocking_issues"].append("workspace integration declared without workspace path references")
+                        result["passed"] = False
+
+                if workspace_level in {"controlled_runtime_consumer", "workspace_first"}:
+                    if has_workspace_governance_squad(squads_root):
+                        result["checks"].append({
+                            "id": "T1-WSP-003A",
+                            "status": "pass",
+                            "message": "Workspace governance squad exists for advanced workspace integration"
+                        })
+                    else:
+                        result["checks"].append({
+                            "id": "T1-WSP-003A",
+                            "status": "fail",
+                            "message": f"Level '{workspace_level}' requires squads/c-level to exist"
+                        })
+                        result["blocking_issues"].append("advanced workspace integration requires squads/c-level")
+                        result["passed"] = False
+
+                    handoff_found = False
+                    for file in squad_path.rglob("*"):
+                        if file.suffix.lower() not in [".md", ".yaml", ".yml"]:
+                            continue
+                        content = file.read_text(encoding='utf-8', errors='ignore')
+                        if any(token in content for token in ["@coo", "COO", "c-level", "workspace-handoff.yaml"]):
+                            handoff_found = True
+                            break
+
+                    if handoff_found:
+                        result["checks"].append({
+                            "id": "T1-WSP-003",
+                            "status": "pass",
+                            "message": "Workspace write integration delegates to COO/c-level"
+                        })
+                    else:
+                        result["checks"].append({
+                            "id": "T1-WSP-003",
+                            "status": "fail",
+                            "message": f"Level '{workspace_level}' requires explicit COO/c-level handoff"
+                        })
+                        result["blocking_issues"].append("workspace write integration missing COO/c-level handoff")
+                        result["passed"] = False
+
+                if workspace_level == "workspace_first":
+                    scripts_dir = squad_path / "scripts"
+                    bootstrap_scripts = list(scripts_dir.glob("bootstrap-*-workspace.sh")) if scripts_dir.exists() else []
+                    essentials_scripts = list(scripts_dir.glob("validate-*-essentials.sh")) if scripts_dir.exists() else []
+
+                    if bootstrap_scripts:
+                        result["checks"].append({
+                            "id": "T1-WSP-004",
+                            "status": "pass",
+                            "message": "workspace_first bootstrap script exists"
+                        })
+                    else:
+                        result["checks"].append({
+                            "id": "T1-WSP-004",
+                            "status": "fail",
+                            "message": "workspace_first requires scripts/bootstrap-*-workspace.sh"
+                        })
+                        result["blocking_issues"].append("workspace_first missing bootstrap workspace script")
+                        result["passed"] = False
+
+                    if essentials_scripts:
+                        result["checks"].append({
+                            "id": "T1-WSP-005",
+                            "status": "pass",
+                            "message": "workspace_first essentials validator script exists"
+                        })
+                    else:
+                        result["checks"].append({
+                            "id": "T1-WSP-005",
+                            "status": "fail",
+                            "message": "workspace_first requires scripts/validate-*-essentials.sh"
+                        })
+                        result["blocking_issues"].append("workspace_first missing essentials validator script")
+                        result["passed"] = False
+        else:
+            result["checks"].append({"id": "T1-CFG-002", "status": "fail", "message": "config.yaml has invalid YAML"})
+            result["blocking_issues"].append("config.yaml has invalid YAML syntax")
+            result["passed"] = False
+    else:
+        result["checks"].append({"id": "T1-CFG-001", "status": "fail", "message": "config.yaml not found"})
+        result["blocking_issues"].append("config.yaml not found")
+        result["passed"] = False
+
+    # T1-ENT-001: Entry agent exists
+    agents_dir = squad_path / "agents"
+    if agents_dir.exists():
+        agent_files = list(agents_dir.glob("*.md"))
+        if agent_files:
+            result["checks"].append({"id": "T1-ENT-001", "status": "pass", "message": f"Found {len(agent_files)} agents"})
+        else:
+            result["checks"].append({"id": "T1-ENT-001", "status": "fail", "message": "No agent files found"})
+            result["blocking_issues"].append("No agent files in agents/")
+            result["passed"] = False
+    else:
+        result["checks"].append({"id": "T1-DIR-001", "status": "fail", "message": "agents/ directory not found"})
+        result["blocking_issues"].append("agents/ directory not found")
+        result["passed"] = False
+
+    # T1-SEC: Security scan
+    security_issues = []
+    for pattern_name, pattern in THRESHOLDS["security_patterns"].items():
+        for file in squad_path.rglob("*.md"):
+            matches = grep_in_file(file, pattern)
+            if matches:
+                # Filter out obvious examples/placeholders
+                real_matches = [m for m in matches if not any(x in str(m).lower() for x in
+                    ["example", "placeholder", "your-", "xxx", "{{", "${"])]
+                if real_matches:
+                    security_issues.append({
+                        "pattern": pattern_name,
+                        "file": str(file.relative_to(squad_path)),
+                        "count": len(real_matches)
+                    })
+
+    if security_issues:
+        result["checks"].append({"id": "T1-SEC-001", "status": "fail", "message": f"Found {len(security_issues)} security issues"})
+        result["blocking_issues"].extend([f"Security: {i['pattern']} in {i['file']}" for i in security_issues])
+        result["passed"] = False
+    else:
+        result["checks"].append({"id": "T1-SEC-001", "status": "pass", "message": "No security issues found"})
+
+    # CI-PAR-002: YAML syntax check for all .yaml/.yml files in squad
+    # Mirrors GrantBirki json-yaml-validate action used in CI validate-yaml job
+    yaml_errors = []
+    for yaml_file in sorted(squad_path.rglob("*.yaml")) + sorted(squad_path.rglob("*.yml")):
+        try:
+            with open(yaml_file, encoding='utf-8', errors='ignore') as f:
+                yaml.safe_load(f)
+        except yaml.YAMLError as e:
+            rel = yaml_file.relative_to(squad_path)
+            mark = getattr(e, 'problem_mark', None)
+            line = mark.line + 1 if mark else '?'
+            yaml_errors.append(f"{rel}:{line} — {e.problem if hasattr(e, 'problem') else str(e)}")
+
+    if yaml_errors:
+        result["checks"].append({
+            "id": "CI-PAR-002",
+            "status": "fail",
+            "message": f"YAML syntax errors in {len(yaml_errors)} file(s)"
+        })
+        result["blocking_issues"].extend([f"Invalid YAML: {e}" for e in yaml_errors])
+        result["passed"] = False
+    else:
+        result["checks"].append({"id": "CI-PAR-002", "status": "pass", "message": "All YAML files have valid syntax"})
+
+    return result
+
+
+# ============================================================================
+# PHASE 2: COVERAGE ANALYSIS
+# ============================================================================
+
+def analyze_coverage(squad_path: Path) -> Dict[str, Any]:
+    """Analyze coverage metrics - Phase 2"""
+    result = {
+        "passed": True,
+        "metrics": {},
+        "checks": [],
+        "warnings": []
+    }
+
+    tasks_dir = squad_path / "tasks"
+    checklists_dir = squad_path / "checklists"
+    data_dir = squad_path / "data"
+    agents_dir = squad_path / "agents"
+
+    # T2-COV-001: Checklist coverage
+    task_count = count_files(tasks_dir, ["*.md"])
+    checklist_count = count_files(checklists_dir, ["*.md"])
+
+    complex_tasks = 0
+    if tasks_dir.exists():
+        for task_file in tasks_dir.glob("*.md"):
+            lines = len(task_file.read_text(encoding='utf-8', errors='ignore').split('\n'))
+            if lines > 500:
+                complex_tasks += 1
+
+    result["metrics"]["task_count"] = task_count
+    result["metrics"]["checklist_count"] = checklist_count
+    result["metrics"]["complex_tasks"] = complex_tasks
+
+    if complex_tasks > 0:
+        coverage = checklist_count / complex_tasks
+        result["metrics"]["checklist_coverage"] = round(coverage, 2)
+
+        if coverage >= THRESHOLDS["checklist_coverage_min"]:
+            result["checks"].append({"id": "T2-COV-001", "status": "pass",
+                "message": f"Checklist coverage: {coverage:.0%}"})
+        else:
+            result["checks"].append({"id": "T2-COV-001", "status": "warn",
+                "message": f"Low checklist coverage: {coverage:.0%} (min: {THRESHOLDS['checklist_coverage_min']:.0%})"})
+            result["warnings"].append(f"Checklist coverage below threshold")
+    else:
+        result["metrics"]["checklist_coverage"] = 1.0
+        result["checks"].append({"id": "T2-COV-001", "status": "pass",
+            "message": "No complex tasks requiring checklists"})
+
+    # T2-ORP-001: Orphan task detection
+    orphan_tasks = []
+    if tasks_dir.exists() and agents_dir.exists():
+        # Get all task names
+        task_names = {f.stem for f in tasks_dir.glob("*.md") if f.name.lower() not in ["readme.md", "changelog.md"]}
+
+        # Get all tasks referenced across agents, workflows, and squad docs/config.
+        referenced_tasks = set()
+        ref_patterns = [
+            r'\*([a-z0-9_-]+)',
+            r'tasks/([a-z0-9_-]+)\.md',
+            r'task_ref:\s*([a-z0-9_-]+)',
+            r'task:\s*([a-z0-9_-]+)',
+        ]
+        for source_file in squad_path.rglob("*"):
+            if source_file.parent == tasks_dir:
+                continue
+            if source_file.suffix.lower() not in [".md", ".yaml", ".yml"]:
+                continue
+            content = source_file.read_text(encoding='utf-8', errors='ignore')
+            for pattern in ref_patterns:
+                for ref in re.findall(pattern, content, re.IGNORECASE):
+                    referenced_tasks.add(ref)
+
+        orphan_tasks = list(task_names - referenced_tasks)
+
+    result["metrics"]["orphan_tasks"] = len(orphan_tasks)
+    result["metrics"]["orphan_task_names"] = orphan_tasks[:5]  # First 5
+
+    if len(orphan_tasks) <= THRESHOLDS["orphan_tasks_max"]:
+        result["checks"].append({"id": "T2-ORP-001", "status": "pass",
+            "message": f"Orphan tasks: {len(orphan_tasks)} (max: {THRESHOLDS['orphan_tasks_max']})"})
+    else:
+        result["checks"].append({"id": "T2-ORP-001", "status": "fail",
+            "message": f"Too many orphan tasks: {len(orphan_tasks)}"})
+        result["passed"] = False
+
+    # T2-DAT-001: Data file usage
+    if data_dir.exists():
+        data_files = list(data_dir.glob("*"))
+        data_file_names = {f.name for f in data_files if f.is_file()}
+
+        # Check how many are referenced
+        referenced_data = set()
+        for md_file in squad_path.rglob("*.md"):
+            if md_file.parent.name == "data":
+                continue
+            content = md_file.read_text(encoding='utf-8', errors='ignore')
+            for data_name in data_file_names:
+                if data_name in content:
+                    referenced_data.add(data_name)
+
+        total_data = len(data_file_names)
+        used_data = len(referenced_data)
+
+        result["metrics"]["data_files_total"] = total_data
+        result["metrics"]["data_files_used"] = used_data
+
+        if total_data > 0:
+            usage = used_data / total_data
+            result["metrics"]["data_usage"] = round(usage, 2)
+
+            if usage >= THRESHOLDS["data_usage_min"]:
+                result["checks"].append({"id": "T2-DAT-001", "status": "pass",
+                    "message": f"Data usage: {usage:.0%}"})
+            else:
+                result["checks"].append({"id": "T2-DAT-001", "status": "warn",
+                    "message": f"Low data usage: {usage:.0%}"})
+                result["warnings"].append("Some data files are unused")
+
+    return result
+
+
+# ============================================================================
+# MAIN
+# ============================================================================
+
+def validate_squad(squad_name: str, verbose: bool = False) -> Dict[str, Any]:
+    """Run Phases 0-2 validation"""
+    try:
+        squads_root = find_squads_root()
+    except FileNotFoundError as e:
+        return {"error": str(e)}
+
+    squad_path = squads_root / squad_name
+
+    if not squad_path.exists():
+        return {"error": f"Squad not found: {squad_name}", "path": str(squad_path)}
+
+    results = {
+        "squad_name": squad_name,
+        "squad_path": str(squad_path),
+        "timestamp": datetime.now().isoformat(),
+        "validator": "validate-squad-structure.py (Worker)",
+        "phases": {}
+    }
+
+    # Phase 0: Type Detection
+    results["phases"]["phase_0_type_detection"] = detect_squad_type(squad_path)
+
+    # Phase 1: Structure
+    results["phases"]["phase_1_structure"] = validate_structure(squad_path)
+
+    # Phase 2: Coverage
+    results["phases"]["phase_2_coverage"] = analyze_coverage(squad_path)
+
+    # Summary
+    all_passed = all(p.get("passed", True) for p in results["phases"].values() if isinstance(p, dict))
+    total_blocking = sum(len(p.get("blocking_issues", [])) for p in results["phases"].values() if isinstance(p, dict))
+    total_warnings = sum(len(p.get("warnings", [])) for p in results["phases"].values() if isinstance(p, dict))
+
+    results["summary"] = {
+        "all_phases_passed": all_passed,
+        "blocking_issues": total_blocking,
+        "warnings": total_warnings,
+        "detected_type": results["phases"]["phase_0_type_detection"]["detected_type"],
+        "recommendation": "PROCEED to Phase 3-6" if all_passed else "FIX blocking issues before proceeding"
+    }
+
+    return results
+
+
+def print_report(results: Dict[str, Any]) -> None:
+    """Print human-readable report"""
+    if "error" in results:
+        print(f"ERROR: {results['error']}")
+        return
+
+    print("\n" + "=" * 60)
+    print(f"VALIDATE-SQUAD-STRUCTURE: {results['squad_name']}")
+    print("=" * 60)
+    print(f"Path: {results['squad_path']}")
+    print(f"Validator: {results['validator']}")
+    print()
+
+    # Phase 0
+    p0 = results["phases"]["phase_0_type_detection"]
+    print(f"PHASE 0: Type Detection")
+    print(f"  Detected: {p0['detected_type']} (confidence: {p0['confidence']}/10)")
+    print(f"  Signals: agents={p0['signals'].get('agent_count', 0)}, "
+          f"tasks={p0['signals'].get('task_count', 0)}, "
+          f"voice_dna={p0['signals'].get('voice_dna_count', 0)}")
+    print()
+
+    # Phase 1
+    p1 = results["phases"]["phase_1_structure"]
+    status1 = "✓ PASS" if p1["passed"] else "✗ FAIL"
+    print(f"PHASE 1: Structure Validation [{status1}]")
+    for check in p1["checks"]:
+        icon = "✓" if check["status"] == "pass" else ("⚠" if check["status"] == "warn" else "✗")
+        print(f"  {icon} [{check['id']}] {check['message']}")
+    if p1["blocking_issues"]:
+        print(f"  BLOCKING: {p1['blocking_issues']}")
+    print()
+
+    # Phase 2
+    p2 = results["phases"]["phase_2_coverage"]
+    status2 = "✓ PASS" if p2["passed"] else "✗ FAIL"
+    print(f"PHASE 2: Coverage Analysis [{status2}]")
+    print(f"  Tasks: {p2['metrics'].get('task_count', 0)}, "
+          f"Checklists: {p2['metrics'].get('checklist_count', 0)}")
+    print(f"  Checklist coverage: {p2['metrics'].get('checklist_coverage', 'N/A')}")
+    print(f"  Orphan tasks: {p2['metrics'].get('orphan_tasks', 0)}")
+    if p2["warnings"]:
+        for w in p2["warnings"]:
+            print(f"  ⚠ {w}")
+    print()
+
+    # Summary
+    summary = results["summary"]
+    status_final = "✓ READY" if summary["all_phases_passed"] else "✗ BLOCKED"
+    print("=" * 60)
+    print(f"SUMMARY: {status_final}")
+    print(f"  Type: {summary['detected_type']}")
+    print(f"  Blocking issues: {summary['blocking_issues']}")
+    print(f"  Warnings: {summary['warnings']}")
+    print(f"  Recommendation: {summary['recommendation']}")
+    print("=" * 60)
+
+
+def build_atomic_output(results: Dict[str, Any]) -> Dict[str, Any]:
+    """Build the atomic JSON output format for orchestrator consumption."""
+    if "error" in results:
+        return {
+            "phase": "structure",
+            "squad_type": "unknown",
+            "type_confidence": 0,
+            "structure_valid": False,
+            "coverage": {"agents": 0, "tasks": 0, "workflows": 0},
+            "blocking_issues": [results["error"]],
+            "warnings": [],
+            "blocking_issue_count": 1,
+            "warning_count": 0,
+            "security_issue_count": 0,
+            "non_security_blocking_count": 1,
+            "issues": [results["error"]],
+            "score": 0
+        }
+
+    p0 = results["phases"]["phase_0_type_detection"]
+    p1 = results["phases"]["phase_1_structure"]
+    p2 = results["phases"]["phase_2_coverage"]
+    summary = results["summary"]
+
+    # Collect issues with category separation
+    blocking_issues: List[str] = []
+    warnings: List[str] = []
+    for phase_data in results["phases"].values():
+        if isinstance(phase_data, dict):
+            blocking_issues.extend(phase_data.get("blocking_issues", []))
+            warnings.extend(phase_data.get("warnings", []))
+
+    security_issues = [issue for issue in blocking_issues if str(issue).startswith("Security:")]
+    non_security_blocking = [issue for issue in blocking_issues if not str(issue).startswith("Security:")]
+    issues = blocking_issues + warnings
+
+    task_count = p0.get("signals", {}).get("task_count", 0)
+    checklist_count = p2.get("metrics", {}).get("checklist_count", 0)
+    orphan_tasks = p2.get("metrics", {}).get("orphan_tasks", 0)
+    checklist_coverage = p2.get("metrics", {}).get("checklist_coverage", 0)
+
+    # Calculate score (0-100 scale)
+    score = 100
+    blocking_count = summary.get("blocking_issues", 0)
+    warning_count = summary.get("warnings", 0)
+    score -= blocking_count * 15
+    score -= warning_count * 5
+    if score < 0:
+        score = 0
+
+    return {
+        "phase": "structure",
+        "squad_type": p0.get("detected_type", "unknown"),
+        "type_confidence": p0.get("confidence", 0),
+        "structure_valid": summary.get("all_phases_passed", False),
+        "coverage": {
+            "agents": p0.get("signals", {}).get("agent_count", 0),
+            "tasks": task_count,
+            "workflows": p0.get("signals", {}).get("workflow_count", 0),
+            "checklists": checklist_count,
+        },
+        "metrics": {
+            "task_count": task_count,
+            "checklist_count": checklist_count,
+            "orphan_tasks": orphan_tasks,
+            "checklist_coverage": checklist_coverage,
+        },
+        "blocking_issues": blocking_issues,
+        "warnings": warnings,
+        "blocking_issue_count": len(blocking_issues),
+        "warning_count": len(warnings),
+        "security_issue_count": len(security_issues),
+        "non_security_blocking_count": len(non_security_blocking),
+        "issues": issues,
+        "score": score
+    }
+
+
+def resolve_squad_input(squad_input: str) -> tuple:
+    """Resolve squad input - accepts either a name or a path.
+
+    Returns (squad_name, squad_path) or raises an error.
+    """
+    input_path = Path(squad_input)
+
+    # If it looks like a path (contains / or is an existing directory)
+    if '/' in squad_input or input_path.is_dir():
+        squad_path = input_path.resolve()
+        if squad_path.exists():
+            return squad_path.name, squad_path
+        # Try as relative
+        if not input_path.is_absolute():
+            cwd_path = Path.cwd() / squad_input
+            if cwd_path.exists():
+                return cwd_path.name, cwd_path.resolve()
+        raise FileNotFoundError(f"Squad path not found: {squad_input}")
+
+    # Otherwise treat as squad name
+    return squad_input, None
+
+
+def validate_squad_by_path(squad_path: Path, verbose: bool = False) -> Dict[str, Any]:
+    """Run Phases 0-2 validation directly on a squad path."""
+    if not squad_path.exists():
+        return {"error": f"Squad path not found: {squad_path}"}
+
+    results = {
+        "squad_name": squad_path.name,
+        "squad_path": str(squad_path),
+        "timestamp": datetime.now().isoformat(),
+        "validator": "validate-squad-structure.py (Worker)",
+        "phases": {}
+    }
+
+    # Phase 0: Type Detection
+    results["phases"]["phase_0_type_detection"] = detect_squad_type(squad_path)
+
+    # Phase 1: Structure
+    results["phases"]["phase_1_structure"] = validate_structure(squad_path)
+
+    # Phase 2: Coverage
+    results["phases"]["phase_2_coverage"] = analyze_coverage(squad_path)
+
+    # Summary
+    all_passed = all(p.get("passed", True) for p in results["phases"].values() if isinstance(p, dict))
+    total_blocking = sum(len(p.get("blocking_issues", [])) for p in results["phases"].values() if isinstance(p, dict))
+    total_warnings = sum(len(p.get("warnings", [])) for p in results["phases"].values() if isinstance(p, dict))
+
+    results["summary"] = {
+        "all_phases_passed": all_passed,
+        "blocking_issues": total_blocking,
+        "warnings": total_warnings,
+        "detected_type": results["phases"]["phase_0_type_detection"]["detected_type"],
+        "recommendation": "PROCEED to Phase 3-6" if all_passed else "FIX blocking issues before proceeding"
+    }
+
+    return results
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="Validate squad structure (Phases 0-2) - Worker script"
+    )
+    parser.add_argument("squad_input", help="Name of squad or path to squad directory")
+    parser.add_argument("--output", "-o", choices=["text", "json"], default="text")
+    parser.add_argument("--verbose", "-v", action="store_true")
+
+    args = parser.parse_args()
+
+    try:
+        squad_name, squad_path = resolve_squad_input(args.squad_input)
+    except FileNotFoundError as e:
+        if args.output == "json":
+            print(json.dumps({"phase": "structure", "error": str(e), "score": 0}, indent=2))
+        else:
+            print(f"ERROR: {e}")
+        sys.exit(2)
+
+    if squad_path:
+        results = validate_squad_by_path(squad_path, args.verbose)
+    else:
+        results = validate_squad(squad_name, args.verbose)
+
+    if args.output == "json":
+        atomic = build_atomic_output(results)
+        print(json.dumps(atomic, indent=2))
+    else:
+        print_report(results)
+
+    # Exit code
+    if "error" in results:
+        sys.exit(2)
+    elif not results["summary"]["all_phases_passed"]:
+        sys.exit(1)
+    else:
+        sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()