@thebassclef/lite 0.0.1 → 0.1.2

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

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

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