guardian-framework 0.1.0

package/templates/pi/scripts/ci/check_planning_packet.py

@@ -0,0 +1,228 @@
+#!/usr/bin/env python3
+"""Validate planning packet structure and core gating rules.
+
+Deterministic validator for epic planning packets produced by the
+Architecture Coordinator. Checks required sections, valid values, and
+structural consistency before the packet is handed off for issue generation.
+
+Usage:
+    python scripts/ci/check_planning_packet.py --input=planning_packet.md
+    python scripts/ci/check_planning_packet.py --input=planning_packet.md --json
+
+Exit codes:
+    0 - Packet is valid
+    1 - Validation errors found
+    2 - Script error
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sys
+from pathlib import Path
+
+
+REQUIRED_SECTIONS = [
+    "## Stream classification",
+    "## Scope summary",
+    "## In scope",
+    "## Out of scope",
+    "## Impacted layers",
+    "## Risk classification",
+    "## Dependency graph",
+    "## Mandatory validators",
+    "## Mandatory CI gates",
+    "## Forbidden shortcuts",
+    "## First implementation issue recommendation",
+    "## Open questions / escalation items",
+]
+
+ALLOWED_STREAMS = {"feature", "hardening", "migration", "control"}
+ALLOWED_RISKS = {"low", "medium", "high"}
+ALLOWED_CI_GATES = {
+    "docs_policy", "architecture_conformance", "lint", "static_analysis",
+    "unit", "integration", "security", "migration_verify", "release_readiness",
+}
+REQUIRED_VALIDATORS = {"architecture-validator"}
+
+
+def extract_section(content: str, heading: str) -> str:
+    pattern = re.compile(rf"^{re.escape(heading)}\s*$", re.MULTILINE)
+    match = pattern.search(content)
+    if not match:
+        return ""
+    start = match.end()
+    next_heading = re.search(r"^##\s+", content[start:], re.MULTILINE)
+    end = start + next_heading.start() if next_heading else len(content)
+    return content[start:end].strip()
+
+
+def contains_list_item(section: str) -> bool:
+    return bool(re.search(r"^[-*]\s+\S|^\d+\.\s+\S", section, re.MULTILINE))
+
+
+def normalize_lower(section: str) -> str:
+    return re.sub(r"\s+", " ", section).strip().lower()
+
+
+def parse_dash_items(section: str) -> list[str]:
+    items: list[str] = []
+    for line in section.splitlines():
+        stripped = line.strip()
+        if stripped.startswith("- "):
+            items.append(stripped[2:].strip())
+    return items
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Validate planning packet structure")
+    parser.add_argument("--input", required=True, help="Path to planning packet markdown")
+    parser.add_argument("--json", action="store_true", help="Emit JSON output")
+    args = parser.parse_args()
+
+    input_path = Path(args.input)
+    if not input_path.exists():
+        print(f"Error: Input file not found: {args.input}", file=sys.stderr)
+        return 2
+
+    content = input_path.read_text(encoding="utf-8")
+    checks: list[dict] = []
+    errors: list[str] = []
+
+    # 1. Required sections present
+    for section in REQUIRED_SECTIONS:
+        if section in content:
+            checks.append({"check": f"section:{section}", "status": "pass"})
+        else:
+            checks.append({"check": f"section:{section}", "status": "fail", "message": f"Missing required section"})
+            errors.append(f"Missing required section: {section}")
+
+    # 2. Stream classification is valid
+    stream_section = extract_section(content, "## Stream classification")
+    if stream_section:
+        stream_lower = normalize_lower(stream_section)
+        found_streams = [s for s in ALLOWED_STREAMS if s.lower() in stream_lower]
+        if found_streams:
+            checks.append({"check": "stream_classification", "status": "pass", "value": found_streams[0]})
+        else:
+            checks.append({"check": "stream_classification", "status": "fail", "message": f"Stream must be one of: {', '.join(sorted(ALLOWED_STREAMS))}"})
+            errors.append("Stream classification must be explicit and valid")
+
+    # 3. Risk classification is valid
+    risk_section = extract_section(content, "## Risk classification")
+    if risk_section:
+        risk_lower = normalize_lower(risk_section)
+        found_risks = [r for r in ALLOWED_RISKS if r in risk_lower]
+        if found_risks:
+            checks.append({"check": "risk_classification", "status": "pass", "value": found_risks[0]})
+        else:
+            checks.append({"check": "risk_classification", "status": "fail", "message": f"Risk must be one of: {', '.join(sorted(ALLOWED_RISKS))}"})
+            errors.append("Risk classification must be explicit and valid")
+
+    # 4. In scope has items
+    in_scope = extract_section(content, "## In scope")
+    if in_scope:
+        if contains_list_item(in_scope):
+            checks.append({"check": "in_scope_items", "status": "pass"})
+        else:
+            checks.append({"check": "in_scope_items", "status": "fail", "message": "In scope section must contain bullet items"})
+            errors.append("In scope section must have at least one bullet item")
+
+    # 5. Out of scope has items
+    out_scope = extract_section(content, "## Out of scope")
+    if out_scope:
+        if contains_list_item(out_scope):
+            checks.append({"check": "out_of_scope_items", "status": "pass"})
+        else:
+            checks.append({"check": "out_of_scope_items", "status": "fail", "message": "Out of scope section must contain bullet items"})
+            errors.append("Out of scope section must have at least one bullet item")
+
+    # 6. Impacted layers identified
+    layers_section = extract_section(content, "## Impacted layers")
+    if layers_section and contains_list_item(layers_section):
+        checks.append({"check": "impacted_layers", "status": "pass"})
+    else:
+        checks.append({"check": "impacted_layers", "status": "fail", "message": "Impacted layers section must contain bullet items"})
+        errors.append("Impacted layers must be listed")
+
+    # 7. Dependency graph has items
+    dep_section = extract_section(content, "## Dependency graph")
+    if dep_section and contains_list_item(dep_section):
+        checks.append({"check": "dependency_graph", "status": "pass"})
+    else:
+        checks.append({"check": "dependency_graph", "status": "fail", "message": "Dependency graph section must contain ordered items"})
+        errors.append("Dependency graph must be specified")
+
+    # 8. Mandatory validators include architecture-validator
+    validators_section = extract_section(content, "## Mandatory validators")
+    if validators_section:
+        items = parse_dash_items(validators_section)
+        items_lower = [i.lower() for i in items]
+        if any("architecture" in i for i in items_lower):
+            checks.append({"check": "mandatory_validators", "status": "pass"})
+        else:
+            checks.append({"check": "mandatory_validators", "status": "fail", "message": f"Architecture validator is mandatory"})
+            errors.append("Architecture Validator must be in mandatory validators")
+    else:
+        checks.append({"check": "mandatory_validators", "status": "fail", "message": "Section not found"})
+
+    # 9. CI gates are valid
+    ci_section = extract_section(content, "## Mandatory CI gates")
+    if ci_section:
+        items = parse_dash_items(ci_section)
+        invalid = [i for i in items if i not in ALLOWED_CI_GATES]
+        if invalid:
+            checks.append({"check": "ci_gates", "status": "fail", "message": f"Unknown CI gates: {', '.join(invalid)}"})
+            errors.append(f"Unknown CI gates: {', '.join(invalid)}")
+        elif items:
+            checks.append({"check": "ci_gates", "status": "pass", "value": items})
+        else:
+            checks.append({"check": "ci_gates", "status": "fail", "message": "No CI gates specified"})
+            errors.append("At least one CI gate must be specified")
+    else:
+        checks.append({"check": "ci_gates", "status": "fail", "message": "Section not found"})
+
+    # 10. First issue recommendation exists
+    first_issue = extract_section(content, "## First implementation issue recommendation")
+    if first_issue and len(first_issue) > 10:
+        checks.append({"check": "first_issue_recommendation", "status": "pass"})
+    else:
+        checks.append({"check": "first_issue_recommendation", "status": "fail", "message": "First implementation issue must be recommended"})
+        errors.append("First implementation issue must be recommended")
+
+    # Summary
+    passed = sum(1 for c in checks if c["status"] == "pass")
+    failed = sum(1 for c in checks if c["status"] == "fail")
+
+    if args.json:
+        output = {
+            "input": str(input_path),
+            "timestamp": __import__("datetime").datetime.utcnow().isoformat() + "Z",
+            "summary": {"total": len(checks), "passed": passed, "failed": failed},
+            "checks": checks,
+            "errors": errors,
+            "status": "pass" if failed == 0 else "fail",
+        }
+        print(json.dumps(output, indent=2))
+    else:
+        print(f"\nPlanning Packet Validation: {args.input}")
+        print(f"{'='*50}")
+        for check in checks:
+            icon = "PASS" if check["status"] == "pass" else "FAIL"
+            print(f"  [{icon}] {check['check']}")
+            if check["status"] == "fail" and "message" in check:
+                print(f"         {check['message']}")
+        print(f"\nSummary: {passed} passed, {failed} failed, {len(checks)} total")
+        if errors:
+            print(f"\nErrors ({len(errors)}):")
+            for e in errors:
+                print(f"  - {e}")
+        print(f"\nResult: {'VALID' if failed == 0 else 'INVALID'}")
+
+    return 0 if failed == 0 else 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/templates/pi/scripts/ci/run_hardening_stages.sh

@@ -0,0 +1,264 @@
+#!/usr/bin/env bash
+# Hardening Stage Runner
+#
+# Runs all 10 hardening stages as defined in the architecture pipeline.
+# Each stage runs its scripts and reports pass/fail.
+# A stage failure prevents MR merge (allow_failure: No).
+#
+# Usage: bash .pi/scripts/ci/run_hardening_stages.sh [--stages <list>] [--verbose]
+#
+# Stages:
+#   1. docs_policy          — MR traceability, docs sync guard
+#   2. architecture_conformance — 11+ architectural contract checks
+#   3. lint                 — ruff/format/coverage
+#   4. static_analysis      — mypy/sonar/import-boundaries/sanity
+#   5. unit                 — domain/app/contract/verification tests
+#   6. integration          — integration tests
+#   7. security             — SBOM/Trivy/secret scan/deps audit
+#   8. migration_verify     — Migration checks (conditional)
+#   9. package_build        — Docker build (conditional, main only)
+#   10. release_readiness   — Runbook/observability/policy checks
+
+set -euo pipefail
+
+PI_DIR=".pi"
+SCRIPTS_DIR="${PI_DIR}/scripts/ci"
+CI_DIR="${PI_DIR}/ci"
+
+# Color output
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+BLUE='\033[0;34m'
+NC='\033[0m'
+
+VERBOSE=false
+ALL_STAGES=true
+SELECTED_STAGES=()
+
+# Parse arguments
+while [[ $# -gt 0 ]]; do
+    case $1 in
+        --stages)
+            ALL_STAGES=false
+            IFS=',' read -ra SELECTED_STAGES <<< "$2"
+            shift 2
+            ;;
+        --verbose)
+            VERBOSE=true
+            shift
+            ;;
+        *)
+            shift
+            ;;
+    esac
+done
+
+should_run_stage() {
+    local stage="$1"
+    if [[ "$ALL_STAGES" == "true" ]]; then
+        return 0
+    fi
+    for s in "${SELECTED_STAGES[@]}"; do
+        if [[ "$s" == "$stage" ]]; then
+            return 0
+        fi
+    done
+    return 1
+}
+
+log_stage_start() {
+    echo ""
+    echo -e "${BLUE}═══ Stage $1: $2 ═══${NC}"
+}
+
+log_stage_pass() {
+    echo -e "  ${GREEN}✓ Stage $1 PASSED${NC}"
+}
+
+log_stage_fail() {
+    echo -e "  ${RED}✗ Stage $1 FAILED${NC}"
+    echo "  $2"
+}
+
+log_stage_skip() {
+    echo -e "  ${YELLOW}⊘ Stage $1 SKIPPED${NC} — $2"
+}
+
+TOTAL_STAGES=0
+PASSED_STAGES=0
+FAILED_STAGES=0
+SKIPPED_STAGES=0
+
+declare -a STAGE_RESULTS=()
+
+run_stage() {
+    local stage_num="$1"
+    local stage_name="$2"
+    local stage_script="$3"
+    local conditional="$4"  # "always", "main_only", "migration_only", "sonar_required"
+
+    if ! should_run_stage "$stage_name"; then
+        return 0
+    fi
+
+    ((TOTAL_STAGES++))
+
+    # Check conditional
+    case "$conditional" in
+        main_only)
+            if [[ "${CI_COMMIT_BRANCH:-}" != "main" && "${GITHUB_REF_NAME:-}" != "main" ]]; then
+                log_stage_skip "$stage_name" "Not on main branch"
+                ((SKIPPED_STAGES++))
+                return 0
+            fi
+            ;;
+        migration_only)
+            local has_migration=false
+            if command -v git &>/dev/null; then
+                if git diff --name-only HEAD~1 HEAD 2>/dev/null | grep -qE "(alembic|migrations?|database.*schema)"; then
+                    has_migration=true
+                fi
+            fi
+            if [[ "$has_migration" == "false" ]]; then
+                log_stage_skip "$stage_name" "No migration changes detected"
+                ((SKIPPED_STAGES++))
+                return 0
+            fi
+            ;;
+        sonar_required)
+            if [[ -z "${SONAR_TOKEN:-}" || -z "${SONAR_HOST_URL:-}" ]]; then
+                log_stage_skip "$stage_name" "SONAR_TOKEN or SONAR_HOST_URL not set"
+                ((SKIPPED_STAGES++))
+                return 0
+            fi
+            ;;
+    esac
+
+    log_stage_start "$stage_num" "$stage_name"
+
+    if [[ ! -f "$stage_script" ]]; then
+        log_stage_skip "$stage_name" "Script not found: $stage_script"
+        ((SKIPPED_STAGES++))
+        return 0
+    fi
+
+    local output
+    if output=$(bash "$stage_script" 2>&1); then
+        log_stage_pass "$stage_name"
+        ((PASSED_STAGES++))
+        STAGE_RESULTS+=("PASS:$stage_name")
+        if [[ "$VERBOSE" == "true" ]]; then
+            echo "$output"
+        fi
+    else
+        log_stage_fail "$stage_name" "$output"
+        ((FAILED_STAGES++))
+        STAGE_RESULTS+=("FAIL:$stage_name:$(echo "$output" | head -5)")
+    fi
+}
+
+echo "╔══════════════════════════════════════════════════════╗"
+echo "║           Guardian Hardening Stage Runner            ║"
+echo "╚══════════════════════════════════════════════════════╝"
+echo ""
+echo "Commit: ${CI_COMMIT_SHA:-${GITHUB_SHA:-unknown}}"
+echo "Branch: ${CI_COMMIT_BRANCH:-${GITHUB_REF_NAME:-unknown}}"
+echo "Pipeline: ${CI_PIPELINE_ID:-local}"
+echo ""
+
+# Stage 1: Docs Policy
+run_stage "1" "docs_policy" \
+    "${SCRIPTS_DIR}/stage_docs_policy.sh" \
+    "always"
+
+# Stage 2: Architecture Conformance
+run_stage "2" "architecture_conformance" \
+    "${SCRIPTS_DIR}/check_architecture_conformance.sh" \
+    "always"
+
+# Stage 3: Lint
+run_stage "3" "lint" \
+    "${SCRIPTS_DIR}/stage_lint.sh" \
+    "always"
+
+# Stage 4: Static Analysis
+run_stage "4" "static_analysis" \
+    "${SCRIPTS_DIR}/stage_static_analysis.sh" \
+    "always"
+
+# Stage 5: Unit Tests
+run_stage "5" "unit" \
+    "${SCRIPTS_DIR}/stage_unit.sh" \
+    "always"
+
+# Stage 6: Integration Tests
+run_stage "6" "integration" \
+    "${SCRIPTS_DIR}/stage_integration.sh" \
+    "always"
+
+# Stage 7: Security
+run_stage "7" "security" \
+    "${SCRIPTS_DIR}/stage_security.sh" \
+    "always"
+
+# Stage 8: Migration Verify (conditional)
+run_stage "8" "migration_verify" \
+    "${SCRIPTS_DIR}/stage_migration_verify.sh" \
+    "migration_only"
+
+# Stage 9: Package Build (conditional)
+run_stage "9" "package_build" \
+    "${SCRIPTS_DIR}/stage_package_build.sh" \
+    "main_only"
+
+# Stage 10: Release Readiness
+run_stage "10" "release_readiness" \
+    "${SCRIPTS_DIR}/stage_release_readiness.sh" \
+    "always"
+
+# ── Summary ──
+
+echo ""
+echo "╔══════════════════════════════════════════════════════╗"
+echo "║               Hardening Stage Summary                ║"
+echo "╚══════════════════════════════════════════════════════╝"
+echo ""
+
+for result in "${STAGE_RESULTS[@]}"; do
+    IFS=':' read -ra parts <<< "$result"
+    status="${parts[0]}"
+    name="${parts[1]}"
+    detail="${parts[2]:-}"
+
+    case "$status" in
+        PASS)
+            echo -e "  ${GREEN}✓${NC} ${name}"
+            ;;
+        FAIL)
+            echo -e "  ${RED}✗${NC} ${name}"
+            if [[ -n "$detail" ]]; then
+                echo -e "     ${RED}${detail}${NC}"
+            fi
+            ;;
+        SKIP)
+            echo -e "  ${YELLOW}⊘${NC} ${name}"
+            ;;
+    esac
+done
+
+echo ""
+echo -e "  ${GREEN}Passed:   ${PASSED_STAGES}${NC}"
+echo -e "  ${RED}Failed:   ${FAILED_STAGES}${NC}"
+echo -e "  ${YELLOW}Skipped:  ${SKIPPED_STAGES}${NC}"
+echo "  Total:    ${TOTAL_STAGES}"
+echo ""
+
+if [[ ${FAILED_STAGES} -gt 0 ]]; then
+    echo -e "${RED}✗ Hardening FAILED. ${FAILED_STAGES} stage(s) did not pass.${NC}"
+    echo "MR cannot be merged until all mandatory stages pass."
+    exit 1
+fi
+
+echo -e "${GREEN}✓ All hardening stages passed. MR is ready for merge.${NC}"
+exit 0