@thebassclef/lite 0.1.2 → 1.0.0

package/substrate/lib/composer-preflight.sh

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