@sebastienrousseau/dotfiles 0.2.499 → 0.2.501

package/scripts/ops/setup.sh

@@ -0,0 +1,137 @@
+#!/usr/bin/env bash
+# Copyright (c) 2015-2026 Dotfiles. All rights reserved.
+# Interactive setup for dotfiles preferences
+# Usage: dot setup
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=../dot/lib/ui.sh
+# shellcheck disable=SC1091
+source "$SCRIPT_DIR/../dot/lib/ui.sh"
+
+ui_init
+
+CONFIG_DIR="${XDG_CONFIG_HOME:-$HOME/.config}/chezmoi"
+CONFIG_FILE="$CONFIG_DIR/chezmoi.toml"
+BACKUP_FILE="$CONFIG_DIR/chezmoi.toml.bak.$(date +%Y%m%d_%H%M%S)"
+mkdir -p "$CONFIG_DIR"
+
+choose() {
+  local prompt="$1"
+  shift
+  if command -v gum >/dev/null 2>&1; then
+    gum choose --cursor.foreground=212 --selected.foreground=212 --header "$prompt" "$@"
+  else
+    echo "$prompt"
+    select opt in "$@"; do
+      echo "$opt"
+      return
+    done
+  fi
+}
+
+confirm() {
+  local prompt="$1"
+  if command -v gum >/dev/null 2>&1; then
+    gum confirm "$prompt"
+  else
+    read -r -p "$prompt [y/N]: " ans
+    [[ "$ans" =~ ^[Yy]$ ]]
+  fi
+}
+
+ui_header "Dotfiles Setup"
+
+profile=$(choose "Select profile" laptop desktop server minimal)
+
+feature_zsh=true
+feature_nvim=true
+feature_tmux=true
+feature_gui=true
+feature_secrets=true
+
+confirm "Enable Zsh config?" || feature_zsh=false
+confirm "Enable Neovim config?" || feature_nvim=false
+confirm "Enable tmux config?" || feature_tmux=false
+confirm "Enable GUI extras (fonts/themes)?" || feature_gui=false
+confirm "Enable secrets integration?" || feature_secrets=false
+
+alias_profile=$(choose "Alias profile" standard minimal)
+strict_mode=false
+confirm "Enable strict alias governance?" && strict_mode=true
+
+secrets_provider=$(choose "Secrets provider" auto sops onepassword bitwarden)
+
+theme_choices=(
+  macos-ai-dark macos-ai-light
+  macos-bigsur-dark macos-bigsur-light
+  macos-blue-dark macos-blue-light
+  macos-blush-dark macos-blush-light
+  macos-citrus-dark macos-citrus-light
+  macos-green-dark macos-green-light
+  macos-gridgreen-dark macos-gridgreen-light
+  macos-heatmap-dark macos-heatmap-light
+  macos-indigo-dark macos-indigo-light
+  macos-miami-dark macos-miami-light
+  macos-mojave-dark macos-mojave-light
+  macos-monterey-dark macos-monterey-light
+  macos-nova-dark macos-nova-light
+  macos-orange-dark macos-orange-light
+  macos-pink-dark macos-pink-light
+  macos-purple-dark macos-purple-light
+  macos-sequoia-dark macos-sequoia-light
+  macos-silver-dark macos-silver-light
+  macos-sonoma-dark macos-sonoma-light
+  macos-tahoe-dark macos-tahoe-light
+  macos-valentine-dark macos-valentine-light
+  macos-ventura-dark macos-ventura-light
+  macos-wave-dark macos-wave-light
+  macos-yellow-dark macos-yellow-light
+)
+theme=$(choose "Theme" "${theme_choices[@]}")
+
+if [[ -f "$CONFIG_FILE" ]]; then
+  cp "$CONFIG_FILE" "$BACKUP_FILE"
+  ui_info "Backup" "$BACKUP_FILE"
+fi
+
+cat >"$CONFIG_FILE" <<TOML
+[data]
+profile = "$profile"
+theme = "$theme"
+
+[data.features]
+zsh = ${feature_zsh}
+nvim = ${feature_nvim}
+tmux = ${feature_tmux}
+gui = ${feature_gui}
+secrets = ${feature_secrets}
+
+[data.aliases]
+profile = "$alias_profile"
+
+[data.aliases.policy]
+strict_mode = ${strict_mode}
+
+[data.aliases.buckets]
+system = true
+svn = true
+
+[data.secrets]
+
+[data.secrets.policy]
+provider = "$secrets_provider"
+auto_load = true
+TOML
+
+ui_ok "Config" "Updated $CONFIG_FILE"
+
+if confirm "Apply dotfiles now?"; then
+  if command -v chezmoi >/dev/null 2>&1; then
+    chezmoi apply
+    ui_ok "Apply" "Complete"
+  else
+    ui_warn "chezmoi" "Not installed"
+  fi
+fi

package/scripts/ops/teleport.sh

@@ -0,0 +1,33 @@
+#!/usr/bin/env bash
+# Copyright (c) 2015-2026 Dotfiles. All rights reserved.
+# Script: teleport.sh
+# Description: Deploys dotfiles to a remote host ephemerally.
+# Usage: ./teleport.sh user@hostname
+
+set -euo pipefail
+
+TARGET="$1"
+
+if [[ -z "$TARGET" ]]; then
+  echo "Usage: $0 user@host"
+  exit 1
+fi
+
+# Validate SSH target: must be user@host format, no shell metacharacters
+if [[ ! "$TARGET" =~ ^[a-zA-Z0-9._-]+@[a-zA-Z0-9._-]+$ ]]; then
+  echo "Invalid SSH target: $TARGET" >&2
+  echo "Expected format: user@hostname (alphanumeric, dots, hyphens, underscores only)" >&2
+  exit 1
+fi
+
+echo " Teleporting dotfiles to ${TARGET}..."
+
+# 1. Archive the current state
+# 2. Pipe to SSH
+# 3. Extract in remote home directory with safety flags
+#    --no-same-owner: don't try to preserve owner (non-root)
+#    --strip-components=0: don't strip path components
+chezmoi archive | ssh "$TARGET" 'tar xz -C "$HOME" --no-same-owner'
+
+echo " Teleport successful!"
+echo "   Note: Changes are applied to files, but shell may need restart or sourcing."

package/scripts/qa/coverage-baseline.sh

@@ -0,0 +1,60 @@
+#!/usr/bin/env bash
+# Copyright (c) 2015-2026 Dotfiles. All rights reserved.
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
+
+include_module_coverage=0
+
+usage() {
+  cat <<'EOF'
+Coverage Baseline
+
+Usage:
+  coverage-baseline.sh [--with-module-coverage]
+
+Options:
+  --with-module-coverage  Run tests/framework/module_coverage.sh and include the result
+  -h, --help              Show this help
+EOF
+}
+
+while [ "$#" -gt 0 ]; do
+  case "$1" in
+    --with-module-coverage)
+      include_module_coverage=1
+      ;;
+    -h | --help)
+      usage
+      exit 0
+      ;;
+    *)
+      printf 'Unknown option: %s\n' "$1" >&2
+      usage >&2
+      exit 1
+      ;;
+  esac
+  shift
+done
+
+unit_tests="$(find "$REPO_ROOT/tests/unit" -name 'test_*.sh' | wc -l | tr -d ' ')"
+integration_tests="$(find "$REPO_ROOT/tests/integration" -name 'test_*.sh' | wc -l | tr -d ' ')"
+total_tests="$(find "$REPO_ROOT/tests" -path '*/framework/*' -prune -o -name 'test_*.sh' -print | wc -l | tr -d ' ')"
+named_tests="$(rg -o '\btest_start\b' "$REPO_ROOT/tests/unit" "$REPO_ROOT/tests/integration" -g 'test_*.sh' | wc -l | tr -d ' ')"
+docs_files="$(find "$REPO_ROOT/docs" -type f \( -name '*.md' -o -name '*.md.tmpl' \) | wc -l | tr -d ' ')"
+shell_surfaces="$(find "$REPO_ROOT/scripts" "$REPO_ROOT/dot_local/bin" "$REPO_ROOT/.chezmoitemplates/functions" -type f \( -name '*.sh' -o -name 'executable_*' \) | wc -l | tr -d ' ')"
+
+printf 'Coverage Baseline\n'
+printf 'Repository: %s\n' "$REPO_ROOT"
+printf 'Documentation files: %s\n' "$docs_files"
+printf 'Executable shell surfaces: %s\n' "$shell_surfaces"
+printf 'Unit test files: %s\n' "$unit_tests"
+printf 'Integration test files: %s\n' "$integration_tests"
+printf 'Total test files: %s\n' "$total_tests"
+printf 'Named tests: %s\n' "$named_tests"
+
+if [ "$include_module_coverage" -eq 1 ]; then
+  printf '\n'
+  (cd "$REPO_ROOT" && bash ./tests/framework/module_coverage.sh)
+fi

package/scripts/qa/docs-coverage.sh

@@ -0,0 +1,111 @@
+#!/usr/bin/env bash
+# Copyright (c) 2015-2026 Dotfiles. All rights reserved.
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
+
+DOT_CLI="$REPO_ROOT/dot_local/bin/executable_dot"
+UTILS_DOC="$REPO_ROOT/docs/reference/UTILS.md"
+AI_DOC="$REPO_ROOT/docs/AI.md"
+SCRIPTS_DOC="$REPO_ROOT/docs/reference/SCRIPTS.md"
+ARCH_DOC="$REPO_ROOT/docs/architecture/ARCHITECTURE.md"
+FUNCTION_GROUPS_JSON="$REPO_ROOT/.chezmoitemplates/functions/groups.json"
+MIN_DOCS_COVERAGE="${MIN_DOCS_COVERAGE:-100}"
+
+TOTAL_CHECKS=0
+COVERED_CHECKS=0
+
+record_doc_check() {
+  local label="$1"
+  local needle="$2"
+  local file="$3"
+
+  TOTAL_CHECKS=$((TOTAL_CHECKS + 1))
+  if grep -Fq "$needle" "$file"; then
+    COVERED_CHECKS=$((COVERED_CHECKS + 1))
+  else
+    printf 'Missing documentation: %s\n' "$label" >&2
+  fi
+}
+
+extract_public_commands() {
+  awk '
+    /_dot_help_specs\(\)/ { in_func=1; next }
+    in_func && /cat <<'\''EOF'\''/ { in_block=1; next }
+    in_block && /^EOF$/ { exit }
+    in_block && /\|/ {
+      split($0, parts, /\|/)
+      print parts[2]
+    }
+  ' "$DOT_CLI"
+}
+
+check_dot_command_docs() {
+  local command=""
+
+  while IFS= read -r command; do
+    [ -n "$command" ] || continue
+    record_doc_check "dot $command in UTILS.md" "\`dot $command" "$UTILS_DOC"
+  done < <(extract_public_commands)
+}
+
+check_ai_provider_docs() {
+  local provider=""
+
+  for provider in cl copilot gemini kiro sgpt ollama opencode aider; do
+    record_doc_check "dot $provider in AI.md" "\`dot $provider\`" "$AI_DOC"
+  done
+}
+
+check_utility_docs() {
+  local utility=""
+
+  for utility in \
+    ai-update ai_core antigravity b64 bm cb dot dot-ai dot-bootstrap dot-launch-or-focus \
+    dot-load-benchmark dot-load-benchmark-pty dot-theme-sync dtags epoch extract gbd gd \
+    git-ai-commit git-ai-diff gl hash hashsum hex jsonv jwt kill-port lorem monitor myip \
+    notify open pw rec-start rec-stop regex start-niri tmux-sessionizer tour up update uuid \
+    win yamlv; do
+    record_doc_check "$utility in SCRIPTS.md" "\`$utility\`" "$SCRIPTS_DOC"
+  done
+}
+
+check_function_group_docs() {
+  local group=""
+
+  for group in $(
+    FUNCTION_GROUPS_JSON="$FUNCTION_GROUPS_JSON" python3 - <<'PY'
+import json
+import os
+from pathlib import Path
+path = Path(os.environ["FUNCTION_GROUPS_JSON"])
+for key in json.loads(path.read_text()).keys():
+    print(key)
+PY
+  ); do
+    record_doc_check "function group $group in ARCHITECTURE.md" "\`$group\`" "$ARCH_DOC"
+  done
+}
+
+report_coverage() {
+  local pct
+  pct="$(awk -v c="$COVERED_CHECKS" -v t="$TOTAL_CHECKS" 'BEGIN{if(t==0){print "0.00"}else{printf "%.2f", (100*c/t)}}')"
+
+  printf 'Docs coverage: %s/%s (%s%%)\n' "$COVERED_CHECKS" "$TOTAL_CHECKS" "$pct"
+  printf 'Threshold: %s%%\n' "$MIN_DOCS_COVERAGE"
+
+  awk -v p="$pct" -v min="$MIN_DOCS_COVERAGE" 'BEGIN{exit !(p+0 >= min+0)}'
+}
+
+main() {
+  check_dot_command_docs
+  check_ai_provider_docs
+  check_utility_docs
+  check_function_group_docs
+  report_coverage
+
+  printf 'PASS: public dot commands, utility entrypoints, AI providers, and function groups are documented at or above the required threshold\n'
+}
+
+main "$@"

package/scripts/qa/powershell-contract.ps1

@@ -0,0 +1,95 @@
+# Copyright (c) 2015-2026 Dotfiles. All rights reserved.
+#
+# PowerShell parity contract — smoke test for the dotfiles PowerShell
+# profile. Run by the windows-latest CI job (#860). Asserts that:
+#
+#   1. The profile parses + loads without throwing.
+#   2. Core function shims (`dot`, `ll`, `la`, `cat`) are defined.
+#   3. PSScriptAnalyzer reports no errors against the profile (warnings
+#      surface but don't fail the gate; tighten later).
+#
+# Exit codes:
+#   0  contract intact.
+#   1  any check failed; details printed to host.
+
+$ErrorActionPreference = 'Stop'
+$Failures = New-Object System.Collections.Generic.List[string]
+
+$RepoRoot = if ($env:GITHUB_WORKSPACE) { $env:GITHUB_WORKSPACE } else { (Get-Location).Path }
+$ProfileSrc = Join-Path $RepoRoot 'dot_config/powershell/Microsoft.PowerShell_profile.ps1.tmpl'
+
+if (-not (Test-Path $ProfileSrc)) {
+    Write-Output "FAIL: profile source not found at $ProfileSrc"
+    exit 1
+}
+
+# Step 1 — chezmoi-render the template into a real .ps1 we can dot-source.
+# In CI, chezmoi is on PATH (installed by setup-chezmoi composite).
+$Rendered = Join-Path $env:TEMP 'Microsoft.PowerShell_profile.ps1'
+if (Get-Command chezmoi -ErrorAction SilentlyContinue) {
+    & chezmoi execute-template --init --promptString version=0.2.501 `
+        --in $ProfileSrc | Set-Content -Path $Rendered -NoNewline
+} else {
+    # Fallback: strip chezmoi template syntax with a simple regex so the
+    # contract still runs locally without chezmoi installed.
+    (Get-Content $ProfileSrc -Raw) -replace '\{\{[^}]+\}\}', '0.0.0-fallback' |
+        Set-Content -Path $Rendered -NoNewline
+}
+
+if (-not (Test-Path $Rendered)) {
+    $Failures.Add("profile template did not render to $Rendered")
+}
+
+# Step 2 — dot-source the rendered profile and verify it didn't throw.
+$loadOk = $false
+try {
+    . $Rendered
+    $loadOk = $true
+    Write-Output "OK: profile dot-sourced"
+} catch {
+    Write-Output "FAIL: profile threw during load: $_"
+    $Failures.Add("profile load: $_")
+}
+
+# Step 3 — verify required function shims are defined.
+$RequiredFunctions = @('dot', 'd', 'll', 'la', 'cat')
+foreach ($fn in $RequiredFunctions) {
+    if (Get-Command $fn -CommandType Function -ErrorAction SilentlyContinue) {
+        Write-Output "OK: function $fn defined"
+    } else {
+        Write-Output "FAIL: function $fn not defined"
+        $Failures.Add("missing function: $fn")
+    }
+}
+
+# Step 4 — PSScriptAnalyzer (static analysis). Pre-installed on the
+# windows-latest GitHub-hosted runner; install on demand if missing.
+if (-not (Get-Module -ListAvailable -Name PSScriptAnalyzer)) {
+    Write-Output "Installing PSScriptAnalyzer..."
+    Install-Module -Name PSScriptAnalyzer -Force -Scope CurrentUser -ErrorAction SilentlyContinue | Out-Null
+}
+
+if (Get-Module -ListAvailable -Name PSScriptAnalyzer) {
+    Import-Module PSScriptAnalyzer -Force
+    $Findings = Invoke-ScriptAnalyzer -Path $Rendered -Severity 'Error' -ErrorAction SilentlyContinue
+    if ($Findings) {
+        foreach ($f in $Findings) {
+            Write-Output "FAIL: PSScriptAnalyzer error: $($f.RuleName) at line $($f.Line): $($f.Message)"
+            $Failures.Add("PSScriptAnalyzer error: $($f.RuleName)")
+        }
+    } else {
+        Write-Output "OK: PSScriptAnalyzer clean (Error severity)"
+    }
+} else {
+    Write-Output "WARN: PSScriptAnalyzer not available — static analysis skipped"
+}
+
+Write-Output ""
+if ($Failures.Count -eq 0) {
+    Write-Output "PowerShell contract: PASS"
+    exit 0
+} else {
+    Write-Output "PowerShell contract: FAIL ($($Failures.Count) issue(s))"
+    foreach ($f in $Failures) { Write-Output "  - $f" }
+    exit 1
+}

package/scripts/qa/reliability-audit.sh

@@ -0,0 +1,138 @@
+#!/usr/bin/env bash
+# Copyright (c) 2015-2026 Dotfiles. All rights reserved.
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
+
+mode="full"
+run_integration=0
+min_coverage="${MIN_COVERAGE:-100}"
+
+platform_name() {
+  case "$(uname -s)" in
+    Darwin) echo "macOS" ;;
+    Linux)
+      if grep -qi microsoft /proc/version 2>/dev/null; then
+        echo "WSL"
+      else
+        echo "Linux"
+      fi
+      ;;
+    *) echo "Unknown" ;;
+  esac
+}
+
+usage() {
+  cat <<'EOF'
+Reliability Audit
+
+Usage:
+  reliability-audit.sh [--quick] [--unit-only] [--with-integration]
+
+Options:
+  --quick             Run syntax, unit, coverage, and examples
+  --unit-only         Run syntax, unit, coverage, and examples
+  --with-integration  Include integration tests
+EOF
+}
+
+run_step() {
+  local label="$1"
+  shift
+  printf '\n[%s] %s\n' "$(date +%H:%M:%S)" "$label"
+  "$@"
+}
+
+shell_syntax() {
+  local failed=0
+  local file
+
+  while IFS= read -r -d '' file; do
+    if ! bash -n "$file"; then
+      failed=$((failed + 1))
+    fi
+  done < <(find "$REPO_ROOT" \
+    \( -path "$REPO_ROOT/.git" -o -path "$REPO_ROOT/.coverage" \) -prune \
+    -o -type f \( -name "*.sh" -o -name "*.bash" \) -print0)
+
+  if [ "$failed" -ne 0 ]; then
+    printf 'Syntax failures: %s\n' "$failed" >&2
+    return 1
+  fi
+}
+
+unit_tests() {
+  cd "$REPO_ROOT"
+  ./tests/framework/test_runner.sh
+}
+
+integration_tests() {
+  cd "$REPO_ROOT"
+  RUN_INTEGRATION=1 ./tests/framework/test_runner.sh -i
+}
+
+coverage_gate() {
+  cd "$REPO_ROOT"
+  MIN_COVERAGE="$min_coverage" ./tests/framework/module_coverage.sh
+}
+
+example_gate() {
+  cd "$REPO_ROOT"
+  bash ./scripts/qa/validate-examples.sh
+}
+
+docs_coverage_gate() {
+  cd "$REPO_ROOT"
+  bash ./scripts/qa/docs-coverage.sh
+}
+
+traceability_gate() {
+  cd "$REPO_ROOT"
+  bash ./scripts/qa/traceability-coverage.sh
+}
+
+while [ "$#" -gt 0 ]; do
+  case "$1" in
+    --quick)
+      mode="quick"
+      ;;
+    --unit-only)
+      mode="unit"
+      ;;
+    --with-integration)
+      run_integration=1
+      ;;
+    -h | --help)
+      usage
+      exit 0
+      ;;
+    *)
+      printf 'Unknown option: %s\n' "$1" >&2
+      usage >&2
+      exit 1
+      ;;
+  esac
+  shift
+done
+
+if [ "$mode" = "full" ]; then
+  run_integration=1
+fi
+
+printf 'Reliability Audit\n'
+printf 'Platform: %s\n' "$(platform_name)"
+printf 'Coverage floor: %s%%\n' "$min_coverage"
+
+run_step "Shell syntax" shell_syntax
+run_step "Unit suite" unit_tests
+run_step "Module coverage" coverage_gate
+run_step "Docs coverage" docs_coverage_gate
+run_step "Traceability coverage" traceability_gate
+run_step "Executable examples" example_gate
+
+if [ "$run_integration" -eq 1 ]; then
+  run_step "Integration suite" integration_tests
+fi
+
+printf '\nReliability audit passed.\n'

package/scripts/qa/traceability-coverage.sh

@@ -0,0 +1,116 @@
+#!/usr/bin/env bash
+# Copyright (c) 2015-2026 Dotfiles. All rights reserved.
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
+TRACE_DOC="$REPO_ROOT/docs/operations/TRACEABILITY.md"
+MIN_TRACEABILITY_COVERAGE="${MIN_TRACEABILITY_COVERAGE:-100}"
+
+TOTAL_TRACE_CHECKS=0
+COVERED_TRACE_CHECKS=0
+
+extract_impl_paths() {
+  awk '
+    /^\| BT-/ {
+      cols = $0
+      sub(/^\|[[:space:]]*/, "", cols)
+      sub(/[[:space:]]*\|[[:space:]]*$/, "", cols)
+      n = split(cols, parts, /\|/)
+      gsub(/^[[:space:]]+|[[:space:]]+$/, "", parts[3])
+      split(parts[3], impls, /,/)
+      for (i in impls) {
+        gsub(/^[[:space:]]+|[[:space:]]+$/, "", impls[i])
+        gsub(/`/, "", impls[i])
+        print impls[i]
+      }
+    }
+  ' "$TRACE_DOC" | sort -u
+}
+
+trim() {
+  sed 's/^[[:space:]]*//; s/[[:space:]]*$//'
+}
+
+record_trace_check() {
+  local label="$1"
+  local target="$2"
+
+  TOTAL_TRACE_CHECKS=$((TOTAL_TRACE_CHECKS + 1))
+  if [ -e "$target" ]; then
+    COVERED_TRACE_CHECKS=$((COVERED_TRACE_CHECKS + 1))
+  else
+    printf 'Missing traceability target: %s (%s)\n' "$label" "$target" >&2
+  fi
+}
+
+check_path_list() {
+  local kind="$1"
+  local value="$2"
+  local behavior_id="$3"
+  local rel=""
+
+  while IFS= read -r rel; do
+    rel="$(printf '%s' "$rel" | trim)"
+    [ -n "$rel" ] || continue
+    rel="${rel#\`}"
+    rel="${rel%\`}"
+    record_trace_check "$behavior_id $kind" "$REPO_ROOT/$rel"
+  done < <(printf '%s\n' "$value" | tr ',' '\n')
+}
+
+report_traceability() {
+  local pct
+  pct="$(awk -v c="$COVERED_TRACE_CHECKS" -v t="$TOTAL_TRACE_CHECKS" 'BEGIN{if(t==0){print "0.00"}else{printf "%.2f", (100*c/t)}}')"
+
+  printf 'Traceability coverage: %s/%s (%s%%)\n' "$COVERED_TRACE_CHECKS" "$TOTAL_TRACE_CHECKS" "$pct"
+  printf 'Threshold: %s%%\n' "$MIN_TRACEABILITY_COVERAGE"
+
+  awk -v p="$pct" -v min="$MIN_TRACEABILITY_COVERAGE" 'BEGIN{exit !(p+0 >= min+0)}'
+}
+
+main() {
+  local line=""
+  local cols=""
+  local behavior_id=""
+  local impls=""
+  local tests=""
+  local docs=""
+
+  while IFS= read -r line; do
+    case "$line" in
+      \|\ BT-*)
+        cols="$(printf '%s\n' "$line" | sed 's/^|//; s/|$//')"
+        behavior_id="$(printf '%s\n' "$cols" | cut -d'|' -f1 | trim)"
+        impls="$(printf '%s\n' "$cols" | cut -d'|' -f3 | trim)"
+        tests="$(printf '%s\n' "$cols" | cut -d'|' -f4 | trim)"
+        docs="$(printf '%s\n' "$cols" | cut -d'|' -f5 | trim)"
+
+        check_path_list "implementation" "$impls" "$behavior_id"
+        check_path_list "test" "$tests" "$behavior_id"
+        check_path_list "doc" "$docs" "$behavior_id"
+        ;;
+    esac
+  done <"$TRACE_DOC"
+
+  while IFS= read -r required; do
+    [ -n "$required" ] || continue
+    TOTAL_TRACE_CHECKS=$((TOTAL_TRACE_CHECKS + 1))
+    if extract_impl_paths | grep -Fxq "$required"; then
+      COVERED_TRACE_CHECKS=$((COVERED_TRACE_CHECKS + 1))
+    else
+      printf 'Missing traceability row for implementation: %s\n' "$required" >&2
+    fi
+  done < <(
+    {
+      find "$REPO_ROOT/scripts/dot/commands" -maxdepth 1 -type f -name '*.sh' | sed "s#^$REPO_ROOT/##"
+      find "$REPO_ROOT/scripts/qa" -maxdepth 1 -type f -name '*.sh' | sed "s#^$REPO_ROOT/##"
+    } | sort -u
+  )
+
+  report_traceability
+
+  printf 'PASS: core internal behaviors have implementation, test, and documentation traceability at or above the required threshold\n'
+}
+
+main "$@"