@sebastienrousseau/dotfiles 0.2.499 → 0.2.500

package/scripts/ci/check-copyright-headers.sh

@@ -0,0 +1,96 @@
+#!/usr/bin/env bash
+# Copyright (c) 2015-2026 Dotfiles. All rights reserved.
+# Copyright header validator (zero-tolerance policy).
+#
+# Scans source files for a copyright header in the first 10 lines. Patterns
+# are deliberately narrow to avoid false positives on C-style `(c)` comments
+# or the word "token" appearing in running text.
+#
+# Usage:
+#   check-copyright-headers.sh [--extensions=sh,lua,nix,...] [--excludes=REGEX]
+#
+# Exit codes:
+#   0  all files have a valid header
+#   1  one or more files are missing a header
+#   2  invalid invocation
+
+set -euo pipefail
+
+EXTENSIONS_DEFAULT="sh,lua,nix,py,js,ts,go,rs,java,cpp,c,h,hpp"
+EXCLUDES_DEFAULT='(^|/)(node_modules|\.git|vendor|target|build)/|\.tmpl$|(^|/)\.chezmoitemplates/'
+
+EXTENSIONS="$EXTENSIONS_DEFAULT"
+EXCLUDES="$EXCLUDES_DEFAULT"
+
+for arg in "$@"; do
+  case "$arg" in
+    --extensions=*) EXTENSIONS="${arg#*=}" ;;
+    --excludes=*) EXCLUDES="${arg#*=}" ;;
+    -h | --help)
+      sed -n '2,14p' "$0" | sed 's/^# \{0,1\}//'
+      exit 0
+      ;;
+    *)
+      echo "Unknown argument: $arg" >&2
+      exit 2
+      ;;
+  esac
+done
+
+# Narrow patterns — each must be specific enough that running prose cannot match.
+# Deliberately DROPPED: bare "(c) " (false-positives in C comments),
+# bare "All rights reserved" (often appears in vendored prose).
+# Matched by `grep -F`, so these are literal strings.
+PATTERNS=(
+  "Copyright (c)"
+  "Copyright ©"
+  "SPDX-License-Identifier:"
+  "© "
+)
+
+# Build a ripgrep glob like `{*.sh,*.lua,*.nix}` from the comma list.
+IFS=',' read -r -a exts <<<"$EXTENSIONS"
+glob="{"
+for i in "${!exts[@]}"; do
+  [[ $i -gt 0 ]] && glob+=","
+  glob+="*.${exts[$i]}"
+done
+glob+="}"
+
+mapfile -t all_files < <(rg --files -g "$glob" 2>/dev/null || true)
+
+if [[ "${#all_files[@]}" -eq 0 ]]; then
+  echo "::notice::No files matched extensions: $EXTENSIONS"
+  exit 0
+fi
+
+missing=()
+for file in "${all_files[@]}"; do
+  if [[ "$file" =~ $EXCLUDES ]]; then
+    continue
+  fi
+
+  found=false
+  # Read the first 10 lines once; search each pattern against that buffer.
+  head_buf="$(head -n 10 "$file" 2>/dev/null || true)"
+  for pattern in "${PATTERNS[@]}"; do
+    if grep -qF -- "$pattern" <<<"$head_buf"; then
+      found=true
+      break
+    fi
+  done
+
+  $found || missing+=("$file")
+done
+
+if [[ "${#missing[@]}" -gt 0 ]]; then
+  echo "::error::Copyright header validation failed — ${#missing[@]} file(s) missing header"
+  echo "Files missing a recognised copyright header:"
+  printf '  - %s\n' "${missing[@]}"
+  echo
+  echo "Add ONE of the following to the first 10 lines:"
+  printf '  - %s\n' "${PATTERNS[@]}"
+  exit 1
+fi
+
+echo "::notice::All ${#all_files[@]} file(s) have a valid copyright header"

package/scripts/ci/guard-gitleaks-checkout.sh

@@ -0,0 +1,57 @@
+#!/usr/bin/env bash
+# Copyright (c) 2015-2026 Dotfiles. All rights reserved.
+# Guard against full-history gitleaks scans on manual runs.
+# This ensures workflow checkout remains shallow near gitleaks steps.
+
+set -euo pipefail
+
+check_workflow() {
+  local workflow="$1"
+  local failed=0
+  local line_no
+
+  while IFS=: read -r line_no _; do
+    local start end context
+    start=$((line_no - 16))
+    end=$((line_no + 2))
+    if [[ "$start" -lt 1 ]]; then
+      start=1
+    fi
+
+    context="$(sed -n "${start},${end}p" "$workflow")"
+
+    if [[ "$context" != *"actions/checkout"* ]]; then
+      echo "ERROR: $workflow:$line_no missing nearby checkout for gitleaks step."
+      failed=1
+      continue
+    fi
+
+    if [[ "$context" != *"fetch-depth: 1"* ]]; then
+      echo "ERROR: $workflow:$line_no gitleaks step must use checkout fetch-depth: 1."
+      failed=1
+    fi
+
+    if [[ "$context" == *"fetch-depth: 0"* ]]; then
+      echo "ERROR: $workflow:$line_no gitleaks step contains forbidden fetch-depth: 0."
+      failed=1
+    fi
+  done < <(grep -n "gitleaks/gitleaks-action" "$workflow" || true)
+
+  return "$failed"
+}
+
+main() {
+  local failed=0
+
+  check_workflow ".github/workflows/ci.yml" || failed=1
+  check_workflow ".github/workflows/security-enhanced.yml" || failed=1
+
+  if [[ "$failed" -ne 0 ]]; then
+    echo "Gitleaks checkout guard failed."
+    exit 1
+  fi
+
+  echo "Gitleaks checkout guard passed."
+}
+
+main "$@"

package/scripts/ci/install-chezmoi-verified.sh

@@ -0,0 +1,64 @@
+#!/usr/bin/env bash
+# Copyright (c) 2015-2026 Dotfiles. All rights reserved.
+# Install a pinned Chezmoi release with checksum verification.
+set -euo pipefail
+
+VERSION="${1:-}"
+BIN_DIR="${2:-$HOME/.local/bin}"
+
+if [[ -z "$VERSION" ]]; then
+  echo "Usage: $0 <chezmoi-version> [bin-dir]" >&2
+  exit 1
+fi
+
+OS="$(uname -s | tr '[:upper:]' '[:lower:]')"
+ARCH="$(uname -m)"
+
+case "$OS" in
+  linux | darwin) ;;
+  *)
+    echo "Unsupported OS: $OS" >&2
+    exit 1
+    ;;
+esac
+
+case "$ARCH" in
+  x86_64 | amd64) ARCH="amd64" ;;
+  arm64 | aarch64) ARCH="arm64" ;;
+  *)
+    echo "Unsupported architecture: $ARCH" >&2
+    exit 1
+    ;;
+esac
+
+ASSET="chezmoi_${VERSION}_${OS}_${ARCH}.tar.gz"
+CHECKSUMS_ASSET="chezmoi_${VERSION}_checksums.txt"
+BASE_URL="https://github.com/twpayne/chezmoi/releases/download/v${VERSION}"
+
+TMP_DIR="$(umask 077 && mktemp -d)"
+trap 'rm -rf "$TMP_DIR"' EXIT
+
+# Support both old and new checksum filenames.
+if ! curl -fsSL -o "$TMP_DIR/checksums.txt" "$BASE_URL/$CHECKSUMS_ASSET"; then
+  curl -fsSL -o "$TMP_DIR/checksums.txt" "$BASE_URL/checksums.txt"
+fi
+curl -fsSL -o "$TMP_DIR/$ASSET" "$BASE_URL/$ASSET"
+
+CHECKSUM_LINE="$(grep -E "[[:space:]]${ASSET}$" "$TMP_DIR/checksums.txt" | head -n1 || true)"
+if [[ -z "$CHECKSUM_LINE" ]]; then
+  echo "Checksum entry not found for $ASSET" >&2
+  exit 1
+fi
+
+(
+  cd "$TMP_DIR"
+  if command -v sha256sum >/dev/null 2>&1; then
+    echo "$CHECKSUM_LINE" | sha256sum -c -
+  else
+    echo "$CHECKSUM_LINE" | shasum -a 256 -c -
+  fi
+)
+
+tar -xzf "$TMP_DIR/$ASSET" -C "$TMP_DIR" chezmoi
+mkdir -p "$BIN_DIR"
+install -m 755 "$TMP_DIR/chezmoi" "$BIN_DIR/chezmoi"

package/scripts/ci/validate-ci-config.sh

@@ -0,0 +1,224 @@
+#!/usr/bin/env bash
+# Copyright (c) 2015-2026 Dotfiles. All rights reserved.
+# CI Configuration Validation Script
+# Verifies that all zero-warning policy components are properly configured
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(dirname "$(dirname "$SCRIPT_DIR")")"
+
+# Colors for output (respect NO_COLOR: https://no-color.org)
+if [[ -z "${NO_COLOR:-}" ]] && [[ -t 1 ]]; then
+  RED='\033[0;31m' GREEN='\033[0;32m' YELLOW='\033[0;33m'
+  BLUE='\033[0;34m' NC='\033[0m'
+else
+  RED='' GREEN='' YELLOW='' BLUE='' NC=''
+fi
+
+printf '%b\n' "${BLUE}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}"
+printf '%b\n' "${BLUE}      CI CONFIGURATION VALIDATOR      ${NC}"
+printf '%b\n' "${BLUE}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}"
+echo ""
+
+ERRORS=0
+WARNINGS=0
+
+# Helper functions
+check_file_exists() {
+  local file="$1"
+  local description="$2"
+
+  if [[ -f "$file" ]]; then
+    printf '%b\n' "  ${GREEN}✓${NC} $description"
+    return 0
+  else
+    printf '%b\n' "  ${RED}✗${NC} $description"
+    ((ERRORS++))
+    return 1
+  fi
+}
+
+check_pattern_in_file() {
+  local file="$1"
+  local pattern="$2"
+  local description="$3"
+
+  if [[ -f "$file" ]] && grep -q "$pattern" "$file"; then
+    printf '%b\n' "  ${GREEN}✓${NC} $description"
+    return 0
+  else
+    printf '%b\n' "  ${RED}✗${NC} $description"
+    ((ERRORS++))
+    return 1
+  fi
+}
+
+warn_if_pattern() {
+  local file="$1"
+  local pattern="$2"
+  local description="$3"
+
+  if [[ -f "$file" ]] && grep -q "$pattern" "$file"; then
+    printf '%b\n' "  ${YELLOW}⚠${NC} $description"
+    ((WARNINGS++))
+    return 1
+  else
+    printf '%b\n' "  ${GREEN}✓${NC} $description"
+    return 0
+  fi
+}
+
+# Check 1: Core CI files exist
+printf '%b\n' "${BLUE}1. Core CI Files${NC}"
+check_file_exists "$REPO_ROOT/.github/workflows/ci.yml" "Main CI workflow exists"
+check_file_exists "$REPO_ROOT/.github/workflows/nightly.yml" "Nightly workflow exists"
+check_file_exists "$REPO_ROOT/.github/workflows/security-enhanced.yml" "Security workflow exists"
+check_file_exists "$REPO_ROOT/config/pre-commit-config.yaml" "Pre-commit configuration exists"
+echo ""
+
+# Check 2: Zero-warning enforcement
+printf '%b\n' "${BLUE}2. Zero-Warning Policy Enforcement${NC}"
+check_pattern_in_file "$REPO_ROOT/.github/workflows/ci.yml" "zero-warning" "Zero-warning policy documented"
+check_pattern_in_file "$REPO_ROOT/.github/workflows/ci.yml" "fail on unformatted code" "Formatter failure enforced"
+check_pattern_in_file "$REPO_ROOT/.github/workflows/ci.yml" "warnings-as-errors" "Warnings treated as errors"
+
+# Verify no || true patterns in security steps
+warn_if_pattern "$REPO_ROOT/.github/workflows/ci.yml" "gitleaks.*||.*true" "Gitleaks bypass detected"
+warn_if_pattern "$REPO_ROOT/.github/workflows/ci.yml" "shellcheck.*||.*true" "Shellcheck bypass detected"
+echo ""
+
+# Check 3: Test coverage requirements
+printf '%b\n' "${BLUE}3. Test Coverage Requirements${NC}"
+check_pattern_in_file "$REPO_ROOT/.github/workflows/ci.yml" "100%" "100% coverage requirement"
+check_pattern_in_file "$REPO_ROOT/.github/workflows/ci.yml" "fail-under" "Coverage threshold enforcement"
+
+if [[ -f "$REPO_ROOT/tests/framework/test_runner.sh" ]]; then
+  printf '%b\n' "  ${GREEN}✓${NC} Test framework exists"
+else
+  printf '%b\n' "  ${RED}✗${NC} Test framework missing"
+  ((ERRORS++))
+fi
+echo ""
+
+# Check 4: Security scanning
+printf '%b\n' "${BLUE}4. Security Scanning Configuration${NC}"
+check_pattern_in_file "$REPO_ROOT/.github/workflows/ci.yml" "security-secrets" "Secret scanning enabled"
+check_pattern_in_file "$REPO_ROOT/.github/workflows/ci.yml" "security-dependencies" "Dependency audit enabled"
+check_pattern_in_file "$REPO_ROOT/config/pre-commit-config.yaml" "gitleaks" "Pre-commit secret scanning"
+check_pattern_in_file "$REPO_ROOT/config/pre-commit-config.yaml" "detect-secrets" "Advanced secret detection"
+
+# Verify no piped execution patterns
+warn_if_pattern "$REPO_ROOT/.github/workflows/ci.yml" "curl.*|.*sh" "Dangerous piped execution"
+warn_if_pattern "$REPO_ROOT/.github/workflows/ci.yml" "wget.*|.*bash" "Dangerous piped execution"
+echo ""
+
+# Check 5: Performance monitoring
+printf '%b\n' "${BLUE}5. Performance Monitoring${NC}"
+check_pattern_in_file "$REPO_ROOT/.github/workflows/ci.yml" "benchmark" "Performance benchmarking enabled"
+check_pattern_in_file "$REPO_ROOT/.github/workflows/ci.yml" "500ms" "Shell startup threshold defined"
+check_pattern_in_file "$REPO_ROOT/.github/workflows/nightly.yml" "performance-tracking" "Nightly performance tracking"
+echo ""
+
+# Check 6: Multi-OS support
+printf '%b\n' "${BLUE}6. Multi-OS Testing${NC}"
+check_pattern_in_file "$REPO_ROOT/.github/workflows/ci.yml" "ubuntu-latest" "Linux testing enabled"
+check_pattern_in_file "$REPO_ROOT/.github/workflows/ci.yml" "macos-latest" "macOS testing enabled"
+check_pattern_in_file "$REPO_ROOT/.github/workflows/nightly.yml" "matrix:" "OS matrix testing configured"
+echo ""
+
+# Check 7: Timeouts and efficiency
+printf '%b\n' "${BLUE}7. Timeout and Efficiency Settings${NC}"
+if grep -q "timeout-minutes: [0-9]" "$REPO_ROOT/.github/workflows/ci.yml"; then
+  MAX_TIMEOUT=$(grep "timeout-minutes:" "$REPO_ROOT/.github/workflows/ci.yml" |
+    awk '{print $2}' | sort -n | tail -1)
+  if [[ $MAX_TIMEOUT -le 15 ]]; then
+    printf '%b\n' "  ${GREEN}✓${NC} Job timeouts properly configured (max: ${MAX_TIMEOUT}min)"
+  else
+    printf '%b\n' "  ${YELLOW}⚠${NC} Some jobs have long timeouts (max: ${MAX_TIMEOUT}min)"
+    ((WARNINGS++))
+  fi
+else
+  printf '%b\n' "  ${RED}✗${NC} No timeout configuration found"
+  ((ERRORS++))
+fi
+
+check_pattern_in_file "$REPO_ROOT/.github/workflows/ci.yml" "cache" "Dependency caching enabled"
+echo ""
+
+# Check 8: Branch protection readiness
+printf '%b\n' "${BLUE}8. Branch Protection Readiness${NC}"
+check_file_exists "$REPO_ROOT/.github/BRANCH_PROTECTION.md" "Branch protection documentation"
+check_pattern_in_file "$REPO_ROOT/.github/workflows/ci.yml" "quality-gate" "Quality gate job defined"
+
+# Check for required status check names
+REQUIRED_CHECKS=(
+  "lint-shell"
+  "security-secrets"
+  "security-dependencies"
+  "test-unit"
+  "quality-gate"
+)
+
+for check in "${REQUIRED_CHECKS[@]}"; do
+  if grep -q "name:.*$check" "$REPO_ROOT/.github/workflows/ci.yml"; then
+    printf '%b\n' "  ${GREEN}✓${NC} Required check '$check' defined"
+  else
+    printf '%b\n' "  ${RED}✗${NC} Required check '$check' missing"
+    ((ERRORS++))
+  fi
+done
+echo ""
+
+# Check 9: Nightly extended testing
+printf '%b\n' "${BLUE}9. Nightly Extended Testing${NC}"
+if [[ -f "$REPO_ROOT/.github/workflows/nightly.yml" ]]; then
+  check_pattern_in_file "$REPO_ROOT/.github/workflows/nightly.yml" "dependency-updates" "Dependency monitoring"
+  check_pattern_in_file "$REPO_ROOT/.github/workflows/nightly.yml" "beta-tools-test" "Beta tool testing"
+  check_pattern_in_file "$REPO_ROOT/.github/workflows/nightly.yml" "security-extended" "Extended security scanning"
+  check_pattern_in_file "$REPO_ROOT/.github/workflows/nightly.yml" "cron:" "Scheduled execution"
+else
+  printf '%b\n' "  ${RED}✗${NC} Nightly workflow missing"
+  ((ERRORS++))
+fi
+echo ""
+
+# Final summary
+printf '%b\n' "${BLUE}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}"
+printf '%b\n' "${BLUE}           VALIDATION SUMMARY         ${NC}"
+printf '%b\n' "${BLUE}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}"
+
+if [[ $ERRORS -eq 0 ]] && [[ $WARNINGS -eq 0 ]]; then
+  printf '%b\n' "${GREEN}✅ PERFECT: CI configuration fully compliant${NC}"
+  echo "   - Zero-warning policy properly enforced"
+  echo "   - All security gates configured"
+  echo "   - Performance monitoring active"
+  echo "   - Ready for branch protection"
+elif [[ $ERRORS -eq 0 ]]; then
+  printf '%b\n' "${YELLOW}⚠️  GOOD: CI mostly compliant with $WARNINGS warning(s)${NC}"
+  echo "   - Core functionality working"
+  echo "   - Minor improvements recommended"
+else
+  printf '%b\n' "${RED}❌ ISSUES: CI configuration has $ERRORS error(s) and $WARNINGS warning(s)${NC}"
+  echo "   - Critical fixes required before deployment"
+fi
+
+echo ""
+echo "Configuration Details:"
+echo "  - Repository: $REPO_ROOT"
+echo "  - Main CI: .github/workflows/ci.yml"
+echo "  - Nightly: .github/workflows/nightly.yml"
+echo "  - Pre-commit: config/pre-commit-config.yaml"
+echo ""
+echo "Next Steps:"
+if [[ $ERRORS -gt 0 ]]; then
+  echo "  1. Fix critical errors listed above"
+  echo "  2. Re-run validation: $0"
+fi
+if [[ $WARNINGS -gt 0 ]]; then
+  echo "  3. Address warnings for optimal configuration"
+fi
+echo "  4. Configure branch protection rules per BRANCH_PROTECTION.md"
+echo "  5. Test CI pipeline with a small PR"
+
+exit $ERRORS

package/scripts/demo/record.sh

@@ -0,0 +1,42 @@
+#!/usr/bin/env bash
+# Copyright (c) 2015-2026 Dotfiles. All rights reserved.
+set -euo pipefail
+
+OUT="${1:-$HOME/.dotfiles/docs/demo/demo.gif}"
+DURATION="${DURATION:-30}"
+FPS="${FPS:-15}"
+
+record_ffmpeg() {
+  if command -v ffmpeg >/dev/null; then
+    echo "Recording with ffmpeg for ${DURATION}s..."
+    if [ "$(uname -s)" = "Darwin" ]; then
+      # macOS (AVFoundation)
+      ffmpeg -y -t "$DURATION" -f avfoundation -i "1:none" -vf "fps=$FPS,scale=1024:-1:flags=lanczos" "$OUT"
+    else
+      # Linux (X11)
+      ffmpeg -y -t "$DURATION" -f x11grab -i :0.0 -vf "fps=$FPS,scale=1024:-1:flags=lanczos" "$OUT"
+    fi
+  else
+    echo "ffmpeg not found. Install it and retry."
+    exit 1
+  fi
+}
+
+record_wf_recorder() {
+  if command -v wf-recorder >/dev/null; then
+    echo "Recording with wf-recorder for ${DURATION}s..."
+    wf-recorder -f "$OUT" -t "$DURATION"
+  else
+    return 1
+  fi
+}
+
+if [ "$(uname -s)" = "Linux" ]; then
+  if record_wf_recorder; then
+    exit 0
+  fi
+fi
+
+record_ffmpeg
+
+printf "Saved demo to %s\n" "$OUT"

package/scripts/diagnostics/a2a-conformance.sh

@@ -0,0 +1,162 @@
+#!/usr/bin/env bash
+# Copyright (c) 2015-2026 Dotfiles. All rights reserved.
+## A2A v0.3 and agent card conformance validation.
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="${REPO_ROOT:-$(cd "$SCRIPT_DIR/../.." && pwd)}"
+
+# shellcheck source=../dot/lib/ui.sh
+source "$SCRIPT_DIR/../dot/lib/ui.sh"
+
+JSON_MODE=0
+STRICT_MODE=0
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --json | -j)
+      JSON_MODE=1
+      shift
+      ;;
+    --strict | -s)
+      STRICT_MODE=1
+      shift
+      ;;
+    *)
+      shift
+      ;;
+  esac
+done
+
+command -v jq >/dev/null 2>&1 || {
+  echo "jq is required for A2A conformance checks." >&2
+  exit 1
+}
+
+a2a_card="$REPO_ROOT/.well-known/agent-card.json"
+legacy_doc="$REPO_ROOT/.well-known/agent.json"
+internal_card="$REPO_ROOT/dot_config/dotfiles/agent-card.json"
+agent_profiles="$REPO_ROOT/dot_config/dotfiles/agent-profiles.json"
+status="healthy"
+issues=()
+
+# Check primary A2A v0.3 card
+if [[ ! -f "$a2a_card" ]]; then
+  issues+=("missing:.well-known/agent-card.json")
+fi
+
+# Check legacy agent.json
+if [[ ! -f "$legacy_doc" ]]; then
+  issues+=("missing:.well-known/agent.json")
+fi
+
+# Check internal card
+if [[ ! -f "$internal_card" ]]; then
+  issues+=("missing:agent-card.json")
+fi
+
+# Check agent profiles
+if [[ ! -f "$agent_profiles" ]]; then
+  issues+=("missing:agent-profiles.json")
+fi
+
+if [[ "${#issues[@]}" -eq 0 ]]; then
+  # Validate A2A v0.3 card
+  spec_version="$(jq -r '.specVersion // empty' "$a2a_card")"
+  [[ "$spec_version" == "0.3" ]] || issues+=("specVersion:expected 0.3, got $spec_version")
+
+  # Skills array
+  jq -e '.skills | type == "array"' "$a2a_card" >/dev/null 2>&1 || issues+=("skills:missing or not array")
+  skills_count="$(jq '.skills | length' "$a2a_card" 2>/dev/null || echo 0)"
+  [[ "$skills_count" -gt 0 ]] || issues+=("skills:empty array")
+
+  # Authentication block
+  jq -e '.authentication' "$a2a_card" >/dev/null 2>&1 || issues+=("authentication:missing")
+
+  # Signing metadata
+  signing_method="$(jq -r '.signing.method // empty' "$a2a_card")"
+  [[ -n "$signing_method" ]] || issues+=("signing:missing method")
+
+  # Capabilities
+  jq -e '.capabilities' "$a2a_card" >/dev/null 2>&1 || issues+=("capabilities:missing")
+
+  # Protocol must be "a2a" not "a2a-ready"
+  if jq -e '.protocols | index("a2a-ready")' "$a2a_card" >/dev/null 2>&1; then
+    issues+=("protocols:should use 'a2a' not 'a2a-ready'")
+  fi
+  jq -e '.protocols | index("a2a")' "$a2a_card" >/dev/null 2>&1 || issues+=("protocols:missing 'a2a'")
+
+  # Validate internal card also uses v0.3 and "a2a"
+  internal_spec="$(jq -r '.specVersion // empty' "$internal_card")"
+  [[ "$internal_spec" == "0.3" ]] || issues+=("internal-card:specVersion expected 0.3")
+  if jq -e '.protocols | index("a2a-ready")' "$internal_card" >/dev/null 2>&1; then
+    issues+=("internal-card:should use 'a2a' not 'a2a-ready'")
+  fi
+
+  # Validate legacy doc points to new card
+  jq -e '.a2aCard' "$legacy_doc" >/dev/null 2>&1 || issues+=("legacy:missing a2aCard pointer")
+  if jq -e '.protocols | index("a2a-ready")' "$legacy_doc" >/dev/null 2>&1; then
+    issues+=("legacy:should use 'a2a' not 'a2a-ready'")
+  fi
+
+  # Name consistency
+  a2a_name="$(jq -r '.name // empty' "$a2a_card")"
+  internal_name="$(jq -r '.name // empty' "$internal_card")"
+  legacy_name="$(jq -r '.name // empty' "$legacy_doc")"
+  [[ "$a2a_name" == "$internal_name" ]] || issues+=("name:mismatch between a2a-card and internal card")
+  [[ "$a2a_name" == "$legacy_name" ]] || issues+=("name:mismatch between a2a-card and legacy doc")
+
+  # Default profile validation
+  default_profile="$(jq -r '.defaultProfile // empty' "$internal_card")"
+  if [[ -n "$default_profile" ]]; then
+    jq -e --arg profile "$default_profile" '.profiles[$profile]' "$agent_profiles" >/dev/null 2>&1 || issues+=("default-profile:missing in agent-profiles.json")
+  fi
+
+  # Card signing in internal card
+  jq -e '.security.cardSigning' "$internal_card" >/dev/null 2>&1 || issues+=("internal-card:missing cardSigning in security")
+fi
+
+if [[ "${#issues[@]}" -gt 0 ]]; then
+  status="issues"
+fi
+
+# Build issues JSON safely
+if [[ "${#issues[@]}" -gt 0 ]]; then
+  issues_json="$(printf '%s\n' "${issues[@]}" | jq -R . | jq -s .)"
+else
+  issues_json="[]"
+fi
+
+payload="$(jq -n \
+  --arg status "$status" \
+  --arg a2a_card "$a2a_card" \
+  --arg legacy_doc "$legacy_doc" \
+  --arg internal_card "$internal_card" \
+  --arg agent_profiles "$agent_profiles" \
+  --argjson strict "$([[ "$STRICT_MODE" -eq 1 ]] && echo true || echo false)" \
+  --argjson issues "$issues_json" \
+  '{status: $status, strict: $strict, specVersion: "0.3", files: {a2a_card: $a2a_card, legacy_doc: $legacy_doc, internal_card: $internal_card, agent_profiles: $agent_profiles}, issues: $issues}')"
+
+if [[ "$JSON_MODE" -eq 1 ]]; then
+  printf '%s\n' "$payload"
+else
+  ui_dot_banner "AI and Agents"
+  ui_header "A2A v0.3 Conformance"
+  if [[ "$status" == "healthy" ]]; then
+    ui_ok "Status" "healthy"
+    ui_ok "Spec version" "0.3"
+    ui_ok "A2A card" "$a2a_card"
+    ui_ok "Legacy doc" "$legacy_doc"
+    ui_ok "Internal card" "$internal_card"
+  else
+    ui_warn "Status" "issues"
+    while IFS= read -r issue; do
+      [[ -n "$issue" ]] || continue
+      ui_warn "Issue" "$issue"
+    done < <(printf '%s' "$payload" | jq -r '.issues[]')
+  fi
+fi
+
+if [[ "$STRICT_MODE" -eq 1 && "$status" != "healthy" ]]; then
+  exit 1
+fi