@thebassclef/lite 1.0.4 → 1.1.0

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

@@ -0,0 +1,459 @@
+#!/usr/bin/env bash
+# tier: lite
+# lib/composer-preflight.sh — shared pre-flight check for composer skills.
+#
+# Composer skills (/launch, /build, /shape full) source this helper
+# in Phase -1 (before Phase 0). Surfaces 6 prerequisites at once:
+#   1. feature-branch  — repo on a feature branch (refuses on main)
+#   2. state-spine     — lib/state.sh present (AUTO-PREP from bassclef)
+#   3. personas        — at least 1 persona scaffolded (signal-and-offer)
+#   4. budget          — iteration_ceiling sufficient for estimate
+#   5. skill-registry  — dispatching skill resolves (covers bassclef#271)
+#   6. deploy-host     — hosting_platform set + adapter shipped (bassclef#449/#450)
+#
+# Usage (from a composer SKILL.md procedure):
+#   source $BASSCLEF_DIR/lib/composer-preflight.sh
+#   composer_preflight_check <skill_name> <estimated_turns> [--no-launch]
+#   case $? in
+#     0) ;;                            # all pass — proceed to Phase 0
+#     1) ;;                            # warnings — composer prompts operator proceed/abort
+#     2) exit 1 ;;                     # failures — composer refuses dispatch
+#   esac
+#
+# --no-launch: variants-only run; Check 6 short-circuits to pass.
+#   Use when /launch is invoked for variant generation only,
+#   no deploy-host chain. /stage (light) is the typical caller.
+#
+# Override: SKIP_COMPOSER_PREFLIGHT=1 (logged via trace-helper).
+#
+# Standard: standards/composer-prerequisites.md
+# Refs bassclef#408 (preflight scaffold) + bassclef#449/#450 (deploy-host check).
+
+# Don't use `set -e` — preflight checks must complete even when one fails.
+
+# Output format (key=value lines on stdout):
+#   check_<n>_name=<check name>
+#   check_<n>_status=<pass|warn|fail>
+#   check_<n>_message=<single-line message>
+#   check_<n>_recommendation=<single-line recommendation>
+#   summary_status=<pass|warn|fail>
+#   summary_count_pass=<n>
+#   summary_count_warn=<n>
+#   summary_count_fail=<n>
+
+composer_preflight_check() {
+  local skill_name="${1:-}"
+  local estimated_turns="${2:-50}"
+  local mode_flag="${3:-}"          # optional: --no-launch for variants-only runs
+
+  # Override hatch
+  if [ "${SKIP_COMPOSER_PREFLIGHT:-0}" = "1" ]; then
+    if command -v trace_log >/dev/null 2>&1; then
+      trace_log "composer-preflight" "OVERRIDE skill=$skill_name" 2>/dev/null || true
+    fi
+    echo "summary_status=skip"
+    return 0
+  fi
+
+  if [ -z "$skill_name" ]; then
+    echo "summary_status=fail" >&2
+    echo "ERROR: composer_preflight_check requires skill_name" >&2
+    return 2
+  fi
+
+  local pass=0 warn=0 fail=0
+
+  # === Check 1: feature-branch ===
+  local current_branch
+  current_branch=$(git branch --show-current 2>/dev/null || echo "")
+  echo "check_1_name=feature-branch"
+  if [ -z "$current_branch" ]; then
+    echo "check_1_status=fail"
+    echo "check_1_message=Not in a git repository OR branch detection failed"
+    echo "check_1_recommendation=Run from inside a git repository"
+    fail=$((fail + 1))
+  elif [ "$current_branch" = "main" ] || [ "$current_branch" = "master" ]; then
+    echo "check_1_status=fail"
+    echo "check_1_message=On $current_branch — composer skills refuse to run from default branch"
+    echo "check_1_recommendation=git checkout -b feature/<slug>"
+    fail=$((fail + 1))
+  else
+    echo "check_1_status=pass"
+    echo "check_1_message=On feature branch: $current_branch"
+    echo "check_1_recommendation="
+    pass=$((pass + 1))
+  fi
+
+  # === Check 2: state-spine ===
+  local repo_root
+  repo_root=$(git rev-parse --show-toplevel 2>/dev/null || pwd)
+  echo "check_2_name=state-spine"
+  if [ -f "$repo_root/lib/state.sh" ]; then
+    echo "check_2_status=pass"
+    echo "check_2_message=lib/state.sh present"
+    echo "check_2_recommendation="
+    pass=$((pass + 1))
+  else
+    # Auto-prep available: bootstrap from BASSCLEF_DIR if reachable
+    local bassclef_state="${BASSCLEF_DIR:-}/lib/state.sh"
+    if [ -n "${BASSCLEF_DIR:-}" ] && [ -f "$bassclef_state" ]; then
+      echo "check_2_status=warn"
+      echo "check_2_message=lib/state.sh missing; AUTO-PREP available from $bassclef_state"
+      echo "check_2_recommendation=cp $bassclef_state $repo_root/lib/state.sh   # safe to auto-execute"
+      warn=$((warn + 1))
+    else
+      echo "check_2_status=fail"
+      echo "check_2_message=lib/state.sh missing AND BASSCLEF_DIR not reachable"
+      echo "check_2_recommendation=Run /onboard-repo to bootstrap bassclef substrate"
+      fail=$((fail + 1))
+    fi
+  fi
+
+  # === Check 3: personas ===
+  echo "check_3_name=personas"
+  local persona_count=0
+  if [ -d "$repo_root/docs/personas" ]; then
+    persona_count=$(find "$repo_root/docs/personas" -maxdepth 1 -name "*.md" -type f 2>/dev/null | wc -l | tr -d ' ')
+  fi
+  if [ "$persona_count" -ge 1 ]; then
+    echo "check_3_status=pass"
+    echo "check_3_message=$persona_count persona(s) scaffolded"
+    echo "check_3_recommendation="
+    pass=$((pass + 1))
+  else
+    echo "check_3_status=warn"
+    echo "check_3_message=No personas scaffolded; composers default to operator-as-persona"
+    echo "check_3_recommendation=Run /personas to seed primary persona OR proceed with operator-only"
+    warn=$((warn + 1))
+  fi
+
+  # === Check 4: budget ===
+  echo "check_4_name=budget"
+  local budget_estimate=$(( estimated_turns * 10 / 100 ))   # rough $0.10/turn proxy
+  local ceiling=""
+  if [ -f "$repo_root/substrate.config.md" ]; then
+    # Use [[:space:]] (POSIX) instead of \s (GNU extension) for BSD sed compat
+    ceiling=$(grep -E '^[[:space:]]*iteration_ceiling:' "$repo_root/substrate.config.md" 2>/dev/null \
+      | head -1 | sed 's/.*:[[:space:]]*//;s/[[:space:]].*//;s/^\$//' || echo "")
+  fi
+  if [ -z "$ceiling" ] || [ "$ceiling" = "0" ]; then
+    # Sequential mode (no burst cost) — pass
+    echo "check_4_status=pass"
+    echo "check_4_message=Sequential mode (\$0 burst); estimated $estimated_turns turns"
+    echo "check_4_recommendation="
+    pass=$((pass + 1))
+  elif ! [[ "$ceiling" =~ ^[0-9]+$ ]]; then
+    # Non-numeric ceiling (e.g., free-form description) — pass with note
+    echo "check_4_status=pass"
+    echo "check_4_message=iteration_ceiling: $ceiling (free-form); estimated $estimated_turns turns"
+    echo "check_4_recommendation="
+    pass=$((pass + 1))
+  elif [ "$ceiling" -lt "$budget_estimate" ]; then
+    echo "check_4_status=warn"
+    echo "check_4_message=iteration_ceiling \$$ceiling < estimated \$$budget_estimate ($estimated_turns turns)"
+    echo "check_4_recommendation=Bump iteration_ceiling in substrate.config.md OR reduce composer tier"
+    warn=$((warn + 1))
+  else
+    echo "check_4_status=pass"
+    echo "check_4_message=iteration_ceiling \$$ceiling >= estimated \$$budget_estimate"
+    echo "check_4_recommendation="
+    pass=$((pass + 1))
+  fi
+
+  # === Check 5: skill-registry ===
+  # Detects bassclef#271 race — skill not picked up by harness registry.
+  # Read-and-check approach: the skill MUST exist as SKILL.md at a discoverable
+  # path. Three discovery paths:
+  #   a) ~/.claude/skills/<skill>/SKILL.md (user-level symlink — harness primary)
+  #   b) <repo>/.claude/skills/<skill>/SKILL.md (repo-level — fallback)
+  #   c) <BASSCLEF_DIR>/.claude/skills/<skill>/SKILL.md (bassclef authoritative)
+  echo "check_5_name=skill-registry"
+  local user_skill="$HOME/.claude/skills/$skill_name/SKILL.md"
+  local repo_skill="$repo_root/.claude/skills/$skill_name/SKILL.md"
+  local bassclef_skill="${BASSCLEF_DIR:-}/.claude/skills/$skill_name/SKILL.md"
+
+  if [ -f "$user_skill" ] || [ -L "$user_skill" ]; then
+    echo "check_5_status=pass"
+    echo "check_5_message=Skill resolves at user-level: $user_skill"
+    echo "check_5_recommendation="
+    pass=$((pass + 1))
+  elif [ -f "$repo_skill" ] || [ -L "$repo_skill" ]; then
+    echo "check_5_status=warn"
+    echo "check_5_message=Skill at repo-level only ($repo_skill); user-level symlink missing — harness may not pick up (bassclef#271)"
+    echo "check_5_recommendation=Run bassclef-sync.sh to create user-level symlink OR restart Claude session"
+    warn=$((warn + 1))
+  elif [ -n "${BASSCLEF_DIR:-}" ] && [ -f "$bassclef_skill" ]; then
+    echo "check_5_status=warn"
+    echo "check_5_message=Skill at bassclef only; consumer-side links missing — substrate sync incomplete"
+    echo "check_5_recommendation=Run bassclef-sync.sh in this repo OR /onboard-repo"
+    warn=$((warn + 1))
+  else
+    echo "check_5_status=fail"
+    echo "check_5_message=Skill /$skill_name not found at any discovery path"
+    echo "check_5_recommendation=Verify skill name OR check bassclef substrate sync"
+    fail=$((fail + 1))
+  fi
+
+  # === Check 6: deploy-host (bassclef#449/#450 + bassclef#523) ===
+  #
+  # Reads hosting_platform from substrate.config.md and verifies (a) a deploy
+  # adapter is shipped AND (b) provisioning has actually happened (the
+  # per-platform provisioning-indicator field is populated with a real value,
+  # not the schema's bracketed placeholder). Catches the preview→production
+  # gap before /launch burns 200t AND the silent-defer-bind class
+  # where Phase 12 silently no-ops because the consumer never ran
+  # /provision-deploy-host (bassclef#523 — today's POA mobile session).
+  #
+  # Logic:
+  #   missing hosting_platform               → fail (set hosting_platform: amplify)
+  #   hosting_platform=none + --no-launch    → pass (variants-only run)
+  #   hosting_platform=none + no --no-launch → fail (refuse dispatch)
+  #   adapter shipped + indicator populated  → pass
+  #   adapter shipped + indicator MISSING    → fail with three-path remediation:
+  #     run /provision-deploy-host inline / re-dispatch with --no-launch /
+  #     explicit defer
+  #   adapter not shipped (vercel | netlify | cf-pages) → warn
+  #   any other value → fail (not in enum)
+  #
+  # Per-platform provisioning indicators (set by /provision-deploy-host on success):
+  #   amplify       → amplify_app_id (e.g., d154l5usyc80nk)
+  #   ec2-tailscale → deploy_host (e.g., poa-prod.tailnet.ts.net)
+  #   mock          → no indicator required (test scaffold)
+  #
+  # The override --no-launch lets /launch run in variants-only mode
+  # (e.g., /stage light callers) without requiring deploy-host provisioning.
+  echo "check_6_name=deploy-host"
+  local hosting=""
+  if [ -f "$repo_root/substrate.config.md" ]; then
+    hosting=$(grep -E '^[[:space:]]*hosting_platform:' "$repo_root/substrate.config.md" 2>/dev/null \
+      | head -1 | sed 's/.*:[[:space:]]*//;s/[[:space:]].*//;s/^["'\'']//;s/["'\'']$//')
+  fi
+  local bassclef_adapter_dir="${BASSCLEF_DIR:-}/scripts/adapters/deploy"
+  local adapter_check=""
+  if [ -n "$hosting" ] && [ -n "${BASSCLEF_DIR:-}" ]; then
+    adapter_check="${bassclef_adapter_dir}/${hosting}.sh"
+  fi
+
+  # Helper: read the per-platform provisioning-indicator field from
+  # substrate.config.md. Returns the field value if populated and not the
+  # bracketed placeholder shape (e.g., `[e.g., d154l...]`); empty otherwise.
+  _check6_provisioning_indicator_value() {
+    local field="$1"
+    [ -f "$repo_root/substrate.config.md" ] || return 0
+    local val
+    val=$(grep -E "^[[:space:]]*${field}:" "$repo_root/substrate.config.md" 2>/dev/null \
+      | head -1 | sed 's/.*:[[:space:]]*//;s/[[:space:]]*#.*$//;s/^["'\'']//;s/["'\'']$//')
+    # Reject placeholders (bracketed values are schema templates, not real values)
+    case "$val" in
+      "" | \[*\] | "[]" )
+        echo ""
+        ;;
+      *)
+        echo "$val"
+        ;;
+    esac
+  }
+
+  if [ -z "$hosting" ]; then
+    echo "check_6_status=fail"
+    echo "check_6_message=hosting_platform missing from substrate.config.md"
+    echo "check_6_recommendation=Add 'hosting_platform: amplify' (bassclef default per ADR-008) OR 'hosting_platform: none' if no UI ships"
+    fail=$((fail + 1))
+  elif [ "$hosting" = "none" ]; then
+    if [ "$mode_flag" = "--no-launch" ]; then
+      echo "check_6_status=pass"
+      echo "check_6_message=hosting_platform=none + --no-launch (variants-only run)"
+      echo "check_6_recommendation="
+      pass=$((pass + 1))
+    else
+      echo "check_6_status=fail"
+      echo "check_6_message=hosting_platform=none — composer would generate variants that can't launch"
+      echo "check_6_recommendation=Set hosting_platform to a deploy provider (amplify) OR re-run with --no-launch for variants-only"
+      fail=$((fail + 1))
+    fi
+  elif [ -n "$adapter_check" ] && [ -f "$adapter_check" ]; then
+    # Adapter shipped — now verify provisioning indicator is populated.
+    # --no-launch override skips this gate (variants-only run).
+    if [ "$mode_flag" = "--no-launch" ]; then
+      echo "check_6_status=pass"
+      echo "check_6_message=hosting_platform=$hosting + --no-launch (variants-only; provisioning indicator gate bypassed)"
+      echo "check_6_recommendation="
+      pass=$((pass + 1))
+    else
+      local indicator_field=""
+      case "$hosting" in
+        amplify)       indicator_field="amplify_app_id" ;;
+        ec2-tailscale) indicator_field="deploy_host" ;;
+        mock)          indicator_field="" ;;  # test scaffold, no indicator required
+      esac
+      local indicator_value=""
+      if [ -n "$indicator_field" ]; then
+        indicator_value=$(_check6_provisioning_indicator_value "$indicator_field")
+      fi
+      if [ -z "$indicator_field" ] || [ -n "$indicator_value" ]; then
+        echo "check_6_status=pass"
+        if [ -n "$indicator_field" ]; then
+          echo "check_6_message=hosting_platform=$hosting; adapter shipped; ${indicator_field}=${indicator_value}"
+        else
+          echo "check_6_message=hosting_platform=$hosting; adapter shipped (no indicator required for $hosting)"
+        fi
+        echo "check_6_recommendation="
+        pass=$((pass + 1))
+      else
+        echo "check_6_status=fail"
+        echo "check_6_message=hosting_platform=$hosting; adapter shipped but ${indicator_field} not populated in substrate.config.md — /provision-deploy-host has not run for this consumer"
+        echo "check_6_recommendation=Three paths: (a) run /provision-deploy-host (creates ${hosting} app + populates ${indicator_field}; ~1-2h, mostly waiting); (b) re-dispatch with --no-launch for variants-only (no deploy host needed); (c) explicit defer — tell the agent 'skip launch deploy-host check this session' (per blocked-items.md deferral syntax)"
+        fail=$((fail + 1))
+      fi
+    fi
+  elif [ "$hosting" = "vercel" ] || [ "$hosting" = "netlify" ] || [ "$hosting" = "cloudflare-pages" ]; then
+    echo "check_6_status=warn"
+    echo "check_6_message=hosting_platform=$hosting in schema enum but adapter not yet shipped"
+    echo "check_6_recommendation=Switch to amplify (bassclef default) OR contribute the adapter at scripts/adapters/deploy/${hosting}.sh"
+    warn=$((warn + 1))
+  elif [ "$hosting" = "amplify" ] || [ "$hosting" = "ec2-tailscale" ] || [ "$hosting" = "mock" ]; then
+    # Known-good enum value but adapter not found at expected path — could be
+    # BASSCLEF_DIR pointing at the wrong place, or substrate sync incomplete
+    if [ -z "${BASSCLEF_DIR:-}" ]; then
+      echo "check_6_status=warn"
+      echo "check_6_message=hosting_platform=$hosting (BASSCLEF_DIR not reachable; can't verify adapter)"
+      echo "check_6_recommendation=Set BASSCLEF_DIR OR run /onboard-repo to sync bassclef substrate"
+      warn=$((warn + 1))
+    else
+      echo "check_6_status=warn"
+      echo "check_6_message=hosting_platform=$hosting in enum but adapter missing at $adapter_check"
+      echo "check_6_recommendation=Run bassclef-sync.sh to refresh adapter symlinks OR check BASSCLEF_DIR points at bassclef repo root"
+      warn=$((warn + 1))
+    fi
+  else
+    echo "check_6_status=fail"
+    echo "check_6_message=hosting_platform=$hosting not in schema enum"
+    echo "check_6_recommendation=Use one of: amplify | ec2-tailscale | vercel | netlify | cloudflare-pages | none"
+    fail=$((fail + 1))
+  fi
+
+  # === Check 7: spec-and-use-case (bet 24a Step 2c per Cockburn ceremony matrix) ===
+  # Fires when staged diff includes code paths that merit spec + use-case coverage.
+  # Warns if no artifact at docs/use-cases/UC-*.md OR docs/specs/*.md OR
+  # docs/decompositions/*.md when substrate + adopter code staged.
+  # Per .claude/rules/oo-ad-entry-point.md (extended to include hook/lib/script paths).
+  # Cockburn tiering — new hook + lib merit brief use case; app code merits fully-dressed.
+  echo "check_7_name=spec-and-use-case"
+  local staged_code
+  staged_code=$(git diff --cached --name-only --diff-filter=AM 2>/dev/null | grep -E \
+    -e '^src/.*\.(ts|tsx|js|py)$' \
+    -e '^\.claude/hooks/[^/]+\.sh$' \
+    -e '^lib/[^/]+\.sh$' \
+    -e '^scripts/[^/]+\.sh$' \
+    || true)
+  if [ -z "$staged_code" ]; then
+    echo "check_7_status=pass"
+    echo "check_7_message=No code paths staged (docs-only or non-code commit)"
+    echo "check_7_recommendation="
+    pass=$((pass + 1))
+  else
+    local uc_count spec_count decomp_count total_artifacts
+    uc_count=$(ls "$repo_root/docs/use-cases/"UC-*.md 2>/dev/null | wc -l | tr -d ' ')
+    spec_count=$(ls "$repo_root/docs/specs/"*.md 2>/dev/null | wc -l | tr -d ' ')
+    decomp_count=$(ls "$repo_root/docs/decompositions/"*.md 2>/dev/null | wc -l | tr -d ' ')
+    total_artifacts=$((uc_count + spec_count + decomp_count))
+    if [ "$total_artifacts" -gt 0 ]; then
+      echo "check_7_status=pass"
+      echo "check_7_message=Code staged + $total_artifacts design artifact(s) present (uc=$uc_count spec=$spec_count decomp=$decomp_count)"
+      echo "check_7_recommendation="
+      pass=$((pass + 1))
+    else
+      echo "check_7_status=warn"
+      echo "check_7_message=Code paths staged but no use-case / spec / decomposition present"
+      echo "check_7_recommendation=Per Cockburn ceremony matrix — new hook + lib merit brief use case at docs/use-cases/UC-<slug>.md; app code merits fully-dressed. Skip only for typo/trivial extensions."
+      warn=$((warn + 1))
+    fi
+  fi
+
+  # === Summary ===
+  echo "summary_count_pass=$pass"
+  echo "summary_count_warn=$warn"
+  echo "summary_count_fail=$fail"
+  if [ "$fail" -gt 0 ]; then
+    echo "summary_status=fail"
+    return 2
+  elif [ "$warn" -gt 0 ]; then
+    echo "summary_status=warn"
+    return 1
+  else
+    echo "summary_status=pass"
+    return 0
+  fi
+}
+
+# Helper: render the structured output as a human-readable block.
+# Composers can pipe `composer_preflight_check ... | composer_preflight_render`
+# for a polished operator-facing surface.
+composer_preflight_render() {
+  local skill_name="${1:-the skill}"
+  local input
+  input=$(cat)
+
+  echo ""
+  echo "============================================"
+  echo "PRE-FLIGHT CHECK — /$skill_name"
+  echo "============================================"
+
+  local i status name message rec
+  for i in 1 2 3 4 5 6 7; do
+    status=$(echo "$input" | grep -E "^check_${i}_status=" | head -1 | sed 's/^check_[0-9]_status=//')
+    name=$(echo "$input" | grep -E "^check_${i}_name=" | head -1 | sed 's/^check_[0-9]_name=//')
+    message=$(echo "$input" | grep -E "^check_${i}_message=" | head -1 | sed 's/^check_[0-9]_message=//')
+    rec=$(echo "$input" | grep -E "^check_${i}_recommendation=" | head -1 | sed 's/^check_[0-9]_recommendation=//')
+
+    # Skip render slot if check didn't fire (e.g., pre-Check-6 fixtures)
+    [ -z "$name" ] && continue
+
+    local glyph
+    case "$status" in
+      pass) glyph="✓" ;;
+      warn) glyph="⚠️ " ;;
+      fail) glyph="✗" ;;
+      *)    glyph="?" ;;
+    esac
+
+    printf "  %s %-15s  %s\n" "$glyph" "$name" "$message"
+    if [ -n "$rec" ]; then
+      printf "    └─ recommendation: %s\n" "$rec"
+    fi
+  done
+
+  local summary_status pass warn fail
+  summary_status=$(echo "$input" | grep "^summary_status=" | head -1 | sed 's/^summary_status=//')
+  pass=$(echo "$input" | grep "^summary_count_pass=" | head -1 | sed 's/^summary_count_pass=//')
+  warn=$(echo "$input" | grep "^summary_count_warn=" | head -1 | sed 's/^summary_count_warn=//')
+  fail=$(echo "$input" | grep "^summary_count_fail=" | head -1 | sed 's/^summary_count_fail=//')
+
+  echo ""
+  case "$summary_status" in
+    pass)
+      echo "DISPATCH READY: all $pass checks pass."
+      ;;
+    warn)
+      echo "DISPATCH WITH WARNINGS: $pass pass, $warn warn, $fail fail."
+      echo "Composer should ask operator to proceed/abort."
+      ;;
+    fail)
+      echo "DISPATCH REFUSED: $pass pass, $warn warn, $fail fail."
+      echo "Resolve fail-tier checks before proceeding."
+      ;;
+    skip)
+      echo "PRE-FLIGHT SKIPPED (SKIP_COMPOSER_PREFLIGHT=1)."
+      ;;
+  esac
+  echo "============================================"
+  echo ""
+}
+
+# If sourced, the functions are available. If executed directly, run a
+# self-test against the current repo + report.
+if [ "${BASH_SOURCE[0]:-$0}" = "${0}" ]; then
+  echo "Self-test mode: running composer_preflight_check for /launch with 60-turn estimate"
+  echo ""
+  composer_preflight_check "launch" 60 | composer_preflight_render "launch"
+fi

package/dist/lite/lib/deferred-actions.sh

@@ -0,0 +1,146 @@
+#!/usr/bin/env bash
+# tier: lite
+# lib/deferred-actions.sh — typed accessor for docs/deferred-actions/
+#
+# Single reader/writer for deferred-action entries. Replaces ad-hoc ls +
+# grep patterns in 60-deferred-actions.sh and similar consumers.
+#
+# Public API:
+#   da_dir                                   → echo path to docs/deferred-actions/
+#   da_completed_dir                         → echo path to docs/deferred-actions/completed/
+#   da_list_open                             → list open *.md (one path per line)
+#   da_list_completed                        → list completed/*.md
+#   da_get_field <id> <field>                → frontmatter field reader
+#   da_resolve <id>                          → git mv id.md → completed/id.md
+#   da_filter_by_capability <cap>            → list open whose required-capability matches
+#   da_filter_by_priority <high|medium|low>  → list open by priority field
+#
+# `<id>` may be a bare filename (`2026-04-26T01-00-00Z-foo.md`) or full path.
+# `<cap>` matches against `requires_capability:` frontmatter field.
+
+set -uo pipefail
+
+da_dir() {
+  if [[ -n "${DEFERRED_ACTIONS_DIR:-}" ]]; then
+    echo "$DEFERRED_ACTIONS_DIR"
+  elif [[ -n "${BASSCLEF_REPO_ROOT:-}" ]]; then
+    echo "$BASSCLEF_REPO_ROOT/docs/deferred-actions"
+  else
+    echo "docs/deferred-actions"
+  fi
+}
+
+da_completed_dir() {
+  echo "$(da_dir)/completed"
+}
+
+da_list_open() {
+  local dir
+  dir="$(da_dir)"
+  [[ -d "$dir" ]] || return 0
+  # Open entries = .md files at top-level (not in completed/), excluding README/template
+  find "$dir" -maxdepth 1 -type f -name '*.md' \
+    ! -name 'README.md' \
+    ! -name 'template.md' \
+    2>/dev/null | sort
+}
+
+da_list_completed() {
+  local dir
+  dir="$(da_completed_dir)"
+  [[ -d "$dir" ]] || return 0
+  find "$dir" -maxdepth 1 -type f -name '*.md' 2>/dev/null | sort
+}
+
+# Resolve <id> → full path. Accepts bare filename or full path.
+# Full path forms: absolute (/foo), explicit relative (./foo), or any other
+# string that already resolves to a file. Bare filename: prepended with da_dir.
+# Non-existent bare-relative: also prepended with da_dir (backward compat).
+_da_resolve_path() {
+  local id="$1"
+  if [[ "$id" == /* || "$id" == ./* ]]; then
+    echo "$id"
+  elif [[ -f "$id" ]]; then
+    # Bare-relative path that already resolves — pass through.
+    # Closes bassclef-upstream#1016 (da_list_open output was being doubled).
+    echo "$id"
+  else
+    echo "$(da_dir)/$id"
+  fi
+}
+
+da_get_field() {
+  local id="$1"
+  local field="$2"
+  local path
+  path="$(_da_resolve_path "$id")"
+  [[ -f "$path" ]] || { echo "not-found: $path" >&2; return 1; }
+  # Read frontmatter only (between two `---` lines)
+  awk -v f="$field" '
+    BEGIN { in_fm = 0; seen_open = 0 }
+    /^---[[:space:]]*$/ {
+      if (!seen_open) { seen_open = 1; in_fm = 1; next }
+      else { in_fm = 0; exit }
+    }
+    in_fm && $0 ~ "^" f ":" {
+      sub("^" f ":[[:space:]]*", "")
+      # Strip surrounding quotes if any
+      gsub(/^"|"$/, "")
+      print
+      exit
+    }
+  ' "$path"
+}
+
+da_resolve() {
+  local id="$1"
+  local src dst dst_dir
+  src="$(_da_resolve_path "$id")"
+  [[ -f "$src" ]] || { echo "da_resolve: not-found: $src" >&2; return 1; }
+  dst_dir="$(da_completed_dir)"
+  mkdir -p "$dst_dir"
+  dst="$dst_dir/$(basename "$src")"
+  git mv "$src" "$dst" 2>/dev/null || mv "$src" "$dst"
+}
+
+da_filter_by_capability() {
+  local cap="$1"
+  local entry value
+  while IFS= read -r entry; do
+    [[ -z "$entry" ]] && continue
+    value="$(da_get_field "$entry" requires_capability 2>/dev/null || true)"
+    # Match if exact OR comma-separated list contains cap
+    if [[ "$value" == "$cap" || ",$value," == *",$cap,"* ]]; then
+      echo "$entry"
+    fi
+  done < <(da_list_open)
+}
+
+da_filter_by_priority() {
+  local prio="$1"
+  local entry value
+  while IFS= read -r entry; do
+    [[ -z "$entry" ]] && continue
+    value="$(da_get_field "$entry" priority 2>/dev/null || true)"
+    [[ "$value" == "$prio" ]] && echo "$entry"
+  done < <(da_list_open)
+}
+
+if [[ "${BASH_SOURCE[0]}" == "${0}" ]]; then
+  cmd="${1:-}"
+  shift || true
+  case "$cmd" in
+    dir)                  da_dir ;;
+    completed_dir)        da_completed_dir ;;
+    list_open)            da_list_open ;;
+    list_completed)       da_list_completed ;;
+    get_field)            da_get_field "$@" ;;
+    resolve)              da_resolve "$@" ;;
+    filter_by_capability) da_filter_by_capability "$@" ;;
+    filter_by_priority)   da_filter_by_priority "$@" ;;
+    *)
+      echo "usage: $0 {dir|completed_dir|list_open|list_completed|get_field|resolve|filter_by_capability|filter_by_priority} [args]" >&2
+      exit 2
+      ;;
+  esac
+fi

package/dist/lite/lib/hook-header-parser.sh

@@ -0,0 +1,61 @@
+#!/usr/bin/env bash
+# tier: lite
+# install-class: dual
+#
+# lib/hook-header-parser.sh — reads the # install-class: header from a hook file
+#
+# @pattern patterns/code/gof/adapter.md
+# Adapts raw header text to typed enum values.
+#
+# Contract (Hoare):
+# - Precondition: hook_path exists and is readable
+# - Postcondition (success): stdout is one of operator|project|dual + exit 0
+# - Postcondition (failure): stdout empty + exit non-zero
+#
+# Per docs/decompositions/2026-09-15-install-class-dispatch.md
+# Per docs/use-cases/UC-lib-hook-installer.md
+
+set -euo pipefail
+
+# Valid install-class values per standards/hook-install-class.md
+_HOOK_INSTALL_CLASS_VALID_VALUES=(operator project dual)
+
+# parse_install_class(hook_path) → prints "operator" | "project" | "dual" | ""
+# Returns 0 on success, non-zero on failure.
+parse_install_class() {
+  local hook_path="$1"
+
+  # Precondition: file exists and is readable (not a directory)
+  if [ ! -f "$hook_path" ] || [ ! -r "$hook_path" ]; then
+    return 1
+  fi
+
+  # Read first 10 lines only — strict header window
+  # Match: optional leading whitespace + "# install-class: <value>"
+  # Case-sensitive on value
+  local raw_class
+  raw_class=$(head -n 10 "$hook_path" | grep -E '^[[:space:]]*# install-class:[[:space:]]*' | head -n 1 || true)
+
+  if [ -z "$raw_class" ]; then
+    return 1
+  fi
+
+  # Extract value — strip leading whitespace, hash, "install-class:", surrounding whitespace
+  local value
+  value=$(echo "$raw_class" | sed -E 's/^[[:space:]]*#[[:space:]]*install-class:[[:space:]]*//; s/[[:space:]]*$//')
+
+  # Validate against enum
+  local v
+  for v in "${_HOOK_INSTALL_CLASS_VALID_VALUES[@]}"; do
+    if [ "$value" = "$v" ]; then
+      echo "$value"
+      return 0
+    fi
+  done
+
+  # Unknown or malformed value
+  return 1
+}
+
+# Export for callers that source this file
+export -f parse_install_class 2>/dev/null || true