@kabran-tecnologia/kabran-config 1.8.0 → 1.10.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kabran-tecnologia/kabran-config",
-  "version": "1.8.0",
+  "version": "1.10.0",
   "description": "Shared quality configurations, enforcement scripts, and CI/CD tooling for Kabran projects",
   "author": "Kabran",
   "license": "MIT",
@@ -11,7 +11,9 @@
   "bin": {
     "kabran-setup": "src/scripts/setup.mjs",
     "kabran-ci": "src/scripts/ci/ci-runner.sh",
-    "kabran-pr-comment": "src/scripts/pr-quality-comment.mjs"
+    "kabran-pr-comment": "src/scripts/pr-quality-comment.mjs",
+    "kabran-traceability": "src/scripts/traceability/validate-traceability.sh",
+    "kabran-coverage": "src/scripts/traceability/coverage-report.sh"
   },
   "exports": {
     "./eslint": "./src/eslint.mjs",
@@ -29,6 +31,7 @@
     "./scripts/env-validator": "./src/scripts/env-validator.mjs",
     "./scripts/ci/*": "./src/scripts/ci/*",
     "./scripts/deploy/*": "./src/scripts/deploy/*",
+    "./scripts/traceability/*": "./src/scripts/traceability/*",
     "./scripts/setup": "./src/scripts/setup.mjs",
     "./scripts/quality-standard-validator": "./src/scripts/quality-standard-validator.mjs",
     "./scripts/generate-ci-result": "./src/scripts/generate-ci-result.mjs",

package/src/scripts/ci/ci-core.sh

@@ -590,6 +590,279 @@ export_ci_data() {
   log_debug "CI data exported to: $output_file"
 }
 
+# ==============================================================================
+# OpenTelemetry Metrics Export
+# ==============================================================================
+
+# Export CI metrics to OTel Collector via OTLP HTTP
+# Usage: export_ci_metrics_to_otel "$CI_DATA_FILE"
+# Environment: OTEL_ENDPOINT must be set (e.g., http://localhost:4318)
+# Returns: 0 on success, 1 on failure (but never fails the build due to || true usage)
+export_ci_metrics_to_otel() {
+  local ci_data_file="${1:-}"
+
+  # Check if OTEL_ENDPOINT is configured
+  if [ -z "${OTEL_ENDPOINT:-}" ]; then
+    log_debug "OTEL_ENDPOINT not set, skipping metrics export"
+    return 0
+  fi
+
+  # Validate input file
+  if [ -z "$ci_data_file" ] || [ ! -f "$ci_data_file" ]; then
+    log_warn "CI data file not found: $ci_data_file"
+    return 1
+  fi
+
+  # Check for curl
+  if ! command -v curl &>/dev/null; then
+    log_warn "curl not available, skipping OTel metrics export"
+    return 1
+  fi
+
+  log_info "Exporting CI metrics to OTel Collector..."
+  log_debug "  Endpoint: $OTEL_ENDPOINT"
+  log_debug "  Data file: $ci_data_file"
+
+  # Extract metrics from CI data
+  local total_ms steps_json project_name trace_id ci_passed
+  total_ms=$(jq -r '.timing.total_ms // 0' "$ci_data_file" 2>/dev/null)
+  steps_json=$(jq -c '.steps // []' "$ci_data_file" 2>/dev/null)
+  project_name=$(jq -r '.project.name // "unknown"' "$ci_data_file" 2>/dev/null)
+  trace_id=$(jq -r '.trace_context.trace_id // ""' "$ci_data_file" 2>/dev/null)
+
+  # Determine overall status
+  local failed_count
+  failed_count=$(echo "$steps_json" | jq '[.[] | select(.status == "fail")] | length' 2>/dev/null || echo "0")
+  if [ "$failed_count" -gt 0 ]; then
+    ci_passed="false"
+  else
+    ci_passed="true"
+  fi
+
+  # Get timestamp in nanoseconds (Unix epoch)
+  local timestamp_ns
+  timestamp_ns=$(date +%s)000000000
+
+  # Build OTLP metrics payload
+  local otlp_payload
+  otlp_payload=$(build_otlp_metrics_payload \
+    "$project_name" \
+    "$total_ms" \
+    "$ci_passed" \
+    "$steps_json" \
+    "$timestamp_ns" \
+    "$trace_id")
+
+  if [ -z "$otlp_payload" ] || [ "$otlp_payload" = "null" ]; then
+    log_warn "Failed to build OTLP payload"
+    return 1
+  fi
+
+  # Send to OTel Collector with aggressive timeouts
+  # --connect-timeout 1: max 1 second to establish connection
+  # --max-time 5: max 5 seconds total for the request
+  # -f: fail silently on HTTP errors
+  local otel_metrics_endpoint="${OTEL_ENDPOINT}/v1/metrics"
+
+  log_debug "Sending metrics to: $otel_metrics_endpoint"
+
+  local http_code
+  http_code=$(curl -s -o /dev/null -w "%{http_code}" \
+    --connect-timeout 1 \
+    --max-time 5 \
+    -X POST \
+    -H "Content-Type: application/json" \
+    -d "$otlp_payload" \
+    "$otel_metrics_endpoint" 2>/dev/null) || {
+      log_warn "Failed to send metrics to OTel Collector (connection error)"
+      return 1
+    }
+
+  if [ "$http_code" -ge 200 ] && [ "$http_code" -lt 300 ]; then
+    log_success "CI metrics exported to OTel Collector (HTTP $http_code)"
+    return 0
+  else
+    log_warn "OTel Collector returned HTTP $http_code"
+    return 1
+  fi
+}
+
+# Build OTLP JSON payload for metrics
+# Usage: build_otlp_metrics_payload "$project" "$duration_ms" "$passed" "$steps_json" "$timestamp_ns" "$trace_id"
+build_otlp_metrics_payload() {
+  local project="$1"
+  local duration_ms="$2"
+  local passed="$3"
+  local steps_json="$4"
+  local timestamp_ns="$5"
+  local trace_id="${6:-}"
+
+  # Service attributes
+  local service_name="ci-runner"
+  local service_version="${CI_CORE_VERSION:-unknown}"
+
+  # Count steps by status
+  local pass_count fail_count skip_count
+  pass_count=$(echo "$steps_json" | jq '[.[] | select(.status == "pass")] | length' 2>/dev/null || echo "0")
+  fail_count=$(echo "$steps_json" | jq '[.[] | select(.status == "fail")] | length' 2>/dev/null || echo "0")
+  skip_count=$(echo "$steps_json" | jq '[.[] | select(.status == "skip")] | length' 2>/dev/null || echo "0")
+
+  # Build step duration data points
+  local step_duration_points
+  step_duration_points=$(echo "$steps_json" | jq -c --arg ts "$timestamp_ns" '
+    [.[] | select(.status != "skip") | {
+      attributes: ([
+        {key: "step.name", value: {stringValue: .name}},
+        {key: "step.category", value: {stringValue: (.category // "custom")}},
+        {key: "step.status", value: {stringValue: .status}}
+      ] + (if (.component // "") != "" then [{key: "step.component", value: {stringValue: .component}}] else [] end)),
+      startTimeUnixNano: $ts,
+      timeUnixNano: $ts,
+      asDouble: .duration_ms
+    }]
+  ' 2>/dev/null || echo "[]")
+
+  # Build resource attributes (conditionally include trace_id)
+  local resource_attributes
+  if [ -n "$trace_id" ]; then
+    resource_attributes=$(jq -n \
+      --arg service_name "$service_name" \
+      --arg service_version "$service_version" \
+      --arg project "$project" \
+      --arg trace_id "$trace_id" \
+      '[
+        {key: "service.name", value: {stringValue: $service_name}},
+        {key: "service.version", value: {stringValue: $service_version}},
+        {key: "project.name", value: {stringValue: $project}},
+        {key: "trace.id", value: {stringValue: $trace_id}}
+      ]')
+  else
+    resource_attributes=$(jq -n \
+      --arg service_name "$service_name" \
+      --arg service_version "$service_version" \
+      --arg project "$project" \
+      '[
+        {key: "service.name", value: {stringValue: $service_name}},
+        {key: "service.version", value: {stringValue: $service_version}},
+        {key: "project.name", value: {stringValue: $project}}
+      ]')
+  fi
+
+  # Determine status string
+  local status_str="fail"
+  if [ "$passed" = "true" ]; then
+    status_str="pass"
+  fi
+
+  # Build the full OTLP payload
+  jq -n \
+    --arg service_version "$service_version" \
+    --arg project "$project" \
+    --arg timestamp_ns "$timestamp_ns" \
+    --arg status_str "$status_str" \
+    --argjson duration_ms "$duration_ms" \
+    --argjson pass_count "$pass_count" \
+    --argjson fail_count "$fail_count" \
+    --argjson skip_count "$skip_count" \
+    --argjson step_duration_points "$step_duration_points" \
+    --argjson resource_attributes "$resource_attributes" \
+    '{
+      resourceMetrics: [{
+        resource: {
+          attributes: $resource_attributes
+        },
+        scopeMetrics: [{
+          scope: {
+            name: "kabran-config/ci-runner",
+            version: $service_version
+          },
+          metrics: [
+            {
+              name: "ci.build.duration",
+              description: "Total duration of CI build in milliseconds",
+              unit: "ms",
+              gauge: {
+                dataPoints: [{
+                  attributes: [
+                    {key: "project", value: {stringValue: $project}},
+                    {key: "status", value: {stringValue: $status_str}}
+                  ],
+                  startTimeUnixNano: $timestamp_ns,
+                  timeUnixNano: $timestamp_ns,
+                  asDouble: $duration_ms
+                }]
+              }
+            },
+            {
+              name: "ci.build.status",
+              description: "CI build status counter (1 = occurrence)",
+              unit: "1",
+              sum: {
+                dataPoints: [{
+                  attributes: [
+                    {key: "project", value: {stringValue: $project}},
+                    {key: "status", value: {stringValue: $status_str}}
+                  ],
+                  startTimeUnixNano: $timestamp_ns,
+                  timeUnixNano: $timestamp_ns,
+                  asInt: "1"
+                }],
+                aggregationTemporality: 2,
+                isMonotonic: true
+              }
+            },
+            {
+              name: "ci.step.count",
+              description: "Count of CI steps by status",
+              unit: "1",
+              sum: {
+                dataPoints: [
+                  {
+                    attributes: [
+                      {key: "project", value: {stringValue: $project}},
+                      {key: "status", value: {stringValue: "pass"}}
+                    ],
+                    startTimeUnixNano: $timestamp_ns,
+                    timeUnixNano: $timestamp_ns,
+                    asInt: ($pass_count | tostring)
+                  },
+                  {
+                    attributes: [
+                      {key: "project", value: {stringValue: $project}},
+                      {key: "status", value: {stringValue: "fail"}}
+                    ],
+                    startTimeUnixNano: $timestamp_ns,
+                    timeUnixNano: $timestamp_ns,
+                    asInt: ($fail_count | tostring)
+                  },
+                  {
+                    attributes: [
+                      {key: "project", value: {stringValue: $project}},
+                      {key: "status", value: {stringValue: "skip"}}
+                    ],
+                    startTimeUnixNano: $timestamp_ns,
+                    timeUnixNano: $timestamp_ns,
+                    asInt: ($skip_count | tostring)
+                  }
+                ],
+                aggregationTemporality: 2,
+                isMonotonic: false
+              }
+            },
+            {
+              name: "ci.step.duration",
+              description: "Duration of individual CI steps in milliseconds",
+              unit: "ms",
+              gauge: {
+                dataPoints: $step_duration_points
+              }
+            }
+          ]
+        }]
+      }]
+    }'
+}
+
 # ==============================================================================
 # JSON Output Generation
 # ==============================================================================

package/src/scripts/ci/ci-runner.sh

@@ -31,6 +31,7 @@ Environment Variables:
   CI_OUTPUT_FILE      Output file for legacy v1 format
   CI_OUTPUT_FILE_V2   Output file for v2 format (default: docs/quality/ci-result.json)
   CI_CONFIG_FILE      Path to project ci-config.sh
+  OTEL_ENDPOINT       OTel Collector endpoint for metrics export (e.g., http://localhost:4318)
 
 Examples:
   # Run all steps
@@ -232,6 +233,14 @@ if [ "$USE_V2" = "true" ]; then
     generate_ci_json "$OUTPUT_FILE" "$CI_PASSED" "$FAILED" "$PROJECT_NAME" "$METADATA"
   fi
 
+  # ==============================================================================
+  # Export Metrics to OTel Collector (if configured)
+  # ==============================================================================
+  # Fail-safe: telemetry failures NEVER fail the build (RN-01)
+  if [ -n "${OTEL_ENDPOINT:-}" ]; then
+    export_ci_metrics_to_otel "$INTERMEDIATE_FILE" || true
+  fi
+
   # Cleanup
   rm -f "$INTERMEDIATE_FILE"
 else

package/src/scripts/traceability/coverage-report.sh

@@ -0,0 +1,222 @@
+#!/usr/bin/env bash
+# ==============================================================================
+# Kabran Traceability Coverage Report
+# Part of @kabran-owner/kabran-config
+# Implements PROP-006: JSDoc Traceability Tags
+#
+# Generates a report of spec coverage in the codebase.
+# Shows which specs have code implementing them and which ACs are covered.
+# ==============================================================================
+
+set -euo pipefail
+
+# Source core functions
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=traceability-core.sh
+source "$SCRIPT_DIR/traceability-core.sh"
+
+# ==============================================================================
+# Configuration
+# ==============================================================================
+
+SEARCH_PATH="${1:-.}"
+SPEC_FILTER="${2:-}"
+OUTPUT_FORMAT="${OUTPUT_FORMAT:-text}"
+
+# ==============================================================================
+# Report Functions
+# ==============================================================================
+
+# Generate report for a specific spec
+report_spec() {
+  local spec="$1"
+  local files
+
+  files=$(grep -rl "@spec $spec" --include="*.ts" --include="*.tsx" "$SEARCH_PATH" 2>/dev/null || true)
+
+  if [ -z "$files" ]; then
+    return
+  fi
+
+  echo ""
+  echo "=== $spec ==="
+  echo ""
+  echo "Files:"
+  echo "$files" | while read -r file; do
+    [ -n "$file" ] && echo "  - $file"
+  done
+
+  echo ""
+  echo "ACs Implemented:"
+  echo "$files" | while read -r file; do
+    [ -n "$file" ] && extract_implements "$file"
+  done | sort -u | while read -r ac; do
+    [ -n "$ac" ] && echo "  - $ac"
+  done
+}
+
+# Generate summary report
+report_summary() {
+  log_section "Traceability Coverage Report v${TRACEABILITY_VERSION}"
+  log_info "Search path: $SEARCH_PATH"
+  echo ""
+
+  local total_files
+  local tagged_files
+  local specs
+
+  total_files=$(count_total_files "$SEARCH_PATH")
+  tagged_files=$(count_tagged_files "$SEARCH_PATH")
+
+  echo "## Overview"
+  echo ""
+  echo "| Metric | Value |"
+  echo "|--------|-------|"
+  echo "| Total TypeScript files | $total_files |"
+  echo "| Files with @spec | $tagged_files |"
+
+  if [ "$total_files" -gt 0 ]; then
+    local coverage=$((tagged_files * 100 / total_files))
+    echo "| Coverage | $coverage% |"
+  fi
+
+  echo ""
+  echo "## Specs Found"
+  echo ""
+
+  # Find all unique specs
+  specs=$(grep -roh '@spec S[0-9]*' --include="*.ts" --include="*.tsx" "$SEARCH_PATH" 2>/dev/null | sed 's/@spec //' | sort -u || true)
+
+  if [ -z "$specs" ]; then
+    echo "No @spec tags found in codebase."
+    return
+  fi
+
+  echo "$specs" | while read -r spec; do
+    if [ -n "$spec" ]; then
+      local file_count
+      file_count=$(grep -rl "@spec $spec" --include="*.ts" --include="*.tsx" "$SEARCH_PATH" 2>/dev/null | wc -l)
+      echo "- **$spec**: $file_count files"
+    fi
+  done
+}
+
+# Generate detailed report for all specs
+report_detailed() {
+  report_summary
+
+  echo ""
+  echo "## Detailed Coverage"
+
+  local specs
+  specs=$(grep -roh '@spec S[0-9]*' --include="*.ts" --include="*.tsx" "$SEARCH_PATH" 2>/dev/null | sed 's/@spec //' | sort -u || true)
+
+  if [ -n "$specs" ]; then
+    echo "$specs" | while read -r spec; do
+      [ -n "$spec" ] && report_spec "$spec"
+    done
+  fi
+}
+
+# Generate JSON report
+report_json() {
+  local total_files
+  local tagged_files
+  local specs
+
+  total_files=$(count_total_files "$SEARCH_PATH")
+  tagged_files=$(count_tagged_files "$SEARCH_PATH")
+  specs=$(grep -roh '@spec S[0-9]*' --include="*.ts" --include="*.tsx" "$SEARCH_PATH" 2>/dev/null | sed 's/@spec //' | sort -u || true)
+
+  local coverage=0
+  if [ "$total_files" -gt 0 ]; then
+    coverage=$((tagged_files * 100 / total_files))
+  fi
+
+  echo "{"
+  echo "  \"version\": \"${TRACEABILITY_VERSION}\","
+  echo "  \"searchPath\": \"$SEARCH_PATH\","
+  echo "  \"totalFiles\": $total_files,"
+  echo "  \"taggedFiles\": $tagged_files,"
+  echo "  \"coverage\": $coverage,"
+  echo "  \"specs\": ["
+
+  local first=true
+  if [ -n "$specs" ]; then
+    echo "$specs" | while read -r spec; do
+      if [ -n "$spec" ]; then
+        local file_count
+        file_count=$(grep -rl "@spec $spec" --include="*.ts" --include="*.tsx" "$SEARCH_PATH" 2>/dev/null | wc -l)
+        if [ "$first" = true ]; then
+          first=false
+        else
+          echo ","
+        fi
+        echo -n "    { \"id\": \"$spec\", \"files\": $file_count }"
+      fi
+    done
+  fi
+
+  echo ""
+  echo "  ]"
+  echo "}"
+}
+
+# ==============================================================================
+# Help
+# ==============================================================================
+
+show_help() {
+  cat << EOF
+Kabran Traceability Coverage Report v${TRACEABILITY_VERSION}
+
+Usage: coverage-report.sh [path] [spec] [options]
+
+Arguments:
+  path              Directory to scan (default: current directory)
+  spec              Filter by specific spec ID (e.g., S25)
+
+Environment Variables:
+  OUTPUT_FORMAT     Output format: text, detailed, json (default: text)
+
+Examples:
+  coverage-report.sh ./src
+  coverage-report.sh ./src S25
+  OUTPUT_FORMAT=json coverage-report.sh ./src
+  OUTPUT_FORMAT=detailed coverage-report.sh ./src
+
+Output Formats:
+  text              Summary with spec counts
+  detailed          Full breakdown with files and ACs per spec
+  json              Machine-readable JSON output
+
+EOF
+}
+
+# ==============================================================================
+# Entry Point
+# ==============================================================================
+
+if [[ "${1:-}" == "--help" ]] || [[ "${1:-}" == "-h" ]]; then
+  show_help
+  exit 0
+fi
+
+# Handle specific spec filter
+if [ -n "$SPEC_FILTER" ]; then
+  report_spec "$SPEC_FILTER"
+  exit 0
+fi
+
+# Generate report based on format
+case "$OUTPUT_FORMAT" in
+  json)
+    report_json
+    ;;
+  detailed)
+    report_detailed
+    ;;
+  *)
+    report_summary
+    ;;
+esac

package/src/scripts/traceability/traceability-core.sh

@@ -0,0 +1,122 @@
+#!/usr/bin/env bash
+# ==============================================================================
+# Kabran Traceability Core - Shared Functions
+# Part of @kabran-owner/kabran-config
+# Implements PROP-006: JSDoc Traceability Tags
+# ==============================================================================
+
+# Version - Dynamically resolve from package.json
+_SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+_PKG_JSON="$_SCRIPT_DIR/../../../package.json"
+if [ -f "$_PKG_JSON" ]; then
+  TRACEABILITY_VERSION=$(grep '"version":' "$_PKG_JSON" | head -1 | sed -E 's/.*"version": "([^"]+)".*/\1/')
+else
+  TRACEABILITY_VERSION="unknown"
+fi
+
+# Colors
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+BLUE='\033[0;34m'
+GRAY='\033[0;90m'
+NC='\033[0m'
+
+# ==============================================================================
+# Logging Functions
+# ==============================================================================
+
+log_info() {
+  echo -e "${BLUE}[INFO]${NC} $1"
+}
+
+log_success() {
+  echo -e "${GREEN}[PASS]${NC} $1"
+}
+
+log_error() {
+  echo -e "${RED}[FAIL]${NC} $1"
+}
+
+log_warn() {
+  echo -e "${YELLOW}[WARN]${NC} $1"
+}
+
+log_section() {
+  echo -e "\n${BLUE}====${NC} $1 ${BLUE}====${NC}"
+}
+
+# ==============================================================================
+# Tag Patterns (PROP-006 Standard)
+# ==============================================================================
+
+# Valid @spec format: @spec SXX (ID only, not full name)
+PATTERN_SPEC_VALID='@spec S[0-9]+'
+PATTERN_SPEC_INVALID='@spec S[0-9]+-'
+
+# Valid @implements format: @implements AC-XX or @implements SXX:AC-XX
+PATTERN_IMPLEMENTS='@implements'
+
+# Valid @task format: @task XXX-NNN
+PATTERN_TASK='@task [A-Z]+-[0-9]+'
+
+# Valid @prd format: @prd RF-XXX or @prd RNF-XXX
+PATTERN_PRD='@prd R(N)?F-[0-9]+'
+
+# ==============================================================================
+# Validation Functions
+# ==============================================================================
+
+# Check if a file has @implements without @spec (integrity error)
+# Usage: check_orphan_implements "path/to/file.ts"
+# Returns: 0 if valid, 1 if orphan found
+check_orphan_implements() {
+  local file="$1"
+
+  if grep -qE "$PATTERN_IMPLEMENTS" "$file" 2>/dev/null; then
+    if ! grep -qE "$PATTERN_SPEC_VALID" "$file" 2>/dev/null; then
+      return 1  # Orphan found
+    fi
+  fi
+  return 0  # Valid
+}
+
+# Check if a file uses invalid @spec format (full name instead of ID)
+# Usage: check_spec_format "path/to/file.ts"
+# Returns: 0 if valid, 1 if invalid format found
+check_spec_format() {
+  local file="$1"
+
+  if grep -qE "$PATTERN_SPEC_INVALID" "$file" 2>/dev/null; then
+    return 1  # Invalid format
+  fi
+  return 0  # Valid
+}
+
+# Extract all @spec tags from a file
+# Usage: extract_specs "path/to/file.ts"
+extract_specs() {
+  local file="$1"
+  grep -oE '@spec S[0-9]+' "$file" 2>/dev/null | sed 's/@spec //' | sort -u
+}
+
+# Extract all @implements tags from a file
+# Usage: extract_implements "path/to/file.ts"
+extract_implements() {
+  local file="$1"
+  grep -oE '@implements [^*]+' "$file" 2>/dev/null | sed 's/@implements //' | tr ',' '\n' | sed 's/^ *//' | sort -u
+}
+
+# Count files with traceability tags
+# Usage: count_tagged_files "path/to/search"
+count_tagged_files() {
+  local search_path="${1:-.}"
+  grep -rl "@spec" --include="*.ts" --include="*.tsx" "$search_path" 2>/dev/null | wc -l
+}
+
+# Count total TypeScript files
+# Usage: count_total_files "path/to/search"
+count_total_files() {
+  local search_path="${1:-.}"
+  find "$search_path" -type f \( -name "*.ts" -o -name "*.tsx" \) 2>/dev/null | wc -l
+}

package/src/scripts/traceability/validate-traceability.sh

@@ -0,0 +1,150 @@
+#!/usr/bin/env bash
+# ==============================================================================
+# Kabran Traceability Validator
+# Part of @kabran-owner/kabran-config
+# Implements PROP-006: JSDoc Traceability Tags
+#
+# Validates FORMAT of traceability tags (not presence).
+# Tags are optional - this script only checks:
+# 1. @implements without @spec (integrity error)
+# 2. @spec with full name instead of ID (format warning)
+# ==============================================================================
+
+set -uo pipefail
+
+# Source core functions
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=traceability-core.sh
+source "$SCRIPT_DIR/traceability-core.sh"
+
+# ==============================================================================
+# Configuration
+# ==============================================================================
+
+SEARCH_PATH="${1:-.}"
+STRICT_MODE="${STRICT_MODE:-false}"
+EXIT_CODE=0
+
+# ==============================================================================
+# Main Validation
+# ==============================================================================
+
+main() {
+  log_section "Traceability Validation v${TRACEABILITY_VERSION}"
+  log_info "Search path: $SEARCH_PATH"
+  log_info "Strict mode: $STRICT_MODE"
+
+  local orphan_count=0
+  local format_count=0
+  local files_checked=0
+
+  # Find all TypeScript files
+  local files
+  files=$(find "$SEARCH_PATH" -type f \( -name "*.ts" -o -name "*.tsx" \) 2>/dev/null || true)
+
+  if [ -z "$files" ]; then
+    log_info "No TypeScript files found"
+    return 0
+  fi
+
+  while IFS= read -r file; do
+    [ -z "$file" ] && continue
+    files_checked=$((files_checked + 1))
+
+    # Check for orphan @implements (ERROR)
+    if ! check_orphan_implements "$file"; then
+      log_error "Orphan @implements (no @spec): $file"
+      orphan_count=$((orphan_count + 1))
+    fi
+
+    # Check for invalid @spec format (WARNING)
+    if ! check_spec_format "$file"; then
+      log_warn "Invalid @spec format (use ID only): $file"
+      format_count=$((format_count + 1))
+    fi
+
+  done <<< "$files"
+
+  # Summary
+  log_section "Validation Summary"
+  log_info "Files checked: $files_checked"
+
+  if [ "$orphan_count" -gt 0 ]; then
+    log_error "Orphan @implements found: $orphan_count"
+    EXIT_CODE=1
+  else
+    log_success "No orphan @implements found"
+  fi
+
+  if [ "$format_count" -gt 0 ]; then
+    log_warn "Invalid @spec format: $format_count"
+    if [ "$STRICT_MODE" = "true" ]; then
+      EXIT_CODE=1
+    fi
+  else
+    log_success "All @spec tags use correct format"
+  fi
+
+  # Coverage stats (informational)
+  local tagged_files
+  local total_files
+  tagged_files=$(count_tagged_files "$SEARCH_PATH")
+  total_files=$(count_total_files "$SEARCH_PATH")
+
+  if [ "$total_files" -gt 0 ]; then
+    local coverage=$((tagged_files * 100 / total_files))
+    log_info "Traceability coverage: $tagged_files/$total_files files ($coverage%)"
+  fi
+
+  return $EXIT_CODE
+}
+
+# ==============================================================================
+# Help
+# ==============================================================================
+
+show_help() {
+  cat << EOF
+Kabran Traceability Validator v${TRACEABILITY_VERSION}
+
+Usage: validate-traceability.sh [path] [options]
+
+Arguments:
+  path              Directory to validate (default: current directory)
+
+Environment Variables:
+  STRICT_MODE       If "true", format warnings become errors (default: false)
+
+Exit Codes:
+  0                 Validation passed
+  1                 Validation failed (orphan @implements or strict mode violations)
+
+Examples:
+  validate-traceability.sh ./src
+  STRICT_MODE=true validate-traceability.sh ./src
+
+Tags Validated (PROP-006):
+  @spec S25         Link to spec (ID only, not full name)
+  @implements AC-01 Acceptance criteria implemented
+  @task AGT-123     Link to Linear task
+  @prd RF-007       Link to PRD requirement
+
+Rules:
+  - All tags are OPTIONAL
+  - @implements WITHOUT @spec is an ERROR
+  - @spec with full name (S25-name) is a WARNING
+
+EOF
+}
+
+# ==============================================================================
+# Entry Point
+# ==============================================================================
+
+if [[ "${1:-}" == "--help" ]] || [[ "${1:-}" == "-h" ]]; then
+  show_help
+  exit 0
+fi
+
+main
+exit $EXIT_CODE