@thebassclef/lite 1.9.9 → 1.9.10

package/dist/lite/lib/capability-probe.sh

@@ -44,8 +44,46 @@ probe_gh_auth() {
 }
 
 probe_mcp_playwright() {
-  # V1 heuristic — env var contract. V2 may read tool inventory.
+  # Fast path — explicit opt-in via env var. Adopters who want to force the
+  # probe TRUE set CLAUDE_MCP_PLAYWRIGHT=1 in their shell init. Documented at
+  # docs/use-cases/UC-lib-capability-probe-mcp-fallback.md.
   [ -n "${CLAUDE_MCP_PLAYWRIGHT:-}" ] && return 0
+
+  # Fallback — look for a Playwright MCP server in known MCP config files.
+  # jq is required for parsing. When absent, the probe fails soft to 1.
+  if ! command -v jq >/dev/null 2>&1; then
+    echo "probe_mcp_playwright: jq not found; env-var fast path only" >&2
+    return 1
+  fi
+
+  local project_dir="${CLAUDE_PROJECT_DIR:-.}"
+  local home_dir="${HOME:-}"
+
+  # Check paths in precedence order. First hit wins.
+  _probe_mcp_json_has_playwright "${project_dir}/.mcp.json"              && return 0
+  _probe_mcp_json_has_playwright "${project_dir}/.claude/settings.json"  && return 0
+  if [ -n "$home_dir" ]; then
+    _probe_mcp_json_has_playwright "${home_dir}/.claude/settings.json"   && return 0
+    _probe_mcp_json_has_playwright "${home_dir}/.claude.json"            && return 0
+  fi
+  return 1
+}
+
+# _probe_mcp_json_has_playwright <path>
+# Returns 0 when the JSON file names a Playwright MCP server. Checks two
+# shapes:
+#   1. Top-level "playwright" key (used by `.mcp.json` on some adopters)
+#   2. Nested "mcpServers.playwright" (used by `settings.json` + `~/.claude.json`)
+# Fail-soft on missing file + malformed JSON — returns 1 silently.
+# Per bassclef-upstream Finding #6 (#2036): `local path` is a zsh-magic variable
+# name — ties to $PATH when sourced from zsh. Renamed to `local p`.
+_probe_mcp_json_has_playwright() {
+  local p="$1"
+  [ -f "$p" ] || return 1
+  # Shape 1 — top-level playwright
+  jq -e '.playwright // empty' "$p" >/dev/null 2>&1 && return 0
+  # Shape 2 — nested mcpServers.playwright
+  jq -e '.mcpServers.playwright // empty' "$p" >/dev/null 2>&1 && return 0
   return 1
 }
 

package/dist/lite/lib/composer-preflight.sh

@@ -178,10 +178,14 @@ composer_preflight_check() {
     echo "check_5_recommendation="
     pass=$((pass + 1))
   elif [ -f "$repo_skill" ] || [ -L "$repo_skill" ]; then
-    echo "check_5_status=warn"
-    echo "check_5_message=Skill at repo-level only ($repo_skill); user-level symlink missing — harness may not pick up (bassclef#271)"
-    echo "check_5_recommendation=Run bassclef-sync.sh to create user-level symlink OR restart Claude session"
-    warn=$((warn + 1))
+    # Per cli#321 — Claude Code's harness loads project .claude/skills/
+    # directly; user-level symlinks are not required. Repo-level IS a
+    # valid discovery path. Previously flagged as WARN, trained adopters
+    # to ignore warnings. Now PASS with informational message.
+    echo "check_5_status=pass"
+    echo "check_5_message=Skill resolves at repo-level: $repo_skill (harness loads project .claude/skills directly)"
+    echo "check_5_recommendation="
+    pass=$((pass + 1))
   elif [ -n "${BASSCLEF_DIR:-}" ] && [ -f "$bassclef_skill" ]; then
     echo "check_5_status=warn"
     echo "check_5_message=Skill at bassclef only; consumer-side links missing — substrate sync incomplete"

package/dist/lite/lib/install-written-paths.sh

@@ -0,0 +1,369 @@
+#!/bin/bash
+# tier: lite
+# Install-written-paths manifest + accessor lib.
+#
+# Records paths written by bassclef install writers so discipline hooks
+# can skip them. Per bassclef-upstream#2036 Finding #8 structural cure
+# (Kunal Slot 1). See docs/decompositions/2026-10-03-install-written-paths-manifest.md
+# for design + patterns applied (Repository + Deep Module + Null Object + Guard Clause).
+#
+# @pattern patterns/code/fowler/repository.md
+# @pattern patterns/code/ousterhout/deep-module.md
+#
+# Public API (5 verbs):
+#   install_written_paths_register <path> <writer>
+#   is_install_written_path <path>
+#   install_written_paths_rename <old-path> <new-path>
+#   install_written_paths_rebuild
+#   install_written_paths_verify
+#
+# Override: SKIP_INSTALL_WRITTEN_PATHS=1 — is_install_written_path returns 1 (false)
+# so hooks fire discipline normally (don't skip).
+#
+# Variable naming: internal locals use `tgt` (target path), `arg_*` prefix,
+# or `_iwp_*` namespace to avoid shadowing shell builtins. Reserved names
+# like `PATH`, `CDPATH`, `FPATH`, `MANPATH` are not used as locals per
+# shell-portability discipline (zsh treats lowercase `path` as array-tied
+# to PATH; renaming avoids the kill).
+
+set -u
+
+# ---- Constants ----
+
+_IWP_SCHEMA_VERSION="1.0.0"
+
+_IWP_WRITERS="bassclef-hook-connect bassclef-sync-template bassclef-sync-dispatcher schedule-auto-save bassclef-init-npm"
+
+# ---- Internal helpers ----
+
+_iwp_manifest_path() {
+  local root="${CLAUDE_PROJECT_DIR:-$(pwd)}"
+  echo "$root/state/install-written-paths.json"
+}
+
+_iwp_log() {
+  if command -v trace_log >/dev/null 2>&1; then
+    trace_log "install-written-paths" "$*"
+  fi
+}
+
+_iwp_sha256() {
+  local file="$1"
+  if [ ! -f "$file" ]; then
+    echo ""
+    return 1
+  fi
+  if command -v sha256sum >/dev/null 2>&1; then
+    sha256sum "$file" 2>/dev/null | awk '{print "sha256:" $1}'
+  elif command -v shasum >/dev/null 2>&1; then
+    shasum -a 256 "$file" 2>/dev/null | awk '{print "sha256:" $1}'
+  else
+    echo ""
+    return 1
+  fi
+}
+
+_iwp_valid_writer() {
+  local w="$1"
+  for valid in $_IWP_WRITERS; do
+    [ "$w" = "$valid" ] && return 0
+  done
+  return 1
+}
+
+_iwp_validate_path() {
+  local p="$1"
+  # Reject path traversal (any component equal to .. OR path exactly ..)
+  case "$p" in
+    *../*|..) return 1 ;;
+  esac
+  # Reject absolute paths outside $CLAUDE_PROJECT_DIR
+  case "$p" in
+    /*)
+      local root="${CLAUDE_PROJECT_DIR:-$(pwd)}"
+      case "$p" in
+        "$root"/*) ;;
+        *) return 1 ;;
+      esac
+      ;;
+  esac
+  return 0
+}
+
+_iwp_ensure_manifest() {
+  local mpath
+  mpath=$(_iwp_manifest_path)
+  if [ ! -f "$mpath" ]; then
+    mkdir -p "$(dirname "$mpath")"
+    cat > "$mpath" <<EOF
+{
+  "schema_version": "$_IWP_SCHEMA_VERSION",
+  "entries": []
+}
+EOF
+  fi
+}
+
+_iwp_manifest_valid() {
+  local mpath
+  mpath=$(_iwp_manifest_path)
+  [ -f "$mpath" ] || return 1
+  jq -e . "$mpath" >/dev/null 2>&1 || return 1
+  return 0
+}
+
+# ---- Public API ----
+
+# install_written_paths_register <path> <writer>
+# Records a path as install-written. Idempotent on path.
+# Returns 0 on success, 1 on validation failure.
+install_written_paths_register() {
+  local tgt="${1:-}"
+  local writer="${2:-}"
+
+  if [ -z "$tgt" ] || [ -z "$writer" ]; then
+    echo "install-written-paths: register requires <path> <writer>" >&2
+    return 1
+  fi
+
+  if ! _iwp_validate_path "$tgt"; then
+    echo "install-written-paths: path '$tgt' rejected (traversal or outside project)" >&2
+    _iwp_log "register-rejected path=$tgt reason=traversal"
+    return 1
+  fi
+
+  if ! _iwp_valid_writer "$writer"; then
+    echo "install-written-paths: writer '$writer' not in allowed enum" >&2
+    _iwp_log "register-rejected path=$tgt writer=$writer reason=unknown-writer"
+    return 1
+  fi
+
+  if ! command -v jq >/dev/null 2>&1; then
+    echo "install-written-paths: jq not available; cannot register" >&2
+    return 1
+  fi
+
+  _iwp_ensure_manifest
+  local mpath
+  mpath=$(_iwp_manifest_path)
+
+  local root="${CLAUDE_PROJECT_DIR:-$(pwd)}"
+  local full_tgt
+  case "$tgt" in
+    /*) full_tgt="$tgt" ;;
+    *) full_tgt="$root/$tgt" ;;
+  esac
+
+  local hash
+  hash=$(_iwp_sha256 "$full_tgt")
+  if [ -z "$hash" ]; then
+    echo "install-written-paths: unable to compute hash for '$full_tgt'" >&2
+    return 1
+  fi
+
+  local now
+  now=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+
+  # Use flock to serialize writes; fall back to no-lock on BSD without flock
+  local tmp
+  tmp=$(mktemp "$mpath.tmp.XXXXXX")
+
+  if command -v flock >/dev/null 2>&1; then
+    (
+      flock -x 9
+      jq --arg path "$tgt" --arg writer "$writer" --arg ts "$now" --arg hash "$hash" \
+        '.entries |= (map(select(.path != $path)) + [{"path": $path, "writer": $writer, "written_at": $ts, "content_hash": $hash}])' \
+        "$mpath" > "$tmp" && mv "$tmp" "$mpath"
+    ) 9>"$mpath.lock"
+  else
+    jq --arg path "$tgt" --arg writer "$writer" --arg ts "$now" --arg hash "$hash" \
+      '.entries |= (map(select(.path != $path)) + [{"path": $path, "writer": $writer, "written_at": $ts, "content_hash": $hash}])' \
+      "$mpath" > "$tmp" && mv "$tmp" "$mpath"
+  fi
+
+  rm -f "$tmp" 2>/dev/null || true
+  _iwp_log "register path=$tgt writer=$writer"
+  return 0
+}
+
+# is_install_written_path <path>
+# Returns 0 (true) when path in manifest AND content hash matches.
+# Returns 1 (false) otherwise.
+# Override: SKIP_INSTALL_WRITTEN_PATHS=1 forces return 1 (hooks fire normally).
+is_install_written_path() {
+  if [ -n "${SKIP_INSTALL_WRITTEN_PATHS:-}" ]; then
+    _iwp_log "check override SKIP_INSTALL_WRITTEN_PATHS=1 path=${1:-}"
+    return 1
+  fi
+
+  local tgt="${1:-}"
+  if [ -z "$tgt" ]; then
+    return 1
+  fi
+
+  local mpath
+  mpath=$(_iwp_manifest_path)
+
+  # Fail-soft: manifest missing or malformed → not install-written
+  if ! _iwp_manifest_valid; then
+    _iwp_log "check path=$tgt result=false reason=no-manifest-or-malformed"
+    [ -f "$mpath" ] && echo "install-written-paths: manifest malformed; treating as not-install-written" >&2
+    return 1
+  fi
+
+  if ! command -v jq >/dev/null 2>&1; then
+    _iwp_log "check path=$tgt result=false reason=no-jq"
+    return 1
+  fi
+
+  # Look up entry
+  local recorded_hash
+  recorded_hash=$(jq -r --arg path "$tgt" '.entries[] | select(.path == $path) | .content_hash' "$mpath" 2>/dev/null)
+  if [ -z "$recorded_hash" ] || [ "$recorded_hash" = "null" ]; then
+    _iwp_log "check path=$tgt result=false reason=not-in-manifest"
+    return 1
+  fi
+
+  # Compute current hash
+  local root="${CLAUDE_PROJECT_DIR:-$(pwd)}"
+  local full_tgt
+  case "$tgt" in
+    /*) full_tgt="$tgt" ;;
+    *) full_tgt="$root/$tgt" ;;
+  esac
+
+  if [ ! -f "$full_tgt" ]; then
+    _iwp_log "check path=$tgt result=false reason=file-missing"
+    return 1
+  fi
+
+  local current_hash
+  current_hash=$(_iwp_sha256 "$full_tgt")
+  if [ -z "$current_hash" ]; then
+    _iwp_log "check path=$tgt result=false reason=hash-fail"
+    return 1
+  fi
+
+  if [ "$recorded_hash" = "$current_hash" ]; then
+    _iwp_log "check path=$tgt result=true reason=match"
+    return 0
+  else
+    _iwp_log "check path=$tgt result=false reason=hash-mismatch"
+    return 1
+  fi
+}
+
+# install_written_paths_rename <old-path> <new-path>
+# Moves entry; preserves writer; bumps written_at.
+install_written_paths_rename() {
+  local old="${1:-}"
+  local new="${2:-}"
+
+  if [ -z "$old" ] || [ -z "$new" ]; then
+    echo "install-written-paths: rename requires <old-path> <new-path>" >&2
+    return 1
+  fi
+
+  if ! _iwp_validate_path "$new"; then
+    echo "install-written-paths: new path '$new' rejected" >&2
+    return 1
+  fi
+
+  if ! _iwp_manifest_valid; then
+    echo "install-written-paths: manifest missing or malformed" >&2
+    return 1
+  fi
+
+  if ! command -v jq >/dev/null 2>&1; then
+    echo "install-written-paths: jq not available" >&2
+    return 1
+  fi
+
+  local mpath
+  mpath=$(_iwp_manifest_path)
+
+  # Check old exists
+  local writer
+  writer=$(jq -r --arg path "$old" '.entries[] | select(.path == $path) | .writer' "$mpath" 2>/dev/null)
+  if [ -z "$writer" ] || [ "$writer" = "null" ]; then
+    echo "install-written-paths: '$old' not in manifest" >&2
+    return 1
+  fi
+
+  local now
+  now=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+
+  # Compute hash from new location if it exists; else keep old hash
+  local root="${CLAUDE_PROJECT_DIR:-$(pwd)}"
+  local full_new
+  case "$new" in
+    /*) full_new="$new" ;;
+    *) full_new="$root/$new" ;;
+  esac
+
+  local new_hash
+  if [ -f "$full_new" ]; then
+    new_hash=$(_iwp_sha256 "$full_new")
+  else
+    new_hash=$(jq -r --arg path "$old" '.entries[] | select(.path == $path) | .content_hash' "$mpath")
+  fi
+
+  local tmp
+  tmp=$(mktemp "$mpath.tmp.XXXXXX")
+
+  jq --arg old "$old" --arg new "$new" --arg writer "$writer" --arg ts "$now" --arg hash "$new_hash" \
+    '.entries |= (map(select(.path != $old)) + [{"path": $new, "writer": $writer, "written_at": $ts, "content_hash": $hash}])' \
+    "$mpath" > "$tmp" && mv "$tmp" "$mpath"
+
+  rm -f "$tmp" 2>/dev/null || true
+  _iwp_log "rename old=$old new=$new"
+  return 0
+}
+
+# install_written_paths_rebuild
+# Regenerates the manifest. V1: creates empty manifest when missing.
+# Future: walks install writers' known output locations.
+install_written_paths_rebuild() {
+  local mpath
+  mpath=$(_iwp_manifest_path)
+  if [ -f "$mpath" ] && _iwp_manifest_valid; then
+    return 0
+  fi
+  rm -f "$mpath" 2>/dev/null || true
+  _iwp_ensure_manifest
+  _iwp_log "rebuild manifest=$mpath"
+  return 0
+}
+
+# install_written_paths_verify
+# Returns 0 on well-formed manifest, 1 on schema violation.
+install_written_paths_verify() {
+  local mpath
+  mpath=$(_iwp_manifest_path)
+
+  if [ ! -f "$mpath" ]; then
+    echo "install-written-paths: manifest file missing at $mpath" >&2
+    return 1
+  fi
+
+  if ! command -v jq >/dev/null 2>&1; then
+    echo "install-written-paths: jq not available" >&2
+    return 1
+  fi
+
+  if ! jq -e . "$mpath" >/dev/null 2>&1; then
+    echo "install-written-paths: manifest JSON malformed" >&2
+    return 1
+  fi
+
+  # Basic shape check — required top-level keys present
+  local has_version has_entries
+  has_version=$(jq -r 'has("schema_version")' "$mpath" 2>/dev/null)
+  has_entries=$(jq -r 'has("entries")' "$mpath" 2>/dev/null)
+  if [ "$has_version" != "true" ] || [ "$has_entries" != "true" ]; then
+    echo "install-written-paths: manifest missing required keys" >&2
+    return 1
+  fi
+
+  return 0
+}

package/dist/lite/lib/luminary-pick.sh

@@ -25,7 +25,7 @@
 #
 # Usage from a caller SKILL body:
 #
-#   source "${BASSCLEF_DIR:-$HOME/src/sunj-labs/bassclef}/lib/luminary-pick.sh"
+#   source "${BASSCLEF_DIR:-${CLAUDE_PROJECT_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}}/lib/luminary-pick.sh"
 #   CATALOG=$(luminary_pick_catalog)
 #   # then Claude reasons over $CATALOG + intent, writes JSON in-turn
 #
@@ -44,22 +44,44 @@ set -euo pipefail
 # Sort: alphabetical by slug.
 # Return: 0 on success (including empty catalog); non-zero if dir missing.
 luminary_pick_catalog() {
-  local basedir="${BASSCLEF_DIR:-$HOME/src/sunj-labs/bassclef}"
+  # Resolve basedir: BASSCLEF_DIR → CLAUDE_PROJECT_DIR → git root → pwd.
+  # cli#313 — the former fallback $HOME/src/sunj-labs/bassclef was the
+  # engineering team's own home path and failed for every adopter.
+  local basedir="${BASSCLEF_DIR:-${CLAUDE_PROJECT_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}}"
   local catalog_dir="${basedir}/state/luminary-implementations"
+  local lite_catalog="${basedir}/.claude/luminaries"
 
-  if [ ! -d "$catalog_dir" ]; then
-    echo "[luminary-pick-catalog] catalog dir missing: $catalog_dir" >&2
-    return 2
+  if [ -d "$catalog_dir" ]; then
+    (
+      shopt -s nullglob
+      set +e
+      for f in "$catalog_dir"/*.json; do
+        jq -r '"\(.luminary_slug) (\(.primary_domain // "unknown")) — \(.name // .luminary_slug)"' "$f" 2>/dev/null || true
+      done | sort -u
+    )
+    return 0
   fi
 
-  (
-    shopt -s nullglob
-    set +e
-    for f in "$catalog_dir"/*.json; do
-      jq -r '"\(.luminary_slug) (\(.primary_domain // "unknown")) — \(.name // .luminary_slug)"' "$f" 2>/dev/null || true
-    done | sort -u
-  )
-  return 0
+  # Lite-tier fallback (cli#313): read frontmatter from .claude/luminaries/*.md.
+  # Every tier ships this directory; state/luminary-implementations/ is upstream-only.
+  if [ -d "$lite_catalog" ]; then
+    (
+      shopt -s nullglob
+      set +e
+      for f in "$lite_catalog"/*.md; do
+        local slug domain name
+        slug=$(awk '/^slug:[[:space:]]/{sub(/^slug:[[:space:]]*/,""); print; exit}' "$f")
+        domain=$(awk '/^primary_domain:[[:space:]]/{sub(/^primary_domain:[[:space:]]*/,""); print; exit}' "$f")
+        name=$(awk '/^name:[[:space:]]/{sub(/^name:[[:space:]]*/,""); print; exit}' "$f")
+        [ -z "$slug" ] && continue
+        echo "${slug} (${domain:-unknown}) — ${name:-$slug}"
+      done | sort -u
+    )
+    return 0
+  fi
+
+  echo "[luminary-pick-catalog] catalog dir missing: $catalog_dir (and no .claude/luminaries/ fallback at $lite_catalog)" >&2
+  return 2
 }
 
 # Grace-window stub preserving the old function signature.

package/dist/lite/lib/state.sh

@@ -40,8 +40,9 @@ __state_check_binary_deps() {
   if [ "${__STATE_DEPS_CHECKED:-}" = "1" ]; then
     return 0
   fi
+  # Baseline deps — awk + jq required unconditionally
   local missing=""
-  for bin in awk python3 jq; do
+  for bin in awk jq; do
     command -v "$bin" >/dev/null 2>&1 || missing="$missing $bin"
   done
   if [ -n "$missing" ]; then
@@ -49,21 +50,63 @@ __state_check_binary_deps() {
 STATE ACCESSOR FAILURE
 Required binary missing from PATH:$missing
 
-These binaries are load-bearing for lib/state.sh accessors (Shape B
-YAML frontmatter extraction + JSON tooling).
+awk + jq are load-bearing for lib/state.sh accessors.
 
 Resolution:
-  macOS: brew install gawk python3 jq
-  Debian: sudo apt-get install gawk python3 jq
-
-Closes the bassclef#598 silent-failure class.
+  macOS: brew install gawk jq
+  Debian: sudo apt-get install gawk jq
 EOF
     return 4
   fi
+
+  # Per cli#308: YAML parser needs EITHER yq OR python3+PyYAML.
+  # Stock macOS has python3 but not PyYAML. Pre-cli#308, that mismatch
+  # caused silent failures where __state_check_binary_deps passed but
+  # the actual yaml parse failed with ModuleNotFoundError. Now we check
+  # that at least one working parser exists.
+  __state_check_yaml_parser || return 6
   export __STATE_DEPS_CHECKED=1
   return 0
 }
 
+# YAML parser check (per cli#308). Returns 0 if yq available OR
+# python3+yaml-module importable. Returns 6 if neither.
+__state_check_yaml_parser() {
+  # Cache the result per shell process.
+  if [ "${__STATE_YAML_PARSER:-}" = "yq" ] || [ "${__STATE_YAML_PARSER:-}" = "python3" ]; then
+    return 0
+  fi
+  # Prefer yq (faster + simpler contract).
+  if command -v yq >/dev/null 2>&1; then
+    export __STATE_YAML_PARSER=yq
+    return 0
+  fi
+  # Fall back to python3+PyYAML.
+  if command -v python3 >/dev/null 2>&1 && python3 -c "import yaml" >/dev/null 2>&1; then
+    export __STATE_YAML_PARSER=python3
+    return 0
+  fi
+  cat >&2 <<EOF
+STATE ACCESSOR FAILURE — no YAML parser available (per cli#308)
+
+lib/state.sh needs ONE of:
+  - yq (preferred — faster, no Python module needed)
+  - python3 + PyYAML module
+
+Both are missing on this machine.
+
+Resolution:
+  macOS (preferred): brew install yq
+  macOS (alt):       python3 -m pip install pyyaml
+  Debian: sudo apt-get install yq  OR  python3 -m pip install pyyaml
+
+Per cli#308 — this check closes the silent-failure class where
+python3 existed but PyYAML did not, and callers reported "goal not
+found" (wrong diagnosis).
+EOF
+  return 6
+}
+
 # yq2json — extract YAML frontmatter from markdown file, emit JSON.
 # Used by Shape B (markdown + YAML frontmatter + body) entity accessors.
 #
@@ -86,7 +129,7 @@ EOF
 # on invalid input) + @luminary michael-feathers (characterization
 # tests RED-first via fixtures/2026-09-06-silent-empty/).
 __state_yq2json() {
-  __state_check_binary_deps || return 4
+  __state_check_binary_deps || return $?
   local file="$1"
   if [ ! -f "$file" ]; then
     return 1
@@ -127,7 +170,23 @@ __state_yq2json() {
 
   local out
   local ec
-  out=$(awk '/^---$/{c++; next} c==1' "$file" | python3 -c "
+  # Per cli#308 — prefer yq when available, fall back to python3+PyYAML.
+  # __state_check_binary_deps (called at top of this function via return 4
+  # path) already resolved __STATE_YAML_PARSER to one of the two.
+  if [ "${__STATE_YAML_PARSER:-}" = "yq" ]; then
+    out=$(awk '/^---$/{c++; next} c==1' "$file" | yq -o=json '.' 2>&1)
+    ec=$?
+    if [ "$ec" -ne 0 ]; then
+      printf 'yaml parse failed (yq): %s\n' "$out" >&2
+      return 3
+    fi
+    # yq returns `null` for empty input; coerce to `{}` for consistency
+    # with python3 path.
+    if [ "$out" = "null" ]; then
+      out="{}"
+    fi
+  else
+    out=$(awk '/^---$/{c++; next} c==1' "$file" | python3 -c "
 import sys, yaml, json
 try:
     data = yaml.safe_load(sys.stdin) or {}
@@ -136,7 +195,8 @@ except Exception as e:
     print(f'yaml parse failed: {e}', file=sys.stderr)
     sys.exit(3)
 ")
-  ec=$?
+    ec=$?
+  fi
   # Instrument real-parse count for #1519 tests + observability.
   __STATE_YQ2JSON_PARSE_COUNT=$(( ${__STATE_YQ2JSON_PARSE_COUNT:-0} + 1 ))
   if [ "$ec" -ne 0 ]; then
@@ -185,7 +245,7 @@ __state_atomic_write() {
 # output) + @luminary michael-nygard (silent-fail wrap; write does not
 # crash caller).
 __state_yaml_write() {
-  __state_check_binary_deps || return 4
+  __state_check_binary_deps || return $?
   # Finding #6 (#2036): `local path` is a zsh-magic variable name — ties to
   # $PATH when sourced from zsh. Renamed to `local p` throughout this file.
   local p="$1"