qualia-framework 2.1.0

package/framework/hooks/pre-deploy-gate.sh

@@ -0,0 +1,151 @@
+#!/bin/bash
+# Pre-deploy gate — blocks `vercel --prod` if checks fail
+# Teal-branded output to stderr, JSON systemMessage to stdout
+# Exit 0 = allow, Exit 2 = block
+
+source "$(dirname "$0")/qualia-colors.sh"
+
+# Parse command from stdin JSON
+if [ ! -t 0 ]; then
+    INPUT=$(cat)
+    COMMAND=$(echo "$INPUT" | node -e "try{const d=JSON.parse(require('fs').readFileSync('/dev/stdin','utf8'));process.stdout.write(d.tool_input?.command||d.tool_input||'')}catch(e){}" 2>/dev/null)
+else
+    COMMAND=""
+fi
+
+# Only gate production deploys
+if ! echo "$COMMAND" | grep -qE 'vercel\s+.*--prod|vercel\s+--prod'; then
+    exit 0
+fi
+
+# Skip if gate was passed recently (within 5 minutes)
+STAMP="/tmp/.deploy-gate-$(echo "$PWD" | md5sum | cut -c1-8)"
+if [ -f "$STAMP" ]; then
+    AGE=$(( $(date +%s) - $(stat -c %Y "$STAMP" 2>/dev/null || echo 0) ))
+    if [ "$AGE" -lt 300 ]; then
+        exit 0
+    fi
+fi
+
+q_header "PRE-DEPLOY GATE"
+
+FAILURES=0
+WARNINGS=0
+FAIL_DETAILS=""
+
+# ─── Check 1: TypeScript ───
+if [ -f "tsconfig.json" ]; then
+    if npx tsc --noEmit 2>/tmp/tsc-gate.txt; then
+        q_pass "TypeScript"
+    else
+        q_fail "TypeScript errors"
+        FAIL_DETAILS="${FAIL_DETAILS}TypeScript errors found. Run npx tsc --noEmit to see details. "
+        FAILURES=$((FAILURES + 1))
+    fi
+else
+    q_skip "TypeScript"
+fi
+
+# ─── Check 2: ESLint ───
+if [ -f ".eslintrc.json" ] || [ -f ".eslintrc.js" ] || [ -f "eslint.config.js" ] || [ -f "eslint.config.mjs" ]; then
+    if npx eslint . --max-warnings=-1 --quiet 2>/dev/null; then
+        q_pass "Lint"
+    else
+        q_fail "Lint errors"
+        FAIL_DETAILS="${FAIL_DETAILS}ESLint errors found. Run npx eslint . to see details. "
+        FAILURES=$((FAILURES + 1))
+    fi
+else
+    q_skip "Lint"
+fi
+
+# ─── Check 3: Tests ───
+if [ -f "package.json" ]; then
+    TEST_SCRIPT=$(node -e "try{console.log(require('./package.json').scripts?.test||'')}catch(e){console.log('')}" 2>/dev/null)
+    if [ -n "$TEST_SCRIPT" ] && [ "$TEST_SCRIPT" != 'echo "Error: no test specified" && exit 1' ]; then
+        if npm test -- --passWithNoTests 2>/tmp/test-gate.txt 1>/dev/null; then
+            q_pass "Tests"
+        else
+            q_fail "Tests failed"
+            FAIL_DETAILS="${FAIL_DETAILS}Tests failed. Run npm test to see details. "
+            FAILURES=$((FAILURES + 1))
+        fi
+    else
+        q_skip "Tests"
+    fi
+fi
+
+# ─── Check 4: Build ───
+if [ -f "package.json" ]; then
+    BUILD_SCRIPT=$(node -e "try{console.log(require('./package.json').scripts?.build||'')}catch(e){console.log('')}" 2>/dev/null)
+    if [ -n "$BUILD_SCRIPT" ]; then
+        if npm run build 2>/tmp/build-gate.txt 1>/dev/null; then
+            q_pass "Build"
+        else
+            q_fail "Build failed"
+            FAIL_DETAILS="${FAIL_DETAILS}Build failed. Run npm run build to see errors. "
+            FAILURES=$((FAILURES + 1))
+        fi
+    else
+        q_skip "Build"
+    fi
+fi
+
+# ─── Check 5: Environment ───
+if [ -f ".env.example" ] && [ ! -f ".env.local" ] && [ ! -f ".env" ]; then
+    q_warn "Missing .env.local"
+    WARNINGS=$((WARNINGS + 1))
+else
+    q_pass "Environment"
+fi
+
+# ─── Check 6: REVIEW.md ───
+REVIEW_FILE=""
+[ -f ".planning/REVIEW.md" ] && REVIEW_FILE=".planning/REVIEW.md"
+[ -z "$REVIEW_FILE" ] && [ -f ".review/REVIEW.md" ] && REVIEW_FILE=".review/REVIEW.md"
+
+if [ -z "$REVIEW_FILE" ]; then
+    q_fail "No REVIEW.md"
+    FAIL_DETAILS="${FAIL_DETAILS}No code review found. Run /qualia-review to generate REVIEW.md. "
+    FAILURES=$((FAILURES + 1))
+else
+    REVIEW_MTIME=$(stat -c %Y "$REVIEW_FILE" 2>/dev/null || echo 0)
+    LATEST_CODE_MTIME=0
+    for DIR in src app pages lib components; do
+        if [ -d "$DIR" ]; then
+            DIR_LATEST=$(find "$DIR" -type f \( -name "*.ts" -o -name "*.tsx" -o -name "*.js" -o -name "*.jsx" \) -printf '%T@\n' 2>/dev/null | sort -rn | head -1 | cut -d. -f1)
+            [ -n "$DIR_LATEST" ] && [ "$DIR_LATEST" -gt "$LATEST_CODE_MTIME" ] && LATEST_CODE_MTIME=$DIR_LATEST
+        fi
+    done
+    if [ "$LATEST_CODE_MTIME" -gt 0 ] && [ "$REVIEW_MTIME" -lt "$LATEST_CODE_MTIME" ]; then
+        q_fail "REVIEW.md stale"
+        FAIL_DETAILS="${FAIL_DETAILS}REVIEW.md is stale. Run /qualia-review to update. "
+        FAILURES=$((FAILURES + 1))
+    else
+        q_pass "Review"
+    fi
+fi
+
+# ─── Verdict ───
+if [ "$FAILURES" -gt 0 ]; then
+    q_blocked "${FAILURES} check(s) failed"
+
+    cat <<EOJSON
+{
+  "continue": false,
+  "stopReason": "◆ Deploy gate: ${FAILURES} check(s) failed",
+  "systemMessage": "DEPLOY BLOCKED by pre-deploy gate. DO NOT ask the user to deploy manually or bypass the gate. Instead, fix the failing checks and retry vercel --prod. Failures: ${FAIL_DETAILS}After fixing, retry the deploy command."
+}
+EOJSON
+    exit 2
+fi
+
+if [ "$WARNINGS" -gt 0 ]; then
+    q_warn "${WARNINGS} warning(s) — proceeding"
+fi
+
+q_approved
+
+# Stamp success
+touch "$STAMP"
+exit 0

package/framework/hooks/qualia-colors.sh

@@ -0,0 +1,32 @@
+# Qualia teal brand palette — source this in all hooks
+# Usage: source "$(dirname "$0")/qualia-colors.sh"
+
+Q_TEAL='\033[38;2;0;188;175m'
+Q_BRIGHT='\033[38;2;45;226;210m'
+Q_DIM='\033[38;2;0;120;112m'
+Q_WHITE='\033[38;2;220;225;230m'
+Q_PASS='\033[38;2;52;211;153m'
+Q_WARN='\033[38;2;234;179;8m'
+Q_FAIL='\033[38;2;239;68;68m'
+Q_GRAY='\033[38;2;70;78;88m'
+Q_RESET='\033[0m'
+Q_MARK="${Q_BRIGHT}◆${Q_RESET}"
+
+# Print a Qualia-branded header line to stderr
+# Usage: q_header "PRE-DEPLOY GATE"
+q_header() {
+    printf "${Q_TEAL}━━━${Q_RESET} ${Q_BRIGHT}◆${Q_RESET} ${Q_TEAL}%s${Q_RESET}\n" "$1" >&2
+}
+
+# Print a pass/fail/warn/skip line to stderr
+# Usage: q_pass "TypeScript"  |  q_fail "Build"  |  q_warn "Env"  |  q_skip "Tests"
+q_pass()  { printf "  ${Q_PASS}✓${Q_RESET} ${Q_WHITE}%s${Q_RESET}\n" "$1" >&2; }
+q_fail()  { printf "  ${Q_FAIL}✗${Q_RESET} ${Q_WHITE}%s${Q_RESET}\n" "$1" >&2; }
+q_warn()  { printf "  ${Q_WARN}▲${Q_RESET} ${Q_WHITE}%s${Q_RESET}\n" "$1" >&2; }
+q_skip()  { printf "  ${Q_GRAY}·${Q_RESET} ${Q_GRAY}%s${Q_RESET}\n" "$1" >&2; }
+q_info()  { printf "  ${Q_DIM}%s${Q_RESET}\n" "$1" >&2; }
+
+# Print verdict line to stderr
+# Usage: q_blocked "2 checks failed"  |  q_approved
+q_blocked() { printf "\n${Q_FAIL}✗${Q_RESET} ${Q_BRIGHT}BLOCKED${Q_RESET} ${Q_DIM}—${Q_RESET} ${Q_WHITE}%s${Q_RESET}\n" "$1" >&2; }
+q_approved(){ printf "\n${Q_PASS}✓${Q_RESET} ${Q_BRIGHT}APPROVED${Q_RESET}\n" >&2; }

package/framework/hooks/retention-cleanup.sh

@@ -0,0 +1,43 @@
+#!/bin/bash
+# Retention cleanup — runs on SessionStart to enforce retention policies
+# Keeps .claude/ lean by pruning stale data automatically
+
+CLAUDE_DIR="$HOME/.claude"
+
+# (debug/ and context-states/ removed — directories don't exist)
+
+# file-history/ — keep 7 days max
+find "$CLAUDE_DIR/file-history/" -type f -mtime +7 -delete 2>/dev/null
+find "$CLAUDE_DIR/file-history/" -type d -empty -delete 2>/dev/null
+
+# session-env/ — keep last 10 UUID dirs (sorted by modification time)
+ls -dt "$CLAUDE_DIR/session-env"/*-*-*-*-* 2>/dev/null | tail -n +11 | while IFS= read -r d; do
+    rm -rf "$d"
+done
+
+# backups/ — keep 3 days
+find "$CLAUDE_DIR/backups/" -type f -mtime +3 -delete 2>/dev/null
+
+# paste-cache/ — keep 3 days
+find "$CLAUDE_DIR/paste-cache/" -type f -mtime +3 -delete 2>/dev/null
+
+# shell-snapshots/ — keep 3 days
+find "$CLAUDE_DIR/shell-snapshots/" -type f -mtime +3 -delete 2>/dev/null
+
+# projects/ session transcripts — keep 7 days (allows --continue on recent sessions)
+find "$CLAUDE_DIR/projects/" -name "*.jsonl" -mtime +7 -delete 2>/dev/null
+find "$CLAUDE_DIR/projects/" -type d -empty -delete 2>/dev/null
+
+# tasks/ — keep 3 days (stale task files from old sessions)
+find "$CLAUDE_DIR/tasks/" -type f -mtime +3 -delete 2>/dev/null
+find "$CLAUDE_DIR/tasks/" -type d -empty -delete 2>/dev/null
+
+# plans/ — keep 7 days (old Claude Code plan mode files)
+find "$CLAUDE_DIR/plans/" -type f -mtime +7 -delete 2>/dev/null
+
+# session-env/ session_*.json — keep last 50 (matches save-session-state.sh)
+ls -t "$CLAUDE_DIR/session-env"/session_*.json 2>/dev/null | tail -n +51 | while IFS= read -r f; do
+    rm -f "$f"
+done
+
+exit 0

package/framework/hooks/save-session-state.sh

@@ -0,0 +1,153 @@
+#!/bin/bash
+# SessionEnd hook — saves session state + updates rolling digest + auto-handoff
+# Enhanced: cross-project session digest, auto .continue-here.md for significant work
+
+SESSION_DIR="$HOME/.claude/session-env"
+KNOWLEDGE_DIR="$HOME/.claude/knowledge"
+DIGEST_FILE="$KNOWLEDGE_DIR/session-digest.md"
+TIMESTAMP=$(date +%Y%m%d_%H%M%S)
+SESSION_FILE="$SESSION_DIR/session_$TIMESTAMP.json"
+
+mkdir -p "$SESSION_DIR"
+mkdir -p "$KNOWLEDGE_DIR"
+
+CWD=$(pwd)
+PROJECT_NAME=$(basename "$CWD")
+
+# --- Git info ---
+GIT_BRANCH=""
+GIT_STATUS=""
+FILES_CHANGED=0
+LAST_COMMIT_MSG=""
+if git rev-parse --is-inside-work-tree &> /dev/null 2>&1; then
+    GIT_BRANCH=$(git branch --show-current 2>/dev/null || echo "")
+    GIT_STATUS=$(git status --porcelain 2>/dev/null | head -20 || echo "")
+    # Count ALL files changed: committed in last 2 hours + uncommitted + staged
+    COMMITTED=$(git diff --name-only "$(git log --since='2 hours ago' --format=%H | tail -1 2>/dev/null || echo HEAD)" HEAD 2>/dev/null | wc -l || echo 0)
+    UNCOMMITTED=$(git diff --name-only 2>/dev/null | wc -l || echo 0)
+    STAGED=$(git diff --cached --name-only 2>/dev/null | wc -l || echo 0)
+    FILES_CHANGED=$((COMMITTED + UNCOMMITTED + STAGED))
+    LAST_COMMIT_MSG=$(git log --oneline -1 --format="%s" 2>/dev/null || echo "")
+fi
+
+# --- Summary line (from last commit or branch name) ---
+SUMMARY=""
+if [ -n "$LAST_COMMIT_MSG" ]; then
+    SUMMARY="$LAST_COMMIT_MSG"
+elif [ -n "$GIT_BRANCH" ]; then
+    SUMMARY="Working on $GIT_BRANCH"
+fi
+
+# --- Save session JSON ---
+cat > "$SESSION_FILE" << EOF
+{
+  "timestamp": "$TIMESTAMP",
+  "working_directory": "$CWD",
+  "project": "$PROJECT_NAME",
+  "git": {
+    "branch": "$GIT_BRANCH",
+    "has_changes": $([ -n "$GIT_STATUS" ] && echo "true" || echo "false"),
+    "files_changed": $FILES_CHANGED
+  },
+  "summary": "$(echo "$SUMMARY" | sed 's/"/\\"/g')",
+  "ended_at": "$(date '+%Y-%m-%d %H:%M:%S')"
+}
+EOF
+
+# --- Update rolling session digest (cross-project awareness) ---
+if [ ! -f "$DIGEST_FILE" ]; then
+    cat > "$DIGEST_FILE" << 'HEADER'
+# Session Digest — Rolling Log
+> Auto-updated by save-session-state.sh. Last 20 sessions across all projects.
+
+HEADER
+fi
+
+# Prepend new entry (most recent first, after header)
+# Skip noise: sessions in .claude, Projects root, or with 0 files and no summary
+if [ "$PROJECT_NAME" != ".claude" ] && [ "$PROJECT_NAME" != "Projects" ] && { [ "$FILES_CHANGED" -gt 0 ] || [ -n "$SUMMARY" ]; }; then
+    DATE_SHORT=$(date '+%m-%d %H:%M')
+    ENTRY="| ${DATE_SHORT} | ${PROJECT_NAME} | ${GIT_BRANCH:-—} | ${FILES_CHANGED} | ${SUMMARY:-—} |"
+
+    # Read existing entries (skip header — first 3 lines), keep last 19
+    EXISTING=$(tail -n +4 "$DIGEST_FILE" | head -19)
+
+    cat > "$DIGEST_FILE" << HEADER
+# Session Digest — Rolling Log
+> Auto-updated by save-session-state.sh. Last 20 sessions across all projects.
+
+${ENTRY}
+${EXISTING}
+HEADER
+fi
+
+# --- Auto-handoff for significant sessions (>5 files changed) ---
+if [ "$FILES_CHANGED" -gt 5 ] && [ "$PROJECT_NAME" != ".claude" ]; then
+    HANDOFF_FILE="$CWD/.continue-here.md"
+    # Only create if one doesn't already exist (don't overwrite manual handoffs)
+    if [ ! -f "$HANDOFF_FILE" ]; then
+        RECENT_COMMITS=$(git log --oneline -5 2>/dev/null || echo "none")
+        UNCOMMITTED_FILES=$(git diff --name-only 2>/dev/null | head -10 || echo "none")
+        STAGED_FILES=$(git diff --cached --name-only 2>/dev/null | head -10 || echo "none")
+
+        # Dead-ends: reverts, stashes, and abandoned branches from this session
+        REVERTS=$(git log --oneline -20 2>/dev/null | grep -i "revert\|undo\|rollback" | head -5 || echo "none")
+        STASHES=$(git stash list 2>/dev/null | head -5 || echo "none")
+
+        cat > "$HANDOFF_FILE" << HANDOFF
+# Auto-Handoff — $(date '+%Y-%m-%d %H:%M')
+
+## What was done
+Branch: ${GIT_BRANCH}
+Files changed: ${FILES_CHANGED}
+
+Recent commits:
+\`\`\`
+${RECENT_COMMITS}
+\`\`\`
+
+## Uncommitted work
+\`\`\`
+${UNCOMMITTED_FILES}
+\`\`\`
+
+## Staged (not committed)
+\`\`\`
+${STAGED_FILES}
+\`\`\`
+
+## Dead-ends (don't repeat these)
+Reverted/undone work:
+\`\`\`
+${REVERTS}
+\`\`\`
+
+Stashed work (may be abandoned):
+\`\`\`
+${STASHES}
+\`\`\`
+
+## Next steps
+Review the recent commits and continue from where this session left off.
+Do NOT retry approaches listed in dead-ends above.
+HANDOFF
+    fi
+fi
+
+# --- Push to portal (non-blocking, fire-and-forget) ---
+PORTAL_API_KEY="${CLAUDE_PORTAL_API_KEY:-}"
+if [ -n "$PORTAL_API_KEY" ] && [ "$PROJECT_NAME" != ".claude" ]; then
+    curl -s -X POST "https://portal.qualiasolutions.net/api/claude/session-log" \
+        -H "X-API-Key: $PORTAL_API_KEY" \
+        -H "Content-Type: application/json" \
+        -d @"$SESSION_FILE" \
+        --max-time 5 \
+        > /dev/null 2>&1 &
+fi
+
+# --- Cleanup old session files (keep last 50 for retrospective analytics — RETR-04) ---
+ls -t "$SESSION_DIR"/session_*.json 2>/dev/null | tail -n +51 | while IFS= read -r f; do
+    rm -f "$f"
+done
+
+exit 0

package/framework/hooks/session-context-loader.sh

@@ -0,0 +1,28 @@
+#!/bin/bash
+# SessionStart hook — provides context for qualia-start skill
+# CLAUDE.md instructs Claude to invoke /qualia-start on every session start
+# This hook just passes along any resume hints
+
+source "$(dirname "$0")/qualia-colors.sh"
+
+CWD=$(pwd)
+SESSION_DIR="$HOME/.claude/session-env"
+COMPACT_FILE="$SESSION_DIR/pre-compact.json"
+HINTS=""
+
+# Check for handoff file
+[ -f "$CWD/.continue-here.md" ] && HINTS="Handoff file exists — read .continue-here.md. "
+
+# Check last session
+if [ -f "$COMPACT_FILE" ]; then
+    LAST_PROJECT=$(node -e "try{const d=JSON.parse(require('fs').readFileSync('$COMPACT_FILE','utf8'));process.stdout.write(d.project_name||'')}catch(e){}" 2>/dev/null)
+    [ -n "$LAST_PROJECT" ] && [ "$LAST_PROJECT" != ".claude" ] && HINTS="${HINTS}Last session: ${LAST_PROJECT}. "
+fi
+
+if [ -n "$HINTS" ]; then
+    printf '{"continue":true,"systemMessage":"%s"}' "$HINTS"
+else
+    printf '{"continue":true}'
+fi
+
+exit 0

package/framework/hooks/session-learn.sh

@@ -0,0 +1,30 @@
+#!/usr/bin/env bash
+# SessionEnd hook: prompt for lessons learned if significant work was done
+# "Significant" = more than 3 files modified in the session
+
+set -euo pipefail
+
+LEARNED_FILE="$HOME/.claude/knowledge/learned-patterns.md"
+
+# Count files modified: committed in last 2 hours + uncommitted
+COMMITTED=$(git diff --name-only "$(git log --since='2 hours ago' --format=%H | tail -1 2>/dev/null || echo HEAD)" HEAD 2>/dev/null | wc -l || echo 0)
+UNCOMMITTED=$(git diff --name-only 2>/dev/null | wc -l || echo 0)
+MODIFIED_COUNT=$((COMMITTED + UNCOMMITTED))
+
+# Only trigger if significant work was done
+if [ "$MODIFIED_COUNT" -le 3 ]; then
+  exit 0
+fi
+
+# Initialize learned-patterns.md if it doesn't exist
+if [ ! -f "$LEARNED_FILE" ]; then
+  echo "# Learned Patterns" > "$LEARNED_FILE"
+  echo "" >> "$LEARNED_FILE"
+  echo "Lessons captured from development sessions." >> "$LEARNED_FILE"
+  echo "" >> "$LEARNED_FILE"
+fi
+
+# Output reminder (shown to Claude in session context)
+echo "SESSION_LEARN: $MODIFIED_COUNT files changed this session. Consider running /learn to capture any lessons."
+
+exit 0