guardian-framework 0.1.0

package/templates/pi/scripts/languages/python/validate-canonical.sh

@@ -0,0 +1,124 @@
+#!/usr/bin/env bash
+# ============================================================================
+# validate-canonical.sh — Python
+# ============================================================================
+set -euo pipefail
+
+if [ -f "poetry.lock" ] && command -v poetry &>/dev/null; then
+    POETRY_ENV=$(poetry env info --path 2>/dev/null || true)
+    if [ -n "$POETRY_ENV" ] && [ -f "$POETRY_ENV/bin/activate" ]; then
+        source "$POETRY_ENV/bin/activate"
+    fi
+fi
+
+PASS_COUNT=0; ERRORS=(); WARNINGS=()
+RED='\033[0;31m'; GREEN='\033[0;32m'; YELLOW='\033[1;33m'; NC='\033[0m'
+pass() { echo -e "${GREEN}✅ PASS${NC} $1"; PASS_COUNT=$((PASS_COUNT + 1)); }
+fail() { echo -e "${RED}❌ FAIL${NC} $1"; ERRORS+=("$1"); }
+warn() { echo -e "${YELLOW}⚠️  WARN${NC} $1"; WARNINGS+=("$1"); }
+
+echo "============================================"
+echo "  Canonical Validation (Python)"
+echo "============================================"
+echo ""
+
+SRC_DIR="${1:-src}"
+
+# ── Architecture reference tracing ──
+echo "--- Architecture Reference Tracing ---"
+TOTAL_PY_FILES=$(find "$SRC_DIR" -name "*.py" 2>/dev/null | wc -l | tr -d ' ')
+if [ "$TOTAL_PY_FILES" -gt 0 ]; then
+    FILES_WITH_REFS=$(grep -rlE "(Canonical:|@canonical|Reference:.*\.pi/architecture)" "$SRC_DIR" --include="*.py" 2>/dev/null | wc -l | tr -d ' ')
+    PCT=$((FILES_WITH_REFS * 100 / TOTAL_PY_FILES))
+    if [ "$FILES_WITH_REFS" -gt 0 ]; then
+        pass "Canonical references detected in $FILES_WITH_REFS/$TOTAL_PY_FILES files (${PCT}%)"
+    else
+        fail "No canonical reference comments found in source files"
+    fi
+else
+    warn "No source files found to check"
+fi
+
+# ── Module-to-implementation mapping ──
+echo ""
+echo "--- Module-to-Implementation Mapping ---"
+if [ -d ".pi/architecture/modules" ]; then
+    MISSING=0
+    for module_file in .pi/architecture/modules/*.md; do
+        [ -f "$module_file" ] || continue
+        # Extract component file paths from the module doc
+        while IFS= read -r impl_path; do
+            impl_path=$(echo "$impl_path" | sed 's/^[[:space:]]*//;s/[[:space:]]*$//')
+            [ -z "$impl_path" ] && continue
+            # Strip backticks and quotes
+            impl_path=$(echo "$impl_path" | tr -d '`"' | sed "s/'//g")
+            if [ -n "$impl_path" ]; then
+                if [ ! -f "$impl_path" ]; then
+                    warn "Architecture references $impl_path but file does not exist"
+                    ((MISSING++))
+                fi
+            fi
+        done < <(grep -oE '`[a-z_/]+\.py`' "$module_file" 2>/dev/null || true)
+    done
+    if [ "$MISSING" -eq 0 ]; then
+        pass "All architecture-referenced implementation files exist"
+    else
+        warn "$MISSING referenced implementation file(s) missing"
+    fi
+else
+    warn "No architecture modules directory found"
+fi
+
+# ── Package documentation ──
+echo ""
+echo "--- Package Documentation ---"
+INIT_DOCS=0
+INIT_WITHOUT_DOCS=0
+for init_file in $(find "$SRC_DIR" -name "__init__.py" 2>/dev/null | head -20); do
+    if grep -qE '"""|"""' "$init_file" 2>/dev/null; then
+        ((INIT_DOCS++))
+    else
+        ((INIT_WITHOUT_DOCS++))
+    fi
+done
+if [ "$INIT_DOCS" -gt 0 ]; then
+    pass "Package docstrings found in $INIT_DOCS __init__.py files"
+fi
+if [ "$INIT_WITHOUT_DOCS" -gt 0 ]; then
+    warn "$INIT_WITHOUT_DOCS __init__.py file(s) lack docstrings"
+fi
+
+# ── ADR linkage ──
+echo ""
+echo "--- ADR Linkage ---"
+if [ -d ".pi/architecture/decisions" ]; then
+    ADR_COUNT=$(find .pi/architecture/decisions -name "ADR-*.md" 2>/dev/null | wc -l | tr -d ' ')
+    ADR_REFS=$(grep -rlE "ADR-[0-9]+" "$SRC_DIR" --include="*.py" 2>/dev/null | wc -l | tr -d ' ')
+    if [ "$ADR_REFS" -gt 0 ]; then
+        pass "ADR references found in $ADR_REFS source files ($ADR_COUNT ADRs exist)"
+    else
+        warn "No ADR references found in source files (consider documenting architectural decisions)"
+    fi
+else
+    warn "No ADR directory found at .pi/architecture/decisions/"
+fi
+
+# ── Summary ──
+echo ""
+echo "============================================"
+echo "  Summary"
+echo "============================================"
+echo -e "  Passed:   ${GREEN}${PASS_COUNT}${NC}"
+echo -e "  Failed:   ${RED}${#ERRORS[@]}${NC}"
+echo ""
+
+if [ ${#ERRORS[@]} -gt 0 ]; then
+    echo "FAILURES:"
+    for err in "${ERRORS[@]}"; do
+        echo "  - $err"
+    done
+    exit 1
+fi
+
+echo -e "${GREEN}Canonical validation passed.${NC}"
+exit 0

package/templates/pi/scripts/languages/python/validate-ci.sh

@@ -0,0 +1,130 @@
+#!/usr/bin/env bash
+# ============================================================================
+# validate-ci.sh — Python (Poetry-based)
+# ============================================================================
+set -euo pipefail
+
+# Activate Poetry venv if available
+if [ -f "poetry.lock" ] && command -v poetry &>/dev/null; then
+    POETRY_ENV=$(poetry env info --path 2>/dev/null || true)
+    if [ -n "$POETRY_ENV" ] && [ -f "$POETRY_ENV/bin/activate" ]; then
+        source "$POETRY_ENV/bin/activate"
+    fi
+fi
+
+ERRORS=()
+WARNINGS=()
+PASS_COUNT=0
+
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+NC='\033[0m'
+
+pass() { echo -e "${GREEN}✅ PASS${NC} $1"; PASS_COUNT=$((PASS_COUNT + 1)); }
+fail() { echo -e "${RED}❌ FAIL${NC} $1"; ERRORS+=("$1"); }
+warn() { echo -e "${YELLOW}⚠️  WARN${NC} $1"; WARNINGS+=("$1"); }
+
+echo "============================================"
+echo "  CI/MR Validation (Python)"
+echo "============================================"
+echo ""
+
+# ---------------------------------------------------------------------------
+# Build
+# ---------------------------------------------------------------------------
+echo "--- Build ---"
+if [ -f "poetry.lock" ] && command -v poetry &>/dev/null; then
+    if poetry build 2>/dev/null; then
+        pass "Build succeeded"
+    else
+        fail "Build failed"
+    fi
+else
+    pass "No build step (dev project)"
+fi
+
+# ---------------------------------------------------------------------------
+# Tests
+# ---------------------------------------------------------------------------
+echo ""
+echo "--- Tests ---"
+if command -v pytest &>/dev/null; then
+    if PYTHONPATH=src pytest -q 2>/dev/null; then
+        pass "All tests passed"
+    else
+        fail "Tests failed"
+    fi
+else
+    warn "pytest not available, skipping tests"
+fi
+
+# ---------------------------------------------------------------------------
+# Lint
+# ---------------------------------------------------------------------------
+echo ""
+echo "--- Lint ---"
+if command -v ruff &>/dev/null; then
+    if ruff check . 2>/dev/null; then
+        pass "Lint passed"
+    else
+        fail "Lint failed"
+    fi
+else
+    warn "ruff not available, skipping lint"
+fi
+
+# ---------------------------------------------------------------------------
+# Format
+# ---------------------------------------------------------------------------
+echo ""
+echo "--- Format ---"
+if command -v ruff &>/dev/null; then
+    if ruff format --check . 2>/dev/null; then
+        pass "Format check passed"
+    else
+        fail "Format check failed"
+    fi
+else
+    warn "ruff not available, skipping format"
+fi
+
+# ---------------------------------------------------------------------------
+# Security Audit
+# ---------------------------------------------------------------------------
+echo ""
+echo "--- Security Audit ---"
+if command -v pip-audit &>/dev/null && [ -f "pyproject.toml" ]; then
+    AUDIT_OUT=$(pip-audit 2>&1 || true)
+    if echo "$AUDIT_OUT" | grep -q "no known vulnerabilities"; then
+        pass "No known vulnerabilities"
+    elif echo "$AUDIT_OUT" | grep -q "Dependency not found on PyPI"; then
+        pass "Dependencies audited (local package skipped)"
+    else
+        warn "pip-audit reported findings (review manually)"
+    fi
+else
+    warn "pip-audit not available, skipping audit"
+fi
+
+# ---------------------------------------------------------------------------
+# Summary
+# ---------------------------------------------------------------------------
+echo ""
+echo "============================================"
+echo "  Summary"
+echo "============================================"
+echo -e "  Passed:   ${GREEN}${PASS_COUNT}${NC}"
+echo -e "  Failed:   ${RED}${#ERRORS[@]}${NC}"
+echo ""
+
+if [ ${#ERRORS[@]} -gt 0 ]; then
+    echo "FAILURES:"
+    for err in "${ERRORS[@]}"; do
+        echo "  - $err"
+    done
+    exit 1
+fi
+
+echo -e "${GREEN}All CI checks passed.${NC}"
+exit 0

package/templates/pi/scripts/languages/python/validate-integration.sh

@@ -0,0 +1,119 @@
+#!/usr/bin/env bash
+# ============================================================================
+# validate-integration.sh — Python
+# ============================================================================
+set -euo pipefail
+
+if [ -f "poetry.lock" ] && command -v poetry &>/dev/null; then
+    POETRY_ENV=$(poetry env info --path 2>/dev/null || true)
+    if [ -n "$POETRY_ENV" ] && [ -f "$POETRY_ENV/bin/activate" ]; then
+        source "$POETRY_ENV/bin/activate"
+    fi
+fi
+
+PASS_COUNT=0; ERRORS=(); WARNINGS=()
+RED='\033[0;31m'; GREEN='\033[0;32m'; YELLOW='\033[1;33m'; NC='\033[0m'
+pass() { echo -e "${GREEN}✅ PASS${NC} $1"; PASS_COUNT=$((PASS_COUNT + 1)); }
+fail() { echo -e "${RED}❌ FAIL${NC} $1"; ERRORS+=("$1"); }
+warn() { echo -e "${YELLOW}⚠️  WARN${NC} $1"; WARNINGS+=("$1"); }
+
+echo "============================================"
+echo "  Integration Validation (Python)"
+echo "============================================"
+echo ""
+
+# ── Integration Tests ──
+echo "--- Integration Tests ---"
+if [ -d "tests/integration" ] && command -v pytest &>/dev/null; then
+    if PYTHONPATH=src pytest tests/integration -q 2>/dev/null; then
+        pass "Integration tests passed"
+    else
+        fail "Integration tests failed"
+    fi
+elif [ -d "tests/integration" ]; then
+    warn "Integration test directory exists but pytest is not available"
+else
+    pass "No integration tests directory (skipped)"
+fi
+
+# ── Docker/Compose Detection ──
+echo ""
+echo "--- Docker/Compose Detection ---"
+if [ -f "docker-compose.yml" ] || [ -f "docker-compose.yaml" ]; then
+    warn "Docker Compose detected — integration tests may require running services"
+    pass "Docker Compose configuration present"
+else
+    pass "No Docker Compose configuration"
+fi
+
+# ── Contract Tests ──
+echo ""
+echo "--- Contract Tests ---"
+CONTRACT_COUNT=$(find tests -name "*contract*" -o -name "*pact*" 2>/dev/null | wc -l | tr -d ' ')
+if [ "$CONTRACT_COUNT" -gt 0 ]; then
+    pass "Contract test files found ($CONTRACT_COUNT)"
+else
+    warn "No contract tests found"
+fi
+
+# ── Mock/Stub Detection ──
+echo ""
+echo "--- Mock/Stub Detection ---"
+HAS_MOCKS=false
+for pattern in "unittest.mock" "mock.patch" "pytest-mock" "responses" "httpretty" "aioresponses" "responses.activate"; do
+    if grep -rq "$pattern" tests/ --include="*.py" 2>/dev/null; then
+        HAS_MOCKS=true
+        break
+    fi
+done
+if [ "$HAS_MOCKS" = true ]; then
+    pass "Mock/stub patterns detected in test suite"
+else
+    warn "No mock patterns found in test suite"
+fi
+
+# ── Database Integration Tests ──
+echo ""
+echo "--- Database Integration Tests ---"
+DB_TEST_COUNT=$(grep -rlE "(pytest.*db|session_scope|test_db|database_url|SQLALCHEMY)" tests/ --include="*.py" 2>/dev/null | wc -l | tr -d ' ')
+if [ "$DB_TEST_COUNT" -gt 0 ]; then
+    pass "Database integration tests found ($DB_TEST_COUNT files)"
+else
+    pass "No database integration tests (skipped if not applicable)"
+fi
+
+# ── HTTP Integration Tests ──
+echo ""
+echo "--- HTTP Integration Tests ---"
+HAS_HTTP_TEST=false
+for pattern in "TestClient" "httpx.AsyncClient" "aiohttp.test" "responses" "requests_mock"; do
+    if grep -rq "$pattern" tests/ --include="*.py" 2>/dev/null; then
+        HAS_HTTP_TEST=true
+        break
+    fi
+done
+if [ "$HAS_HTTP_TEST" = true ]; then
+    pass "HTTP integration test patterns detected"
+else
+    pass "No HTTP integration test patterns found"
+fi
+
+# ── Summary ──
+echo ""
+echo "============================================"
+echo "  Summary"
+echo "============================================"
+echo -e "  Passed:   ${GREEN}${PASS_COUNT}${NC}"
+echo -e "  Failed:   ${RED}${#ERRORS[@]}${NC}"
+echo ""
+
+if [ ${#ERRORS[@]} -gt 0 ]; then
+    echo "FAILURES:"
+    for err in "${ERRORS[@]}"; do
+        echo "  - $err"
+    done
+    exit 1
+fi
+
+echo -e "${GREEN}Integration validation passed.${NC}"
+exit 0

package/templates/pi/scripts/languages/python/validate-operations.sh

@@ -0,0 +1,107 @@
+#!/usr/bin/env bash
+# ============================================================================
+# validate-operations.sh — Python
+# ============================================================================
+set -euo pipefail
+
+if [ -f "poetry.lock" ] && command -v poetry &>/dev/null; then
+    POETRY_ENV=$(poetry env info --path 2>/dev/null || true)
+    if [ -n "$POETRY_ENV" ] && [ -f "$POETRY_ENV/bin/activate" ]; then
+        source "$POETRY_ENV/bin/activate"
+    fi
+fi
+
+PASS_COUNT=0; ERRORS=(); WARNINGS=()
+RED='\033[0;31m'; GREEN='\033[0;32m'; YELLOW='\033[1;33m'; NC='\033[0m'
+pass() { echo -e "${GREEN}✅ PASS${NC} $1"; PASS_COUNT=$((PASS_COUNT + 1)); }
+fail() { echo -e "${RED}❌ FAIL${NC} $1"; ERRORS+=("$1"); }
+warn() { echo -e "${YELLOW}⚠️  WARN${NC} $1"; WARNINGS+=("$1"); }
+
+echo "============================================"
+echo "  Operations Validation (Python)"
+echo "============================================"
+echo ""
+
+SRC_DIR="${1:-src}"
+
+# ── Structured Logging ──
+echo "--- Structured Logging ---"
+if grep -rqE "(structlog|import logging|loguru|log\.info|log\.error|logger\.info|logger\.error)" "$SRC_DIR" --include="*.py" 2>/dev/null; then
+    pass "Structured logging detected"
+else
+    warn "No structured logging framework detected"
+fi
+
+# ── Health Checks ──
+echo ""
+echo "--- Health Checks ---"
+if grep -rqE "(/health|/healthz|healthcheck)" "$SRC_DIR" --include="*.py" 2>/dev/null; then
+    pass "Health check endpoint(s) detected"
+else
+    warn "No health check endpoints found"
+fi
+
+# ── Graceful Shutdown ──
+echo ""
+echo "--- Graceful Shutdown ---"
+if grep -rqE "signal\.(signal|SIGTERM|SIGINT)|atexit\.register|contextmanager" "$SRC_DIR" --include="*.py" 2>/dev/null; then
+    pass "Graceful shutdown patterns detected"
+else
+    warn "No graceful shutdown patterns found"
+fi
+
+# ── Metrics ──
+echo ""
+echo "--- Metrics & Observability ---"
+if grep -rqE "(prometheus_client|opentelemetry|datadog|statsd|metrics|counter|histogram|gauge)" "$SRC_DIR" --include="*.py" 2>/dev/null; then
+    pass "Metrics framework detected"
+else
+    warn "No metrics framework detected"
+fi
+
+# ── Distributed Tracing ──
+echo ""
+echo "--- Distributed Tracing ---"
+if grep -rqE "(opentelemetry|jaeger|zipkin|sentry_sdk|ddtrace)" "$SRC_DIR" --include="*.py" 2>/dev/null; then
+    pass "Distributed tracing detected"
+else
+    warn "No distributed tracing detected"
+fi
+
+# ── Configuration Management ──
+echo ""
+echo "--- Configuration Management ---"
+if grep -rqE "(pydantic\.BaseSettings|pydantic_settings|environ|os\.environ|dynaconf|python-dotenv)" "$SRC_DIR" --include="*.py" 2>/dev/null; then
+    pass "Configuration management framework detected"
+else
+    warn "No configuration management detected (consider pydantic-settings or environs)"
+fi
+
+# ── Retry & Resilience ──
+echo ""
+echo "--- Retry & Resilience ---"
+if grep -rqE "(tenacity|@retry|backoff|circuitbreaker)" "$SRC_DIR" --include="*.py" 2>/dev/null; then
+    pass "Retry/resilience patterns detected"
+else
+    warn "No retry or circuit breaker patterns found"
+fi
+
+# ── Summary ──
+echo ""
+echo "============================================"
+echo "  Summary"
+echo "============================================"
+echo -e "  Passed:   ${GREEN}${PASS_COUNT}${NC}"
+echo -e "  Failed:   ${RED}${#ERRORS[@]}${NC}"
+echo ""
+
+if [ ${#ERRORS[@]} -gt 0 ]; then
+    echo "FAILURES:"
+    for err in "${ERRORS[@]}"; do
+        echo "  - $err"
+    done
+    exit 1
+fi
+
+echo -e "${GREEN}Operations validation passed.${NC}"
+exit 0

package/templates/pi/scripts/languages/python/validate-security.sh

@@ -0,0 +1,68 @@
+#!/usr/bin/env bash
+# validate-security.sh — Python
+set -euo pipefail
+
+# Activate Poetry venv if available
+if [ -f "poetry.lock" ] && command -v poetry &>/dev/null; then
+    POETRY_ENV=$(poetry env info --path 2>/dev/null || true)
+    if [ -n "$POETRY_ENV" ] && [ -f "$POETRY_ENV/bin/activate" ]; then
+        source "$POETRY_ENV/bin/activate"
+    fi
+fi
+
+SRC_DIR="${1:-src}"
+PASS_COUNT=0; ERRORS=(); WARNINGS=()
+RED='\033[0;31m'; GREEN='\033[0;32m'; YELLOW='\033[1;33m'; NC='\033[0m'
+pass() { echo -e "${GREEN}✅ PASS${NC} $1"; PASS_COUNT=$((PASS_COUNT + 1)); }
+fail() { echo -e "${RED}❌ FAIL${NC} $1"; ERRORS+=("$1"); }
+warn() { echo -e "${YELLOW}⚠️  WARN${NC} $1"; WARNINGS+=("$1"); }
+
+echo "============================================"
+echo "  Security Scan (Python)"
+echo "============================================"
+
+# Hardcoded secrets
+echo "--- Hardcoded Secrets ---"
+SECRET_COUNT=$(grep -rE "(api_key|secret_key|password|token)\s*=\s*['\"][^'\"]{8,}" "$SRC_DIR" --include="*.py" 2>/dev/null | grep -v "__init__" | grep -v "test" | wc -l | tr -d ' ')
+if [ "$SECRET_COUNT" -eq 0 ]; then
+    pass "No hardcoded secrets detected"
+else
+    warn "Potential hardcoded secrets ($SECRET_COUNT findings)"
+fi
+
+# SQL injection
+echo ""
+echo "--- Injection Patterns ---"
+INJECT_COUNT=$(grep -rE "(execute|cursor\.execute)\s*\(\s*['\"]" "$SRC_DIR" --include="*.py" 2>/dev/null | wc -l | tr -d ' ')
+if [ "$INJECT_COUNT" -eq 0 ]; then
+    pass "No obvious injection patterns"
+else
+    warn "Potential injection patterns ($INJECT_COUNT findings — verify parameterized queries)"
+fi
+
+# Dependency audit
+echo ""
+echo "--- Dependency Audit ---"
+if command -v pip-audit &>/dev/null && [ -f "pyproject.toml" ]; then
+    AUDIT_OUT=$(pip-audit 2>&1 || true)
+    if echo "$AUDIT_OUT" | grep -q "no known vulnerabilities"; then
+        pass "No known vulnerabilities"
+    elif echo "$AUDIT_OUT" | grep -q "Dependency not found on PyPI"; then
+        pass "Dependencies audited (local package skipped)"
+    else
+        warn "pip-audit reported findings (review manually)"
+    fi
+else
+    warn "pip-audit not available"
+fi
+
+# Summary
+echo ""
+echo "============================================"
+echo "  Passed: ${GREEN}${PASS_COUNT}${NC}  Failed: ${RED}${#ERRORS[@]}${NC}  Warn: ${YELLOW}${#WARNINGS[@]}${NC}"
+if [ ${#ERRORS[@]} -gt 0 ]; then
+    for err in "${ERRORS[@]}"; do echo "  - $err"; done
+    exit 1
+fi
+echo -e "${GREEN}Security scan passed.${NC}"
+exit 0

package/templates/pi/scripts/languages/python/validate-tests.sh

@@ -0,0 +1,102 @@
+#!/usr/bin/env bash
+# ============================================================================
+# validate-tests.sh — Python (Poetry-based)
+# ============================================================================
+set -euo pipefail
+
+# Activate Poetry venv if available
+if [ -f "poetry.lock" ] && command -v poetry &>/dev/null; then
+    POETRY_ENV=$(poetry env info --path 2>/dev/null || true)
+    if [ -n "$POETRY_ENV" ] && [ -f "$POETRY_ENV/bin/activate" ]; then
+        source "$POETRY_ENV/bin/activate"
+    fi
+fi
+
+ERRORS=()
+WARNINGS=()
+PASS_COUNT=0
+
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+NC='\033[0m'
+
+pass() { echo -e "${GREEN}✅ PASS${NC} $1"; PASS_COUNT=$((PASS_COUNT + 1)); }
+fail() { echo -e "${RED}❌ FAIL${NC} $1"; ERRORS+=("$1"); }
+warn() { echo -e "${YELLOW}⚠️  WARN${NC} $1"; WARNINGS+=("$1"); }
+
+echo "============================================"
+echo "  Test Validation (Python)"
+echo "============================================"
+echo ""
+
+# ---------------------------------------------------------------------------
+# Unit Tests
+# ---------------------------------------------------------------------------
+echo "--- Unit Tests ---"
+if [ -d "tests/unit" ] && command -v pytest &>/dev/null; then
+    if PYTHONPATH=src pytest tests/unit -q 2>/dev/null; then
+        pass "Unit tests passed"
+    else
+        fail "Unit tests failed"
+    fi
+else
+    pass "No unit tests (skipped)"
+fi
+
+# ---------------------------------------------------------------------------
+# Integration Tests
+# ---------------------------------------------------------------------------
+echo ""
+echo "--- Integration Tests ---"
+if [ -d "tests/integration" ] && command -v pytest &>/dev/null; then
+    if PYTHONPATH=src pytest tests/integration -q 2>/dev/null; then
+        pass "Integration tests passed"
+    else
+        fail "Integration tests failed"
+    fi
+else
+    pass "No integration tests (skipped)"
+fi
+
+# ---------------------------------------------------------------------------
+# Coverage
+# ---------------------------------------------------------------------------
+echo ""
+echo "--- Coverage ---"
+if command -v pytest &>/dev/null && command -v coverage &>/dev/null; then
+    COVERAGE_OUTPUT=$(PYTHONPATH=src pytest tests/ --cov=src --cov-report=term-missing 2>&1 || true)
+    COVERAGE_PCT=$(echo "$COVERAGE_OUTPUT" | grep "^TOTAL" | awk '{print $NF}' | tr -d '%' || echo "0")
+    if [ -z "$COVERAGE_PCT" ]; then
+        COVERAGE_PCT="0"
+    fi
+    if [ "$(echo "$COVERAGE_PCT >= 80" | bc -l 2>/dev/null || echo 0)" -eq 1 ]; then
+        pass "Coverage: ${COVERAGE_PCT}% (≥ 80%)"
+    else
+        fail "Coverage: ${COVERAGE_PCT}% (< 80%)"
+    fi
+else
+    warn "coverage tools not available"
+fi
+
+# ---------------------------------------------------------------------------
+# Summary
+# ---------------------------------------------------------------------------
+echo ""
+echo "============================================"
+echo "  Summary"
+echo "============================================"
+echo -e "  Passed:   ${GREEN}${PASS_COUNT}${NC}"
+echo -e "  Failed:   ${RED}${#ERRORS[@]}${NC}"
+echo ""
+
+if [ ${#ERRORS[@]} -gt 0 ]; then
+    echo "FAILURES:"
+    for err in "${ERRORS[@]}"; do
+        echo "  - $err"
+    done
+    exit 1
+fi
+
+echo -e "${GREEN}Test validation passed.${NC}"
+exit 0