@thebassclef/lite 0.1.2 → 1.0.0

package/substrate/.claude/hooks/skill-step-list-check.sh

@@ -1,171 +0,0 @@
-#!/bin/bash
-# tier: lite
-# install-class: dual
-# Skill-step-list check — Stop hook that scans the transcript for a Skill tool
-# dispatch followed by an assistant response without a step-list block.
-#
-# Per sunj-labs/bassclef-upstream#1119: closes the SKILL-step-skip class caught
-# in session 2026-08-05a. Rule at .claude/rules/skill-procedure-step-list.md.
-# Ships as pair per bootstrap-pair-discipline.md.
-#
-# Sibling pattern: .claude/hooks/turn-prose-kiss-check.sh (Stop hook + transcript scan).
-#
-# Input (stdin): JSON with transcript_path + session_id
-#   {"transcript_path": "/path/to/transcript.jsonl", "session_id": "..."}
-#
-# Toggle (env or .claude/bassclef-configs.jsonc):
-#   SKILL_STEP_LIST_TOGGLE=true    — advisory (exit 0, findings to stderr) [DEFAULT]
-#   SKILL_STEP_LIST_TOGGLE=strict  — strict (exit 2, blocks stop, forces rewrite)
-#   SKILL_STEP_LIST_TOGGLE=false   — silent (exit 0, no scan)
-#
-# Override per-call:
-#   SKIP_SKILL_STEP_LIST=1         — skip scan, exit 0
-#
-# Exit codes:
-#   0 — pass (no findings, advisory mode, toggle off, override set, or no Skill dispatched)
-#   2 — block stop (strict mode + Skill dispatched + no step-list in response)
-#
-# Reads:
-#   - $TRANSCRIPT_PATH (JSONL, one event per line)
-#   - .claude/bassclef-configs.jsonc (toggle when env not set)
-
-set +e
-
-# === Override path ===
-if [ "${SKIP_SKILL_STEP_LIST:-0}" = "1" ]; then
-  exit 0
-fi
-
-# === Source install-class resolver ===
-SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-
-# Hook liveness heartbeat (silent-fail)
-{
-  for _hb_c in "${SCRIPT_DIR}/../../lib/hook-heartbeat.sh" "${HOME:-/}/lib/hook-heartbeat.sh"; do
-    [ -f "$_hb_c" ] && source "$_hb_c" && heartbeat_mark "skill-step-list-check" && break
-  done
-  unset _hb_c
-} 2>/dev/null || true
-
-for _candidate in \
-  "${SCRIPT_DIR}/../../lib/hook-inject.sh" \
-  "${HOME_OVERRIDE:-${HOME:-/}}/lib/hook-inject.sh"; do
-  if [ -f "$_candidate" ]; then
-    # shellcheck disable=SC1090
-    source "$_candidate"
-    break
-  fi
-done
-unset _candidate
-
-# === Parse stdin JSON ===
-STDIN_JSON=$(cat 2>/dev/null || echo '{}')
-TRANSCRIPT_PATH=$(echo "$STDIN_JSON" | jq -r '.transcript_path // ""' 2>/dev/null)
-
-# Graceful skip if no transcript path
-if [ -z "$TRANSCRIPT_PATH" ]; then
-  exit 0
-fi
-
-# Graceful skip if transcript file missing
-if [ ! -f "$TRANSCRIPT_PATH" ]; then
-  exit 0
-fi
-
-# === Resolve config file ===
-if declare -f resolve_config_path >/dev/null 2>&1; then
-  CONFIG_FILE=$(resolve_config_path 2>/dev/null) || CONFIG_FILE=""
-else
-  CONFIG_FILE="${SCRIPT_DIR}/../bassclef-configs.jsonc"
-fi
-
-# === Resolve toggle ===
-TOGGLE="${SKILL_STEP_LIST_TOGGLE:-}"
-if [ -z "$TOGGLE" ]; then
-  if [ -n "$CONFIG_FILE" ] && [ -f "$CONFIG_FILE" ]; then
-    TOGGLE=$(sed 's|//.*||g' "$CONFIG_FILE" 2>/dev/null \
-      | jq -r '.skill_step_list.toggle // "true"' 2>/dev/null)
-  fi
-  TOGGLE="${TOGGLE:-true}"
-fi
-
-case "$TOGGLE" in
-  true|"true") MODE="advisory" ;;
-  strict|"strict") MODE="strict" ;;
-  false|"false") exit 0 ;;
-  *) MODE="advisory" ;;
-esac
-
-# === Scan transcript for a Skill tool_use ===
-# We scan the last 200 lines to keep the hook fast.
-LAST_LINES=$(tail -200 "$TRANSCRIPT_PATH" 2>/dev/null)
-
-# Find lines with Skill tool_use
-SKILL_LINE_NUM=$(echo "$LAST_LINES" | grep -n '"type":"tool_use"' 2>/dev/null | grep '"name":"Skill"' | tail -1 | cut -d: -f1)
-
-if [ -z "$SKILL_LINE_NUM" ]; then
-  # No Skill dispatched in recent transcript — silent pass
-  exit 0
-fi
-
-# === Find the assistant text_content event AFTER the Skill line ===
-# The response we care about is the one after the Skill tool_result comes back.
-AFTER_SKILL=$(echo "$LAST_LINES" | tail -n +"$((SKILL_LINE_NUM + 1))" 2>/dev/null)
-
-# Get the latest assistant text_content in that portion
-LAST_ASSISTANT_AFTER=$(echo "$AFTER_SKILL" | grep '"type":"assistant"' | tail -1)
-
-if [ -z "$LAST_ASSISTANT_AFTER" ]; then
-  # Skill dispatched but no response yet — silent pass
-  exit 0
-fi
-
-# Extract text content from the assistant message
-MESSAGE_TEXT=$(echo "$LAST_ASSISTANT_AFTER" \
-  | jq -r '.message.content[]? |
-      if .type == "text" then
-        .text
-      else
-        empty
-      end' 2>/dev/null)
-
-if [ -z "$MESSAGE_TEXT" ]; then
-  # Assistant message had no text content (tool_use only) — silent pass
-  exit 0
-fi
-
-# === Check for step-list pattern ===
-# Pattern: two markers must both appear:
-#   1. A "Step N" reference (Step + digit)
-#   2. At least one "[x]" or "[~]" bracket status marker
-HAS_STEP=$(echo "$MESSAGE_TEXT" | grep -cE 'Step[[:space:]]+[0-9]+' 2>/dev/null)
-HAS_MARKER=$(echo "$MESSAGE_TEXT" | grep -cE '\[[x~]\]' 2>/dev/null)
-
-if [ "$HAS_STEP" -gt 0 ] && [ "$HAS_MARKER" -gt 0 ]; then
-  # Step-list present — silent pass
-  exit 0
-fi
-
-# === Missing step-list — emit finding ===
-NOTICE="SKILL step-list check: recent Skill dispatch response lacks a step-list block."
-NOTICE="$NOTICE Per .claude/rules/skill-procedure-step-list.md,"
-NOTICE="$NOTICE write each SKILL procedure step with [x] done+source OR [~] deferred+reason."
-
-# Trace log if trace-helper available
-if [ -f "${SCRIPT_DIR}/../../lib/trace-helper.sh" ]; then
-  source "${SCRIPT_DIR}/../../lib/trace-helper.sh" 2>/dev/null
-  if declare -f trace_record >/dev/null 2>&1; then
-    trace_record "skill-step-list-check" "advisory-fired" "$NOTICE" 2>/dev/null
-  fi
-fi
-
-if [ "$MODE" = "strict" ]; then
-  echo "🛑 BLOCKED: $NOTICE" >&2
-  echo "" >&2
-  echo "To resolve: rewrite the response with a step list at the top." >&2
-  echo "Override: SKIP_SKILL_STEP_LIST=1 <command> (logged)" >&2
-  exit 2
-else
-  echo "⚠ ADVISORY: $NOTICE" >&2
-  exit 0
-fi

package/substrate/.claude/hooks/state-validate.sh

@@ -1,271 +0,0 @@
-#!/usr/bin/env bash
-# tier: lite
-# state-validate.sh — PreToolUse hook that validates state-spine entity
-# writes against their JSON schemas.
-#
-# Wires per .claude/settings.json under hooks.PreToolUse with matcher
-# "Edit|Write". Reads the tool's event JSON from stdin, detects whether
-# the target file is a state-spine entity, extracts its data per the
-# entity's storage shape, validates against the schema, and BLOCKs
-# (exit non-zero) on failure.
-#
-# Per ADR-015: JSON Schema only for v0. Validator: ajv-cli draft-2020-12.
-# Per state-spine.md: three storage shapes (A/B/C) handled via path-based
-# entity-type detection.
-# Per accessor-library-discipline.md: this is the write-side gate.
-#
-# Override: SKIP_STATE_VALIDATE=1 (logged to stderr).
-#
-# Pairs with: .claude/rules/state-schema-validation.md
-
-set -u
-
-# === Hook liveness heartbeat (WU-3 of bet 2026-07-31d; closes #1002) ===
-# Silent-fail — a missing lib never crashes the hook.
-{
-  _hb_sd="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-  for _hb_c in "${_hb_sd}/../../lib/hook-heartbeat.sh" "${HOME:-/}/lib/hook-heartbeat.sh"; do
-    [ -f "$_hb_c" ] && source "$_hb_c" && heartbeat_mark "state-validate" && break
-  done
-  unset _hb_sd _hb_c
-} 2>/dev/null || true
-
-# === Override path ===
-
-if [ "${SKIP_STATE_VALIDATE:-}" = "1" ]; then
-  echo "[state-validate.sh] SKIP_STATE_VALIDATE=1 — bypassing validation" >&2
-  exit 0
-fi
-
-# === Read PreToolUse event ===
-
-EVENT_JSON="$(cat)"
-TOOL_NAME="$(echo "$EVENT_JSON" | jq -r '.tool_name // empty')"
-TARGET_PATH="$(echo "$EVENT_JSON" | jq -r '.tool_input.file_path // empty')"
-
-# Tool filter: only Edit and Write trigger validation
-case "$TOOL_NAME" in
-  Edit|Write|MultiEdit) ;;
-  *) exit 0 ;;
-esac
-
-# Empty path → pass-through
-if [ -z "$TARGET_PATH" ]; then
-  exit 0
-fi
-
-# === Resolve project dir + schema dir ===
-
-PROJECT_DIR="${CLAUDE_PROJECT_DIR:-$(pwd)}"
-SCHEMA_DIR="${PROJECT_DIR}/standards/state-spine/schemas"
-
-# If schema dir doesn't exist, this repo doesn't have spine v0 yet — pass through
-if [ ! -d "$SCHEMA_DIR" ]; then
-  exit 0
-fi
-
-# === Path-based entity detection ===
-#
-# Returns the entity slug (matching <slug>.schema.json) if path is a
-# state-spine entity, empty otherwise.
-detect_entity_type() {
-  local path="$1"
-  # Strip project_dir prefix if present
-  local rel="${path#${PROJECT_DIR}/}"
-  rel="${rel#./}"
-
-  local result=""
-  case "$rel" in
-    docs/whereami.json)                    result="whereami" ;;
-    substrate.config.json)                 result="substrate-config" ;;
-    docs/preview-state/*.json)             result="preview-state" ;;
-    docs/iteration-bets/*.md)              result="iteration-bet" ;;
-    docs/roadmaps/*.md)                    result="roadmap" ;;
-    docs/stacks/*.md)                      result="stack" ;;
-    docs/decompositions/*.md)              result="decomposition" ;;
-    docs/personas/*.md)                    result="persona" ;;
-    docs/deferred-actions/*.md)            result="deferred-action" ;;
-    chronicle/*.md|docs/chronicle/*.md)    result="chronicle" ;;
-    state/markers/*/*.json)                result="marker" ;;
-    docs/sessions/*.json)                  result="session" ;;
-    docs/sessions/*.md)                    result="session" ;;
-    docs/input-artifacts/*.json)           result="input-artifact" ;;
-    state/template-instances/*.json)       result="template-instance" ;;
-    state/inbox/*.json)                    result="inbox-work-item" ;;
-    state/stack-templates/*.json)          result="stack-template" ;;
-    bassclef-platform.yml|bassclef-platform.yaml) result="bassclef-platform" ;;
-  esac
-
-  # bassclef-platform.yml lives at the root of a SIBLING repo (e.g.,
-  # sunj-labs/platform-config). When edited from outside PROJECT_DIR,
-  # the absolute path doesn't strip cleanly — match by basename suffix
-  # as a fallback. The file MUST be at a repo root (not nested).
-  if [ -z "$result" ]; then
-    case "$path" in
-      */bassclef-platform.yml|*/bassclef-platform.yaml) result="bassclef-platform" ;;
-    esac
-  fi
-
-  echo "$result"
-}
-
-ENTITY="$(detect_entity_type "$TARGET_PATH")"
-
-# Non-state file → pass-through
-if [ -z "$ENTITY" ]; then
-  exit 0
-fi
-
-# === Resolve schema file ===
-
-SCHEMA_FILE="${SCHEMA_DIR}/${ENTITY}.schema.json"
-if [ ! -f "$SCHEMA_FILE" ]; then
-  echo "[state-validate.sh] schema for entity '$ENTITY' not found at $SCHEMA_FILE — pass-through" >&2
-  exit 0
-fi
-
-# === Storage shape detection ===
-#
-# A = pure JSON (whole file validates)
-# B = markdown + YAML frontmatter (extract frontmatter, validate)
-# C = pure JSON (whole file validates) — same as A but for collection entities
-#
-# In practice for the validator: anything ending in .json validates the
-# whole file; anything ending in .md extracts YAML frontmatter and
-# validates that.
-
-extract_data_for_validation() {
-  local path="$1"
-  if [ ! -f "$path" ]; then
-    echo "[state-validate.sh] file does not exist at write time: $path" >&2
-    return 4
-  fi
-  case "$path" in
-    *.json)
-      cat "$path"
-      ;;
-    *.md)
-      # Extract YAML frontmatter, convert to JSON
-      awk '/^---$/{c++; next} c==1' "$path" | python3 -c "
-import sys, yaml, json
-try:
-    data = yaml.safe_load(sys.stdin) or {}
-    print(json.dumps(data, default=str))
-except Exception as e:
-    print(f'YAML parse failed: {e}', file=sys.stderr)
-    sys.exit(3)
-"
-      ;;
-    *.yml|*.yaml)
-      # Pure YAML file (Shape D — entity is the whole file). Convert
-      # to JSON and validate. Used by bassclef-platform.yml.
-      python3 -c "
-import sys, yaml, json
-try:
-    with open('$path') as f:
-        data = yaml.safe_load(f) or {}
-    print(json.dumps(data, default=str))
-except Exception as e:
-    print(f'YAML parse failed: {e}', file=sys.stderr)
-    sys.exit(3)
-"
-      ;;
-    *)
-      echo "[state-validate.sh] unsupported extension for path: $path" >&2
-      return 5
-      ;;
-  esac
-}
-
-# Hoare precondition cure (#1001): on new-file Write the target does not
-# yet exist on disk. Read tool_input.content from the event JSON and
-# materialize a temp file so the extract function can read it. Preserves
-# the disk-read path for Edit and existing-file Write. Silent no-op when
-# content is absent (matches prior file-missing behavior).
-NEW_FILE_TMP=""
-if [ ! -f "$TARGET_PATH" ] && [ "$TOOL_NAME" = "Write" ]; then
-  WRITE_CONTENT="$(echo "$EVENT_JSON" | jq -r '.tool_input.content // empty')"
-  if [ -n "$WRITE_CONTENT" ]; then
-    NEW_FILE_TMP="$(mktemp -t state-validate-newfile-XXXXXX)${TARGET_PATH##*.}"
-    # Add trailing dot if the extension detection above collapsed
-    case "$TARGET_PATH" in
-      *.*) NEW_FILE_TMP="${NEW_FILE_TMP%.*}.${TARGET_PATH##*.}" ;;
-    esac
-    printf '%s' "$WRITE_CONTENT" > "$NEW_FILE_TMP"
-    trap 'rm -f "$NEW_FILE_TMP"' EXIT
-    DATA_JSON="$(extract_data_for_validation "$NEW_FILE_TMP")"
-    EXTRACT_EXIT=$?
-  else
-    exit 0
-  fi
-else
-  DATA_JSON="$(extract_data_for_validation "$TARGET_PATH")"
-  EXTRACT_EXIT=$?
-fi
-
-if [ "$EXTRACT_EXIT" -ne 0 ]; then
-  exit "$EXTRACT_EXIT"
-fi
-
-# Legacy pass-through: pre-spine artifacts have no YAML frontmatter at
-# all (e.g., bets authored before schemas existed). Skip validation
-# with WARN to nudge migration without BLOCKing routine work. WU-4
-# migration brings these into conformance progressively.
-if [ -z "$DATA_JSON" ] || [ "$DATA_JSON" = "{}" ] || [ "$DATA_JSON" = "null" ]; then
-  echo "[state-validate.sh] WARN: $TARGET_PATH ($ENTITY) has no YAML frontmatter — legacy pass-through. Migrate via WU-4 to add minimal metadata." >&2
-  exit 0
-fi
-
-# === Validate via ajv-cli ===
-
-# Stage data as a temp JSON file for ajv -d.
-# Note: ajv-cli detects format by file extension, and macOS mktemp -t
-# appends random suffix AFTER the template, so .json must be explicitly
-# tacked on via mv to ensure it's the trailing extension.
-DATA_TMP_RAW="$(mktemp -t state-validate-XXXXXX)"
-DATA_TMP="${DATA_TMP_RAW}.json"
-mv "$DATA_TMP_RAW" "$DATA_TMP"
-trap 'rm -f "$DATA_TMP"' EXIT
-echo "$DATA_JSON" > "$DATA_TMP"
-
-# Stage all schemas as -r refs so $ref resolution works (e.g., _reference, _value_prop, _appetite_actuals, step)
-REF_ARGS=""
-for ref_schema in "$SCHEMA_DIR"/_*.schema.json "$SCHEMA_DIR"/step.schema.json; do
-  if [ -f "$ref_schema" ] && [ "$ref_schema" != "$SCHEMA_FILE" ]; then
-    REF_ARGS="$REF_ARGS -r $ref_schema"
-  fi
-done
-
-# Run ajv-cli; silence its noisy npm warnings, capture only validation result
-VALIDATION_OUTPUT="$(npx -y -p ajv-cli@5 -p ajv-formats@2 ajv validate \
-  --spec=draft2020 \
-  -s "$SCHEMA_FILE" \
-  $REF_ARGS \
-  -d "$DATA_TMP" \
-  -c ajv-formats 2>&1)"
-VALIDATION_EXIT=$?
-
-if [ "$VALIDATION_EXIT" -eq 0 ]; then
-  exit 0
-fi
-
-# === BLOCK with structured error ===
-
-echo "" >&2
-echo "🛑 STATE-VALIDATE — BLOCKED 🛑" >&2
-echo "" >&2
-echo "Entity:   $ENTITY" >&2
-echo "Schema:   $SCHEMA_FILE" >&2
-echo "Path:     $TARGET_PATH" >&2
-echo "" >&2
-echo "Validation error:" >&2
-# Strip noisy npm warnings; surface only ajv's actual error lines
-echo "$VALIDATION_OUTPUT" | grep -v "^npm warn" | grep -v "^$" >&2
-echo "" >&2
-echo "Per .claude/rules/state-schema-validation.md: state-spine entity" >&2
-echo "writes must conform to their schema. Either:" >&2
-echo "  1. Fix the data to match the schema (preferred)" >&2
-echo "  2. Update the schema if it's wrong (requires PR review)" >&2
-echo "  3. Override with SKIP_STATE_VALIDATE=1 (logged; rare; not for normal work)" >&2
-echo "" >&2
-exit 3