@thebassclef/lite 0.0.1 → 0.1.2

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

@@ -0,0 +1,1088 @@
+#!/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
+}