@thebassclef/lite 0.1.3 → 1.0.0

package/substrate/lib/tier-dependency-audit.sh

@@ -1,1088 +0,0 @@
-#!/usr/bin/env bash
-# tier: lite
-# lib/tier-dependency-audit.sh
-#
-# Sourced library for the tier-dependency-audit subsystem. Ships the 8
-# Larman/GRASP responsibilities named in
-# docs/decompositions/2026-08-17a-tier-dependency-audit.md Phase 1.
-#
-# Per D1 — extracted from scripts/analyze-tier-dependencies.sh for
-# per-function testability + reuse across tier consumers (lite, standard,
-# standard-pro, ultra, upstream).
-#
-# Per D3 — REFERENCE_KINDS lookup table replaces hardcoded reference kinds.
-# Per D4 — reader functions log per-source counts to stderr.
-#
-# Anchor luminaries:
-#   @luminary david-parnas — information hiding; each function hides one
-#     design decision behind a stable contract
-#   @luminary john-ousterhout — deep modules; small interface + hidden work
-#   @luminary michael-feathers — characterization tests per function
-#     (see .claude/hooks/tests/lib-tier-dependency-audit.test.sh)
-#
-# Consumers source this file:
-#   source lib/tier-dependency-audit.sh
-#
-# Tests: .claude/hooks/tests/lib-tier-dependency-audit.test.sh (48 tests as of goal 08-17d)
-# Standard: standards/tier-dependency-analysis.md
-
-# Repo root derived from lib file location — stable across callers' CWDs.
-# Used by read_runtime_deps for glob expansion via `git -C`.
-_TIER_AUDIT_LIB_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-_TIER_AUDIT_REPO_ROOT="$(cd "$_TIER_AUDIT_LIB_DIR/.." && pwd)"
-
-# ---------------------------------------------------------------------------
-# REFERENCE_KINDS — the 7 reference kinds the subsystem walks
-# Per D3. Each entry: "kind|grep-pattern|extraction-fn"
-# Extension: add a new line + implement the extraction fn below.
-# ---------------------------------------------------------------------------
-REFERENCE_KINDS=(
-  "composes_with|^composes_with:|_extract_composes_with"
-  "source_lib|^[[:space:]]*source[[:space:]]+lib/|_extract_source_lib"
-  "additional_directories|additionalDirectories|_extract_additional_directories"
-  "bash_scripts|bash[[:space:]]+scripts/|_extract_bash_scripts"
-  "luminary_ref|@luminary[[:space:]]+|_extract_luminary_ref"
-  "standards_ref|standards/[a-zA-Z0-9._/-]+\\.md|_extract_standards_ref"
-  "rules_ref|\\.claude/rules/[a-zA-Z0-9._/-]+\\.md|_extract_rules_ref"
-  "jsonc_config|bassclef-configs\\.jsonc|_extract_jsonc_config"
-  "hook_ref|\\.claude/hooks/[a-zA-Z0-9._/-]+\\.sh|_extract_hook_ref"
-  "marker_ref|state/markers/[a-zA-Z0-9._/-]+\\.marker|_extract_marker_ref"
-  "state_file_read|state/[a-zA-Z0-9._/-]+\\.json|_extract_state_file_read"
-  "template_ref|templates/[a-zA-Z0-9._/-]+\\.md_or_yml|_extract_template_ref"
-  "python_script|scripts/[a-zA-Z0-9._/-]+\\.py|_extract_python_script"
-  "allowlist_ref|\\.claude/hooks/[a-zA-Z0-9._/-]*-allowlist\\.txt|_extract_allowlist_ref"
-)
-
-# ---------------------------------------------------------------------------
-# parse_tier_arg — Validate tier arg, return normalized value
-# Interface: ITierArgParser (Larman)
-# Inputs:  $1 = tier string
-# Outputs: stdout normalized tier; stderr usage on error
-# Exit:    0 valid, 2 invalid or missing
-# ---------------------------------------------------------------------------
-parse_tier_arg() {
-  local tier="${1:-}"
-  if [ -z "$tier" ]; then
-    echo "Usage: parse_tier_arg <tier>" >&2
-    echo "  tier: one of lite | standard | standard-pro | ultra | upstream" >&2
-    return 2
-  fi
-  case "$tier" in
-    lite|standard|standard-pro|ultra|upstream)
-      echo "$tier"
-      return 0
-      ;;
-    *)
-      echo "parse_tier_arg: invalid tier '$tier'" >&2
-      echo "  expected one of lite | standard | standard-pro | ultra | upstream" >&2
-      return 2
-      ;;
-  esac
-}
-
-# ---------------------------------------------------------------------------
-# parse_tier_list_arg — Parse combined-tier arg into a list
-# Per ADR-052 D5. Accepts "all" (expands to 5 tiers) OR a comma list
-# (e.g., "lite,standard"). Single tier also accepted for uniform callers.
-# Interface: ITierListParser (Larman)
-# Inputs:  $1 = arg string (all | tier | tier,tier[,...])
-# Outputs: stdout: one tier per line; stderr usage on error
-# Exit:    0 valid, 2 invalid or missing (empty, unknown tier, or mixed "all,X")
-# ---------------------------------------------------------------------------
-parse_tier_list_arg() {
-  local arg="${1:-}"
-  if [ -z "$arg" ]; then
-    echo "Usage: parse_tier_list_arg <arg>" >&2
-    echo "  arg: 'all' | <tier> | <tier>,<tier>[,...]" >&2
-    echo "  tier: one of lite | standard | standard-pro | ultra | upstream" >&2
-    return 2
-  fi
-  # 'all' expands to the 5 canonical tiers; must be alone, not mixed.
-  if [ "$arg" = "all" ]; then
-    printf "lite\nstandard\nstandard-pro\nultra\nupstream\n"
-    return 0
-  fi
-  # Reject mixed "all,X" or "X,all"
-  case ",$arg," in
-    *,all,*)
-      echo "parse_tier_list_arg: 'all' cannot be mixed with tier names" >&2
-      return 2
-      ;;
-  esac
-  # Split on comma; validate each; dedupe via sort -u
-  local tmp
-  tmp="$(mktemp)"
-  local item
-  local IFS=','
-  # shellcheck disable=SC2086
-  for item in $arg; do
-    case "$item" in
-      lite|standard|standard-pro|ultra|upstream)
-        echo "$item" >> "$tmp"
-        ;;
-      *)
-        echo "parse_tier_list_arg: invalid tier '$item'" >&2
-        echo "  expected one of lite | standard | standard-pro | ultra | upstream" >&2
-        rm -f "$tmp"
-        return 2
-        ;;
-    esac
-  done
-  sort -u "$tmp"
-  rm -f "$tmp"
-  return 0
-}
-
-# ---------------------------------------------------------------------------
-# read_intended_source_1 — files carrying tier: <tier> frontmatter or header
-# Interface: IIntendedSourceReader (Larman)
-# Inputs:  $1 = tier
-# Outputs: stdout: one path per line, sorted-unique
-#          stderr: "Source 1: <N> files" per D4 observability
-# Exit:    0
-# ---------------------------------------------------------------------------
-read_intended_source_1() {
-  local tier="$1"
-  local out
-  out="$({
-    git grep -l "^tier: ${tier}$" -- '*.md' 2>/dev/null || true
-    git grep -l "^# tier: ${tier}$" -- '*.sh' 2>/dev/null || true
-  } | sort -u)"
-  local count
-  count="$(echo "$out" | grep -c . 2>/dev/null || echo 0)"
-  echo "Source 1 (tagged): $count files" >&2
-  if [ -n "$out" ]; then
-    echo "$out"
-  fi
-  return 0
-}
-
-# ---------------------------------------------------------------------------
-# extract_references — parse references from a file
-# Interface: IReferenceExtractor (Larman); Strategy per D3
-# Inputs:  $1 = file path
-# Outputs: stdout: one target path per line
-# Exit:    0 (missing file returns empty, no error)
-# ---------------------------------------------------------------------------
-extract_references() {
-  local f="$1"
-  [ -f "$f" ] || return 0
-  local entry kind pattern extractor
-  for entry in "${REFERENCE_KINDS[@]}"; do
-    IFS='|' read -r kind pattern extractor <<< "$entry"
-    "$extractor" "$f" 2>/dev/null || true
-  done
-}
-
-# Reference extractors (one per REFERENCE_KIND row)
-_extract_composes_with() {
-  local f="$1"
-  # composes_with: [alpha, beta] OR composes_with: alpha
-  awk '
-    /^composes_with:/ {
-      line=$0
-      sub(/^composes_with:[[:space:]]*\[?/, "", line)
-      sub(/\].*$/, "", line)
-      gsub(/[[:space:]]/, "", line)
-      n = split(line, arr, ",")
-      for (i = 1; i <= n; i++) if (arr[i] != "") print ".claude/skills/" arr[i] "/SKILL.md"
-    }
-  ' "$f"
-}
-
-_extract_source_lib() {
-  local f="$1"
-  # grep -oE is more portable than BSD awk match() for this pattern
-  grep -oE 'lib/[a-zA-Z0-9._/-]+\.sh' "$f" 2>/dev/null | sort -u
-}
-
-_extract_additional_directories() {
-  local f="$1"
-  awk '
-    /additionalDirectories/ {
-      # Best-effort — grep the values on the same or nearby lines
-      match($0, /"[^"]+"/)
-      while (RSTART > 0) {
-        val = substr($0, RSTART + 1, RLENGTH - 2)
-        if (val ~ /\//) print val
-        s = substr($0, RSTART + RLENGTH)
-        $0 = s
-        match($0, /"[^"]+"/)
-      }
-    }
-  ' "$f"
-}
-
-_extract_bash_scripts() {
-  local f="$1"
-  # G1 fix (goal 2026-08-21b): BSD awk match+substr unreliable on macOS
-  # per memory feedback_grep_oE_beats_bsd_awk_match_for_portability.
-  # Replace with grep -oE + sed prefix strip; keeps the "bash scripts/*"
-  # invocation constraint (mere mention of scripts/foo.sh in prose is
-  # NOT a runtime edge; the "bash " prefix marks actual invocation).
-  grep -oE 'bash[[:space:]]+scripts/[a-zA-Z0-9._/-]+\.sh' "$f" 2>/dev/null | \
-    sed -E 's/^bash[[:space:]]+//' | sort -u
-}
-
-_extract_luminary_ref() {
-  local f="$1"
-  awk '
-    {
-      s = $0
-      while (match(s, /@luminary[[:space:]]+[a-z][a-z0-9-]+/)) {
-        val = substr(s, RSTART, RLENGTH)
-        sub(/@luminary[[:space:]]+/, "", val)
-        print ".claude/luminaries/" val ".md"
-        s = substr(s, RSTART + RLENGTH)
-      }
-    }
-  ' "$f"
-}
-
-_extract_standards_ref() {
-  local f="$1"
-  # grep -oE more portable than BSD awk match() loops
-  grep -oE 'standards/[a-zA-Z0-9._/-]+\.md' "$f" 2>/dev/null | sort -u
-}
-
-_extract_rules_ref() {
-  local f="$1"
-  grep -oE '\.claude/rules/[a-zA-Z0-9._/-]+\.md' "$f" 2>/dev/null | sort -u
-}
-
-# G4a extractor (goal 2026-08-21b Step 3): JSONC config reads
-# Matches `.claude/bassclef-configs.jsonc` OR bare `bassclef-configs.jsonc`;
-# normalizes both to the canonical substrate path so the walk finds the
-# same target regardless of how the caller wrote it.
-_extract_jsonc_config() {
-  local f="$1"
-  grep -oE '(\.claude/)?bassclef-configs\.jsonc' "$f" 2>/dev/null | \
-    sed -E 's|^bassclef-configs\.jsonc$|.claude/bassclef-configs.jsonc|' | \
-    sort -u
-}
-
-# G4b extractor (goal 2026-08-21b Step 4): hook references
-# Matches `.claude/hooks/<path>.sh` anywhere in a file. Primary use case:
-# YAML workflow refs (GitHub Actions call hooks via bash + shell steps),
-# but also catches doc mentions + settings.json wiring references.
-_extract_hook_ref() {
-  local f="$1"
-  grep -oE '\.claude/hooks/[a-zA-Z0-9._/-]+\.sh' "$f" 2>/dev/null | sort -u
-}
-
-# G4d extractors (goal 2026-08-21b Step 5): marker + state file reads
-# Marker edges: hooks read state/markers/**/*.marker to gate behavior
-# (temperance markers, luminary markers, etc). State-file edges: hooks
-# read state/*.json (state-spine entities like whereami.json, session
-# markers). Adopter runtime state edge class per gap analysis G4d.
-_extract_marker_ref() {
-  local f="$1"
-  grep -oE 'state/markers/[a-zA-Z0-9._/-]+\.marker' "$f" 2>/dev/null | sort -u
-}
-
-_extract_state_file_read() {
-  local f="$1"
-  grep -oE 'state/[a-zA-Z0-9._/-]+\.json' "$f" 2>/dev/null | sort -u
-}
-
-# G4c extractor (goal 2026-08-22a Step 1; ticket #1353): template references
-# Matches `templates/<name>.<ext>` where ext is md/yml/yaml/json. Templates
-# live at repo root under templates/ per `ls templates/` (21 files as of
-# 2026-08-22). Same shape as _extract_hook_ref pattern per G4b (PR #1347).
-_extract_template_ref() {
-  local f="$1"
-  grep -oE 'templates/[a-zA-Z0-9._/-]+\.(md|yml|yaml|json)' "$f" 2>/dev/null | sort -u
-}
-
-# G4e extractor (goal 2026-08-22a Step 2; ticket #1354): Python script refs
-# Matches `scripts/<name>.py` anywhere. Covers bare mentions, `python3
-# scripts/foo.py` invocations, and cross-refs from docs. ~30 Python
-# scripts live under scripts/ per `ls scripts/*.py`. Same shape as G4b.
-_extract_python_script() {
-  local f="$1"
-  grep -oE 'scripts/[a-zA-Z0-9._/-]+\.py' "$f" 2>/dev/null | sort -u
-}
-
-# G4f extractor (goal 2026-08-22a Step 3; ticket #1355): allowlist txt refs
-# Matches `.claude/hooks/<...>-allowlist.txt`. 10 allowlist files exist
-# under .claude/hooks/. Pattern requires the `-allowlist.txt` suffix so
-# we do not match plain .txt files (docs, fixtures). Same grep shape as
-# G4b hook-ref.
-_extract_allowlist_ref() {
-  local f="$1"
-  grep -oE '\.claude/hooks/[a-zA-Z0-9._/-]*-allowlist\.txt' "$f" 2>/dev/null | sort -u
-}
-
-# C0 circuit-breaker (goal 2026-08-22a Step 4; ticket #1356): detect
-# reference-shaped strings in a file that no registered extractor caught.
-# Silent-skip cure — the walker cannot tell "no reference exists" from
-# "extractor missing". This function surfaces the gap.
-#
-# V1 narrow scope: function + Tier 0 tests only. Runner + CI hook wire
-# deferred to Phase 2 (follow-on ticket).
-#
-# Candidate pattern matches any path-shaped string with a file extension:
-# starts with letter or dot, has one or more path parts joined by /, ends
-# with .<lowercase-ext>. Then diffs against what registered extractors
-# returned via extract_references(). Difference = unhandled.
-#
-# Per @luminary michael-feathers — characterization test for the walker's
-# coverage gap. Per @luminary saltzer-schroeder — fail-safe: silent skip
-# becomes surfaced signal.
-_detect_unhandled_references() {
-  local f="$1"
-  [ -f "$f" ] || return 0
-  local candidates handled
-  candidates="$(grep -oE '[.a-zA-Z][.a-zA-Z0-9_-]*/[.a-zA-Z0-9_/-]+\.[a-z]+' "$f" 2>/dev/null | sort -u)"
-  [ -z "$candidates" ] && return 0
-  handled="$(extract_references "$f" 2>/dev/null | sort -u)"
-  comm -23 <(echo "$candidates") <(echo "$handled")
-}
-
-# ---------------------------------------------------------------------------
-# walk_graph_bfs — BFS from seed set using an extractor function
-# Interface: IGraphWalker (Larman)
-# Inputs:  $1 = seeds file, $2 = extractor function name
-# Outputs: stdout: reachable paths, sorted-unique
-# Exit:    0
-# Cycle protection: visited set prevents re-processing
-# ---------------------------------------------------------------------------
-walk_graph_bfs() {
-  local seeds_file="$1"
-  local extractor="$2"
-  local visited_file queue_file
-  visited_file="$(mktemp)"
-  queue_file="$(mktemp)"
-  trap 'rm -f "$visited_file" "$queue_file"' RETURN
-
-  # Seed the queue
-  if [ -s "$seeds_file" ]; then
-    cp "$seeds_file" "$queue_file"
-  fi
-
-  local max_iter=1000 iter=0
-  while [ -s "$queue_file" ] && [ "$iter" -lt "$max_iter" ]; do
-    iter=$((iter + 1))
-    local next_file; next_file="$(mktemp)"
-    while IFS= read -r path; do
-      [ -z "$path" ] && continue
-      # Skip if visited
-      if grep -Fxq "$path" "$visited_file" 2>/dev/null; then
-        continue
-      fi
-      echo "$path" >> "$visited_file"
-      # Extract references from this file
-      "$extractor" "$path" 2>/dev/null | while IFS= read -r ref; do
-        [ -n "$ref" ] && echo "$ref" >> "$next_file"
-      done
-    done < "$queue_file"
-    mv "$next_file" "$queue_file"
-    sort -u -o "$queue_file" "$queue_file"
-  done
-
-  sort -u "$visited_file"
-  return 0
-}
-
-# ---------------------------------------------------------------------------
-# read_runtime_deps — parse tier-runtime-deps fenced block, expand globs
-# Interface: IRuntimeDepsReader (Larman)
-# Per goal 08-17d Session 1b Step 2.5 — extended with glob expansion so a
-# single pattern (e.g., state/luminary-implementations/*.json) covers auto-
-# generated file sets the graph walk cannot reach.
-# Inputs:  $1 = runtime-deps file path
-# Outputs: stdout: one path per line (globs expanded relative to repo root
-#          via git ls-files; literal paths passed through)
-#          stderr: "Source 3: <N> files" per D4 observability
-# Exit:    0 pass, 3 missing file
-# ---------------------------------------------------------------------------
-read_runtime_deps() {
-  local f="$1"
-  if [ ! -f "$f" ]; then
-    echo "read_runtime_deps: runtime-deps file not found at $f" >&2
-    return 3
-  fi
-  # Parse the fenced block, expand each line
-  local expanded
-  expanded="$(
-    awk '
-      /^```/ { in_block = !in_block; next }
-      in_block && !/^[[:space:]]*(#|$)/ { print }
-    ' "$f" | while IFS= read -r line; do
-      [ -z "$line" ] && continue
-      if [[ "$line" == *"*"* ]]; then
-        # Glob — expand via git ls-files (respects .gitignore)
-        git -C "$_TIER_AUDIT_REPO_ROOT" ls-files -- "$line" 2>/dev/null || true
-      else
-        printf "%s\n" "$line"
-      fi
-    done
-  )"
-  local count
-  count="$(echo "$expanded" | grep -c . 2>/dev/null || echo 0)"
-  echo "Source 3 (runtime deps): $count files" >&2
-  if [ -n "$expanded" ]; then
-    echo "$expanded"
-  fi
-  return 0
-}
-
-# ---------------------------------------------------------------------------
-# read_actual_source — invoke release-script dry-run + parse include list
-# Interface: IActualSourceReader (Larman); Adapter for external cmd
-# Inputs:  $1 = tier
-# Outputs: stdout: release-script include list, sorted-unique
-#          stderr: "Source 4: <N> files" per D4 observability
-# Exit:    0 pass, 4 release script failure
-# ---------------------------------------------------------------------------
-read_actual_source() {
-  local tier="$1"
-  local release_script
-  release_script="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)/scripts/release-to-bassclef.sh"
-  if [ ! -x "$release_script" ]; then
-    echo "read_actual_source: release script not found or not executable at $release_script" >&2
-    return 4
-  fi
-  # Real-mode: invoke dry-run with INCLUDE_LIST_OUT hook.
-  # The release script writes the include list to $INCLUDE_LIST_OUT after
-  # building it, before its BLOCK gates fire (sync-delete threshold, andon).
-  # This means we get the include list even when the release would fail
-  # for reasons unrelated to file inclusion — exactly the case for tier audits
-  # (we WANT to know what's shipping even if release is blocked).
-  # Bypasses: SKIP_PRIOR_PR_CHECK (audit doesn't care about prior PRs)
-  #           SYNC_DELETE=0 (audit computes bucket 3 itself)
-  local include_out
-  include_out="$(mktemp)"
-  INCLUDE_LIST_OUT="$include_out" \
-    SKIP_PRIOR_PR_CHECK=1 SYNC_DELETE=0 \
-    "$release_script" --dry-run --supersede >/dev/null 2>&1 || true
-  # Even if the release script exits non-zero (BLOCKed at andon or tag-exists),
-  # INCLUDE_LIST_OUT should be populated if the pipeline reached the file-list build.
-  if [ ! -s "$include_out" ]; then
-    echo "read_actual_source: release script did not produce include list at $include_out" >&2
-    rm -f "$include_out"
-    return 4
-  fi
-  local out; out="$(sort -u "$include_out")"
-  rm -f "$include_out"
-  local count
-  count="$(echo "$out" | grep -c . 2>/dev/null || echo 0)"
-  echo "Source 4 (release include): $count files" >&2
-  if [ -n "$out" ]; then
-    echo "$out"
-  fi
-  return 0
-}
-
-# ---------------------------------------------------------------------------
-# classify_files — assign each file to bucket 1-4
-# Interface: IClassifier (Larman); pure function
-# Inputs:  $1 = intended file, $2 = actual file, $3 = tags file (path\ttier),
-#          $4 = out-dir, $5 = tier
-# Outputs: writes 4 bucket files to out-dir
-# Exit:    0
-# ---------------------------------------------------------------------------
-classify_files() {
-  local intended="$1" actual="$2" tags="$3" out_dir="$4" tier="$5"
-  mkdir -p "$out_dir"
-  local bucket_1="$out_dir/bucket-1.txt"
-  local bucket_2a="$out_dir/bucket-2a.txt"
-  local bucket_2b="$out_dir/bucket-2b.txt"
-  local bucket_3="$out_dir/bucket-3.txt"
-  local bucket_4="$out_dir/bucket-4.txt"
-  : > "$bucket_1"; : > "$bucket_2a"; : > "$bucket_2b"
-  : > "$bucket_3"; : > "$bucket_4"
-
-  # Sort inputs for comm
-  local intended_sorted actual_sorted
-  intended_sorted="$(mktemp)"; actual_sorted="$(mktemp)"
-  sort -u "$intended" > "$intended_sorted"
-  sort -u "$actual" > "$actual_sorted"
-
-  # Bucket 1 + Bucket 2a + Bucket 2b — split intersection by tag state.
-  # Per ADR-043 D1 + docs/canvases/2026-07-19-bassclef-lite.md L76:
-  #   tag == target tier   → bucket 1 (ships correctly in this tier)
-  #   no tag at all        → bucket 2a (safe mechanical tag)
-  #   tag == other tier    → bucket 2b (chain-snap risk; per-file cure)
-  comm -12 "$intended_sorted" "$actual_sorted" | while IFS= read -r path; do
-    # Look up tag for path in tags file. Returns "" for untagged (no tab)
-    # or missing entry; returns tier value when tagged.
-    local file_tag
-    file_tag="$(awk -F'\t' -v p="$path" '$1 == p { print ($2 ? $2 : ""); exit }' "$tags")"
-    if [ "$file_tag" = "$tier" ]; then
-      echo "$path" >> "$bucket_1"
-    elif [ -z "$file_tag" ]; then
-      echo "$path" >> "$bucket_2a"
-    else
-      echo "$path" >> "$bucket_2b"
-    fi
-  done
-
-  # Bucket 3 — ACTUAL \ INTENDED
-  comm -23 "$actual_sorted" "$intended_sorted" > "$bucket_3"
-
-  # Bucket 4 — INTENDED \ ACTUAL
-  comm -13 "$actual_sorted" "$intended_sorted" > "$bucket_4"
-
-  rm -f "$intended_sorted" "$actual_sorted"
-  return 0
-}
-
-# ---------------------------------------------------------------------------
-# classify_files_combined — assign each file to bucket 1-4 under combined-tier
-# Per ADR-052 D5. INTENDED is the union of all named tiers' INTENDED sets.
-# The 2a/2b split disappears — combined mode does not distinguish "tagged for
-# a different tier" because in combined mode, that tag IS the file's home in
-# the union.
-# Interface: IClassifierCombined (Larman); pure function
-# Inputs:  $1 = intended file (union across tiers), $2 = actual file,
-#          $3 = tags file (path\ttier), $4 = out-dir
-# Outputs: writes 4 bucket files to out-dir (bucket-1, bucket-2, bucket-3, bucket-4)
-# Exit:    0
-# ---------------------------------------------------------------------------
-classify_files_combined() {
-  local intended="$1" actual="$2" tags="$3" out_dir="$4"
-  mkdir -p "$out_dir"
-  local bucket_1="$out_dir/bucket-1.txt"
-  local bucket_2="$out_dir/bucket-2.txt"
-  local bucket_3="$out_dir/bucket-3.txt"
-  local bucket_4="$out_dir/bucket-4.txt"
-  : > "$bucket_1"; : > "$bucket_2"
-  : > "$bucket_3"; : > "$bucket_4"
-
-  local intended_sorted actual_sorted
-  intended_sorted="$(mktemp)"; actual_sorted="$(mktemp)"
-  sort -u "$intended" > "$intended_sorted"
-  sort -u "$actual" > "$actual_sorted"
-
-  # Bucket 1 + Bucket 2 — split intersection by tag presence.
-  # In combined mode, ANY non-empty tag places the file in bucket 1.
-  comm -12 "$intended_sorted" "$actual_sorted" | while IFS= read -r path; do
-    local file_tag
-    file_tag="$(awk -F'\t' -v p="$path" '$1 == p { print ($2 ? $2 : ""); exit }' "$tags")"
-    if [ -n "$file_tag" ]; then
-      echo "$path" >> "$bucket_1"
-    else
-      echo "$path" >> "$bucket_2"
-    fi
-  done
-
-  # Bucket 3 — ACTUAL \ INTENDED_ALL (true accidental leaks)
-  comm -23 "$actual_sorted" "$intended_sorted" > "$bucket_3"
-
-  # Bucket 4 — INTENDED_ALL \ ACTUAL (missing from release)
-  comm -13 "$actual_sorted" "$intended_sorted" > "$bucket_4"
-
-  rm -f "$intended_sorted" "$actual_sorted"
-  return 0
-}
-
-# ---------------------------------------------------------------------------
-# write_manifest — emit markdown from bucket files
-# Interface: IManifestWriter (Larman)
-# Inputs:  $1 = bucket dir (contains bucket-N.txt), $2 = date, $3 = tier,
-#          $4 = output path
-# Outputs: writes manifest file at $4
-# Exit:    0 pass, 5 dir not writable
-# ---------------------------------------------------------------------------
-write_manifest() {
-  local bucket_dir="$1" date="$2" tier="$3" outfile="$4"
-  local out_parent; out_parent="$(dirname "$outfile")"
-  mkdir -p "$out_parent" 2>/dev/null || { echo "write_manifest: cannot create $out_parent" >&2; return 5; }
-  local c1 c2a c2b c3 c4
-  c1="$(wc -l < "$bucket_dir/bucket-1.txt" 2>/dev/null | tr -d ' ')"
-  c2a="$(wc -l < "$bucket_dir/bucket-2a.txt" 2>/dev/null | tr -d ' ')"
-  c2b="$(wc -l < "$bucket_dir/bucket-2b.txt" 2>/dev/null | tr -d ' ')"
-  c3="$(wc -l < "$bucket_dir/bucket-3.txt" 2>/dev/null | tr -d ' ')"
-  c4="$(wc -l < "$bucket_dir/bucket-4.txt" 2>/dev/null | tr -d ' ')"
-  {
-    echo "---"
-    echo "tier_audit: ${tier}"
-    echo "generated_at: ${date}"
-    echo "---"
-    echo ""
-    echo "# Tier-dependency audit — ${tier} — ${date}"
-    echo ""
-    echo "Per standards/tier-dependency-analysis.md. Five-bucket classification (Bucket 2 split into 2a + 2b per ADR-043 D1 + canvas 2026-07-19-bassclef-lite.md L76)."
-    echo ""
-    echo "## Summary"
-    echo ""
-    echo "Bucket 1 (Tagged; ships correctly): ${c1:-0}"
-    echo "Bucket 2a (No tag; safe mechanical tag): ${c2a:-0}"
-    echo "Bucket 2b (Chain-snap risk; tagged non-${tier}; needs per-file cure): ${c2b:-0}"
-    echo "Bucket 3 (Accidental leak; needs removal): ${c3:-0}"
-    echo "Bucket 4 (Missing from release; needs release fix): ${c4:-0}"
-    echo ""
-    for i in 1 2a 2b 3 4; do
-      local label file
-      file="$bucket_dir/bucket-${i}.txt"
-      case "$i" in
-        1) label="Bucket 1 — Tagged (ships correctly)" ;;
-        2a) label="Bucket 2a — Missing tag (no tier tag; safe mechanical add)" ;;
-        2b) label="Bucket 2b — Chain-snap risk (tagged non-${tier}; per-file cure per canvas Q1+Q2)" ;;
-        3) label="Bucket 3 — Accidental leak (in release but not in graph)" ;;
-        4) label="Bucket 4 — Missing from release (in graph but not in release)" ;;
-      esac
-      echo "## ${label}"
-      echo ""
-      if [ -s "$file" ]; then
-        sort "$file" | sed 's/^/- /'
-      else
-        echo "_(empty)_"
-      fi
-      echo ""
-    done
-    echo "## Recommended fix order"
-    echo ""
-    echo "1. Fix Bucket 4 first (release script gap; may hide legit ships)"
-    echo "2. Fix Bucket 2a (mechanical tag; safe helper at scripts/apply-bucket2-tier-tags.sh)"
-    echo "3. Review Bucket 2b (per-file: promote to ${tier}, inline into caller, or determine graph over-included)"
-    echo "4. Fix Bucket 3 (remove accidental leaks + extend .gitignore)"
-  } > "$outfile"
-  return 0
-}
-
-# ---------------------------------------------------------------------------
-# write_manifest_combined — emit markdown for combined-tier audit
-# Per ADR-052 D5. 4 buckets (no 2a/2b split); header names the tier list.
-# Interface: IManifestWriterCombined (Larman)
-# Inputs:  $1 = bucket dir (contains bucket-1.txt, bucket-2.txt, bucket-3.txt, bucket-4.txt),
-#          $2 = date, $3 = tier list string (e.g., "lite,standard" or "all"),
-#          $4 = output path
-# Outputs: writes manifest file at $4
-# Exit:    0 pass, 5 dir not writable
-# ---------------------------------------------------------------------------
-write_manifest_combined() {
-  local bucket_dir="$1" date="$2" tier_list="$3" outfile="$4"
-  local out_parent; out_parent="$(dirname "$outfile")"
-  mkdir -p "$out_parent" 2>/dev/null || { echo "write_manifest_combined: cannot create $out_parent" >&2; return 5; }
-  local c1 c2 c3 c4
-  c1="$(wc -l < "$bucket_dir/bucket-1.txt" 2>/dev/null | tr -d ' ')"
-  c2="$(wc -l < "$bucket_dir/bucket-2.txt" 2>/dev/null | tr -d ' ')"
-  c3="$(wc -l < "$bucket_dir/bucket-3.txt" 2>/dev/null | tr -d ' ')"
-  c4="$(wc -l < "$bucket_dir/bucket-4.txt" 2>/dev/null | tr -d ' ')"
-  {
-    echo "---"
-    echo "tier_audit: combined"
-    echo "tier_list: ${tier_list}"
-    echo "generated_at: ${date}"
-    echo "---"
-    echo ""
-    echo "# Tier-dependency audit — combined-tier (${tier_list}) — ${date}"
-    echo ""
-    echo "Per standards/tier-dependency-analysis.md § Combined-tier mode + ADR-052 D5. Four-bucket classification against the union of the named tiers' INTENDED sets. No 2a/2b split — in combined mode any tier tag is legit."
-    echo ""
-    echo "## Summary"
-    echo ""
-    echo "Bucket 1 (Tagged for any tier in list; ships correctly): ${c1:-0}"
-    echo "Bucket 2 (No tag; needs per-tier assignment): ${c2:-0}"
-    echo "Bucket 3 (True accidental leak; not in any tier's graph; needs removal): ${c3:-0}"
-    echo "Bucket 4 (In graph but not in release; needs release fix): ${c4:-0}"
-    echo ""
-    local i label file
-    for i in 1 2 3 4; do
-      file="$bucket_dir/bucket-${i}.txt"
-      case "$i" in
-        1) label="Bucket 1 — Tagged for a tier in the list (ships correctly)" ;;
-        2) label="Bucket 2 — No tag (needs per-tier assignment)" ;;
-        3) label="Bucket 3 — True accidental leak (in release but no tier's graph pulls it in)" ;;
-        4) label="Bucket 4 — Missing from release (in some tier's graph but release script drops it)" ;;
-      esac
-      echo "## ${label}"
-      echo ""
-      if [ -s "$file" ]; then
-        sort "$file" | sed 's/^/- /'
-      else
-        echo "_(empty)_"
-      fi
-      echo ""
-    done
-    echo "## Recommended fix order"
-    echo ""
-    echo "1. Fix Bucket 4 first (release script gap; may hide legit ships across tiers)"
-    echo "2. Fix Bucket 3 (remove true accidental leaks + extend .gitignore) — this is the class combined mode was built to identify safely"
-    echo "3. Assign Bucket 2 files to a tier (operator per-file review)"
-  } > "$outfile"
-  return 0
-}
-
-# ===========================================================================
-# TIER GRAPH-CLOSURE EXTENSION (goal 2026-08-21a)
-# ===========================================================================
-# Extends the outbound BFS + tag reader with:
-#   - build_reverse_index         — path → callers map (for inbound walk)
-#   - walk_graph_bfs_inbound      — reverse BFS using the reverse index
-#   - compute_kind_coverage       — per REFERENCE_KIND edge count
-#   - _extract_schema_ref         — new REFERENCE_KIND for JSON schema $ref
-#   - read_intended_source_1_extended — extends tag reader to .json/.jsonc/.yml/.py
-#
-# Anchor luminaries:
-#   @luminary hunt-thomas  — DRY (graph as single source of truth for tier);
-#                            orthogonality (each new function independent);
-#                            tracer bullets (thin end-to-end first)
-#   @luminary alistair-cockburn — walking skeleton; hexagonal (extractors as
-#                            adapters plugging into central BFS core)
-# ---------------------------------------------------------------------------
-
-# ---------------------------------------------------------------------------
-# _is_substrate_relevant_path — filter for closure computation (G3 cure)
-# Interface: IPathFilter (Larman); pure predicate
-# Inputs:  $1 = path
-# Outputs: exit 0 (pass) if substrate-relevant; exit 1 (skip) otherwise
-#
-# Rejects paths that pollute the mismatch report per goal 2026-08-21b Step 2:
-#   - absolute paths + parent-relative (sibling repos via symlinks)
-#   - .git internals
-#   - runner's own output (state/tier-graph-closure/*)
-#   - transient session-state markers (intent-drift-session, turn-*, session-timing)
-#   - SDLC trace logs
-# ---------------------------------------------------------------------------
-_is_substrate_relevant_path() {
-  local path="$1"
-  # Normalize leading ./ prefix so patterns match consistently.
-  # Closure files mix "./foo" (from find) with "foo" (from git grep).
-  # Per #1385 walker cure — extends G3 filter beyond initial pattern set.
-  path="${path#./}"
-  case "$path" in
-    /*|../*|.git/*|*/.git/*) return 1 ;;
-    # Runtime state — walker outputs + gate markers + session state + analysis.
-    # None ship to adopters regardless of tier tag. Per #1385.
-    # Recursive state/* pattern covers all subtrees + root-level state files.
-    # lite-manifest.json + standard-manifest.json + ultra-manifest.json live at
-    # repo root, NOT state/, so this pattern is safe for shipping artifacts.
-    state/*) return 1 ;;
-    docs/sdlc-traces/*) return 1 ;;
-    docs/preview-state/*) return 1 ;;
-    # Per #1385 phase 2 — mirror tier-tag-required-at-write allowlist for
-    # test fixtures (never ship; exempt from tags) + prototype galleries (dev
-    # artifacts) + chronicles (gitignored session logs) + sibling-repo mirrors.
-    .claude/hooks/tests/fixtures/*) return 1 ;;
-    .claude/skills/*/tests/fixtures/*) return 1 ;;
-    lib/tests/fixtures/*) return 1 ;;
-    scripts/tests/fixtures/*) return 1 ;;
-    docs/prototypes/*) return 1 ;;
-    chronicle/*) return 1 ;;
-    docs/chronicle/*) return 1 ;;
-    docs/confirmed-archive/*) return 1 ;;
-    bassclef/*) return 1 ;;
-  esac
-  return 0
-}
-
-# ---------------------------------------------------------------------------
-# build_reverse_index — for each seed path, find files that reference it
-# Interface: IReverseIndexBuilder (Larman)
-# Inputs:  $1 = seeds file (one path per line), $2 = out file
-# Outputs: writes "<seed_path>\t<caller_path>" per finding
-# Exit:    0
-# Tier-blind — caller passes any tier's seed set
-# G3 cure (goal 2026-08-21b Step 2): callers filtered via
-#   _is_substrate_relevant_path to keep only substrate-relevant paths.
-# ---------------------------------------------------------------------------
-build_reverse_index() {
-  local seeds_file="$1"
-  local out_file="$2"
-  : > "$out_file"
-  [ ! -s "$seeds_file" ] && return 0
-  while IFS= read -r seed; do
-    [ -z "$seed" ] && continue
-    # Escape seed for grep. Use fixed-string search since paths are literal.
-    # git grep first (respects .gitignore); fallback to plain grep if not in a repo.
-    local matches
-    matches="$(git grep -lF "$seed" 2>/dev/null || grep -rlF "$seed" . 2>/dev/null)"
-    while IFS= read -r caller; do
-      [ -z "$caller" ] && continue
-      # Skip self-reference (a file referencing its own path is not a caller)
-      [ "$caller" = "$seed" ] && continue
-      # G3 cure: filter noise paths
-      _is_substrate_relevant_path "$caller" || continue
-      # Emit seed\tcaller
-      printf "%s\t%s\n" "$seed" "$caller" >> "$out_file"
-    done <<< "$matches"
-  done < "$seeds_file"
-  return 0
-}
-
-# ---------------------------------------------------------------------------
-# walk_graph_bfs_inbound — reverse BFS from seed set using a reverse index
-# Interface: IInboundGraphWalker (Larman)
-# Inputs:  $1 = seeds file, $2 = reverse index file (from build_reverse_index)
-# Outputs: stdout: reachable-inbound paths, sorted-unique
-# Exit:    0
-# Cycle protection: visited set prevents re-processing (same as forward walk)
-# ---------------------------------------------------------------------------
-walk_graph_bfs_inbound() {
-  local seeds_file="$1"
-  local rev_index="$2"
-  local visited_file="" queue_file=""
-  visited_file="$(mktemp)"
-  queue_file="$(mktemp)"
-  # shellcheck disable=SC2064
-  trap "rm -f '$visited_file' '$queue_file'" RETURN
-
-  if [ ! -s "$seeds_file" ]; then
-    : > "$visited_file"
-    sort -u "$visited_file"
-    return 0
-  fi
-  cp "$seeds_file" "$queue_file"
-
-  local max_iter=1000 iter=0
-  while [ -s "$queue_file" ] && [ "$iter" -lt "$max_iter" ]; do
-    iter=$((iter + 1))
-    local next_file; next_file="$(mktemp)"
-    while IFS= read -r path; do
-      [ -z "$path" ] && continue
-      if grep -Fxq "$path" "$visited_file" 2>/dev/null; then continue; fi
-      echo "$path" >> "$visited_file"
-      # Look up callers of $path in the reverse index (path is column 1; caller is column 2)
-      awk -F'\t' -v p="$path" '$1 == p { print $2 }' "$rev_index" | while IFS= read -r caller; do
-        [ -n "$caller" ] && echo "$caller" >> "$next_file"
-      done
-    done < "$queue_file"
-    mv "$next_file" "$queue_file"
-    sort -u -o "$queue_file" "$queue_file"
-  done
-
-  sort -u "$visited_file"
-  return 0
-}
-
-# ---------------------------------------------------------------------------
-# compute_kind_coverage — per REFERENCE_KIND edge count from a walk output
-# Interface: ICoverageCounter (Larman)
-# Inputs:  $1 = walk output file with rows shaped "<kind>\t<from>\t<to>",
-#          $2 = tier (used for report labeling)
-# Outputs: stdout: "<kind>\t<count>" per REFERENCE_KIND (0 for kinds not seen)
-# Exit:    0
-# ---------------------------------------------------------------------------
-compute_kind_coverage() {
-  local walk_file="$1"
-  local tier="$2"
-  # Derive known kinds from REFERENCE_KINDS at run time so new
-  # extractor rows automatically appear in coverage. Pre-fix this
-  # list was hardcoded and drifted from REFERENCE_KINDS — hook_ref
-  # existed as a walked kind but was missing from coverage output
-  # (bug 1 per docs/audits/2026-09-10-tier-graph-walk-miss.md).
-  # schema_ref is not in REFERENCE_KINDS but has its own extractor
-  # per _extract_schema_ref; keep it as a static append so schema
-  # coverage still emits.
-  local known_kinds=()
-  local entry name
-  for entry in "${REFERENCE_KINDS[@]}"; do
-    name="${entry%%|*}"
-    known_kinds+=("$name")
-  done
-  known_kinds+=("schema_ref")
-  local kind count
-  for kind in "${known_kinds[@]}"; do
-    count=0
-    if [ -s "$walk_file" ]; then
-      count="$(awk -F'\t' -v k="$kind" '$1 == k { c++ } END { print c+0 }' "$walk_file")"
-    fi
-    printf "%s\t%s\n" "$kind" "$count"
-  done
-  return 0
-}
-
-# ---------------------------------------------------------------------------
-# _extract_schema_ref — new REFERENCE_KIND for JSON schema $ref
-# Interface: IReferenceExtractor (Larman); Strategy per D3
-# Inputs:  $1 = file path (typically .json schema)
-# Outputs: stdout: resolved schema paths (one per line)
-# Exit:    0 (missing file returns empty, no error)
-# Handles: absolute refs like "path/to/schema.json"
-# Skips:   internal refs like "#/definitions/X" (JSON Pointer, not file ref)
-# ---------------------------------------------------------------------------
-_extract_schema_ref() {
-  local f="$1"
-  [ -f "$f" ] || return 0
-  # Grep $ref values. Skip refs starting with # (internal JSON Pointer).
-  grep -oE '"\$ref"[[:space:]]*:[[:space:]]*"[^"#][^"]*"' "$f" 2>/dev/null | \
-    sed -E 's/.*"\$ref"[[:space:]]*:[[:space:]]*"([^"]+)".*/\1/' | \
-    sort -u
-}
-
-# ---------------------------------------------------------------------------
-# read_intended_source_1_extended — extends tag reader to non-md/sh formats
-# Interface: IIntendedSourceReader (Larman); extension of read_intended_source_1
-# Inputs:  $1 = tier
-# Outputs: stdout: one path per line, sorted-unique
-#          stderr: "Source 1 (extended): <N> files"
-# Exit:    0
-# Covers ALL these tag shapes:
-#   .md      → YAML frontmatter tier: <tier>          (from original)
-#   .sh      → # tier: <tier>                         (from original)
-#   .json    → top-level "tier": "<tier>"             (new)
-#   .json    → "$comment": "tier: <tier>"             (new)
-#   .jsonc   → // tier: <tier>                         (new)
-#   .yml/yaml → # tier: <tier>                         (new)
-#   .py      → # tier: <tier>                         (new)
-# ---------------------------------------------------------------------------
-read_intended_source_1_extended() {
-  local tier="$1"
-  local out
-  out="$({
-    # Existing .md + .sh (mirror of read_intended_source_1)
-    git grep -l "^tier: ${tier}$" -- '*.md' 2>/dev/null || true
-    git grep -l "^# tier: ${tier}$" -- '*.sh' 2>/dev/null || true
-    # .json top-level "tier": "<tier>" — allow leading { or whitespace before "tier"
-    git grep -lE "\"tier\":[[:space:]]*\"${tier}\"" -- '*.json' 2>/dev/null || true
-    # .json "$comment": "tier: <tier>"
-    git grep -lE "\"\\\$comment\":[[:space:]]*\"tier:[[:space:]]*${tier}\"" -- '*.json' 2>/dev/null || true
-    # .jsonc // tier: <tier>
-    git grep -l "^// tier: ${tier}$" -- '*.jsonc' 2>/dev/null || true
-    # .yml/.yaml # tier: <tier> (comment or frontmatter shape)
-    git grep -l "^# tier: ${tier}$" -- '*.yml' '*.yaml' 2>/dev/null || true
-    git grep -l "^tier: ${tier}$" -- '*.yml' '*.yaml' 2>/dev/null || true
-    # .py # tier: <tier>
-    git grep -l "^# tier: ${tier}$" -- '*.py' 2>/dev/null || true
-  } | sort -u)"
-  local count
-  count="$(echo "$out" | grep -c . 2>/dev/null || echo 0)"
-  echo "Source 1 (extended): $count files" >&2
-  if [ -n "$out" ]; then echo "$out"; fi
-  return 0
-}
-
-# ---------------------------------------------------------------------------
-# G5 extension (goal 2026-09-09b): per-edge tier alignment check
-# Ships in PR-2 alongside Bug 1 fix for coverage reporter. Closes the
-# gap Shape e was designed to catch — SKILL body references to hooks
-# tagged at higher tier than the SKILL itself (broken adopter promise
-# per @luminary linus-torvalds and ADR-043 D1 concentric inclusion).
-# ---------------------------------------------------------------------------
-
-# _tier_rank_full — full 5-tier rank map per ADR-043 D1
-# lite < standard < standard-pro < ultra < upstream
-# Rank 0 for unknown or missing tier (treated as neutral).
-_tier_rank_full() {
-  case "$1" in
-    lite) echo 1 ;;
-    standard) echo 2 ;;
-    standard-pro) echo 3 ;;
-    ultra) echo 4 ;;
-    upstream) echo 5 ;;
-    *) echo 0 ;;
-  esac
-}
-
-# _read_file_tier — extract tier tag from a file
-# Mirrors scripts/release-to-bassclef.sh:read_tier per standards/tier-tag-schema.md
-# Returns tier name on stdout; empty when no tag present.
-_read_file_tier() {
-  local f="$1"
-  [ -f "$f" ] || return 0
-  case "$f" in
-    *.md)
-      awk '
-        BEGIN{infm=0}
-        NR==1 && /^---/ {infm=1; next}
-        infm && /^---/ {exit}
-        infm && /^tier:[[:space:]]/ {sub(/^tier:[[:space:]]*/,""); gsub(/[[:space:]]/,""); print; exit}
-      ' "$f"
-      ;;
-    *.sh|*.py)
-      head -5 "$f" | awk '/^# tier:[[:space:]]/ {sub(/^# tier:[[:space:]]*/,""); gsub(/[[:space:]]/,""); print; exit}'
-      ;;
-    *.yml|*.yaml)
-      head -5 "$f" | awk '
-        /^---/ {next}
-        /^# tier:[[:space:]]/ {sub(/^# tier:[[:space:]]*/,""); gsub(/[[:space:]]/,""); print; exit}
-        /^tier:[[:space:]]/ {sub(/^tier:[[:space:]]*/,""); gsub(/[[:space:]]/,""); print; exit}
-      '
-      ;;
-    *.jsonc)
-      head -5 "$f" | awk '/^\/\/ tier:[[:space:]]/ {sub(/^\/\/ tier:[[:space:]]*/,""); gsub(/[[:space:]]/,""); print; exit}'
-      ;;
-    *.json)
-      head -5 "$f" | awk '
-        /"tier":[[:space:]]*"[^"]+"/ {
-          match($0, /"tier":[[:space:]]*"[^"]+"/); s=substr($0, RSTART, RLENGTH);
-          gsub(/"tier":[[:space:]]*"/, "", s); gsub(/"$/, "", s);
-          print s; exit
-        }
-        /"_tier":[[:space:]]*"[^"]+"/ {
-          match($0, /"_tier":[[:space:]]*"[^"]+"/); s=substr($0, RSTART, RLENGTH);
-          gsub(/"_tier":[[:space:]]*"/, "", s); gsub(/"$/, "", s);
-          print s; exit
-        }
-      '
-      ;;
-    *) : ;;
-  esac
-}
-
-# check_tier_alignment_on_edges — per-edge tier alignment check
-# Interface: ITierAlignmentChecker (per Larman GRASP naming)
-# Inputs:  $1 = walk-with-kinds.tsv path (rows: <kind>\t<from>\t<to>)
-#          $2 = target tier (e.g. "lite")
-#          $3 = optional out-file for violation report (default: stdout)
-# Outputs: writes violations as "<kind>\t<from>\t<from-tier>\t<to>\t<to-tier>"
-# Exit:    0 always. Count of violations on final stderr line.
-# Rule:    ADR-043 D1 concentric inclusion — source tier T guarantees
-#          target tier <= T. When source has target tier AND target
-#          file has HIGHER tier rank, source's tier promise breaks.
-check_tier_alignment_on_edges() {
-  local walk_file="$1"
-  local target_tier="$2"
-  local out_file="${3:-/dev/stdout}"
-  [ -f "$walk_file" ] || { echo "check_tier_alignment_on_edges: walk file missing at $walk_file" >&2; return 1; }
-  local target_rank
-  target_rank="$(_tier_rank_full "$target_tier")"
-  [ "$target_rank" = "0" ] && { echo "check_tier_alignment_on_edges: unknown target tier '$target_tier'" >&2; return 1; }
-  # Optimization: cache tiers per unique file. Then use awk with an
-  # associative array for O(1) lookup during edge walk. Prior shape
-  # ran awk per edge lookup = O(edges * cache) ~ 10M ops on lite tier.
-  # Initialize local var so `set -u` callers do not trip on the trap
-  # when mktemp fails or the local declaration races against the trap.
-  local tier_cache=""
-  tier_cache="$(mktemp)" || tier_cache="/tmp/tier_cache_fallback_$$"
-  # shellcheck disable=SC2064
-  trap "rm -f '${tier_cache}'" RETURN
-  # First pass: collect unique files then read tier per file (bash loop).
-  local file tier
-  while IFS= read -r file; do
-    [ -n "$file" ] || continue
-    tier="$(_read_file_tier "$file" 2>/dev/null || true)"
-    printf "%s\t%s\n" "$file" "${tier:-none}"
-  done < <(awk -F'\t' '{print $2; print $3}' "$walk_file" | sort -u) > "$tier_cache"
-  # Second pass: awk-side associative array; single sweep of walk_file.
-  local violations
-  violations="$(awk -F'\t' \
-    -v target="$target_tier" \
-    -v target_rank="$target_rank" \
-    -v out="$out_file" \
-    -v cache="$tier_cache" '
-    BEGIN {
-      # Preload rank map
-      rank["lite"] = 1; rank["standard"] = 2; rank["standard-pro"] = 3;
-      rank["ultra"] = 4; rank["upstream"] = 5;
-      # Preload tier cache
-      while ((getline line < cache) > 0) {
-        n = split(line, parts, "\t")
-        if (n >= 2) tier_of[parts[1]] = parts[2]
-      }
-      close(cache)
-      v = 0
-      # Truncate out file
-      printf "" > out
-    }
-    {
-      kind = $1; from = $2; to = $3
-      if (kind == "" || from == "" || to == "") next
-      ft = tier_of[from]
-      tt = tier_of[to]
-      if (ft != target) next
-      tr = rank[tt] + 0
-      if (tr == 0) next
-      if (tr > target_rank) {
-        print kind "\t" from "\t" ft "\t" to "\t" tt >> out
-        v++
-      }
-    }
-    END { print v }
-  ' "$walk_file")"
-  echo "check_tier_alignment_on_edges: $violations violations for target_tier=$target_tier" >&2
-  return 0
-}