@thebassclef/lite 0.0.1 → 0.1.2

package/substrate/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