@thebassclef/lite 1.0.3 → 1.1.0

package/dist/lite/presence/install/schedule-auto-save.cron.sh

@@ -0,0 +1,88 @@
+#!/usr/bin/env bash
+# tier: lite
+# description: schedule-auto-save.cron.sh — install a cron entry that fires auto-save-idle.sh
+# schedule-auto-save.cron.sh — install a cron entry that fires auto-save-idle.sh
+#                              every 15 minutes on macOS + Linux + WSL.
+#
+# Per ADR-046 (cross-OS auto-save scheduling). Replaces the macOS-only
+# launchd path for adopters on Linux or WSL. Native Windows adopters
+# should read presence/install/schedule-auto-save.taskscheduler.md instead.
+#
+# Usage:
+#   bash presence/install/schedule-auto-save.cron.sh [path-to-hook]
+#
+# Default hook path: $HOME/src/sunj-labs/bassclef/.claude/hooks/auto-save-idle.sh
+#
+# The installer is idempotent — running twice does not add duplicate entries.
+# The installer writes to the current user's crontab (crontab -l | grep -v ...).
+#
+# Override paths:
+#   SKIP_CRON_INSTALL=1 — bypass the install (logged; no crontab change)
+#   BASSCLEF_HOOK_PATH  — override the default hook path
+#
+# Exit codes:
+#   0 = success (installed, updated, or already present)
+#   1 = cron not available or crontab command missing
+#   2 = hook file not found at target path
+#   3 = user cancelled or explicit skip
+
+set -euo pipefail
+
+BASSCLEF_HOOK_DEFAULT="$HOME/src/sunj-labs/bassclef/.claude/hooks/auto-save-idle.sh"
+HOOK_PATH="${1:-${BASSCLEF_HOOK_PATH:-$BASSCLEF_HOOK_DEFAULT}}"
+CRON_MARKER="# bassclef auto-save (ADR-046)"
+CRON_ENTRY="*/15 * * * * bash ${HOOK_PATH} >/dev/null 2>&1"
+
+echo "=== bassclef auto-save cron installer ==="
+echo "Hook path: ${HOOK_PATH}"
+
+# Override check
+if [ "${SKIP_CRON_INSTALL:-0}" = "1" ]; then
+  echo "SKIP_CRON_INSTALL=1 — skipping install (logged)"
+  exit 3
+fi
+
+# Check cron availability
+if ! command -v crontab >/dev/null 2>&1; then
+  echo "ERROR: crontab command not found. This installer needs cron."
+  echo "  - macOS: cron ships by default; check /usr/bin/crontab"
+  echo "  - Linux: install via 'apt install cron' or 'yum install cronie'"
+  echo "  - Native Windows: use presence/install/schedule-auto-save.taskscheduler.md instead"
+  exit 1
+fi
+
+# Check hook file exists
+if [ ! -f "$HOOK_PATH" ]; then
+  echo "ERROR: hook file not found at ${HOOK_PATH}"
+  echo "  Pass the path as an argument OR set BASSCLEF_HOOK_PATH env var."
+  echo "  Example: bash $0 /path/to/bassclef/.claude/hooks/auto-save-idle.sh"
+  exit 2
+fi
+
+# Read current crontab (empty if none)
+CURRENT_CRONTAB=$(crontab -l 2>/dev/null || echo "")
+
+# Idempotency check — skip if bassclef entry already present
+if echo "$CURRENT_CRONTAB" | grep -qF "$CRON_MARKER"; then
+  echo "Bassclef auto-save entry already present in crontab — no change."
+  echo ""
+  echo "Current entry:"
+  echo "$CURRENT_CRONTAB" | grep -A1 -F "$CRON_MARKER" | head -2
+  exit 0
+fi
+
+# Install: append the marker + entry to the existing crontab
+NEW_CRONTAB=$(printf '%s\n%s\n%s\n' "$CURRENT_CRONTAB" "$CRON_MARKER" "$CRON_ENTRY")
+
+# Write via crontab -
+echo "$NEW_CRONTAB" | crontab -
+
+echo "Installed cron entry:"
+echo "  ${CRON_MARKER}"
+echo "  ${CRON_ENTRY}"
+echo ""
+echo "Verify with: crontab -l"
+echo "Remove with: crontab -l | grep -v 'bassclef auto-save' | crontab -"
+echo ""
+echo "Auto-save fires every 15 minutes. Feature branches are skipped by save-state.sh"
+echo "guards. SESSION_LOCK held by an active /longrun session suppresses fires."

package/dist/lite/presence/install/schedule-auto-save.taskscheduler.md

@@ -0,0 +1,122 @@
+---
+tier: lite
+title: Native Windows setup — auto-save via Task Scheduler
+adr_references: [ADR-046]
+audience: bassclef adopters on native Windows without WSL
+---
+
+# Auto-save on native Windows via Task Scheduler
+
+Bassclef's auto-save fires every 15 minutes on macOS + Linux + WSL via cron. See `presence/install/schedule-auto-save.cron.sh` for that path.
+
+On native Windows without WSL, cron is not available. This doc gives the manual steps to register a scheduled task that runs the same hook via Git Bash (or MSYS bash).
+
+Per ADR-046.
+
+## Prerequisites
+
+- Windows 10 or 11
+- Git for Windows installed (`git --version` works from PowerShell)
+- Bassclef checked out at `%USERPROFILE%\src\sunj-labs\bassclef` (or note your path)
+- Task Scheduler access (built into Windows; requires admin for some operations)
+
+## Step 1 — Confirm the hook path
+
+Open PowerShell. Run:
+
+```powershell
+Test-Path "$env:USERPROFILE\src\sunj-labs\bassclef\.claude\hooks\auto-save-idle.sh"
+```
+
+Expected: `True`. If `False`, adjust the path to where you checked out bassclef.
+
+## Step 2 — Find Git Bash
+
+Task Scheduler needs to invoke bash directly. Git for Windows ships `bash.exe` at:
+
+```
+C:\Program Files\Git\bin\bash.exe
+```
+
+Confirm with:
+
+```powershell
+Test-Path "C:\Program Files\Git\bin\bash.exe"
+```
+
+If the path differs (32-bit install, custom install), note the actual location for Step 3.
+
+## Step 3 — Register the scheduled task
+
+Run in an elevated PowerShell (Run as Administrator):
+
+```powershell
+$hookPath = "$env:USERPROFILE\src\sunj-labs\bassclef\.claude\hooks\auto-save-idle.sh"
+$bashExe  = "C:\Program Files\Git\bin\bash.exe"
+
+$action = New-ScheduledTaskAction `
+  -Execute $bashExe `
+  -Argument "-lc `"bash '$hookPath'`""
+
+$trigger = New-ScheduledTaskTrigger `
+  -Once -At (Get-Date) `
+  -RepetitionInterval (New-TimeSpan -Minutes 15) `
+  -RepetitionDuration (New-TimeSpan -Days 3650)
+
+$settings = New-ScheduledTaskSettingsSet `
+  -AllowStartIfOnBatteries `
+  -DontStopIfGoingOnBatteries `
+  -StartWhenAvailable
+
+Register-ScheduledTask `
+  -TaskName "BassclefAutoSave" `
+  -Description "Bassclef auto-save fires every 15 minutes (ADR-046)" `
+  -Action $action `
+  -Trigger $trigger `
+  -Settings $settings `
+  -User $env:USERNAME
+```
+
+The task fires every 15 minutes for 10 years. Idempotent — running the register command twice fails the second time with a name collision (safe to re-run after `Unregister-ScheduledTask`).
+
+## Step 4 — Verify
+
+```powershell
+Get-ScheduledTask -TaskName "BassclefAutoSave" | Get-ScheduledTaskInfo
+```
+
+Shows `LastRunTime` after the first fire (~15 minutes after registration). Errors surface in `LastTaskResult` (0 = success).
+
+Manual fire for immediate check:
+
+```powershell
+Start-ScheduledTask -TaskName "BassclefAutoSave"
+```
+
+Then wait ~10 seconds and check the git log in your bassclef checkout for a `chore: auto-save checkpoint` commit.
+
+## Step 5 — Remove (when needed)
+
+```powershell
+Unregister-ScheduledTask -TaskName "BassclefAutoSave" -Confirm:$false
+```
+
+## Notes
+
+- The task runs as the current user, not SYSTEM. Files created by the task inherit the user's permissions.
+- Windows Task Scheduler wakes the machine only if the "Wake the computer to run this task" setting is enabled (not set by default here). Adopters who sleep their machine will miss fires during sleep.
+- When the machine reboots, the task resumes on schedule.
+- Session-end.sh Guard 0 (per bet 27b Step 2) still fires — the SESSION_LOCK precedence check works cross-OS because it reads the file, not the OS scheduler.
+
+## Alternatives
+
+- **WSL2 available?** Skip this doc; use `presence/install/schedule-auto-save.cron.sh` inside WSL. Cron there watches your Windows filesystem via `/mnt/c/Users/...`.
+- **Prefer a .ps1 installer?** File a ticket. The current ship stays doc-only to avoid installer complexity for a population not yet observed. Path B (per-OS installers) upgrade is a follow-on.
+
+## References
+
+- ADR-046 — Cross-OS auto-save scheduling
+- Bet 27b Step 4 — Native Windows path (this doc)
+- `presence/install/schedule-auto-save.cron.sh` — sister installer for macOS + Linux + WSL
+- `.claude/hooks/auto-save-idle.sh` — the hook this schedule invokes
+- `.claude/hooks/session-end.sh` — SESSION_LOCK precedence cure applies cross-OS

package/dist/lite/scripts/aggregate-telemetry.sh

@@ -0,0 +1,217 @@
+#!/usr/bin/env bash
+# scripts/aggregate-telemetry.sh — read local telemetry store; emit uptake report
+# tier: lite
+# install-class: dual
+#
+# Reads state/telemetry/events-*.jsonl files, counts events by type + skill +
+# install source, writes docs/telemetry-reports/YYYY-MM-DD.md.
+#
+# CLI:
+#   bash scripts/aggregate-telemetry.sh                     # full store, today's report
+#   bash scripts/aggregate-telemetry.sh --from 2026-08-01 --to 2026-08-31
+#   bash scripts/aggregate-telemetry.sh --output /tmp/rep.md
+#
+# Deep module per @luminary john-ousterhout — one CLI hides read + parse +
+# aggregate + write.
+# Local-first per ADR-049 — reads adopter machine only.
+#
+# Bash 3.2 compatible (macOS default) — uses temp files rather than
+# associative arrays.
+
+set -u
+
+REPO_ROOT="${REPO_ROOT:-$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)}"
+EVENTS_DIR="${REPO_ROOT}/state/telemetry"
+TODAY="$(date -u +%Y-%m-%d)"
+OUTPUT_DIR="${REPO_ROOT}/docs/telemetry-reports"
+OUTPUT_FILE=""
+DATE_FROM=""
+DATE_TO=""
+
+# --- Arg parsing -----------------------------------------------------------
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --from)   DATE_FROM="$2"; shift 2 ;;
+    --to)     DATE_TO="$2"; shift 2 ;;
+    --output) OUTPUT_FILE="$2"; shift 2 ;;
+    --help|-h)
+      grep '^# ' "$0" | head -20 | sed 's/^# //'
+      exit 0
+      ;;
+    *) echo "unknown arg: $1" >&2; exit 2 ;;
+  esac
+done
+
+[ -z "$OUTPUT_FILE" ] && OUTPUT_FILE="${OUTPUT_DIR}/${TODAY}.md"
+
+# --- Scratch counts dir (bash-3-compatible replacement for declare -A) ----
+COUNTS_DIR="$(mktemp -d -t telem-counts.XXXXXX)"
+trap 'rm -rf "$COUNTS_DIR"' EXIT
+mkdir -p "$COUNTS_DIR/skills" "$COUNTS_DIR/installs" "$COUNTS_DIR/sessions"
+
+_incr_dir() {
+  local dir="$1"
+  local key="$2"
+  # Sanitize key for filesystem (allow /, alnum, dash, underscore)
+  local safe_key
+  safe_key=$(echo "$key" | tr '/' '_' | tr -c 'a-zA-Z0-9_-' '_')
+  local file="$COUNTS_DIR/$dir/$safe_key"
+  local n
+  n=$(cat "$file" 2>/dev/null || echo 0)
+  echo $((n + 1)) > "$file"
+  # Also store original key for report output
+  echo "$key" > "$COUNTS_DIR/$dir/$safe_key.name"
+}
+
+_mark_session() {
+  local sid="$1"
+  # Sanitize
+  local safe_sid
+  safe_sid=$(echo "$sid" | tr -c 'a-zA-Z0-9-' '_')
+  touch "$COUNTS_DIR/sessions/$safe_sid"
+}
+
+# --- Enumerate matching event files ----------------------------------------
+EVENT_FILES=()
+if [ -d "$EVENTS_DIR" ]; then
+  shopt -s nullglob
+  for f in "$EVENTS_DIR"/events-*.jsonl; do
+    base=$(basename "$f" .jsonl)
+    date_stamp="${base#events-}"
+    d="${date_stamp:0:4}-${date_stamp:4:2}-${date_stamp:6:2}"
+    [ -n "$DATE_FROM" ] && [ "$d" \< "$DATE_FROM" ] && continue
+    [ -n "$DATE_TO" ] && [ "$d" \> "$DATE_TO" ] && continue
+    EVENT_FILES+=("$f")
+  done
+  shopt -u nullglob
+fi
+
+# --- Counters --------------------------------------------------------------
+total_events=0
+count_session_start=0
+count_session_end=0
+count_skill_invoke=0
+count_tier_boundary=0
+count_install_probe=0
+
+for f in ${EVENT_FILES[@]+"${EVENT_FILES[@]}"}; do
+  while IFS= read -r line; do
+    [ -z "$line" ] && continue
+    total_events=$((total_events + 1))
+
+    if command -v jq >/dev/null 2>&1; then
+      et=$(echo "$line" | jq -r '.event_type // empty' 2>/dev/null)
+      sid=$(echo "$line" | jq -r '.session_id // empty' 2>/dev/null)
+    else
+      et=$(echo "$line" | grep -oE '"event_type"[[:space:]]*:[[:space:]]*"[^"]*"' | head -1 | sed 's/.*"\([^"]*\)"$/\1/')
+      sid=$(echo "$line" | grep -oE '"session_id"[[:space:]]*:[[:space:]]*"[^"]*"' | head -1 | sed 's/.*"\([^"]*\)"$/\1/')
+    fi
+
+    [ -n "$sid" ] && _mark_session "$sid"
+
+    case "$et" in
+      session_start)
+        count_session_start=$((count_session_start + 1))
+        ;;
+      session_end)
+        count_session_end=$((count_session_end + 1))
+        ;;
+      skill_invoke)
+        count_skill_invoke=$((count_skill_invoke + 1))
+        if command -v jq >/dev/null 2>&1; then
+          skill=$(echo "$line" | jq -r '.payload.skill_name // empty' 2>/dev/null)
+        else
+          skill=$(echo "$line" | grep -oE '"skill_name"[[:space:]]*:[[:space:]]*"[^"]*"' | head -1 | sed 's/.*"\([^"]*\)"$/\1/')
+        fi
+        [ -n "$skill" ] && _incr_dir skills "$skill"
+        ;;
+      tier_boundary_attempt)
+        count_tier_boundary=$((count_tier_boundary + 1))
+        ;;
+      install_probe)
+        count_install_probe=$((count_install_probe + 1))
+        if command -v jq >/dev/null 2>&1; then
+          src=$(echo "$line" | jq -r '.payload.install_source // empty' 2>/dev/null)
+        else
+          src=$(echo "$line" | grep -oE '"install_source"[[:space:]]*:[[:space:]]*"[^"]*"' | head -1 | sed 's/.*"\([^"]*\)"$/\1/')
+        fi
+        [ -n "$src" ] && _incr_dir installs "$src"
+        ;;
+    esac
+  done < "$f"
+done
+
+# Session count = number of session marker files
+session_count=$(ls -1 "$COUNTS_DIR/sessions" 2>/dev/null | wc -l | tr -d ' ')
+
+# --- Write report ----------------------------------------------------------
+mkdir -p "$(dirname "$OUTPUT_FILE")"
+
+{
+  echo "---"
+  echo "report_type: telemetry-uptake"
+  echo "generated_at: $(date -u +%Y-%m-%dT%H:%M:%SZ)"
+  echo "date_range_from: ${DATE_FROM:-<all>}"
+  echo "date_range_to: ${DATE_TO:-<all>}"
+  echo "source: local"
+  echo "---"
+  echo ""
+  echo "# Telemetry uptake report — $TODAY"
+  echo ""
+  echo "## Summary"
+  echo ""
+  echo "- **Total events:** $total_events"
+  echo "- **Distinct sessions:** $session_count"
+  echo "- **Files scanned:** ${#EVENT_FILES[@]}"
+  echo ""
+  echo "## Event counts by type"
+  echo ""
+  echo "| Type | Count |"
+  echo "|---|---|"
+  echo "| session_start | $count_session_start |"
+  echo "| session_end | $count_session_end |"
+  echo "| skill_invoke | $count_skill_invoke |"
+  echo "| tier_boundary_attempt | $count_tier_boundary |"
+  echo "| install_probe | $count_install_probe |"
+  echo ""
+  echo "## Skill invocations"
+  echo ""
+  skill_files=$(ls -1 "$COUNTS_DIR/skills"/*.name 2>/dev/null || true)
+  if [ -z "$skill_files" ]; then
+    echo "_No skill invocations recorded._"
+  else
+    echo "| Skill | Count |"
+    echo "|---|---|"
+    for name_file in "$COUNTS_DIR/skills"/*.name; do
+      count_file="${name_file%.name}"
+      skill=$(cat "$name_file")
+      n=$(cat "$count_file")
+      echo "| \`$skill\` | $n |"
+    done | sort
+  fi
+  echo ""
+  echo "## Install source distribution"
+  echo ""
+  install_files=$(ls -1 "$COUNTS_DIR/installs"/*.name 2>/dev/null || true)
+  if [ -z "$install_files" ]; then
+    echo "_No install probes recorded._"
+  else
+    echo "| Source | Count |"
+    echo "|---|---|"
+    for name_file in "$COUNTS_DIR/installs"/*.name; do
+      count_file="${name_file%.name}"
+      src=$(cat "$name_file")
+      n=$(cat "$count_file")
+      echo "| $src | $n |"
+    done | sort
+  fi
+  echo ""
+  echo "## Notes"
+  echo ""
+  echo "- Report is local-only per ADR-049 (opt-in default OFF; no remote endpoint)"
+  echo "- Adopters share reports at their discretion; raw events stay on adopter machine"
+  echo "- Iteration 3 pricing decision reads aggregated shared reports"
+} > "$OUTPUT_FILE"
+
+echo "telemetry report written: $OUTPUT_FILE"
+echo "  total_events=$total_events sessions=$session_count files=${#EVENT_FILES[@]}"

package/dist/lite/scripts/analyze-tier-dependencies.sh

@@ -0,0 +1,239 @@
+#!/usr/bin/env bash
+# tier: lite
+# analyze-tier-dependencies.sh — orchestrator for the tier-dependency-audit subsystem
+#
+# Per standards/tier-dependency-analysis.md — walks the dependency graph
+# for a given tier and classifies every file into one of 4 buckets.
+#
+# Per docs/decompositions/2026-08-17a-tier-dependency-audit.md — this script
+# is the orchestrator (main + dispatch). Actual work lives in
+# lib/tier-dependency-audit.sh (8 named functions per Larman GRASP).
+#
+# Usage:
+#   scripts/analyze-tier-dependencies.sh <tier>
+#     tier: one of lite | standard | standard-pro | ultra | upstream
+#            OR 'all'          (combined-tier — all 5 tiers)
+#            OR 'tier,tier,..' (combined-tier — named list; e.g., lite,standard)
+#
+# Combined-tier mode (ADR-052 D5): INTENDED = union of every named tier's
+# INTENDED set. Buckets 1+3+4 report against the union. Bucket 3 becomes
+# TRUE accidental leaks (files no tier's graph claims), not
+# tagged-for-other-tier files that show up as false leaks in single-tier mode.
+#
+# Overrides (used by Tier 0 tests + advanced consumers):
+#   OUTPUT_DIR             — where to write manifest (default: docs/dependency-audits)
+#   INTENDED_FIXTURE       — file listing INTENDED set (skips Sources 1+2 walk)
+#   ACTUAL_FIXTURE         — file listing ACTUAL set (skips release-script call)
+#   TAGS_FIXTURE           — file listing "<path>\t<tier>" for tag data
+#   RUNTIME_DEPS_FILE      — override the tier-runtime-deps file location (single-tier only)
+#   SKIP_TIER_DEPENDENCY_AUDIT=1 — bypass path (logged); exits 0 without writing
+
+set -uo pipefail
+
+REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+
+# Source the lib with named functions (single-tier + combined-tier)
+# shellcheck disable=SC1091
+source "$REPO_ROOT/lib/tier-dependency-audit.sh"
+
+# Bypass path
+if [ "${SKIP_TIER_DEPENDENCY_AUDIT:-0}" = "1" ]; then
+  echo "analyze-tier-dependencies: SKIP bypass (SKIP_TIER_DEPENDENCY_AUDIT=1 logged)" >&2
+  exit 0
+fi
+
+# --- Combined-tier mode detection ------------------------------------------
+# If arg is 'all' or contains comma, dispatch to combined path and exit
+# before the single-tier code runs.
+ARG_RAW="${1:-}"
+if [ "$ARG_RAW" = "all" ] || [[ "$ARG_RAW" == *,* ]]; then
+  TIER_LIST="$(parse_tier_list_arg "$ARG_RAW")" || exit $?
+  OUTPUT_DIR="${OUTPUT_DIR:-$REPO_ROOT/docs/dependency-audits}"
+  INTENDED_TMP="$(mktemp)"
+  ACTUAL_TMP="$(mktemp)"
+  TAGS_TMP="$(mktemp)"
+  BUCKET_DIR="$(mktemp -d)"
+  trap 'rm -rf "$INTENDED_TMP" "$ACTUAL_TMP" "$TAGS_TMP" "$BUCKET_DIR"' EXIT
+
+  # Loop per tier: build INTENDED_i (Source 1 seeds + Source 2 BFS + Source 3 runtime deps)
+  cd "$REPO_ROOT"
+  while IFS= read -r t; do
+    [ -z "$t" ] && continue
+    echo "combined-tier: building INTENDED for $t" >&2
+    seeds_tmp="$(mktemp)"
+    read_intended_source_1 "$t" > "$seeds_tmp"
+    walk_graph_bfs "$seeds_tmp" extract_references >> "$INTENDED_TMP"
+    rm -f "$seeds_tmp"
+    # Source 3 — runtime deps if present for this tier
+    rt_file="$REPO_ROOT/standards/tier-runtime-deps/${t}.md"
+    if [ -f "$rt_file" ]; then
+      read_runtime_deps "$rt_file" >> "$INTENDED_TMP"
+    else
+      echo "combined-tier: no runtime-deps file for $t at $rt_file (skipping)" >&2
+    fi
+  done <<< "$TIER_LIST"
+  sort -u -o "$INTENDED_TMP" "$INTENDED_TMP"
+
+  # ACTUAL — release script include list (same regardless of tier; it is the full public release)
+  if [ -n "${ACTUAL_FIXTURE:-}" ]; then
+    cp "$ACTUAL_FIXTURE" "$ACTUAL_TMP"
+  else
+    # Pass 'lite' arg to keep read_actual_source signature; the release
+    # script output is the full ACTUAL set regardless.
+    read_actual_source "lite" > "$ACTUAL_TMP" || {
+      echo "analyze-tier-dependencies: Source 4 (release script) failed" >&2
+      exit 4
+    }
+  fi
+  sort -u -o "$ACTUAL_TMP" "$ACTUAL_TMP"
+
+  # TAGS — derive by grepping each file in INTENDED_TMP for its tier tag
+  if [ -n "${TAGS_FIXTURE:-}" ]; then
+    cp "$TAGS_FIXTURE" "$TAGS_TMP"
+  else
+    : > "$TAGS_TMP"
+    while IFS= read -r path; do
+      [ -z "$path" ] && continue
+      tag=""
+      if [ -f "$path" ]; then
+        case "$path" in
+          *.md)
+            tag="$(awk '
+              BEGIN{infm=0}
+              NR==1 && /^---/ {infm=1; next}
+              infm && /^---/ {exit}
+              infm && /^tier:[[:space:]]/ {sub(/^tier:[[:space:]]*/,""); gsub(/[[:space:]]/,""); print; exit}
+            ' "$path")"
+            ;;
+          *.sh)
+            tag="$(head -5 "$path" | awk '/^# tier:[[:space:]]/ {sub(/^# tier:[[:space:]]*/,""); gsub(/[[:space:]]/,""); print; exit}')"
+            ;;
+        esac
+      fi
+      if [ -n "$tag" ]; then
+        printf "%s\t%s\n" "$path" "$tag" >> "$TAGS_TMP"
+      else
+        printf "%s\n" "$path" >> "$TAGS_TMP"
+      fi
+    done < "$INTENDED_TMP"
+  fi
+
+  classify_files_combined "$INTENDED_TMP" "$ACTUAL_TMP" "$TAGS_TMP" "$BUCKET_DIR"
+
+  TODAY="$(date -u +%Y-%m-%d)"
+  # Slug the tier list for the filename (commas → dashes; keeps 'all' as-is)
+  TIER_SLUG="$(echo "$ARG_RAW" | tr ',' '-')"
+  OUTFILE="$OUTPUT_DIR/${TODAY}-combined-${TIER_SLUG}.md"
+  write_manifest_combined "$BUCKET_DIR" "$TODAY" "$ARG_RAW" "$OUTFILE" || {
+    echo "analyze-tier-dependencies: write_manifest_combined failed" >&2
+    exit 5
+  }
+  echo "analyze-tier-dependencies: wrote $OUTFILE" >&2
+  exit 0
+fi
+# --- End combined-tier mode ------------------------------------------------
+
+# Validate tier arg (parse_tier_arg from lib)
+TIER="$(parse_tier_arg "${1:-}")" || exit $?
+
+# Resolve inputs (fixture overrides for tests; real sources otherwise)
+OUTPUT_DIR="${OUTPUT_DIR:-$REPO_ROOT/docs/dependency-audits}"
+RUNTIME_DEPS_FILE="${RUNTIME_DEPS_FILE:-$REPO_ROOT/standards/tier-runtime-deps/${TIER}.md}"
+
+# Check runtime-deps file exists (unless fixture mode short-circuits later)
+if [ ! -f "$RUNTIME_DEPS_FILE" ]; then
+  echo "analyze-tier-dependencies: runtime-deps file missing at $RUNTIME_DEPS_FILE" >&2
+  echo "  create per standards/tier-dependency-analysis.md Source 3" >&2
+  exit 3
+fi
+
+INTENDED_FIXTURE="${INTENDED_FIXTURE:-}"
+ACTUAL_FIXTURE="${ACTUAL_FIXTURE:-}"
+TAGS_FIXTURE="${TAGS_FIXTURE:-}"
+
+# Check intended fixture exists when in fixture mode
+if [ -n "$INTENDED_FIXTURE" ] && [ ! -f "$INTENDED_FIXTURE" ]; then
+  echo "analyze-tier-dependencies: intended fixture not found at $INTENDED_FIXTURE" >&2
+  exit 3
+fi
+
+# Temp files for the pipeline
+INTENDED_TMP="$(mktemp)"
+ACTUAL_TMP="$(mktemp)"
+TAGS_TMP="$(mktemp)"
+BUCKET_DIR="$(mktemp -d)"
+trap 'rm -rf "$INTENDED_TMP" "$ACTUAL_TMP" "$TAGS_TMP" "$BUCKET_DIR"' EXIT
+
+# Build INTENDED set — Sources 1 + 2 (BFS from tagged root set) + Source 3 (runtime deps)
+if [ -n "$INTENDED_FIXTURE" ]; then
+  cat "$INTENDED_FIXTURE" > "$INTENDED_TMP"
+else
+  # Real mode — Source 1 seed + Source 2 BFS
+  cd "$REPO_ROOT"
+  seeds_tmp="$(mktemp)"
+  read_intended_source_1 "$TIER" > "$seeds_tmp"
+  walk_graph_bfs "$seeds_tmp" extract_references > "$INTENDED_TMP"
+  rm -f "$seeds_tmp"
+fi
+
+# Source 3 — runtime deps
+read_runtime_deps "$RUNTIME_DEPS_FILE" >> "$INTENDED_TMP"
+
+sort -u -o "$INTENDED_TMP" "$INTENDED_TMP"
+
+# Build ACTUAL set — Source 4 (release script dry-run)
+if [ -n "$ACTUAL_FIXTURE" ]; then
+  cp "$ACTUAL_FIXTURE" "$ACTUAL_TMP"
+else
+  read_actual_source "$TIER" > "$ACTUAL_TMP" || {
+    echo "analyze-tier-dependencies: Source 4 (release script) failed" >&2
+    exit 4
+  }
+fi
+sort -u -o "$ACTUAL_TMP" "$ACTUAL_TMP"
+
+# Build TAGS map
+if [ -n "$TAGS_FIXTURE" ]; then
+  cp "$TAGS_FIXTURE" "$TAGS_TMP"
+else
+  # Real mode — derive tags via grep against INTENDED set
+  cd "$REPO_ROOT"
+  : > "$TAGS_TMP"
+  while IFS= read -r path; do
+    [ -z "$path" ] && continue
+    tag=""
+    if [ -f "$path" ]; then
+      case "$path" in
+        *.md)
+          tag="$(awk '
+            BEGIN{infm=0}
+            NR==1 && /^---/ {infm=1; next}
+            infm && /^---/ {exit}
+            infm && /^tier:[[:space:]]/ {sub(/^tier:[[:space:]]*/,""); gsub(/[[:space:]]/,""); print; exit}
+          ' "$path")"
+          ;;
+        *.sh)
+          tag="$(head -5 "$path" | awk '/^# tier:[[:space:]]/ {sub(/^# tier:[[:space:]]*/,""); gsub(/[[:space:]]/,""); print; exit}')"
+          ;;
+      esac
+    fi
+    if [ -n "$tag" ]; then
+      printf "%s\t%s\n" "$path" "$tag" >> "$TAGS_TMP"
+    else
+      printf "%s\n" "$path" >> "$TAGS_TMP"
+    fi
+  done < "$INTENDED_TMP"
+fi
+
+# Classify + write manifest
+classify_files "$INTENDED_TMP" "$ACTUAL_TMP" "$TAGS_TMP" "$BUCKET_DIR" "$TIER"
+
+TODAY="$(date -u +%Y-%m-%d)"
+OUTFILE="$OUTPUT_DIR/${TODAY}-${TIER}.md"
+write_manifest "$BUCKET_DIR" "$TODAY" "$TIER" "$OUTFILE" || {
+  echo "analyze-tier-dependencies: write_manifest failed" >&2
+  exit 5
+}
+
+echo "analyze-tier-dependencies: wrote $OUTFILE" >&2
+exit 0