@thebassclef/lite 1.0.0 → 1.0.1

package/dist/lite/.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