@sebastienrousseau/dotfiles 0.2.518 → 0.2.520

package/scripts/fonts/install-nerd-fonts.sh

@@ -1,5 +1,5 @@
 #!/usr/bin/env bash
-# SPDX-License-Identifier: MIT
+# SPDX-License-Identifier: Apache-2.0 OR MIT
 # Copyright (c) 2015-2026 Sebastien Rousseau
 set -euo pipefail
 

package/scripts/fonts/patch-fonts.sh

@@ -1,5 +1,5 @@
 #!/usr/bin/env bash
-# SPDX-License-Identifier: MIT
+# SPDX-License-Identifier: Apache-2.0 OR MIT
 # Copyright (c) 2015-2026 Sebastien Rousseau
 set -euo pipefail
 

package/scripts/git-hooks/install.sh

@@ -1,5 +1,5 @@
 #!/usr/bin/env bash
-# SPDX-License-Identifier: MIT
+# SPDX-License-Identifier: Apache-2.0 OR MIT
 # Copyright (c) 2015-2026 Sebastien Rousseau
 set -euo pipefail
 

package/scripts/git-hooks/pre-commit-audit.sh

@@ -1,5 +1,5 @@
 #!/usr/bin/env bash
-# SPDX-License-Identifier: MIT
+# SPDX-License-Identifier: Apache-2.0 OR MIT
 # Copyright (c) 2015-2026 Sebastien Rousseau
 # Dotfiles Pre-Commit Sentinel (Audit Hook)
 # Prevents secrets, hardcoded paths, and shell hygiene violations.
@@ -141,6 +141,6 @@ if [[ $FAILED -eq 1 ]]; then
   printf '%b\\n' "   (Use --no-verify to bypass if absolutely necessary)"
   exit 1
 else
-  printf '%b\n' "${GREEN}${BOLD}✅ Audit passed.${NC} v0.2.518 standards maintained."
+  printf '%b\n' "${GREEN}${BOLD}✅ Audit passed.${NC} v0.2.520 standards maintained."
   exit 0
 fi

package/scripts/lib/secrets_provider.sh

@@ -1,5 +1,5 @@
 #!/usr/bin/env bash
-# SPDX-License-Identifier: MIT
+# SPDX-License-Identifier: Apache-2.0 OR MIT
 # Copyright (c) 2015-2026 Sebastien Rousseau
 # Provider-agnostic secrets bridge for dotfiles.
 
@@ -96,9 +96,24 @@ dot_secrets_store_plain_enc() {
   dot_secrets_ensure_layout
   tmp_rec="$(umask 077 && mktemp)"
   file="$DOT_SECRETS_STORE_DIR/${key}.age"
-  trap 'rm -f "$tmp_rec"' RETURN
-  age-keygen -y "$DOT_SECRETS_AGE_KEY" >"$tmp_rec"
-  printf "%s" "$value" | age -R "$tmp_rec" -o "$file"
+
+  # No RETURN trap here. A RETURN trap set inside a function also fires when
+  # its CALLER returns, and by then `tmp_rec` — local to this function — is
+  # out of scope: under `set -u` the trap aborted dot_secrets_set with
+  # "tmp_rec: unbound variable" AFTER the encrypted file had been written, so
+  # `dot secrets set` reported failure on a write that had succeeded. Clean up
+  # explicitly on both paths instead.
+  if ! age-keygen -y "$DOT_SECRETS_AGE_KEY" >"$tmp_rec"; then
+    rm -f "$tmp_rec"
+    echo "failed to derive the age recipient from $DOT_SECRETS_AGE_KEY" >&2
+    return 1
+  fi
+  if ! printf "%s" "$value" | age -R "$tmp_rec" -o "$file"; then
+    rm -f "$tmp_rec"
+    echo "failed to encrypt secret: $key" >&2
+    return 1
+  fi
+  rm -f "$tmp_rec"
   chmod 600 "$file" 2>/dev/null || true
 }
 

package/scripts/nvim/headless-upgrade.lua

@@ -0,0 +1,81 @@
+-- Copyright (c) 2015-2026 Dotfiles. All rights reserved.
+-- headless-upgrade.lua — plugin/tool refresh for `dot upgrade`.
+--
+-- Runs Lazy sync and then waits for Mason's async install queue to drain
+-- before exiting.  The naive invocation
+--     nvim --headless "+Lazy! sync" +qa
+-- races on two fronts:
+--   1. Lazy's own async ops (git fetch/checkout, `build` hooks) can outlive
+--      the `Lazy! sync` command return.
+--   2. `mason-nvim-dap` and `mason-lspconfig` fire `ensure_installed` on
+--      plugin load; those installs are enqueued to mason.nvim and run
+--      async, so `+qa` aborts them mid-download (leaving codelldb / debugpy
+--      / delve half-installed, per repeated user reports on `dot upgrade`).
+--
+-- We explicitly wait for both queues before quitting.
+
+local LAZY_TIMEOUT_MS  = 300000  -- 5 min per phase
+local MASON_TIMEOUT_MS = 300000
+
+local function log(msg)
+  io.stderr:write(("[headless-upgrade] %s\n"):format(msg))
+end
+
+-- ---------------------------------------------------------------------------
+-- Phase 1: Lazy sync (blocking)
+-- ---------------------------------------------------------------------------
+local ok_lazy, lazy = pcall(require, "lazy")
+if not ok_lazy then
+  log("lazy.nvim not available; skipping plugin update")
+  vim.cmd("quitall!")
+  return
+end
+
+lazy.sync({ wait = true, show = false })
+
+-- Belt-and-braces: give any residual runner tasks a chance to drain even if
+-- `wait = true` returned early on the last task in a batch.
+pcall(function()
+  local ok_runner, runner = pcall(require, "lazy.manage.runner")
+  if not ok_runner then return end
+  vim.wait(LAZY_TIMEOUT_MS, function()
+    return not (runner.running and runner.running())
+  end, 200)
+end)
+
+-- ---------------------------------------------------------------------------
+-- Phase 2: drain Mason's async install queue
+-- ---------------------------------------------------------------------------
+pcall(function()
+  local ok_reg, registry = pcall(require, "mason-registry")
+  if not ok_reg then return end
+
+  -- Refresh the remote registry so ensure_installed picks up latest versions.
+  local refreshed = false
+  registry.refresh(function() refreshed = true end)
+  vim.wait(30000, function() return refreshed end, 200)
+
+  local function any_installing()
+    for _, pkg in ipairs(registry.get_all_packages() or {}) do
+      if pkg.is_installing and pkg:is_installing() then
+        return true
+      end
+    end
+    return false
+  end
+
+  -- Small settle time so installs triggered by ensure_installed hooks have
+  -- a chance to enter the installing state before we start polling.
+  vim.wait(2000, function() return false end, 200)
+
+  local done = vim.wait(MASON_TIMEOUT_MS, function()
+    return not any_installing()
+  end, 500)
+
+  if not done then
+    log(("Mason install queue still active after %ds; exiting anyway"):format(
+      MASON_TIMEOUT_MS / 1000))
+  end
+end)
+
+vim.cmd("quitall!")

package/scripts/ops/ai-setup.sh

@@ -1,5 +1,5 @@
 #!/usr/bin/env bash
-# SPDX-License-Identifier: MIT
+# SPDX-License-Identifier: Apache-2.0 OR MIT
 # Copyright (c) 2015-2026 Sebastien Rousseau
 # Universal AI Toolchain Setup & Authentication.
 

package/scripts/ops/bundle.sh

@@ -1,5 +1,5 @@
 #!/usr/bin/env bash
-# SPDX-License-Identifier: MIT
+# SPDX-License-Identifier: Apache-2.0 OR MIT
 # Copyright (c) 2015-2026 Sebastien Rousseau
 # Create an offline bundle of the dotfiles environment for air-gapped systems.
 

package/scripts/ops/chaos.sh

@@ -1,5 +1,5 @@
 #!/usr/bin/env bash
-# SPDX-License-Identifier: MIT
+# SPDX-License-Identifier: Apache-2.0 OR MIT
 # Copyright (c) 2015-2026 Sebastien Rousseau
 # Chaos Engineering: Randomly corrupt config files to test self-healing (dot heal)
 # USE WITH CAUTION: This intentionally breaks your environment.

package/scripts/ops/chezmoi-apply.sh

@@ -1,5 +1,5 @@
 #!/usr/bin/env bash
-# SPDX-License-Identifier: MIT
+# SPDX-License-Identifier: Apache-2.0 OR MIT
 # Copyright (c) 2015-2026 Sebastien Rousseau
 set -euo pipefail
 

package/scripts/ops/chezmoi-diff.sh

@@ -1,5 +1,5 @@
 #!/usr/bin/env bash
-# SPDX-License-Identifier: MIT
+# SPDX-License-Identifier: Apache-2.0 OR MIT
 # Copyright (c) 2015-2026 Sebastien Rousseau
 set -euo pipefail
 

package/scripts/ops/chezmoi-remove.sh

@@ -1,5 +1,5 @@
 #!/usr/bin/env bash
-# SPDX-License-Identifier: MIT
+# SPDX-License-Identifier: Apache-2.0 OR MIT
 # Copyright (c) 2015-2026 Sebastien Rousseau
 set -euo pipefail
 
@@ -36,11 +36,11 @@ if [[ $remove_source -eq 0 ]]; then
   args+=("--keep-source")
 fi
 
-printf "About to run: chezmoi remove %s %s\n" "${args[*]}" "${paths[*]}"
+printf "About to run: chezmoi remove %s %s\n" "${args[*]:-}" "${paths[*]}"
 read -r -p "Proceed? [y/N] " confirm
 if [[ "$confirm" != "y" && "$confirm" != "Y" ]]; then
   echo "Aborted."
   exit 1
 fi
 
-chezmoi remove "${args[@]}" "${paths[@]}"
+chezmoi remove ${args[@]+"${args[@]}"} "${paths[@]}"

package/scripts/ops/chezmoi-update.sh

@@ -1,5 +1,5 @@
 #!/usr/bin/env bash
-# SPDX-License-Identifier: MIT
+# SPDX-License-Identifier: Apache-2.0 OR MIT
 # Copyright (c) 2015-2026 Sebastien Rousseau
 set -euo pipefail
 
@@ -45,7 +45,11 @@ NOTICE_FILE="$STATE_DIR/notice"
 
 run_update() {
   echo "Updating dotfiles..."
-  chezmoi update "${args[@]}"
+  # `${args[@]+...}`: with DOTFILES_INTERACTIVE_APPLY=1 no flags are added,
+  # and bash 3.2 (the system bash on macOS) treats an unguarded empty array
+  # expansion under `set -u` as an unbound variable — `dot update` then died
+  # instead of running chezmoi.
+  chezmoi update ${args[@]+"${args[@]}"}
 }
 
 if $ASYNC; then

package/scripts/ops/heal-chezmoi.sh

@@ -1,5 +1,5 @@
 #!/usr/bin/env bash
-# SPDX-License-Identifier: MIT
+# SPDX-License-Identifier: Apache-2.0 OR MIT
 # Copyright (c) 2015-2026 Sebastien Rousseau
 # shellcheck disable=SC2034
 # =============================================================================

package/scripts/ops/heal-system.sh

@@ -1,5 +1,5 @@
 #!/usr/bin/env bash
-# SPDX-License-Identifier: MIT
+# SPDX-License-Identifier: Apache-2.0 OR MIT
 # Copyright (c) 2015-2026 Sebastien Rousseau
 # shellcheck disable=SC2034
 # =============================================================================

package/scripts/ops/heal-tools.sh

@@ -1,5 +1,5 @@
 #!/usr/bin/env bash
-# SPDX-License-Identifier: MIT
+# SPDX-License-Identifier: Apache-2.0 OR MIT
 # Copyright (c) 2015-2026 Sebastien Rousseau
 # shellcheck disable=SC2034
 # =============================================================================

package/scripts/ops/heal.sh

@@ -1,5 +1,5 @@
 #!/usr/bin/env bash
-# SPDX-License-Identifier: MIT
+# SPDX-License-Identifier: Apache-2.0 OR MIT
 # Copyright (c) 2015-2026 Sebastien Rousseau
 # shellcheck disable=SC2034
 # =============================================================================

package/scripts/ops/post-apply-repair.sh

@@ -1,5 +1,5 @@
 #!/usr/bin/env bash
-# SPDX-License-Identifier: MIT
+# SPDX-License-Identifier: Apache-2.0 OR MIT
 # Copyright (c) 2015-2026 Sebastien Rousseau
 set -euo pipefail
 

package/scripts/ops/prewarm.sh

@@ -1,5 +1,5 @@
 #!/usr/bin/env bash
-# SPDX-License-Identifier: MIT
+# SPDX-License-Identifier: Apache-2.0 OR MIT
 # Copyright (c) 2015-2026 Sebastien Rousseau
 # Pre-warm shell initialization caches for ultra-fast startup.
 

package/scripts/ops/release.sh

@@ -1,5 +1,5 @@
 #!/usr/bin/env bash
-# SPDX-License-Identifier: MIT
+# SPDX-License-Identifier: Apache-2.0 OR MIT
 # Copyright (c) 2015-2026 Sebastien Rousseau
 # =============================================================================
 # Dotfiles Release Script

package/scripts/ops/rollback.sh

@@ -1,5 +1,5 @@
 #!/usr/bin/env bash
-# SPDX-License-Identifier: MIT
+# SPDX-License-Identifier: Apache-2.0 OR MIT
 # Copyright (c) 2015-2026 Sebastien Rousseau
 # shellcheck disable=SC2034
 # =============================================================================
@@ -35,6 +35,11 @@ BACKUP_DIR="${XDG_DATA_HOME:-$HOME/.local/share}/dotfiles/backups"
 STATE_DIR="${XDG_STATE_HOME:-$HOME/.local/state}/dotfiles"
 ROLLBACK_LOG="$STATE_DIR/rollback.log"
 MAX_BACKUPS=10
+# sysexits.h EX_TEMPFAIL: the command did nothing because another instance
+# holds the lock. Distinct from 1 (the rollback ran and failed) and from 0
+# (the rollback ran and succeeded) — a caller has to be able to tell those
+# three apart.
+EXIT_BUSY=75
 
 # Logging — delegates to shared ui.sh primitives
 ui_init
@@ -525,8 +530,12 @@ main() {
   if command -v flock >/dev/null 2>&1; then
     exec 9>"$LOCK_FILE"
     if ! flock -n 9; then
+      # Losing the lock means this invocation did nothing. Exiting 0 made
+      # "did nothing" indistinguishable from "rolled back" to any caller or
+      # CI step, which is the one thing a recovery tool must never be
+      # ambiguous about. 75 is EX_TEMPFAIL: nothing is wrong, try again.
       ui_warn "Already running" "Another rollback instance is active"
-      exit 0
+      exit "$EXIT_BUSY"
     fi
   fi
 

package/scripts/ops/setup.sh

@@ -1,5 +1,5 @@
 #!/usr/bin/env bash
-# SPDX-License-Identifier: MIT
+# SPDX-License-Identifier: Apache-2.0 OR MIT
 # Copyright (c) 2015-2026 Sebastien Rousseau
 # Interactive setup for dotfiles preferences
 # Usage: dot setup

package/scripts/ops/teleport.sh

@@ -1,5 +1,5 @@
 #!/usr/bin/env bash
-# SPDX-License-Identifier: MIT
+# SPDX-License-Identifier: Apache-2.0 OR MIT
 # Copyright (c) 2015-2026 Sebastien Rousseau
 # Script: teleport.sh
 # Description: Deploys dotfiles to a remote host ephemerally.

package/scripts/qa/check-feature-matrix.sh

@@ -0,0 +1,296 @@
+#!/usr/bin/env bash
+# SPDX-License-Identifier: Apache-2.0 OR MIT
+# Copyright (c) 2015-2026 Sebastien Rousseau
+#
+# check-feature-matrix.sh — drift gate for docs/reference/FEATURE-MATRIX.md.
+#
+# The matrix is a contract: every user-facing feature of the `dot` CLI has a
+# row naming the regression test, benchmark, example and manual section that
+# cover it. A contract nobody checks rots, so this script checks it, and
+# ci.yml runs it on every push.
+#
+# Four checks:
+#
+#   1. Command coverage — every command the dispatcher can route (bin/dot's
+#      route table, which is what `scripts/dot/commands/*.sh` are reached
+#      through) and every command in the generated docs/manual/command-index.md
+#      has at least one row.
+#   2. Test coverage — every regression test function named in a row is
+#      defined by one of tests/regression/test_feature_matrix_*.sh.
+#   3. Benchmark coverage — every benchmark id named in a row is produced by
+#      `benches/dot_command_bench.sh --list-ids`.
+#   4. Example coverage — every example file named in a row exists and is
+#      executable by scripts/qa/validate-examples.sh.
+#
+# Usage:
+#   scripts/qa/check-feature-matrix.sh [--quiet]
+#
+# Exit codes:
+#   0  the matrix is in sync
+#   1  drift detected (details on stderr)
+#   2  bad invocation, or a file the gate depends on is missing
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="${REPO_ROOT:-$(cd "$SCRIPT_DIR/../.." && pwd)}"
+cd "$REPO_ROOT"
+
+MATRIX="docs/reference/FEATURE-MATRIX.md"
+DOT_BIN="bin/dot"
+COMMAND_INDEX="docs/manual/command-index.md"
+BENCH="benches/dot_command_bench.sh"
+TEST_GLOB="tests/regression/test_feature_matrix_*.sh"
+
+QUIET=0
+case "${1:-}" in
+  --quiet | -q) QUIET=1 ;;
+  -h | --help)
+    sed -n '5,30p' "${BASH_SOURCE[0]}" | sed 's/^# \{0,1\}//'
+    exit 0
+    ;;
+  "") ;;
+  *)
+    printf 'Unknown option: %s\n' "$1" >&2
+    exit 2
+    ;;
+esac
+
+say() { [[ "$QUIET" -eq 1 ]] || printf '%s\n' "$*"; }
+
+for required in "$MATRIX" "$DOT_BIN" "$COMMAND_INDEX" "$BENCH"; do
+  if [[ ! -f "$required" ]]; then
+    printf '::error::required file missing: %s\n' "$required" >&2
+    exit 2
+  fi
+done
+
+failures=0
+fail() {
+  printf '::error::%s\n' "$1" >&2
+  failures=$((failures + 1))
+}
+
+work="$(mktemp -d)"
+trap 'rm -rf "$work"' EXIT
+
+# ---------------------------------------------------------------------------
+# Parse the matrix.
+#
+# Rows look like:
+#   | `dot fleet apply` | --dry-run | `test_fm_x` | `run:y` | `examples/z.sh` | `docs/…` | regression |
+#
+# Field 1 is the command (backticked, "dot " prefix), 3 the test function,
+# 4 the benchmark id, 5 the example path. The two explanatory tables at the
+# top of the document have different shapes and are skipped by requiring a
+# leading "| `dot ".
+# ---------------------------------------------------------------------------
+
+awk '
+  # A cell may legitimately contain an escaped pipe (a variant like
+  # "set advisory\|strict"). Neutralise those BEFORE splitting on "|", or the
+  # row shifts a column and every later check reads the wrong cell.
+  /^\| `dot / {
+    line = $0
+    gsub(/\\\|/, "\002", line)
+    n = split(line, cell, "|")
+    # 7 content columns become 9 fields: the empty strings either side of the
+    # leading and trailing pipes. The document also carries a 3-column summary
+    # table of the unmeasurable rows, which must not be parsed as feature rows.
+    if (n < 9) next
+    for (i = 1; i <= n; i++) {
+      gsub(/^[ \t]+|[ \t]+$/, "", cell[i])
+      gsub(/`/, "", cell[i])
+      gsub(/\002/, "|", cell[i])
+    }
+    # cell[2] command, cell[4] test, cell[5] bench, cell[6] example, cell[8] coverage
+    print cell[2] "\t" cell[4] "\t" cell[5] "\t" cell[6] "\t" cell[8]
+  }
+' "$MATRIX" >"$work/rows.tsv"
+
+row_count="$(wc -l <"$work/rows.tsv" | tr -d ' ')"
+if [[ "$row_count" -lt 50 ]]; then
+  fail "only $row_count rows parsed from $MATRIX — has the table format changed?"
+  exit 1
+fi
+
+# The command cell is "dot <command>"; a row may name a subcommand
+# ("dot fleet apply"), so the routable command is the first word after "dot".
+cut -f1 "$work/rows.tsv" | sed 's/^dot  *//' | awk '{print $1}' |
+  sort -u >"$work/matrix-commands.txt"
+cut -f2 "$work/rows.tsv" | sort -u | grep -v '^$' >"$work/matrix-tests.txt"
+cut -f3 "$work/rows.tsv" | sort -u | grep -v '^$' >"$work/matrix-benches.txt"
+cut -f4 "$work/rows.tsv" | sort -u | grep -v '^$' >"$work/matrix-examples.txt"
+
+say "Feature matrix: $row_count rows, $(wc -l <"$work/matrix-commands.txt" | tr -d ' ') distinct commands"
+
+# ---------------------------------------------------------------------------
+# 1. Command coverage
+# ---------------------------------------------------------------------------
+
+# bin/dot's route table is the authority on what the dispatcher can reach.
+# Flag aliases (--help/-h/--version/-v) are not commands and are excluded.
+awk '/^_dot_command_routes\(\)/,/^EOF$/' "$DOT_BIN" |
+  awk -F'|' '/^[a-z][a-z0-9-]*\|[a-z]+$/ { print $1 }' |
+  sort -u >"$work/routed.txt"
+
+# The generated command index is the documented surface.
+grep -oE '^\| `dot [a-z][a-z0-9-]*' "$COMMAND_INDEX" |
+  sed 's/^| `dot //' | sort -u >"$work/indexed.txt"
+
+missing_routed="$(comm -23 "$work/routed.txt" "$work/matrix-commands.txt")"
+if [[ -n "$missing_routed" ]]; then
+  while IFS= read -r cmd; do
+    [[ -n "$cmd" ]] || continue
+    fail "routable command has no FEATURE-MATRIX row: dot $cmd"
+  done <<<"$missing_routed"
+else
+  say "  ✓ every routable command has a row ($(wc -l <"$work/routed.txt" | tr -d ' ') commands)"
+fi
+
+missing_indexed="$(comm -23 "$work/indexed.txt" "$work/matrix-commands.txt")"
+if [[ -n "$missing_indexed" ]]; then
+  while IFS= read -r cmd; do
+    [[ -n "$cmd" ]] || continue
+    fail "command documented in $COMMAND_INDEX has no FEATURE-MATRIX row: dot $cmd"
+  done <<<"$missing_indexed"
+else
+  say "  ✓ every documented command has a row ($(wc -l <"$work/indexed.txt" | tr -d ' ') commands)"
+fi
+
+# A row naming a command the dispatcher cannot route is a phantom: the
+# feature was removed but its coverage claim was not.
+phantom="$(comm -13 <(sort -u "$work/routed.txt" "$work/indexed.txt") \
+  "$work/matrix-commands.txt")"
+if [[ -n "$phantom" ]]; then
+  while IFS= read -r cmd; do
+    [[ -n "$cmd" ]] || continue
+    fail "FEATURE-MATRIX row names a command that is neither routable nor documented: dot $cmd"
+  done <<<"$phantom"
+else
+  say "  ✓ no phantom command rows"
+fi
+
+# ---------------------------------------------------------------------------
+# 2. Test coverage
+# ---------------------------------------------------------------------------
+
+# `|| true`: this runs at top level under `set -euo pipefail`, so without it an
+# unmatched glob (or a grep that simply finds nothing) aborts the whole script
+# with grep's status before the emptiness check below can run — exit 2 and not
+# a word about why, instead of the diagnostic that check exists to print.
+# shellcheck disable=SC2086
+grep -ho '^test_fm_[a-z0-9_]*()' $TEST_GLOB 2>/dev/null |
+  sed 's/()//' | sort -u >"$work/defined-tests.txt" || true
+
+if [[ ! -s "$work/defined-tests.txt" ]]; then
+  fail "no test functions found in $TEST_GLOB"
+else
+  undefined="$(comm -23 "$work/matrix-tests.txt" "$work/defined-tests.txt")"
+  if [[ -n "$undefined" ]]; then
+    while IFS= read -r fn; do
+      [[ -n "$fn" ]] || continue
+      fail "FEATURE-MATRIX names a test function that does not exist: $fn"
+    done <<<"$undefined"
+  else
+    say "  ✓ every named test function exists ($(wc -l <"$work/matrix-tests.txt" | tr -d ' ') referenced, $(wc -l <"$work/defined-tests.txt" | tr -d ' ') defined)"
+  fi
+
+  # A defined-but-unreferenced test is not an error — it may be a helper or a
+  # cross-cutting invariant — but it is worth surfacing so coverage does not
+  # quietly drift out of the table.
+  orphan_count="$(comm -13 "$work/matrix-tests.txt" "$work/defined-tests.txt" | grep -c . || true)"
+  if [[ "$orphan_count" -gt 0 ]]; then
+    say "  · $orphan_count test function(s) defined but not referenced by any row"
+  fi
+fi
+
+# Every function the matrix names must also actually be CALLED by its file;
+# a defined-but-never-invoked test passes vacuously.
+uncalled=0
+while IFS= read -r fn; do
+  [[ -n "$fn" ]] || continue
+  # shellcheck disable=SC2086
+  if ! grep -hqE "^[[:space:]]*${fn}([[:space:]]|$)" $TEST_GLOB 2>/dev/null; then
+    fail "test function is defined but never called: $fn"
+    uncalled=$((uncalled + 1))
+  fi
+done <"$work/matrix-tests.txt"
+[[ "$uncalled" -eq 0 ]] && say "  ✓ every named test function is invoked by its file"
+
+# ---------------------------------------------------------------------------
+# 3. Benchmark coverage
+# ---------------------------------------------------------------------------
+
+if bash "$BENCH" --list-ids >"$work/bench-ids.txt" 2>/dev/null &&
+  [[ -s "$work/bench-ids.txt" ]]; then
+  sort -u -o "$work/bench-ids.txt" "$work/bench-ids.txt"
+  unknown_bench="$(comm -23 "$work/matrix-benches.txt" "$work/bench-ids.txt")"
+  if [[ -n "$unknown_bench" ]]; then
+    while IFS= read -r id; do
+      [[ -n "$id" ]] || continue
+      fail "FEATURE-MATRIX names a benchmark id the harness does not produce: $id"
+    done <<<"$unknown_bench"
+  else
+    say "  ✓ every named benchmark id exists ($(wc -l <"$work/matrix-benches.txt" | tr -d ' ') referenced, $(wc -l <"$work/bench-ids.txt" | tr -d ' ') available)"
+  fi
+
+  # Cold-start coverage must be total: one help benchmark per routable command.
+  missing_bench=0
+  while IFS= read -r cmd; do
+    [[ -n "$cmd" ]] || continue
+    if ! grep -qx "help:$cmd" "$work/bench-ids.txt"; then
+      fail "no cold-start benchmark for routable command: dot $cmd"
+      missing_bench=$((missing_bench + 1))
+    fi
+  done <"$work/routed.txt"
+  [[ "$missing_bench" -eq 0 ]] &&
+    say "  ✓ every routable command has a cold-start benchmark"
+else
+  fail "could not list benchmark ids: $BENCH --list-ids"
+fi
+
+# ---------------------------------------------------------------------------
+# 4. Example coverage
+# ---------------------------------------------------------------------------
+
+missing_example=0
+while IFS= read -r path; do
+  [[ -n "$path" ]] || continue
+  if [[ ! -f "$path" ]]; then
+    fail "FEATURE-MATRIX names an example that does not exist: $path"
+    missing_example=$((missing_example + 1))
+  elif [[ "$path" != examples/*.sh ]]; then
+    fail "example is outside the directory validate-examples.sh runs: $path"
+    missing_example=$((missing_example + 1))
+  fi
+done <"$work/matrix-examples.txt"
+[[ "$missing_example" -eq 0 ]] &&
+  say "  ✓ every named example exists ($(wc -l <"$work/matrix-examples.txt" | tr -d ' ') referenced)"
+
+# Every command module should be demonstrated by at least one example.
+missing_group=0
+for module in scripts/dot/commands/*.sh; do
+  [[ -f "$module" ]] || continue
+  name="$(basename "$module" .sh)"
+  if ! grep -rqlE "scripts/dot/commands/${name}\.sh" examples/ 2>/dev/null; then
+    fail "no example references the command module: $module"
+    missing_group=$((missing_group + 1))
+  fi
+done
+[[ "$missing_group" -eq 0 ]] &&
+  say "  ✓ every command module is referenced by an example"
+
+# ---------------------------------------------------------------------------
+# Verdict
+# ---------------------------------------------------------------------------
+
+if [[ "$failures" -ne 0 ]]; then
+  printf '\nFEATURE-MATRIX drift: %s problem(s).\n' "$failures" >&2
+  printf 'Add or correct the row(s) in %s, then re-run this check.\n' "$MATRIX" >&2
+  exit 1
+fi
+
+say ""
+say "FEATURE-MATRIX is in sync."
+exit 0