@thebassclef/lite 0.0.1 → 0.1.0

package/substrate/.claude/hooks/post-skill-friction-check.sh

@@ -0,0 +1,177 @@
+#!/bin/bash
+# tier: lite
+# Post-Skill Friction Check — fires on PostToolUse for Skill tool.
+# After "major composer" skills complete, classify the output:
+#   - Unambiguous friction → emit /promote suggestion + log to friction-log
+#   - Borderline friction → log to friction-log (operator curates)
+#   - No friction → silent
+#
+# The friction log is docs/session-friction-log.md (lazy-created).
+# Operator returning from unattended scenario reads the log and triages.
+#
+# Closes the "rough edges noticed but not filed" gap that surfaces when
+# operator runs unattended scenario tests; agent self-monitors during
+# multi-skill chains.
+#
+# Override: SKIP_FRICTION_CHECK=1 to bypass (logged via trace-helper).
+# Per-skill opt-out: skill SKILL.md frontmatter `disable_friction_check: true`
+#
+# Refs bassclef#400.
+
+set +e  # never crash the tool call; fall through silently on any error
+
+INPUT=$(cat)
+TOOL_NAME=$(jq <<< "$INPUT" -r '.tool_name // ""' 2>/dev/null)
+TOOL_INPUT=$(jq <<< "$INPUT" -r '.tool_input // {}' 2>/dev/null)
+TOOL_OUTPUT=$(jq <<< "$INPUT" -r '.tool_output // ""' 2>/dev/null)
+
+# Only fire on Skill tool
+if [ "$TOOL_NAME" != "Skill" ]; then
+  exit 0
+fi
+
+# Override hatch — log and skip
+if [ "${SKIP_FRICTION_CHECK:-0}" = "1" ]; then
+  SCRIPT_DIR="$(cd "$(dirname "$0")" 2>/dev/null && pwd)"
+  if [ -n "$SCRIPT_DIR" ] && [ -f "$SCRIPT_DIR/trace-helper.sh" ]; then
+    source "$SCRIPT_DIR/trace-helper.sh" 2>/dev/null || true
+    trace_log "post-skill-friction-check" "OVERRIDE $TOOL_NAME" 2>/dev/null || true
+  fi
+  exit 0
+fi
+
+# Extract skill name from tool input
+SKILL_NAME=$(jq <<< "$TOOL_INPUT" -r '.skill // ""' 2>/dev/null)
+
+# Major composer skills — these chain other skills or do heavy work.
+# Friction surfaces best at their boundaries.
+MAJOR_SKILLS_PATTERN="^(preview|preview-build|build|shape|longrun|decompose|spec|architect-review|frontend-design|prototype-variants|prototype-gallery|interpret-input|objectory-decompose|ux-migration|ia-model|interaction-design|use-case|user-stories|jtbd-tasks|task-scenarios)$"
+
+if ! echo "$SKILL_NAME" | grep -qE "$MAJOR_SKILLS_PATTERN"; then
+  exit 0
+fi
+
+# Check per-skill opt-out (frontmatter disable_friction_check: true)
+PROJECT_DIR="${CLAUDE_PROJECT_DIR:-$(pwd)}"
+SKILL_FILE="$PROJECT_DIR/.claude/skills/$SKILL_NAME/SKILL.md"
+if [ -f "$SKILL_FILE" ] && head -20 "$SKILL_FILE" | grep -qE "^disable_friction_check:[[:space:]]*true"; then
+  exit 0
+fi
+
+# === Friction classification ===
+#
+# Unambiguous: skill returned error OR clear stub markers
+# Borderline: placeholder text, partial output, drift signals
+# None: clean output
+
+CLASS=""
+SIGNAL=""
+
+# Unambiguous friction signals
+if echo "$TOOL_OUTPUT" | grep -qiE 'deferred to Phase [A-Z]|stub return|TODO: implement|not yet implemented|operator decides .{0,30} manually|placeholder.{0,20}fill in'; then
+  CLASS="unambiguous"
+  SIGNAL=$(echo "$TOOL_OUTPUT" | grep -oiE '(deferred to Phase [A-Z]|stub return|TODO: implement|not yet implemented|operator decides .{0,30} manually|placeholder.{0,20}fill in)' | head -1)
+elif echo "$TOOL_OUTPUT" | grep -qiE '^Error:|exit code [1-9]|skill failed|unable to complete'; then
+  CLASS="unambiguous"
+  SIGNAL=$(echo "$TOOL_OUTPUT" | grep -iE '^Error:|exit code [1-9]|skill failed|unable to complete' | head -1)
+fi
+
+# Borderline friction signals (only check if not already classified)
+if [ -z "$CLASS" ]; then
+  if echo "$TOOL_OUTPUT" | grep -qiE 'lorem ipsum|fill in here|XXX|FIXME|partial.{0,20}output|incomplete'; then
+    CLASS="borderline"
+    SIGNAL=$(echo "$TOOL_OUTPUT" | grep -oiE 'lorem ipsum|fill in here|XXX|FIXME|partial.{0,20}output|incomplete' | head -1)
+  fi
+fi
+
+# No friction → silent exit
+if [ -z "$CLASS" ]; then
+  exit 0
+fi
+
+# === Append to friction log ===
+
+LOG_FILE="$PROJECT_DIR/docs/session-friction-log.md"
+TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+DATE_HEADER=$(date -u +"%Y-%m-%d")
+
+# Lazy-create log file if missing
+if [ ! -f "$LOG_FILE" ]; then
+  mkdir -p "$(dirname "$LOG_FILE")" 2>/dev/null
+  cat > "$LOG_FILE" <<'HEADER'
+# Session Friction Log
+
+Tracks rough edges, stub returns, and other friction encountered
+during chained skill dispatches. Generated by
+`.claude/hooks/post-skill-friction-check.sh` (bassclef#400).
+
+**Format**: `<timestamp> [<class>] /<skill> — <signal> — <action taken>`
+
+**Classes**:
+- `unambiguous` — clear friction (error, stub return, deferred phase); auto-files /promote OR logs here
+- `borderline` — partial output, placeholder text; operator triages on return
+
+**Operator workflow on return**:
+1. Read recent entries
+2. For each `borderline` worth filing → run `/promote substrate-defect`
+3. Move resolved entries to `## Resolved` section below
+
+---
+
+## Active
+
+HEADER
+fi
+
+# Truncate signal to one line
+SIGNAL_TRUNCATED=$(echo "$SIGNAL" | head -c 200 | tr '\n' ' ' | sed 's/[[:space:]]\+/ /g; s/[[:space:]]$//')
+
+# Append entry
+ENTRY="- ${TIMESTAMP} [${CLASS}] /${SKILL_NAME} — ${SIGNAL_TRUNCATED}"
+
+# Check if today's date header already exists; append under it
+if grep -qF "## Active" "$LOG_FILE"; then
+  # Append to Active section. Use awk to insert after "## Active" line.
+  awk -v entry="$ENTRY" '
+    /^## Active$/ { print; print ""; print entry; next }
+    { print }
+  ' "$LOG_FILE" > "$LOG_FILE.tmp" && mv "$LOG_FILE.tmp" "$LOG_FILE"
+fi
+
+# === Emit to operator + agent context ===
+#
+# stderr is captured by Claude Code and surfaced to the agent on next turn.
+
+cat >&2 <<EOF
+
+🔍 POST-SKILL FRICTION CHECK
+─────────────────────────────────────
+Skill:  /$SKILL_NAME
+Class:  $CLASS
+Signal: $SIGNAL_TRUNCATED
+
+Logged to: docs/session-friction-log.md
+
+EOF
+
+if [ "$CLASS" = "unambiguous" ]; then
+  cat >&2 <<EOF
+RECOMMENDED: file /promote substrate-defect now (don't defer).
+The signal is clear-cut; auto-prompting operator-on-return adds latency.
+
+To file: /promote substrate-defect $SKILL_NAME — $SIGNAL_TRUNCATED
+
+To skip (rare): SKIP_FRICTION_CHECK=1 next invocation.
+─────────────────────────────────────
+EOF
+else
+  cat >&2 <<EOF
+ACTION: continue — operator will triage on return.
+If you (agent) judge this warrants /promote inline, fire it.
+Otherwise log entry above is sufficient.
+─────────────────────────────────────
+EOF
+fi
+
+# Always exit 0 — friction-check is informational, not blocking
+exit 0

package/substrate/.claude/hooks/post-skill-telemetry.sh

@@ -0,0 +1,62 @@
+#!/usr/bin/env bash
+# .claude/hooks/post-skill-telemetry.sh
+# tier: lite
+# install-class: dual
+# PostToolUse: Skill
+#
+# Emits a `skill_invoke` telemetry event after any Skill tool call.
+# Silent-fail per @luminary michael-nygard R1 — never crashes the session.
+# Reads Claude Code PostToolUse JSON on stdin; extracts skill name from
+# tool_input.
+#
+# Wired in .claude/settings.json under hooks.PostToolUse[matcher=Skill].
+
+set -u
+
+CWD="${CLAUDE_PROJECT_DIR:-$PWD}"
+
+# Silent-fail wrap — any error path exits 0 cleanly
+{
+  if [ ! -f "$CWD/lib/telemetry.sh" ]; then
+    exit 0
+  fi
+
+  # Read Claude Code stdin JSON
+  input=$(cat 2>/dev/null || echo "")
+  if [ -z "$input" ]; then
+    exit 0
+  fi
+
+  # Extract skill name — tool_input.name is the standard field for Skill tool
+  if command -v jq >/dev/null 2>&1; then
+    skill_name=$(echo "$input" | jq -r '.tool_input.skill // .tool_input.name // empty' 2>/dev/null)
+  else
+    # Bash-only fallback — grep for skill or name field
+    skill_name=$(echo "$input" | grep -oE '"skill"[[:space:]]*:[[:space:]]*"[^"]*"' | head -1 | sed 's/.*"\([^"]*\)"$/\1/')
+    [ -z "$skill_name" ] && skill_name=$(echo "$input" | grep -oE '"name"[[:space:]]*:[[:space:]]*"[^"]*"' | head -1 | sed 's/.*"\([^"]*\)"$/\1/')
+  fi
+
+  # Skill names must start with a letter; normalize to /skill-name shape
+  if [ -z "$skill_name" ]; then
+    exit 0
+  fi
+  # Strip leading slash if present
+  skill_name="${skill_name#/}"
+  # Only ship if the name matches the schema pattern
+  if ! echo "$skill_name" | grep -qE '^[a-z][a-z0-9-]*$'; then
+    exit 0
+  fi
+  skill_name="/$skill_name"
+
+  # shellcheck source=/dev/null
+  source "$CWD/lib/telemetry.sh" 2>/dev/null || exit 0
+
+  if telemetry_is_enabled; then
+    sid=$(telemetry_session_id)
+    uid=$(uuidgen 2>/dev/null | tr '[:upper:]' '[:lower:]' || echo "00000000-0000-4000-8000-000000000002")
+    ts=$(date -u +%Y-%m-%dT%H:%M:%SZ)
+    telemetry_emit "{\"event_type\":\"skill_invoke\",\"event_id\":\"$uid\",\"session_id\":\"$sid\",\"timestamp\":\"$ts\",\"tier\":\"lite\",\"payload\":{\"skill_name\":\"$skill_name\"}}"
+  fi
+} 2>/dev/null || true
+
+exit 0