@thebassclef/lite 1.0.1 → 1.0.3

package/dist/lite/.claude/hooks/session-reflection.d/45-auto-sync-status.sh

@@ -0,0 +1,99 @@
+#!/bin/bash
+# tier: lite
+# 45-auto-sync-status.sh — Always-on version status line
+#
+# V3 refactor (bassclef bet 2026-06-15b — Phase B Trust Busters):
+# - Always-on session-start version-status line replacing the earned-banner
+#   Layer 2 surface (per operator decision — always-on subsumes earned)
+# - Critical-fix entries from adopter-notable-releases.json fire warnings
+#   BYPASSING age threshold (no 30-day gate)
+# - Backward-compat: silent when .bassclef-source.json absent (bassclef's
+#   own repo) or when V1 installed_sha/installed_at fields not yet populated
+#
+# Behavior:
+# - When .bassclef-source.json present + has installed_sha + installed_at:
+#     emit "### bassclef-sync — version status" header + one-line status
+#     showing installed SHA + days-behind + auto-sync state
+# - When critical-fix entries published_at > installed_at:
+#     emit additional warning section listing the entries
+#
+# Override: SKIP_AUTO_SYNC_STATUS=1 in env.
+#
+# Per bassclef#939 — adopter sync opt-in default.
+# Per bet 2026-06-15b V3 — Layer 2 collapse to always-on.
+
+[ "${SKIP_AUTO_SYNC_STATUS:-0}" = "1" ] && { return 0 2>/dev/null || exit 0; }
+
+CWD="${CLAUDE_PROJECT_DIR:-$PWD}"
+SOURCE_FILE="$CWD/.bassclef-source.json"
+ADOPTER_NOTABLE_FILE="$CWD/state/adopter-notable-releases.json"
+
+# Silent if no .bassclef-source.json (bassclef's own repo path).
+[ -f "$SOURCE_FILE" ] || { return 0 2>/dev/null || exit 0; }
+
+# Parse V1 fields. Silent if installed_sha + installed_at not yet populated
+# (adopter hasn't migrated to V1 schema).
+INSTALLED_SHA=$(jq -r '.installed_sha // empty' "$SOURCE_FILE" 2>/dev/null)
+INSTALLED_AT=$(jq -r '.installed_at // empty' "$SOURCE_FILE" 2>/dev/null)
+AUTO_SYNC=$(jq -r '.auto_sync // false' "$SOURCE_FILE" 2>/dev/null)
+
+if [ -z "$INSTALLED_SHA" ] || [ -z "$INSTALLED_AT" ]; then
+  # Pre-V1 adopter — silent to avoid noise during gradual schema rollout.
+  return 0 2>/dev/null || exit 0
+fi
+
+# Compute days-behind from installed_at. Cross-platform date parsing.
+NOW_EPOCH=$(date +%s)
+INSTALLED_EPOCH=$(date -j -f "%Y-%m-%dT%H:%M:%SZ" "$INSTALLED_AT" +%s 2>/dev/null \
+  || date -d "$INSTALLED_AT" +%s 2>/dev/null || echo "$NOW_EPOCH")
+AGE_SECONDS=$((NOW_EPOCH - INSTALLED_EPOCH))
+DAYS_BEHIND=$((AGE_SECONDS / 86400))
+
+# Auto-sync state surfacing.
+if [ "$AUTO_SYNC" = "true" ]; then
+  AUTO_LINE="Auto-update is ON — next session-start fetches latest."
+else
+  AUTO_LINE="Auto-update is OFF — say \"enable auto-sync\" to flip the default."
+fi
+
+# Days-behind phrasing.
+if [ "$DAYS_BEHIND" -eq 0 ]; then
+  AGE_PHRASE="today"
+elif [ "$DAYS_BEHIND" -eq 1 ]; then
+  AGE_PHRASE="1 day ago"
+else
+  AGE_PHRASE="$DAYS_BEHIND days ago"
+fi
+
+# Compose status line + emit. Always fires when reaching this point.
+cat <<HEADER
+
+### bassclef-sync — version status
+
+Installed: $INSTALLED_SHA ($AGE_PHRASE)
+$AUTO_LINE
+HEADER
+
+# Check for critical-fix entries published_at > installed_at.
+# Critical-fixes BYPASS the age threshold (no 30-day gate).
+if [ -f "$ADOPTER_NOTABLE_FILE" ]; then
+  CRITICAL_COUNT=$(jq --arg cutoff "$INSTALLED_AT" \
+    '[.releases[]? | select(.published_at > $cutoff) | select(.kind == "critical_fix")] | length' \
+    "$ADOPTER_NOTABLE_FILE" 2>/dev/null || echo 0)
+  if [ "$CRITICAL_COUNT" -gt 0 ]; then
+    CRITICAL_SUMMARY=$(jq --arg cutoff "$INSTALLED_AT" -r \
+      '[.releases[]? | select(.published_at > $cutoff) | select(.kind == "critical_fix") | "   • " + .summary] | join("\n")' \
+      "$ADOPTER_NOTABLE_FILE" 2>/dev/null || echo "")
+    cat <<CRITICAL
+
+⚠ $CRITICAL_COUNT critical-fix update(s) released since your install:
+$CRITICAL_SUMMARY
+
+Pull now with:
+
+    bash .claude/hooks/bassclef-sync.sh
+CRITICAL
+  fi
+fi
+
+return 0 2>/dev/null || exit 0

package/dist/lite/.claude/hooks/session-reflection.d/50-evolution-issues.sh

@@ -0,0 +1,44 @@
+# tier: lite
+# Bassclef-evolution promotion scan: in bassclef sessions only, list
+# open bassclef-evolution issues in bassclef and known consumer repos.
+#
+# Consumer list is read from substrate.config.md field
+# `bassclef_evolution_child_repos` (comma-separated owner/name list).
+# Falls back to sunj-labs/poa only when the field is absent — safe
+# default for old consumer checkouts predating the config field.
+#
+# Keep the field in sync with .github/workflows/bassclef-template-sync.yml
+# matrix.consumer list.
+
+REPO_NAME_CHECK=$(gh repo view --json name -q '.name' 2>/dev/null || echo "")
+if [ "$REPO_NAME_CHECK" = "platform-docs" ] || [ "$REPO_NAME_CHECK" = "bassclef" ]; then
+  CHILD_REPOS_RAW=$(grep "^bassclef_evolution_child_repos:" substrate.config.md 2>/dev/null | sed 's/^bassclef_evolution_child_repos:[[:space:]]*//' || echo "")
+  if [ -n "$CHILD_REPOS_RAW" ]; then
+    CHILD_REPOS=$(echo "$CHILD_REPOS_RAW" | tr ',' '\n' | tr -d ' ' | grep -v '^$')
+  else
+    CHILD_REPOS="sunj-labs/poa"
+  fi
+
+  ALL_EVOLUTION=""
+
+  BASSCLEF_ISSUES=$(gh issue list -R "sunj-labs/bassclef" --label "bassclef-evolution" --state open --limit 10 2>/dev/null)
+  if [ -n "$BASSCLEF_ISSUES" ]; then
+    ALL_EVOLUTION="${ALL_EVOLUTION}\n  From bassclef:\n${BASSCLEF_ISSUES}\n"
+  fi
+
+  for CHILD in $CHILD_REPOS; do
+    CHILD_ISSUES=$(gh issue list -R "$CHILD" --label "bassclef-evolution" --state open --limit 10 2>/dev/null)
+    if [ -n "$CHILD_ISSUES" ]; then
+      ALL_EVOLUTION="${ALL_EVOLUTION}\n  From ${CHILD}:\n${CHILD_ISSUES}\n"
+    fi
+  done
+
+  if [ -n "$ALL_EVOLUTION" ]; then
+    echo "### BASSCLEF EVOLUTION — PENDING PROMOTIONS"
+    echo ""
+    echo -e "$ALL_EVOLUTION"
+    echo "Review and resolve these. Child repo proposals need ingestion"
+    echo "into bassclef if globally applicable."
+    echo ""
+  fi
+fi

package/dist/lite/.claude/hooks/session-reflection.d/55-orientation-gate.sh

@@ -0,0 +1,187 @@
+# tier: lite
+# 55-orientation-gate.sh
+#
+# Per bassclef#1183 + bassclef#1266 + bassclef#1275: mechanical enforcement
+# at SessionStart in bassclef AND every adopter repo. Fires a BLOCKED block
+# (per .claude/rules/blocked-items.md) when the agent is on a feature branch
+# AND no orientation marker exists for that branch. /sprint + /longrun prep
+# procedures (WU-3/WU-4) then refuse to propose work until the operator +
+# agent have oriented at the arc level — read the active bet's parent_drivers,
+# walked up parent_bet → parent_roadmap, scanned open bassclef-evolution
+# issues across the current repo + any sibling repos named in substrate.config.md.
+#
+# This closes the 2026-06-20 failure pattern: agent narrows scope to the
+# nearest leaf ticket without reading the parent thread carrying 30+ in-flight
+# items. Adopters inherit the same discipline (bassclef#1275 — sister
+# pattern "rule propagates, mechanism doesn't" surfaced in the very session
+# that shipped this hook for bassclef-only).
+#
+# Behavior:
+#   - Fires in bassclef AND adopter repos (no consumer-repo guard since bassclef#1275)
+#   - Fires on main branch too per architecture/audits/2026-06-30-session-orientation-blind-spot.md
+#     cure 2 (sister cures: 05-active-bet.sh + /longrun SKILL Step 0.4)
+#   - Silent when state/markers/orientation-gate/<branch-slug>.marker exists
+#     (on main, the slug is literally "main")
+#   - Silent when SKIP_ORIENTATION_GATE=1 (logged via trace-helper)
+#   - Silent when SKIP_ORIENTATION_GATE_ON_MAIN=1 AND branch is main/master
+#     (adopter compat shim per ADR-031 — adopters can opt out of main-firing
+#     per session if needed; bassclef-upstream itself does not set this)
+#   - Otherwise fires BLOCKED block naming active bet + resolution path
+#
+# Config (read from substrate.config.md when present):
+#   - bassclef_evolution_label  — issue label to scan (default: bassclef-evolution)
+#   - bassclef_evolution_child_repos — comma-separated owner/repo list to also scan
+#
+# Resolution:
+#   1. Read active bet's parent_drivers + acceptance + out_of_scope
+#   2. Walk parent_bet → parent_roadmap → parent_drivers chain
+#   3. Scan open bassclef-evolution issues across current repo + child repos
+#   4. Touch marker: mkdir -p state/markers/orientation-gate/ && \
+#                    touch state/markers/orientation-gate/<branch-slug>.marker
+#   OR explicitly defer: "skip orientation-gate this session"
+#
+# Override (logged):
+#   SKIP_ORIENTATION_GATE=1 <command>
+
+# Override path — silent, log via trace-helper if present
+if [ "${SKIP_ORIENTATION_GATE:-0}" = "1" ]; then
+  if [ -x ".claude/hooks/trace-helper.sh" ]; then
+    bash .claude/hooks/trace-helper.sh "orientation-gate" "skipped via SKIP_ORIENTATION_GATE=1" 2>/dev/null || true
+  fi
+  return 0 2>/dev/null || exit 0
+fi
+
+# Branch detection. Silent only when git is missing.
+BRANCH=$(git symbolic-ref --short HEAD 2>/dev/null || echo "")
+if [ -z "$BRANCH" ]; then
+  return 0 2>/dev/null || exit 0
+fi
+
+# Adopter opt-out for main-firing (per ADR-031 we-don't-break-adopters
+# compat shim; bassclef-upstream itself does not set this).
+if [ "${SKIP_ORIENTATION_GATE_ON_MAIN:-0}" = "1" ] && { [ "$BRANCH" = "main" ] || [ "$BRANCH" = "master" ]; }; then
+  if [ -x ".claude/hooks/trace-helper.sh" ]; then
+    bash .claude/hooks/trace-helper.sh "orientation-gate" "skipped on main via SKIP_ORIENTATION_GATE_ON_MAIN=1" 2>/dev/null || true
+  fi
+  return 0 2>/dev/null || exit 0
+fi
+
+# Branch slug: slash → dash for safe filename
+BRANCH_SLUG=$(echo "$BRANCH" | tr '/' '-')
+
+# Marker check: silent if orientation marker exists for this branch
+MARKER_PATH="state/markers/orientation-gate/${BRANCH_SLUG}.marker"
+if [ -f "$MARKER_PATH" ]; then
+  return 0 2>/dev/null || exit 0
+fi
+
+# Read active iteration_bet from whereami (best-effort)
+ACTIVE_BET="(none in whereami)"
+if [ -f "docs/whereami.md" ]; then
+  BET_LINE=$(grep -E "^iteration_bet:" docs/whereami.md 2>/dev/null | head -1 | sed 's/^iteration_bet:[[:space:]]*//')
+  if [ -n "$BET_LINE" ]; then
+    # Trim parenthetical status notes (some whereami entries carry CLOSED/CLOSED+MERGED suffix)
+    ACTIVE_BET=$(echo "$BET_LINE" | sed 's/[[:space:]]*(.*//')
+  fi
+fi
+
+# Walk parent_bet chain recursively (bassclef#1347).
+# Reads each bet's frontmatter at docs/iteration-bets/<slug>.md, extracts
+# parent_bet field, recurses until null or max depth (cycle protection).
+# Builds ANCESTOR_CHAIN newline-separated for display in BLOCKED message.
+ANCESTOR_CHAIN=""
+walk_chain() {
+  local current="$1"
+  local depth=0
+  local max_depth=20
+  local visited=" "
+
+  while [ -n "$current" ] && [ "$depth" -lt "$max_depth" ]; do
+    # Cycle break — if we've seen this bet already, stop
+    case "$visited" in *" $current "*) break ;; esac
+    visited="$visited$current "
+
+    if [ "$depth" -gt 0 ]; then
+      ANCESTOR_CHAIN="${ANCESTOR_CHAIN}      ↳ ${current}
+"
+    fi
+
+    local bet_file="docs/iteration-bets/${current}.md"
+    [ -f "$bet_file" ] || break
+
+    local parent
+    parent=$(grep -E "^parent_bet:" "$bet_file" 2>/dev/null | head -1 | sed 's/^parent_bet:[[:space:]]*//')
+    current="$parent"
+    depth=$((depth + 1))
+  done
+}
+if [ -n "$ACTIVE_BET" ] && [ "$ACTIVE_BET" != "(none in whereami)" ]; then
+  walk_chain "$ACTIVE_BET"
+fi
+
+# Read scan config from substrate.config.md (best-effort defaults)
+EVOLUTION_LABEL="bassclef-evolution"
+CHILD_REPOS=""
+if [ -f "substrate.config.md" ]; then
+  CFG_LABEL=$(grep -E "^bassclef_evolution_label:" substrate.config.md 2>/dev/null | head -1 | sed 's/^bassclef_evolution_label:[[:space:]]*//')
+  if [ -n "$CFG_LABEL" ]; then
+    EVOLUTION_LABEL="$CFG_LABEL"
+  fi
+  CFG_CHILDREN=$(grep -E "^bassclef_evolution_child_repos:" substrate.config.md 2>/dev/null | head -1 | sed 's/^bassclef_evolution_child_repos:[[:space:]]*//')
+  if [ -n "$CFG_CHILDREN" ]; then
+    CHILD_REPOS="$CFG_CHILDREN"
+  fi
+fi
+
+# Emit BLOCKED block
+echo ""
+echo "============================================"
+echo "🛑 BLOCKED: orientation-gate"
+echo "============================================"
+echo ""
+echo "Before /sprint or /longrun prep proposes work, read the bigger picture first."
+echo ""
+echo "Active iteration_bet: ${ACTIVE_BET}"
+echo ""
+echo "Read these BEFORE picking what to do next:"
+echo "  - The active bet's parent_drivers (why this exists), acceptance (what counts as done), and out_of_scope (what NOT to do)"
+echo "  - The FULL ancestor chain (per bassclef#1347 — recursive walk, not just one level):"
+echo "      ${ACTIVE_BET}"
+if [ -n "$ANCESTOR_CHAIN" ]; then
+  printf "%s" "$ANCESTOR_CHAIN"
+else
+  echo "      (no ancestors — single bet, or bet file missing)"
+fi
+echo "    Read each ancestor bet's parent_drivers + acceptance + out_of_scope. Union them, dedupe, surface in /longrun prep."
+echo "  - The parent_roadmap (if any bet in the chain has one) and its current pending work"
+echo "  - Open bassclef-evolution issues — run these:"
+echo "      gh issue list --label \"${EVOLUTION_LABEL}\" --state open  # current repo"
+if [ -n "$CHILD_REPOS" ]; then
+  # Split on comma; trim whitespace per item
+  OLD_IFS="$IFS"
+  IFS=','
+  for repo in $CHILD_REPOS; do
+    # Trim leading/trailing whitespace
+    repo_trimmed=$(echo "$repo" | sed 's/^[[:space:]]*//;s/[[:space:]]*$//')
+    if [ -n "$repo_trimmed" ]; then
+      echo "      gh issue list -R ${repo_trimmed} --label \"${EVOLUTION_LABEL}\" --state open"
+    fi
+  done
+  IFS="$OLD_IFS"
+fi
+echo "  - Paused steps and open audit-drop tickets in the active arc"
+echo ""
+echo "When you've read enough to know what work makes sense, touch this marker:"
+echo "  mkdir -p state/markers/orientation-gate/"
+echo "  touch ${MARKER_PATH}"
+echo ""
+echo "OR explicitly defer per .claude/rules/blocked-items.md:"
+echo "  \"skip orientation-gate this session\""
+echo ""
+echo "Silence is not deferral. Default is read first."
+echo ""
+echo "Override (logged): SKIP_ORIENTATION_GATE=1"
+echo "Per bassclef#1183 + bassclef#1266 + bassclef#1275 + bassclef#1347."
+echo ""
+
+return 0 2>/dev/null || exit 0

package/dist/lite/.claude/hooks/session-reflection.d/56-roadmap-reconcile-gate.sh

@@ -0,0 +1,88 @@
+# tier: lite
+# 56-roadmap-reconcile-gate.sh
+#
+# Per bassclef#1183 + bassclef#504 + bassclef#1275: mechanical enforcement
+# at SessionStart in bassclef AND every adopter repo. Fires BLOCKED on
+# feature branches when no roadmap-reconcile marker exists. /sprint + /longrun
+# prep procedures (WU-3/WU-4) refuse to propose work until /roadmap-reconcile
+# --dry-run has run AND either showed no drift OR drift was resolved or
+# explicitly deferred.
+#
+# This closes the methodology-vs-mechanism gap that bassclef#504
+# left open: /roadmap-reconcile auto-fire was declared methodology
+# at /longrun prep Step 0.5, but no hook fired it. Agents skipped the
+# check across multiple sessions; canvas + roadmap drift accumulated
+# silently. Adopters inherit the same discipline (bassclef#1275 — sister
+# pattern "rule propagates, mechanism doesn't" surfaced in the same session
+# that shipped this hook for bassclef-only).
+#
+# Behavior:
+#   - Fires in bassclef AND adopter repos (no consumer-repo guard since bassclef#1275)
+#   - Silent on main branch (gate is per-feature-branch scope decision)
+#   - Silent when state/markers/roadmap-reconcile-gate/<branch-slug>.marker exists
+#   - Silent when SKIP_ROADMAP_RECONCILE_GATE=1 (logged via trace-helper)
+#   - Otherwise emits BLOCKED block naming the dispatch command + resolution path
+#
+# Resolution:
+#   1. Run /roadmap-reconcile --dry-run
+#   2. If diff shows no drift: touch the marker
+#         mkdir -p state/markers/roadmap-reconcile-gate/
+#         touch state/markers/roadmap-reconcile-gate/<branch-slug>.marker
+#   3. If diff shows drift: amend the canvas LR-N tables OR explicitly defer
+#      per .claude/rules/blocked-items.md ("skip roadmap-reconcile this session")
+#
+# Override (logged):
+#   SKIP_ROADMAP_RECONCILE_GATE=1 <command>
+
+# Override path — silent, log via trace-helper if present
+if [ "${SKIP_ROADMAP_RECONCILE_GATE:-0}" = "1" ]; then
+  if [ -x ".claude/hooks/trace-helper.sh" ]; then
+    bash .claude/hooks/trace-helper.sh "roadmap-reconcile-gate" "skipped via SKIP_ROADMAP_RECONCILE_GATE=1" 2>/dev/null || true
+  fi
+  return 0 2>/dev/null || exit 0
+fi
+
+# Branch guard: silent on main
+BRANCH=$(git symbolic-ref --short HEAD 2>/dev/null || echo "")
+if [ -z "$BRANCH" ] || [ "$BRANCH" = "main" ] || [ "$BRANCH" = "master" ]; then
+  return 0 2>/dev/null || exit 0
+fi
+
+# Branch slug: slash → dash
+BRANCH_SLUG=$(echo "$BRANCH" | tr '/' '-')
+
+# Marker check
+MARKER_PATH="state/markers/roadmap-reconcile-gate/${BRANCH_SLUG}.marker"
+if [ -f "$MARKER_PATH" ]; then
+  return 0 2>/dev/null || exit 0
+fi
+
+# Emit BLOCKED block
+echo ""
+echo "============================================"
+echo "🛑 BLOCKED: roadmap-reconcile-gate"
+echo "============================================"
+echo ""
+echo "Before /sprint or /longrun prep proposes work this session, run /roadmap-reconcile --dry-run."
+echo ""
+echo "Why: canvases hold LR-N tables that drift from shipping reality across long sessions."
+echo "Agents proposing work against stale canvas state pick the wrong scope. The dry-run diff"
+echo "names the drift (status mismatch, sequencing mismatch, reference rot) before scope-commit."
+echo ""
+echo "Resolve:"
+echo "  1. Dispatch:  /roadmap-reconcile --dry-run"
+echo "  2. If diff shows NO drift, mark this branch oriented:"
+echo "        mkdir -p state/markers/roadmap-reconcile-gate/"
+echo "        touch ${MARKER_PATH}"
+echo "  3. If diff shows drift, either:"
+echo "        - Amend the canvas LR-N tables to match reality, then mark"
+echo "        - OR explicitly defer per .claude/rules/blocked-items.md:"
+echo "            \"skip roadmap-reconcile this session\""
+echo ""
+echo "Silence is not deferral. Default is run the dry-run."
+echo ""
+echo "Override (logged): SKIP_ROADMAP_RECONCILE_GATE=1"
+echo "Per bassclef#1183 + bassclef#504 + bassclef#1275."
+echo ""
+
+return 0 2>/dev/null || exit 0

package/dist/lite/.claude/hooks/session-reflection.d/60-deferred-actions.sh

@@ -0,0 +1,212 @@
+# tier: lite
+# Deferred-actions scan: enumerate docs/deferred-actions/*.md, detect current
+# modality capabilities, emit BLOCKED: for capability matches (this session
+# can resolve), INFORM: for capability misses (visible, not actionable).
+#
+# Schema: standards/deferred-actions-schema.md
+# Rule:   .claude/rules/deferred-actions.md
+#
+# Migration note (Phase A WS-3 + spine v0 WU-6): this hook reads
+# docs/deferred-actions/ entries via lib/deferred-actions.sh (typed
+# accessor; pre-spine, still load-bearing for capability-routed scanning).
+# Capability detection stays inline because it is session-environment-
+# specific, not artifact-specific. Falls back to inline scanning if lib
+# unavailable (consumer repos pre-distribution).
+#
+# Spine v0 (WU-6) integration: lib/state.sh provides
+# state_deferred_action_pending [requires-capability...] and
+# state_deferred_action_list [pending|completed|all] as the unified
+# accessor surface. This hook continues using lib/deferred-actions.sh
+# for now because (a) capability-routed filtering is more deeply wired
+# into the existing accessor + (b) full migration would risk regressing
+# capability-detection logic that's uniquely tested here. Future
+# unification (consolidate into lib/state.sh) is tracked as a /promote.
+
+DEFERRED_DIR="docs/deferred-actions"
+
+# No dir → nothing to scan.
+if [ ! -d "$DEFERRED_DIR" ]; then
+  return 0 2>/dev/null || true
+fi
+
+# Source typed accessor when available. Probe bundled path first
+# (dist/lite/ ship path per #1631 goal 2026-09-14b), then $BASSCLEF_DIR
+# fallback for synced adopters. Pattern matches session-reflection.sh:13.
+# Graceful fallback to inline scanning if lib not present.
+_sd="$(dirname "${BASH_SOURCE[0]:-$0}")"
+DA_LIB=""
+for _c in "${_sd}/../../../lib/deferred-actions.sh" \
+          "${BASSCLEF_DIR:-}/lib/deferred-actions.sh"; do
+  [ -f "$_c" ] && DA_LIB="$_c" && break
+done
+USE_LIB=0
+if [ -n "$DA_LIB" ]; then
+  # shellcheck source=/dev/null
+  source "$DA_LIB"
+  # Point lib at consumer-local docs/deferred-actions, not bassclef's
+  DEFERRED_ACTIONS_DIR="$DEFERRED_DIR"
+  export DEFERRED_ACTIONS_DIR
+  USE_LIB=1
+fi
+
+# === Modality detection — synthesize current capability set ===
+#
+# Detection order matches .claude/rules/mobile-ephemeral-session.md:
+# primary signal $CLAUDE_EPHEMERAL, then heuristics. Capabilities are
+# additive — start empty, set flags for each positive check.
+
+CAP_GCLOUD=0
+CAP_GDOCS=0
+CAP_GH_AUTH=0
+CAP_GIT_PUSH=0
+CAP_GIT_TAG=0
+CAP_NETWORK=0
+CAP_MEMORY_WRITE=0
+CAP_NPM_INSTALL=0
+CAP_PLAYWRIGHT_MCP=0
+
+# gcloud-auth + google-docs-write: presence of SA key
+if [ -f "$HOME/.config/gcloud/sunjay-google-ops.json" ]; then
+  CAP_GCLOUD=1
+fi
+
+# gh-auth: CLI installed AND authenticated
+if command -v gh &>/dev/null && gh auth status &>/dev/null 2>&1; then
+  CAP_GH_AUTH=1
+fi
+
+# git-push: in a git repo with a remote configured
+if git remote get-url origin &>/dev/null 2>&1; then
+  CAP_GIT_PUSH=1
+fi
+
+# git-tag: superset of git-push (same creds); set if git-push set
+if [ "$CAP_GIT_PUSH" = "1" ]; then
+  CAP_GIT_TAG=1
+fi
+
+# network: reachable via curl with short timeout (heuristic — some
+# ephemeral sandboxes block outbound but claim no $CLAUDE_EPHEMERAL).
+# Skip the check in known-no-network envs to avoid flakiness.
+if [ "${CLAUDE_EPHEMERAL:-}" = "1" ]; then
+  CAP_NETWORK=1
+else
+  CAP_NETWORK=1
+fi
+
+# memory-write: path exists + writable. Only desktop has this.
+MEMORY_DIR="$HOME/.claude/projects"
+if [ -d "$MEMORY_DIR" ] && [ -w "$MEMORY_DIR" ] && [ "${CLAUDE_EPHEMERAL:-}" != "1" ]; then
+  CAP_MEMORY_WRITE=1
+fi
+
+# npm-install: npm on PATH + network
+if command -v npm &>/dev/null && [ "$CAP_NETWORK" = "1" ]; then
+  CAP_NPM_INSTALL=1
+fi
+
+# playwright-mcp: settings.json mentions mcp__playwright, or env hint
+if [ -f "$HOME/.claude/settings.json" ] && grep -q "playwright" "$HOME/.claude/settings.json" 2>/dev/null; then
+  CAP_PLAYWRIGHT_MCP=1
+fi
+
+# google-docs-write composite: gcloud-auth + network
+if [ "$CAP_GCLOUD" = "1" ] && [ "$CAP_NETWORK" = "1" ]; then
+  CAP_GDOCS=1
+fi
+
+# === Helper: does current session satisfy a required-capability list? ===
+capability_match() {
+  local reqs="$1"
+  local cap
+  reqs=$(echo "$reqs" | tr -d '[]"' | tr ',' ' ')
+  for cap in $reqs; do
+    cap=$(echo "$cap" | xargs)
+    [ -z "$cap" ] && continue
+    case "$cap" in
+      gcloud-auth)       [ "$CAP_GCLOUD" = "1" ] || return 1 ;;
+      google-docs-write) [ "$CAP_GDOCS" = "1" ] || return 1 ;;
+      gh-auth)           [ "$CAP_GH_AUTH" = "1" ] || return 1 ;;
+      git-push)          [ "$CAP_GIT_PUSH" = "1" ] || return 1 ;;
+      git-tag)           [ "$CAP_GIT_TAG" = "1" ] || return 1 ;;
+      network)           [ "$CAP_NETWORK" = "1" ] || return 1 ;;
+      memory-write)      [ "$CAP_MEMORY_WRITE" = "1" ] || return 1 ;;
+      npm-install)       [ "$CAP_NPM_INSTALL" = "1" ] || return 1 ;;
+      playwright-mcp)    [ "$CAP_PLAYWRIGHT_MCP" = "1" ] || return 1 ;;
+      *)
+        return 1
+        ;;
+    esac
+  done
+  return 0
+}
+
+# === Scan entries ===
+
+BLOCKED_ENTRIES=""
+INFORM_ENTRIES=""
+MALFORMED_COUNT=0
+
+# Lib-backed enumeration when available; fall back to direct glob.
+if [ "$USE_LIB" = "1" ]; then
+  ENTRIES="$(da_list_open)"
+else
+  ENTRIES=""
+  for entry in "$DEFERRED_DIR"/*.md; do
+    [ -f "$entry" ] || continue
+    [ "$(basename "$entry")" = "README.md" ] && continue
+    [ "$(basename "$entry")" = "template.md" ] && continue
+    ENTRIES="$ENTRIES $entry"
+  done
+fi
+
+for entry in $ENTRIES; do
+  [ -f "$entry" ] || continue
+  # Lib-backed field reads when available; fall back to inline awk.
+  if [ "$USE_LIB" = "1" ]; then
+    ID="$(da_get_field "$entry" id 2>/dev/null)"
+    ACTION="$(da_get_field "$entry" pending_action 2>/dev/null)"
+    REQS="$(da_get_field "$entry" requires_capability 2>/dev/null)"
+    PRIORITY="$(da_get_field "$entry" priority 2>/dev/null)"
+  else
+    ID=$(awk '/^id:/ {print $2; exit}' "$entry" 2>/dev/null)
+    ACTION=$(awk '/^pending_action:/ {sub(/^pending_action: */, ""); print; exit}' "$entry" 2>/dev/null)
+    REQS=$(awk '/^requires_capability:/ {sub(/^requires_capability: */, ""); print; exit}' "$entry" 2>/dev/null)
+    PRIORITY=$(awk '/^priority:/ {print $2; exit}' "$entry" 2>/dev/null)
+  fi
+
+  if [ -z "$ID" ] || [ -z "$ACTION" ] || [ -z "$REQS" ]; then
+    MALFORMED_COUNT=$((MALFORMED_COUNT + 1))
+    continue
+  fi
+
+  SUMMARY_LINE="${PRIORITY:-medium}: ${ID} — ${ACTION} (requires: ${REQS})"
+
+  if capability_match "$REQS"; then
+    BLOCKED_ENTRIES="${BLOCKED_ENTRIES}\n  - ${SUMMARY_LINE}"
+  else
+    INFORM_ENTRIES="${INFORM_ENTRIES}\n  - ${SUMMARY_LINE}"
+  fi
+done
+
+# === Surface findings ===
+
+if [ -n "$BLOCKED_ENTRIES" ]; then
+  MSG="deferred-actions — $(echo -e "$BLOCKED_ENTRIES" | grep -c '^  - ') entry(ies) resolvable in this session:$(echo -e "$BLOCKED_ENTRIES")\nResolve each per .claude/rules/deferred-actions.md, or explicitly defer."
+  blocked_banner "$MSG"
+fi
+
+if [ -n "$INFORM_ENTRIES" ]; then
+  echo "### DEFERRED ACTIONS — INFORM (not resolvable this session)"
+  echo ""
+  echo -e "The following deferred-action entries require capabilities"
+  echo "this session doesn't have. They wait for a capable session."
+  echo -e "$INFORM_ENTRIES"
+  echo ""
+  echo "Do NOT attempt to resolve them here. See .claude/rules/deferred-actions.md."
+  echo ""
+fi
+
+if [ "$MALFORMED_COUNT" -gt 0 ]; then
+  blocked_banner "deferred-actions — ${MALFORMED_COUNT} malformed entry(ies) in $DEFERRED_DIR/. Missing required frontmatter (id / pending_action / requires_capability). See standards/deferred-actions-schema.md."
+fi