@event4u/agent-config 2.23.0 → 2.25.0

package/scripts/ai-video/lib/load-config.sh

@@ -0,0 +1,140 @@
+#!/usr/bin/env bash
+# scripts/ai-video/lib/load-config.sh — provider config loader for /video:*.
+#
+# Parses agents/.ai-video.xml with xmllint --xpath and surfaces a single
+# provider's settings as AIV_KEY / AIV_ENDPOINT / AIV_MODEL / AIV_DRYRUN
+# env vars to its caller. The key is NEVER echoed — status output is only
+# `present` or `missing`.
+#
+# Usage (sourced):
+#
+#   . scripts/ai-video/lib/load-config.sh
+#   aiv_load_provider gemini-veo
+#   echo "key: $(aiv_key_status)"     # → present | missing
+#   echo "endpoint: $AIV_ENDPOINT"
+#   echo "dryrun: $AIV_DRYRUN"
+#
+# Usage (CLI status check, no key echoed):
+#
+#   bash scripts/ai-video/lib/load-config.sh status gemini-veo
+#   → provider=gemini-veo key=present dryrun=true model=veo-3.0-generate-001
+#
+# Defaults:
+#   - AIV_DRYRUN defaults to `true` when not set in XML
+#   - AIV_DRYRUN can be overridden by the AIV_DRYRUN env var set by caller
+#   - missing file is non-fatal in `status` mode (prints all-missing line)
+
+set -u
+
+AIV_CONFIG_PATH="${AIV_CONFIG_PATH:-agents/.ai-video.xml}"
+
+_aiv_xpath() {
+  # $1 = xpath expression; reads from $AIV_CONFIG_PATH
+  # Returns text content or empty string. Never errors on missing path.
+  if [ ! -f "${AIV_CONFIG_PATH}" ]; then
+    printf ''
+    return 0
+  fi
+  if ! command -v xmllint >/dev/null 2>&1; then
+    printf ''
+    return 0
+  fi
+  xmllint --xpath "string(${1})" "${AIV_CONFIG_PATH}" 2>/dev/null || printf ''
+}
+
+aiv_default_image_provider() {
+  _aiv_xpath '/ai-video/default-image-provider'
+}
+
+aiv_default_video_provider() {
+  _aiv_xpath '/ai-video/default-video-provider'
+}
+
+aiv_load_provider() {
+  local pid="${1:-}"
+  if [ -z "${pid}" ]; then
+    echo "aiv_load_provider: provider id required" >&2
+    return 2
+  fi
+
+  # Resolve from the top-level <provider> blocks OR the <extra> slot.
+  local base="(/ai-video/provider[@id='${pid}']|/ai-video/extra/provider[@id='${pid}'])"
+
+  AIV_PROVIDER_ID="${pid}"
+  AIV_KEY="$(_aiv_xpath "${base}/api-key")"
+  AIV_ENDPOINT="$(_aiv_xpath "${base}/endpoint")"
+  AIV_MODEL="$(_aiv_xpath "${base}/default-model")"
+  AIV_KIND="$(_aiv_xpath "${base}/@kind")"
+
+  local dryrun_xml
+  dryrun_xml="$(_aiv_xpath "${base}/dry-run")"
+  # Caller-set AIV_DRYRUN takes precedence; otherwise XML; otherwise true.
+  if [ -n "${AIV_DRYRUN:-}" ]; then
+    : # respect caller
+  elif [ -n "${dryrun_xml}" ]; then
+    AIV_DRYRUN="${dryrun_xml}"
+  else
+    AIV_DRYRUN="true"
+  fi
+  export AIV_DRYRUN
+
+  # Tuning fields — adapters read these directly when present.
+  AIV_TUNING_ASPECT="$(_aiv_xpath "${base}/tuning/aspect")"
+  AIV_TUNING_FPS="$(_aiv_xpath "${base}/tuning/fps")"
+  AIV_TUNING_MAX_DURATION="$(_aiv_xpath "${base}/tuning/max-duration")"
+  AIV_TUNING_AUDIO_NATIVE="$(_aiv_xpath "${base}/tuning/audio-native")"
+  AIV_TUNING_PRESET="$(_aiv_xpath "${base}/tuning/preset")"
+  AIV_TUNING_QUALITY="$(_aiv_xpath "${base}/tuning/quality")"
+  AIV_TUNING_BEST_OF_N="$(_aiv_xpath "${base}/tuning/best-of-n")"
+  export AIV_TUNING_ASPECT AIV_TUNING_FPS AIV_TUNING_MAX_DURATION \
+    AIV_TUNING_AUDIO_NATIVE AIV_TUNING_PRESET AIV_TUNING_QUALITY \
+    AIV_TUNING_BEST_OF_N
+
+  # Register key with redact.sh if loaded — adapters always source both.
+  if command -v aiv_redact_register >/dev/null 2>&1; then
+    aiv_redact_register "${AIV_KEY}"
+  fi
+
+  return 0
+}
+
+aiv_key_status() {
+  case "${AIV_KEY:-}" in
+    ""|"REPLACE-ME"|*"-REPLACE-ME") printf 'missing' ;;
+    *) printf 'present' ;;
+  esac
+}
+
+# CLI mode — only `status <provider-id>` is supported; never echoes the key.
+if [ "${BASH_SOURCE[0]:-}" = "${0}" ]; then
+  cmd="${1:-}"
+  case "${cmd}" in
+    status)
+      pid="${2:-}"
+      if [ -z "${pid}" ]; then
+        echo "usage: load-config.sh status <provider-id>" >&2
+        exit 2
+      fi
+      aiv_load_provider "${pid}" >/dev/null
+      printf 'provider=%s key=%s dryrun=%s model=%s endpoint=%s kind=%s\n' \
+        "${AIV_PROVIDER_ID}" \
+        "$(aiv_key_status)" \
+        "${AIV_DRYRUN:-true}" \
+        "${AIV_MODEL:-}" \
+        "${AIV_ENDPOINT:-}" \
+        "${AIV_KIND:-}"
+      ;;
+    defaults)
+      printf 'default-image-provider=%s\n' "$(aiv_default_image_provider)"
+      printf 'default-video-provider=%s\n' "$(aiv_default_video_provider)"
+      ;;
+    "")
+      echo "usage: load-config.sh {status <id> | defaults}" >&2
+      exit 2
+      ;;
+    *)
+      echo "load-config.sh: unknown subcommand '${cmd}'" >&2
+      exit 2
+      ;;
+  esac
+fi

package/scripts/ai-video/lib/operator-pick.sh

@@ -0,0 +1,119 @@
+#!/usr/bin/env bash
+# operator-pick.sh — best-of-N selection checkpoint invoked after image
+# render by /video:from-script and /video:scene. Renders a thumbnail
+# contact-sheet PNG of the candidates under a scene, then waits for the
+# operator to write <project>/scenes/<id>/selection.json.
+#
+# Dry-run mode (AIV_DRYRUN=true, default) auto-picks candidate 1 and
+# writes the same selection.json so smoke tests stay unattended.
+#
+# Usage:
+#   operator-pick.sh <project-dir> <scene-id>
+#
+# Inputs:
+#   <project-dir>/scenes/<scene-id>/candidates/*.png   (N>=1 image files)
+#
+# Outputs (stdout, one path per line so callers can capture both):
+#   sheet=<project-dir>/scenes/<scene-id>/contact-sheet.png
+#   selected=<absolute path to locked image>
+#
+# Exit codes:
+#   0   selection.json present, locked image path emitted
+#   2   missing candidates directory or empty
+#   3   selection.json malformed or names an unknown candidate
+#   4   operator declined (selection.json absent in live mode)
+
+set -euo pipefail
+
+if [ "$#" -ne 2 ]; then
+  printf 'operator-pick: usage: %s <project-dir> <scene-id>\n' "$0" >&2
+  exit 2
+fi
+
+project_dir="$1"
+scene_id="$2"
+scene_dir="${project_dir}/scenes/${scene_id}"
+cand_dir="${scene_dir}/candidates"
+sheet="${scene_dir}/contact-sheet.png"
+sel_file="${scene_dir}/selection.json"
+
+if [ ! -d "${cand_dir}" ]; then
+  printf 'operator-pick: missing candidate dir: %s\n' "${cand_dir}" >&2
+  exit 2
+fi
+
+# Collect candidates in deterministic order (lexical). Portable to
+# macOS bash 3.2 — no `mapfile`.
+candidates=()
+while IFS= read -r _p; do
+  candidates+=("${_p}")
+done < <(find "${cand_dir}" -maxdepth 1 -type f -name '*.png' | LC_ALL=C sort)
+if [ "${#candidates[@]}" -eq 0 ]; then
+  printf 'operator-pick: no candidate PNGs under %s\n' "${cand_dir}" >&2
+  exit 2
+fi
+
+# Build the contact-sheet PNG via ffmpeg. ceil(sqrt(N)) columns.
+n="${#candidates[@]}"
+cols=1
+while [ $((cols * cols)) -lt "${n}" ]; do cols=$((cols + 1)); done
+
+# ffmpeg's `tile` filter needs an input concat; use `-pattern_type glob`.
+if command -v ffmpeg >/dev/null 2>&1; then
+  ffmpeg -y -loglevel error \
+    -pattern_type glob -i "${cand_dir}/*.png" \
+    -filter_complex "tile=${cols}x0:padding=8:margin=16" \
+    "${sheet}" || {
+      printf 'operator-pick: ffmpeg tile failed; falling back to first candidate as sheet\n' >&2
+      cp "${candidates[0]}" "${sheet}"
+    }
+else
+  # ffmpeg absent (e.g. minimal CI). Copy the first candidate as the sheet.
+  cp "${candidates[0]}" "${sheet}"
+fi
+
+# Dry-run: auto-select candidate 1 and write selection.json verbatim so
+# downstream resume reads it identically to a real operator pick.
+if [ "${AIV_DRYRUN:-true}" = "true" ]; then
+  first="$(basename "${candidates[0]}")"
+  cat > "${sel_file}" <<JSON
+{
+  "selected": "${first}",
+  "reason": "auto-selected by operator-pick.sh (AIV_DRYRUN=true)"
+}
+JSON
+fi
+
+# Wait-loop is not appropriate here — the caller (command file) decides
+# whether to poll or hand back. We assert selection.json exists and
+# resolve it; if missing in live mode, we exit non-zero so the caller
+# can pause and re-invoke.
+if [ ! -f "${sel_file}" ]; then
+  printf 'operator-pick: selection.json absent; write %s with {"selected":"<filename>"} and re-run\n' "${sel_file}" >&2
+  exit 4
+fi
+
+# Read selection.json (jq required — already a hard dep for adapters).
+if ! command -v jq >/dev/null 2>&1; then
+  printf 'operator-pick: jq is required\n' >&2
+  exit 3
+fi
+selected_name="$(jq -r '.selected // empty' "${sel_file}")"
+if [ -z "${selected_name}" ]; then
+  printf 'operator-pick: selection.json missing "selected" field\n' >&2
+  exit 3
+fi
+
+selected_path="${cand_dir}/${selected_name}"
+if [ ! -f "${selected_path}" ]; then
+  printf 'operator-pick: selected candidate not found: %s\n' "${selected_path}" >&2
+  exit 3
+fi
+
+# Also write a stable locked.png symlink/copy at the scene root so the
+# motion step can resolve the locked image without re-reading selection.json.
+locked="${scene_dir}/locked.png"
+cp -f "${selected_path}" "${locked}"
+
+printf 'sheet=%s\n' "${sheet}"
+printf 'selected=%s\n' "${locked}"

package/scripts/ai-video/lib/parse-blueprint.sh

@@ -0,0 +1,122 @@
+#!/usr/bin/env bash
+# parse-blueprint.sh — read a 12-block Cinematic Scene Blueprint
+# from stdin (or a file arg) and emit adapter-contract JSON on
+# stdout. Pure POSIX-compatible bash (no associative arrays, runs
+# on macOS bash 3.2); jq required for JSON safety.
+#
+# Schema: .agent-src.uncompressed/skills/scene-expander/scene-blueprint.schema.yaml
+# Contract: scripts/ai-video/lib/adapter-contract.md
+#
+# Usage:
+#   parse-blueprint.sh < prompt.txt > blueprint.json
+#   parse-blueprint.sh prompt.txt > blueprint.json
+#
+# Exit codes:
+#   0   valid blueprint, JSON emitted on stdout
+#   2   missing required block — name on stderr
+#   3   parse error (unknown block, malformed DURATION, etc.)
+
+set -euo pipefail
+
+command -v jq >/dev/null 2>&1 || {
+  echo "parse-blueprint: jq required" >&2
+  exit 3
+}
+
+input="${1:-/dev/stdin}"
+[ -r "$input" ] || { echo "parse-blueprint: cannot read $input" >&2; exit 3; }
+
+V_STYLE=""; V_SUBJECT=""; V_ENVIRONMENT=""; V_ACTION=""
+V_CAMERA=""; V_LENS=""; V_LIGHTING=""; V_MOOD=""
+V_DIALOGUE=""; V_AMBIENT_SOUND=""; V_DURATION=""; V_NEGATIVE=""
+
+append_to() {
+  local name="$1"; local line="$2"
+  local cur; eval "cur=\${$name}"
+  if [ -z "$cur" ]; then
+    eval "$name=\$line"
+  else
+    eval "$name=\"\${$name}
+\$line\""
+  fi
+}
+
+set_var() {
+  eval "$1=\$2"
+}
+
+current=""
+while IFS= read -r line || [ -n "$line" ]; do
+  stripped="$(printf '%s' "$line" | sed -E 's/^[[:space:]]*//; s/^\*\*//; s/\*\*[[:space:]]*$//')"
+  label="$(printf '%s' "$stripped" | sed -nE 's/^([A-Z][A-Z ]+)[[:space:]]*:.*$/\1/p')"
+  if [ -n "$label" ]; then
+    key="$(printf '%s' "$label" | tr ' ' '_' | tr '[:lower:]' '[:upper:]')"
+    case "$key" in
+      STYLE|SUBJECT|ENVIRONMENT|ACTION|CAMERA|LENS|LIGHTING|MOOD|DIALOGUE|AMBIENT_SOUND|DURATION|NEGATIVE)
+        current="V_$key"
+        rest="$(printf '%s' "$stripped" | sed -E "s/^${label}[[:space:]]*:[[:space:]]*//")"
+        set_var "$current" "$rest"
+        continue
+        ;;
+    esac
+  fi
+  if [ -n "$current" ] && [ -n "$line" ]; then
+    append_to "$current" "$line"
+  fi
+done < "$input"
+
+for short in STYLE SUBJECT ENVIRONMENT ACTION CAMERA LENS LIGHTING MOOD DURATION NEGATIVE; do
+  eval "v=\$V_$short"
+  if [ -z "$v" ]; then
+    echo "parse-blueprint: missing required block: $short" >&2
+    exit 2
+  fi
+done
+
+if ! printf '%s' "$V_DURATION" | grep -Eq '^[0-9]+(\.[0-9])?$'; then
+  echo "parse-blueprint: DURATION not numeric: $V_DURATION" >&2
+  exit 3
+fi
+
+negative_json="$(printf '%s' "$V_NEGATIVE" | tr ',\n' '\n\n' | sed '/^[[:space:]]*$/d' | sed -E 's/^[[:space:]]*//; s/[[:space:]]*$//' | jq -R . | jq -s .)"
+
+to_array_or_null() {
+  if [ -z "$1" ]; then
+    printf '%s' "null"
+  else
+    printf '%s\n' "$1" | sed '/^[[:space:]]*$/d' | jq -R . | jq -s .
+  fi
+}
+dialogue_json="$(to_array_or_null "$V_DIALOGUE")"
+ambient_json="$(to_array_or_null "$V_AMBIENT_SOUND")"
+
+audio_native=false
+if [ "$dialogue_json" != "null" ] || [ "$ambient_json" != "null" ]; then
+  audio_native=true
+fi
+
+jq -n \
+  --arg style       "$V_STYLE" \
+  --arg subject     "$V_SUBJECT" \
+  --arg environment "$V_ENVIRONMENT" \
+  --arg action      "$V_ACTION" \
+  --arg camera      "$V_CAMERA" \
+  --arg lens        "$V_LENS" \
+  --arg lighting    "$V_LIGHTING" \
+  --arg mood        "$V_MOOD" \
+  --argjson dialogue "$dialogue_json" \
+  --argjson ambient  "$ambient_json" \
+  --argjson duration "$V_DURATION" \
+  --argjson negative "$negative_json" \
+  --argjson native   "$audio_native" \
+  '{
+    prompt: {
+      style: $style, subject: $subject, environment: $environment,
+      action: $action, camera: $camera, lens: $lens,
+      lighting: $lighting, mood: $mood
+    },
+    audio: { dialogue: $dialogue, ambient: $ambient, enable_native_audio: $native },
+    duration: $duration,
+    negative: $negative,
+    requires: { audio_native: $native }
+  }'

package/scripts/ai-video/lib/redact.sh

@@ -0,0 +1,85 @@
+#!/usr/bin/env bash
+# scripts/ai-video/lib/redact.sh — secret-scrubbing helper for /video:* adapters.
+#
+# Sourced by every adapter under scripts/ai-video/adapters/*.sh. Provides
+# two helpers:
+#
+#   aiv_redact_register <secret>   — register a string to scrub (idempotent)
+#   aiv_redact <text>              — print text with every registered
+#                                    secret replaced by ***REDACTED***
+#
+# Iron Law: an API key must never reach stdout/stderr verbatim. Adapters
+# pipe every network response, curl error, and trace through aiv_redact
+# before printing. Empty / unset values are skipped silently — an unset
+# secret cannot leak.
+#
+# Pure bash, no external dependencies. Safe under `set -euo pipefail`.
+
+# Guard against double-source.
+if [ -n "${AIV_REDACT_LOADED:-}" ]; then
+  return 0 2>/dev/null || exit 0
+fi
+AIV_REDACT_LOADED=1
+
+# Registry of secrets to scrub. Newline-separated; populated by
+# aiv_redact_register. Never echoed.
+AIV_REDACT_SECRETS=""
+
+aiv_redact_register() {
+  local secret="${1:-}"
+  # Treat empty / placeholder values as no-op so adapters can call this
+  # unconditionally without leaking the placeholder string.
+  case "${secret}" in
+    ""|"REPLACE-ME"|*"-REPLACE-ME") return 0 ;;
+  esac
+  # Require a minimum length so single characters do not nuke the log.
+  if [ "${#secret}" -lt 8 ]; then
+    return 0
+  fi
+  # Idempotent — skip if already registered.
+  case "${AIV_REDACT_SECRETS}" in
+    *"${secret}"*) return 0 ;;
+  esac
+  AIV_REDACT_SECRETS="${AIV_REDACT_SECRETS}${secret}
+"
+}
+
+aiv_redact() {
+  local input
+  if [ "$#" -gt 0 ]; then
+    input="$*"
+  else
+    input="$(cat)"
+  fi
+  if [ -z "${AIV_REDACT_SECRETS}" ]; then
+    printf '%s\n' "${input}"
+    return 0
+  fi
+  # Apply replacements one secret at a time using awk so special chars
+  # in the secret cannot break a sed expression. Use a here-string to
+  # avoid running the loop in a subshell (which would discard mutations
+  # to ${input}).
+  local secret
+  while IFS= read -r secret; do
+    [ -z "${secret}" ] && continue
+    input="$(printf '%s' "${input}" | awk -v s="${secret}" '
+      {
+        out = ""
+        rest = $0
+        while ((i = index(rest, s)) > 0) {
+          out = out substr(rest, 1, i - 1) "***REDACTED***"
+          rest = substr(rest, i + length(s))
+        }
+        print out rest
+      }')"
+  done <<< "${AIV_REDACT_SECRETS}"
+  printf '%s\n' "${input}"
+}
+
+# Convenience wrapper: pipe stdin through aiv_redact line by line so
+# adapters can do `curl … 2>&1 | aiv_redact_stream`.
+aiv_redact_stream() {
+  while IFS= read -r line; do
+    aiv_redact "${line}"
+  done
+}

package/scripts/ai-video/lib/validate-deps.sh

@@ -0,0 +1,132 @@
+#!/usr/bin/env bash
+# validate-deps.sh — startup validator invoked by every /video:* command
+# BEFORE any adapter or network call. Reads the YAML frontmatter from
+# the command file, resolves every declared persona + skill against
+# .agent-src/personas/ and .agent-src/skills/, and fails fast with the
+# missing-id list.
+#
+# Scope (per roadmap Phase 5 Step 5): existence + frontmatter `id` match
+# only. No version pinning (scope-control § rules); no schema validation
+# of persona / skill bodies — that lives in `task lint-skills`.
+#
+# Usage:
+#   validate-deps.sh <path-to-command.md>
+#
+# Exit codes:
+#   0   all declared personas + skills resolve
+#   2   command file missing or no frontmatter
+#   3   one or more declared ids do not resolve (list on stderr)
+
+set -euo pipefail
+
+if [ "$#" -ne 1 ]; then
+  printf 'validate-deps: usage: %s <path-to-command.md>\n' "$0" >&2
+  exit 2
+fi
+
+cmd_file="$1"
+if [ ! -f "${cmd_file}" ]; then
+  printf 'validate-deps: command file not found: %s\n' "${cmd_file}" >&2
+  exit 2
+fi
+
+# Resolve repo root from this script's location (scripts/ai-video/lib/).
+script_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+repo_root="$(cd "${script_dir}/../../.." && pwd)"
+
+# AIV_PERSONAS_DIR / AIV_SKILLS_DIR allow overrides for tests; defaults
+# point at the generated mirrors (skills+personas live there at runtime).
+personas_dir="${AIV_PERSONAS_DIR:-${repo_root}/.agent-src/personas}"
+skills_dir="${AIV_SKILLS_DIR:-${repo_root}/.agent-src/skills}"
+
+# Extract the frontmatter block (between the first two `---` lines).
+fm="$(awk '
+  BEGIN { in_fm=0; count=0 }
+  /^---[[:space:]]*$/ { count++; if (count==1) { in_fm=1; next } if (count==2) { exit } }
+  in_fm { print }
+' "${cmd_file}")"
+
+if [ -z "${fm}" ]; then
+  printf 'validate-deps: no YAML frontmatter in %s\n' "${cmd_file}" >&2
+  exit 2
+fi
+
+# Parse `personas:` and `skills:` lines. We accept inline-list form only
+# (the template we ship), e.g. `personas: [a, b]`. No multi-line block
+# form — keeps the validator dependency-free (no yq / python).
+_extract_list() {
+  # $1 = key name (personas|skills)
+  printf '%s\n' "${fm}" \
+    | awk -v key="$1" '
+        $0 ~ "^" key ":" {
+          line=$0
+          sub("^" key ":[[:space:]]*", "", line)
+          sub("^\\[", "", line)
+          sub("\\][[:space:]]*$", "", line)
+          gsub(",", " ", line)
+          print line
+        }' \
+    | tr -s ' ' '\n' \
+    | sed 's/^[[:space:]]*//; s/[[:space:]]*$//' \
+    | sed '/^$/d'
+}
+
+# Portable to macOS bash 3.2 — no `mapfile`.
+personas=()
+while IFS= read -r _id; do
+  personas+=("${_id}")
+done < <(_extract_list personas)
+skills=()
+while IFS= read -r _id; do
+  skills+=("${_id}")
+done < <(_extract_list skills)
+
+missing=()
+
+# bash 3.2 treats `"${arr[@]}"` on an empty array as unbound under
+# `set -u`. Guard each loop with the length check.
+
+# A persona is "present" if .agent-src/personas/<id>.md exists OR
+# .agent-src/personas/<id>/persona.md exists (template-specialist shape).
+if [ "${#personas[@]}" -gt 0 ]; then
+for p in "${personas[@]}"; do
+  [ -z "${p}" ] && continue
+  if [ ! -f "${personas_dir}/${p}.md" ] && [ ! -f "${personas_dir}/${p}/persona.md" ]; then
+    missing+=("persona:${p}")
+    continue
+  fi
+  # Frontmatter id match: read `id:` (optional) or `name:` from the
+  # persona file; if present it must equal the declared slug.
+  src_file="${personas_dir}/${p}.md"
+  [ -f "${src_file}" ] || src_file="${personas_dir}/${p}/persona.md"
+  declared_id="$(awk '/^id:[[:space:]]*/ { sub("^id:[[:space:]]*", ""); print; exit } /^name:[[:space:]]*/ { sub("^name:[[:space:]]*", ""); print; exit }' "${src_file}" | tr -d '"' | tr -d "'")"
+  if [ -n "${declared_id}" ] && [ "${declared_id}" != "${p}" ]; then
+    missing+=("persona:${p} (file declares id=${declared_id})")
+  fi
+done
+fi
+
+# A skill is "present" if .agent-src/skills/<id>/SKILL.md exists.
+if [ "${#skills[@]}" -gt 0 ]; then
+for s in "${skills[@]}"; do
+  [ -z "${s}" ] && continue
+  skill_file="${skills_dir}/${s}/SKILL.md"
+  if [ ! -f "${skill_file}" ]; then
+    missing+=("skill:${s}")
+    continue
+  fi
+  declared_id="$(awk '/^name:[[:space:]]*/ { sub("^name:[[:space:]]*", ""); print; exit }' "${skill_file}" | tr -d '"' | tr -d "'")"
+  if [ -n "${declared_id}" ] && [ "${declared_id}" != "${s}" ]; then
+    missing+=("skill:${s} (file declares name=${declared_id})")
+  fi
+done
+fi
+
+if [ "${#missing[@]}" -gt 0 ]; then
+  printf 'validate-deps: unresolved declarations in %s:\n' "${cmd_file}" >&2
+  printf '  - %s\n' "${missing[@]}" >&2
+  exit 3
+fi
+
+# Silent success — callers can `set -e` and continue.
+exit 0