guardian-framework 0.1.0

package/templates/pi/scripts/git/create-tracking-issue.sh

@@ -0,0 +1,174 @@
+#!/usr/bin/env bash
+# Git Wrapper: Create Tracking Issue
+#
+# Creates a tracking issue on GitHub or GitLab that tracks epic progress.
+# Posts to the issue body as each step completes.
+#
+# Usage: bash .pi/scripts/git/create-tracking-issue.sh \
+#   --title "Epic: Auth Module v2" \
+#   --body "Tracking issue content" \
+#   --labels "epic,tracking"
+#
+# Environment variables:
+#   GITHUB_TOKEN / GITLAB_TOKEN — API token
+#   GITHUB_REPO / GITLAB_PROJECT_ID — repo/project identifier
+#   GIT_PLATFORM — "github" or "gitlab" (auto-detected)
+
+set -euo pipefail
+
+detect_platform() {
+    # First: check guardian-manifest.json for repoTool
+    if [ -f "guardian-manifest.json" ]; then
+        local tool=$(jq -r '.repoTool // ""' guardian-manifest.json 2>/dev/null || echo "")
+        if [[ "$tool" == "glab" ]]; then echo "gitlab"; return; fi
+        if [[ "$tool" == "gh" ]]; then echo "github"; return; fi
+    fi
+    # Fallback: check environment or installed CLIs
+    if [[ -n "${GIT_PLATFORM:-}" ]]; then
+        echo "$GIT_PLATFORM"
+    elif command -v gh &>/dev/null && gh auth status &>/dev/null 2>&1; then
+        echo "github"
+    elif command -v glab &>/dev/null && glab auth status &>/dev/null 2>&1; then
+        echo "gitlab"
+    else
+        echo "none"
+    fi
+}
+
+# Extract trailing number from a URL or string (macOS-compatible, no -P flag)
+extract_number() {
+    echo "$1" | grep -o '[0-9][0-9]*$' || echo ""
+}
+
+TITLE=""
+BODY=""
+BODY_FILE=""
+LABELS=""
+MILESTONE=""
+REPO=""
+
+while [[ $# -gt 0 ]]; do
+    case $1 in
+        --title) TITLE="$2"; shift 2 ;;
+        --body) BODY="$2"; shift 2 ;;
+        --body-file) BODY_FILE="$2"; shift 2 ;;
+        --labels) LABELS="$2"; shift 2 ;;
+        --milestone) MILESTONE="$2"; shift 2 ;;
+        --repo) REPO="$2"; shift 2 ;;
+        *) shift ;;
+    esac
+done
+
+# If --body-file is provided, read body from file (stripping YAML frontmatter)
+if [[ -n "$BODY_FILE" && -f "$BODY_FILE" ]]; then
+    # Extract everything after the second --- (YAML frontmatter delimiter)
+    BODY=$(awk '/^---$/{n++; next} n>=2{print}' "$BODY_FILE")
+    # If stripping produced empty output, use the raw file as fallback
+    if [[ -z "$BODY" ]]; then
+        BODY=$(cat "$BODY_FILE")
+    fi
+fi
+
+PLATFORM=$(detect_platform)
+
+if [[ "$PLATFORM" == "none" ]]; then
+    echo "No git platform detected. Set GITHUB_TOKEN or GITLAB_TOKEN, or install gh/glab CLI."
+    echo "Creating local tracking file instead."
+    mkdir -p .pi/.tracking
+    TRACKING_FILE=".pi/.tracking/issue-$(date +%s).md"
+    cat > "$TRACKING_FILE" << EOF
+# $TITLE
+
+$BODY
+
+Labels: $LABELS
+Milestone: $MILESTONE
+Created: $(date -u +%Y-%m-%dT%H:%M:%SZ)
+EOF
+    echo "TRACKING_ID=local:$(basename "$TRACKING_FILE")"
+    exit 0
+fi
+
+case "$PLATFORM" in
+    github)
+        # Build gh issue create command directly (no eval needed)
+        ARGS=()
+        [[ -n "$REPO" ]] && ARGS+=(--repo "$REPO")
+        [[ -n "$TITLE" ]] && ARGS+=(--title "$TITLE")
+        [[ -n "$MILESTONE" ]] && ARGS+=(--milestone "$MILESTONE")
+
+        # Body: strip YAML frontmatter from --body-file, then write to temp file for gh
+        if [[ -n "$BODY_FILE" && -f "$BODY_FILE" ]]; then
+            STRIPPED_BODY=$(awk '/^---$/{n++; next} n>=2{print}' "$BODY_FILE")
+            if [[ -n "$STRIPPED_BODY" ]]; then
+                TMP_BODY=$(mktemp /tmp/guardian-issue-XXXXXX.md)
+                echo "$STRIPPED_BODY" > "$TMP_BODY"
+                ARGS+=(--body-file "$TMP_BODY")
+                trap "rm -f '$TMP_BODY'" EXIT
+            else
+                ARGS+=(--body-file "$BODY_FILE")
+            fi
+        elif [[ -n "$BODY" ]]; then
+            ARGS+=(--body "$BODY")
+        fi
+
+        # Create issue (no labels — they may not exist on new repos)
+        ISSUE_OUTPUT=$(gh issue create "${ARGS[@]}" 2>&1) || ISSUE_OUTPUT=""
+
+        if [[ -z "$ISSUE_OUTPUT" ]] || [[ "$ISSUE_OUTPUT" == *"could not"* ]] || [[ "$ISSUE_OUTPUT" == *"GraphQL"* ]] || [[ "$ISSUE_OUTPUT" == *"must provide"* ]]; then
+            echo "Failed to create issue: $ISSUE_OUTPUT" >&2
+            echo "TRACKING_ID="
+            exit 1
+        fi
+
+        ISSUE_NUMBER=$(extract_number "$ISSUE_OUTPUT")
+
+        # Try to add labels separately (non-fatal)
+        if [[ -n "$LABELS" && -n "$ISSUE_NUMBER" ]]; then
+            gh issue edit "$ISSUE_NUMBER" --add-label "$LABELS" 2>/dev/null || true
+        fi
+
+        echo "TRACKING_ID=$ISSUE_NUMBER"
+        echo "TRACKING_URL=$ISSUE_OUTPUT"
+        ;;
+
+    gitlab)
+        ARGS=()
+        [[ -n "$REPO" ]] && ARGS+=(--repo "$REPO")
+        [[ -n "$TITLE" ]] && ARGS+=(--title "$TITLE")
+        [[ -n "$MILESTONE" ]] && ARGS+=(--milestone "$MILESTONE")
+
+        # Body: strip YAML frontmatter from --body-file, then write to temp file for glab
+        if [[ -n "$BODY_FILE" && -f "$BODY_FILE" ]]; then
+            STRIPPED_BODY=$(awk '/^---$/{n++; next} n>=2{print}' "$BODY_FILE")
+            if [[ -n "$STRIPPED_BODY" ]]; then
+                TMP_BODY=$(mktemp /tmp/guardian-issue-XXXXXX.md)
+                echo "$STRIPPED_BODY" > "$TMP_BODY"
+                ARGS+=(--description-file "$TMP_BODY")
+                trap "rm -f '$TMP_BODY'" EXIT
+            else
+                ARGS+=(--description-file "$BODY_FILE")
+            fi
+        elif [[ -n "$BODY" ]]; then
+            ARGS+=(--description "$BODY")
+        fi
+
+        ISSUE_OUTPUT=$(glab issue create "${ARGS[@]}" 2>&1) || ISSUE_OUTPUT=""
+
+        if [[ -z "$ISSUE_OUTPUT" ]]; then
+            echo "Failed to create issue" >&2
+            echo "TRACKING_ID="
+            exit 1
+        fi
+
+        ISSUE_NUMBER=$(extract_number "$ISSUE_OUTPUT")
+
+        # Try to add labels separately (non-fatal)
+        if [[ -n "$LABELS" && -n "$ISSUE_NUMBER" ]]; then
+            glab issue update "$ISSUE_NUMBER" --label "$LABELS" 2>/dev/null || true
+        fi
+
+        echo "TRACKING_ID=$ISSUE_NUMBER"
+        echo "TRACKING_URL=$ISSUE_OUTPUT"
+        ;;
+esac

package/templates/pi/scripts/git/link-issue-to-epic.sh

@@ -0,0 +1,51 @@
+#!/usr/bin/env bash
+# Git Wrapper: Link Issue to Epic
+#
+# Usage: bash .pi/scripts/git/link-issue-to-epic.sh \
+#   --issue-id 102 \
+#   --epic-id 101
+
+set -euo pipefail
+
+detect_platform() {
+    if [ -f "guardian-manifest.json" ]; then
+        local tool=$(jq -r '.repoTool // ""' guardian-manifest.json 2>/dev/null || echo "")
+        if [[ "$tool" == "glab" ]]; then echo "gitlab"; return; fi
+        if [[ "$tool" == "gh" ]]; then echo "github"; return; fi
+    fi
+    if [[ -n "${GIT_PLATFORM:-}" ]]; then echo "$GIT_PLATFORM"
+    elif command -v gh &>/dev/null && gh auth status &>/dev/null 2>&1; then echo "github"
+    elif command -v glab &>/dev/null && glab auth status &>/dev/null 2>&1; then echo "gitlab"
+    else echo "none"; fi
+}
+
+ISSUE_ID=""
+EPIC_ID=""
+
+while [[ $# -gt 0 ]]; do
+    case $1 in
+        --issue-id) ISSUE_ID="$2"; shift 2 ;;
+        --epic-id) EPIC_ID="$2"; shift 2 ;;
+        *) shift ;;
+    esac
+done
+
+[[ -z "$ISSUE_ID" || -z "$EPIC_ID" ]] && { echo "Usage: $0 --issue-id <issue> --epic-id <epic>"; exit 1; }
+PLATFORM=$(detect_platform)
+
+case "$PLATFORM" in
+    github)
+        # GitHub uses "closes #N" or "fixes #N" in issue body to link
+        gh issue edit "$ISSUE_ID" --body "$(gh issue view "$ISSUE_ID" --json body -q .body)
+
+Relates to #$EPIC_ID" 2>/dev/null
+        echo "Linked GitHub issue #$ISSUE_ID to #$EPIC_ID"
+        ;;
+    gitlab)
+        glab issue update "$ISSUE_ID" --milestone "$EPIC_ID" 2>/dev/null
+        echo "Linked GitLab issue #$ISSUE_ID to epic #$EPIC_ID"
+        ;;
+    *)
+        echo "Linked local issue #$ISSUE_ID to epic #$EPIC_ID (no platform)"
+        ;;
+esac

package/templates/pi/scripts/git/update-tracking-issue.sh

@@ -0,0 +1,66 @@
+#!/usr/bin/env bash
+# Git Wrapper: Update Tracking Issue
+#
+# Posts a progress update comment to a tracking issue.
+#
+# Usage: bash .pi/scripts/git/update-tracking-issue.sh \
+#   --id 100 \
+#   --comment "✓ Issue #102 complete (CI green, tests pass)"
+
+set -euo pipefail
+
+detect_platform() {
+    if [ -f "guardian-manifest.json" ]; then
+        local tool=$(jq -r '.repoTool // ""' guardian-manifest.json 2>/dev/null || echo "")
+        if [[ "$tool" == "glab" ]]; then echo "gitlab"; return; fi
+        if [[ "$tool" == "gh" ]]; then echo "github"; return; fi
+    fi
+    if [[ -n "${GIT_PLATFORM:-}" ]]; then echo "$GIT_PLATFORM"
+    elif command -v gh &>/dev/null && gh auth status &>/dev/null 2>&1; then echo "github"
+    elif command -v glab &>/dev/null && glab auth status &>/dev/null 2>&1; then echo "gitlab"
+    else echo "none"; fi
+}
+
+ISSUE_ID=""
+COMMENT=""
+
+while [[ $# -gt 0 ]]; do
+    case $1 in
+        --id) ISSUE_ID="$2"; shift 2 ;;
+        --comment) COMMENT="$2"; shift 2 ;;
+        *) shift ;;
+    esac
+done
+
+PLATFORM=$(detect_platform)
+
+if [[ -z "$ISSUE_ID" || -z "$COMMENT" ]]; then
+    echo "Usage: $0 --id <issue_number> --comment <comment_text>"
+    exit 1
+fi
+
+# Handle local tracking files
+if [[ "$ISSUE_ID" == local:* ]]; then
+    TRACKING_FILE=".pi/.tracking/$(echo "$ISSUE_ID" | cut -d: -f2)"
+    if [[ -f "$TRACKING_FILE" ]]; then
+        echo "" >> "$TRACKING_FILE"
+        echo "---" >> "$TRACKING_FILE"
+        echo "$COMMENT" >> "$TRACKING_FILE"
+        echo "Updated local tracking file: $TRACKING_FILE"
+    fi
+    exit 0
+fi
+
+case "$PLATFORM" in
+    github)
+        gh issue comment "$ISSUE_ID" --body "$COMMENT" 2>/dev/null && echo "Comment posted to GitHub issue #$ISSUE_ID"
+        ;;
+    gitlab)
+        glab issue note "$ISSUE_ID" --message "$COMMENT" 2>/dev/null && echo "Comment posted to GitLab issue #$ISSUE_ID"
+        ;;
+    none)
+        echo "No git platform detected. Comment not posted."
+        echo "  Issue: #$ISSUE_ID"
+        echo "  Comment: $COMMENT"
+        ;;
+esac

package/templates/pi/scripts/languages/go/validate-architecture.sh

@@ -0,0 +1,139 @@
+#!/usr/bin/env bash
+# ============================================================================
+# validate-architecture.sh — Go
+# ============================================================================
+set -euo pipefail
+
+SRC_DIR="${1:-.}"
+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 "  Architecture Validation (Go)"
+echo "============================================"
+echo ""
+
+# ---------------------------------------------------------------------------
+# Layer Structure
+# ---------------------------------------------------------------------------
+echo "--- Layer Structure ---"
+HAS_INTERNAL=false
+HAS_PKG=false
+[ -d "internal" ] && HAS_INTERNAL=true
+[ -d "pkg" ] && HAS_PKG=true
+if [ "$HAS_INTERNAL" = true ] && [ "$HAS_PKG" = true ]; then
+    pass "Domain (internal/) and shared (pkg/) layers present"
+elif [ "$HAS_INTERNAL" = true ]; then
+    pass "Internal layer present (clean architecture pattern)"
+elif [ "$HAS_PKG" = true ]; then
+    pass "Pkg layer present (shared library pattern)"
+else
+    warn "No internal/ or pkg/ directory (consider Go clean architecture layout)"
+fi
+
+# ---------------------------------------------------------------------------
+# Canonical References
+# ---------------------------------------------------------------------------
+echo ""
+echo "--- Canonical References ---"
+if [ -d ".pi/architecture/modules" ]; then
+    MODULE_COUNT=$(find .pi/architecture/modules -name "*.md" 2>/dev/null | wc -l | tr -d ' ')
+    pass "Canonical architecture documents found ($MODULE_COUNT modules)"
+else
+    warn "No canonical architecture directory (.pi/architecture/modules) found"
+fi
+
+# ---------------------------------------------------------------------------
+# Domain Models
+# ---------------------------------------------------------------------------
+echo ""
+echo "--- Domain Models ---"
+DOMAIN_FILES=0
+for dir in "internal/domain" "pkg/domain"; do
+    if [ -d "$dir" ]; then
+        COUNT=$(grep -rlE 'type\s+\w+\s+struct' "$dir" --include="*.go" 2>/dev/null | wc -l | tr -d ' ')
+        DOMAIN_FILES=$((DOMAIN_FILES + COUNT))
+    fi
+done
+if [ "$DOMAIN_FILES" -gt 0 ]; then
+    pass "Domain model struct definitions found ($DOMAIN_FILES files)"
+else
+    warn "No domain model struct definitions in internal/domain/ or pkg/domain/"
+fi
+
+# ---------------------------------------------------------------------------
+# Dependency Direction
+# ---------------------------------------------------------------------------
+echo ""
+echo "--- Dependency Direction ---"
+VIOLATIONS=0
+for dir in "internal/domain" "pkg/domain"; do
+    if [ -d "$dir" ]; then
+        # Domain should not import from infrastructure or cmd
+        VIOLATIONS=$((VIOLATIONS + $(grep -rlE 'import.*"(.*/infrastructure|/cmd)"' "$dir" --include="*.go" 2>/dev/null | wc -l | tr -d ' ')))
+    fi
+done
+if [ "$VIOLATIONS" -eq 0 ]; then
+    pass "Domain layer has no infrastructure/cmd import violations"
+else
+    fail "Domain layer imports from infrastructure/cmd ($VIOLATIONS violations)"
+fi
+
+# ---------------------------------------------------------------------------
+# Error Handling
+# ---------------------------------------------------------------------------
+echo ""
+echo "--- Error Handling ---"
+if [ -f "go.mod" ]; then
+    ERROR_VARIABS=$(grep -rE 'var\s+Err\w+\s*=\s*(errors\.New|fmt\.Errorf)' . --include="*.go" 2>/dev/null | wc -l | tr -d ' ')
+    ERROR_STRUCTS=$(grep -rE 'type\s+\w*Error\w*\s+struct' . --include="*.go" 2>/dev/null | wc -l | tr -d ' ')
+    TOTAL=$((ERROR_VARIABS + ERROR_STRUCTS))
+    if [ "$TOTAL" -gt 0 ]; then
+        pass "Custom error types defined ($TOTAL definitions)"
+    else
+        warn "No custom error types found (consider using sentinel errors or error types)"
+    fi
+else
+    warn "Not in a Go module, skipping error handling check"
+fi
+
+# ---------------------------------------------------------------------------
+# Interfaces
+# ---------------------------------------------------------------------------
+echo ""
+echo "--- Interfaces ---"
+if [ -f "go.mod" ]; then
+    INTERFACE_COUNT=$(grep -rE 'type\s+\w+\s+interface' . --include="*.go" 2>/dev/null | wc -l | tr -d ' ')
+    if [ "$INTERFACE_COUNT" -gt 0 ]; then
+        pass "Interface definitions found ($INTERFACE_COUNT interfaces)"
+    else
+        warn "No interface definitions found (consider defining contracts)"
+    fi
+else
+    warn "Not in a Go module, skipping interface check"
+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}Architecture validation passed.${NC}"
+exit 0

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

@@ -0,0 +1,129 @@
+#!/usr/bin/env bash
+# ============================================================================
+# validate-canonical.sh — Go
+# ============================================================================
+set -euo pipefail
+
+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 Reference Validation (Go)"
+echo "============================================"
+echo ""
+
+# ---------------------------------------------------------------------------
+# Architecture Reference Tracing
+# ---------------------------------------------------------------------------
+echo "--- Architecture Reference Tracing ---"
+if [ -f "go.mod" ]; then
+    GO_FILES=$(find . -name "*.go" -not -path "./vendor/*" 2>/dev/null | wc -l | tr -d ' ')
+    if [ "$GO_FILES" -gt 0 ]; then
+        CANONICAL_REFS=$(grep -rlE '//\s*(Canonical:|@canonical|Reference:|Canonical\s+ref)' . --include="*.go" 2>/dev/null | wc -l | tr -d ' ')
+        if [ "$CANONICAL_REFS" -gt 0 ]; then
+            PCT=$((CANONICAL_REFS * 100 / GO_FILES))
+            pass "Canonical references found in ${CANONICAL_REFS}/${GO_FILES} Go files (${PCT}%)"
+        else
+            fail "No canonical reference comments (// Canonical: or // @canonical) found"
+        fi
+    else
+        pass "No Go source files to check"
+    fi
+else
+    warn "Not in a Go module, skipping reference tracing"
+fi
+
+# ---------------------------------------------------------------------------
+# Module-to-Implementation Mapping
+# ---------------------------------------------------------------------------
+echo ""
+echo "--- Module-to-Implementation Mapping ---"
+if [ -d ".pi/architecture/modules" ]; then
+    MAPPED=0
+    TOTAL=0
+    for md in .pi/architecture/modules/*.md; do
+        [ -f "$md" ] || continue
+        TOTAL=$((TOTAL + 1))
+        # Extract module name from filename (strip .md and path)
+        MODULE_NAME=$(basename "$md" .md)
+        # Check if any Go file path contains the module name component
+        if find . -name "*.go" -not -path "./vendor/*" 2>/dev/null | grep -qi "/${MODULE_NAME}"; then
+            MAPPED=$((MAPPED + 1))
+        fi
+    done
+    if [ "$TOTAL" -gt 0 ]; then
+        PCT=$((MAPPED * 100 / TOTAL))
+        if [ "$MAPPED" -eq "$TOTAL" ]; then
+            pass "All $TOTAL modules have matching Go implementations"
+        else
+            warn "$MAPPED/$TOTAL modules mapped to Go files (${PCT}%)"
+        fi
+    else
+        pass "No architecture modules to map"
+    fi
+else
+    warn "No canonical architecture modules directory found"
+fi
+
+# ---------------------------------------------------------------------------
+# Package Documentation
+# ---------------------------------------------------------------------------
+echo ""
+echo "--- Package Documentation ---"
+if [ -f "go.mod" ]; then
+    PKG_FILES_WITH_DOC=$(grep -rlE '//\s*Package\s+\w+\s+(implements|provides|defines|is|contains)' . --include="*.go" 2>/dev/null | wc -l | tr -d ' ')
+    GO_PACKAGES=$(go list ./... 2>/dev/null | wc -l | tr -d ' ')
+    if [ "$GO_PACKAGES" -gt 0 ] && [ "$PKG_FILES_WITH_DOC" -gt 0 ]; then
+        pass "Package documentation found in $PKG_FILES_WITH_DOC files"
+    else
+        warn "No package-level doc comments found (// Package X implements...)"
+    fi
+else
+    warn "Not in a Go module, skipping package doc check"
+fi
+
+# ---------------------------------------------------------------------------
+# ADR Linkage
+# ---------------------------------------------------------------------------
+echo ""
+echo "--- ADR Linkage ---"
+if [ -d ".pi/architecture/decisions" ]; then
+    ADR_COUNT=$(find .pi/architecture/decisions -name "*.md" 2>/dev/null | wc -l | tr -d ' ')
+    if [ "$ADR_COUNT" -gt 0 ]; then
+        ADR_REFS=$(grep -rlE '//\s*ADR[-_]?\d+' . --include="*.go" 2>/dev/null | wc -l | tr -d ' ')
+        if [ "$ADR_REFS" -gt 0 ]; then
+            pass "ADR references found in $ADR_REFS Go files"
+        else
+            warn "No ADR references in code ($ADR_COUNT decisions exist)"
+        fi
+    else
+        pass "No ADRs to link to"
+    fi
+else
+    warn "No ADR directory (.pi/architecture/decisions) 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}Canonical reference validation passed.${NC}"
+exit 0