qualia-framework 2.1.0

package/framework/commands/design.md

@@ -0,0 +1,53 @@
+---
+description: Apply professional design system for websites, apps, UI/UX, components, and business documents
+argument-hint: "[website|app|dashboard|landing-page|component|document] [description or URL]"
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Glob
+  - Grep
+  - AskUserQuestion
+---
+
+<objective>
+Design and build professionally styled interfaces, components, and documents using a comprehensive design system. Uses the `frontend-master` skill for consistent visual hierarchy, spacing, color tokens, and modern design patterns.
+
+**Supported contexts:**
+- **Websites & Landing Pages** — Hero sections, feature grids, pricing tables, testimonials, CTAs, footers
+- **Web Apps & Dashboards** — Sidebar nav, stat cards, data tables, charts, activity feeds, filters
+- **UI Components** — Buttons, forms, cards, modals, navigation, tables, toasts, dropdowns
+- **Mobile & Responsive** — Bottom nav, touch targets, responsive breakpoints, mobile-first layouts
+- **Business Documents** — Contracts, proposals, SOWs, NDAs, invoices, reports (docx/PDF output)
+
+**What it does:**
+- Applies design tokens: colors (light/dark mode), typography scale, 8px spacing grid
+- Implements component patterns with proper states (hover, focus, active, disabled, loading, error)
+- Ensures WCAG AA accessibility (contrast, keyboard nav, screen reader, touch targets)
+- Uses responsive breakpoints (640px → 1536px+) with mobile-first approach
+- Structures layouts using CSS Grid/Flexbox with proper max-widths
+- Outputs as HTML/React/JSX for interfaces, or .docx/.pdf for documents
+</objective>
+
+<process>
+1. Read the `frontend-master` skill from `skills/frontend-master/SKILL.md`
+2. Determine the design context from $ARGUMENTS:
+   - **Interface/component**: Identify what's being built (page, component, full app)
+   - **Document**: Identify document type (contract, proposal, invoice, etc.)
+3. If redesigning existing work, read/screenshot it and identify improvements
+4. If creating from scratch:
+   - Ask for key details (purpose, audience, features, brand preferences)
+   - Select appropriate layout pattern from the skill
+   - Choose color palette (or use defaults with primary accent)
+5. Build with the design system:
+   - Apply color tokens, typography scale, spacing grid
+   - Implement proper component patterns with all interaction states
+   - Ensure responsive behavior at all breakpoints
+   - Add accessibility features (contrast, focus indicators, ARIA)
+6. Run through the design checklist (visual, interactive, responsive, performance)
+7. Output the appropriate format:
+   - HTML/React/JSX for web interfaces
+   - .docx or .pdf for business documents
+   - Code snippets for individual components
+</process>

package/framework/commands/quick-db.md

@@ -0,0 +1,22 @@
+---
+description: Quick Supabase database operation (query, migration, RLS)
+---
+
+Perform a Supabase database operation using the Supabase CLI (not MCP).
+
+## Available Operations:
+1. **Query**: Run SELECT queries via `supabase db execute`
+2. **Migration**: Create schema changes via `supabase migration new`
+3. **RLS**: Set up row-level security policies
+4. **Types**: Generate TypeScript types via `supabase gen types typescript`
+
+## Process:
+1. Understand the request
+2. Use the `/supabase` skill's CLI-first approach to execute
+3. Show results or created SQL
+4. If migration, provide the SQL file content
+
+For comprehensive database operations, use `/supabase` instead.
+
+## Request:
+$ARGUMENTS

package/framework/config/retention.json

@@ -0,0 +1,35 @@
+{
+  "version": "1.0",
+  "description": "Retention policies for .claude directory state management",
+  "policies": {
+    "file-history": {
+      "max_versions": 5,
+      "max_age_days": 7,
+      "compress_after_days": 3,
+      "description": "File modification tracking"
+    },
+    "debug-logs": {
+      "max_age_days": 30,
+      "compress_after_days": 7,
+      "description": "Agent execution traces"
+    },
+    "shell-snapshots": {
+      "max_age_days": 7,
+      "description": "Bash environment snapshots"
+    },
+    "todos": {
+      "archive_after_days": 180,
+      "description": "Task tracking files"
+    },
+    "projects": {
+      "archive_after_days": 90,
+      "compress": true,
+      "description": "Per-project session state"
+    },
+    "session-env": {
+      "cleanup_empty": true,
+      "max_age_days": 30,
+      "description": "Session environment state"
+    }
+  }
+}

package/framework/core/PRINCIPLES.md

@@ -0,0 +1,77 @@
+# Software Engineering Principles
+
+**Core Directive**: Evidence > assumptions | Code > documentation | Efficiency > verbosity
+
+## Philosophy
+- **Task-First Approach**: Understand → Plan → Execute → Validate
+- **Evidence-Based Reasoning**: All claims verifiable through testing, metrics, or documentation
+- **Parallel Thinking**: Maximize efficiency through intelligent batching and coordination
+- **Context Awareness**: Maintain project understanding across sessions and operations
+
+## Engineering Mindset
+
+### SOLID
+- **Single Responsibility**: Each component has one reason to change
+- **Open/Closed**: Open for extension, closed for modification
+- **Liskov Substitution**: Derived classes substitutable for base classes
+- **Interface Segregation**: Don't depend on unused interfaces
+- **Dependency Inversion**: Depend on abstractions, not concretions
+
+### Core Patterns
+- **DRY**: Abstract common functionality, eliminate duplication
+- **KISS**: Prefer simplicity over complexity in design decisions
+- **YAGNI**: Implement current requirements only, avoid speculation
+
+### Systems Thinking
+- **Ripple Effects**: Consider architecture-wide impact of decisions
+- **Long-term Perspective**: Evaluate immediate vs. future trade-offs
+- **Risk Calibration**: Balance acceptable risks with delivery constraints
+
+## Decision Framework
+
+### Data-Driven Choices
+- **Measure First**: Base optimization on measurements, not assumptions
+- **Hypothesis Testing**: Formulate and test systematically
+- **Source Validation**: Verify information credibility
+- **Bias Recognition**: Account for cognitive biases
+
+### Trade-off Analysis
+- **Temporal Impact**: Immediate vs. long-term consequences
+- **Reversibility**: Classify as reversible, costly, or irreversible
+- **Option Preservation**: Maintain future flexibility under uncertainty
+
+### Risk Management
+- **Proactive Identification**: Anticipate issues before manifestation
+- **Impact Assessment**: Evaluate probability and severity
+- **Mitigation Planning**: Develop risk reduction strategies
+
+## Quality Philosophy
+
+### Quality Quadrants
+- **Functional**: Correctness, reliability, feature completeness
+- **Structural**: Code organization, maintainability, technical debt
+- **Performance**: Speed, scalability, resource efficiency
+- **Security**: Vulnerability management, access control, data protection
+
+### Quality Standards
+- **Automated Enforcement**: Use tooling for consistent quality
+- **Preventive Measures**: Catch issues early when cheaper to fix
+- **Human-Centered Design**: Prioritize user welfare and autonomy
+
+## Confidence-First Implementation
+
+### Pre-Execution Validation
+Before starting significant work, assess confidence level:
+
+- **≥90% Confidence**: Proceed with implementation
+- **70-89% Confidence**: Present alternatives, gather more information
+- **<70% Confidence**: STOP - Ask questions, do not proceed
+
+### Confidence Checklist
+- [ ] No duplicate implementation exists
+- [ ] Architecture patterns consulted
+- [ ] Official documentation verified
+- [ ] Root cause identified (for debugging)
+- [ ] Edge cases considered
+
+**ROI**: 100-200 token investment prevents 5,000-50,000 token waste on wrong direction

package/framework/hooks/auto-format.sh

@@ -0,0 +1,45 @@
+#!/bin/bash
+# Auto-format hook for PostToolUse(Write)
+# Runs prettier on supported file types if available in the project
+
+# Parse file path from stdin JSON (Claude Code hook protocol)
+if [ ! -t 0 ]; then
+    INPUT=$(cat)
+    FILE_PATH=$(echo "$INPUT" | node -e "try{const d=JSON.parse(require('fs').readFileSync('/dev/stdin','utf8'));process.stdout.write(d.tool_input?.file_path||'')}catch(e){}" 2>/dev/null)
+else
+    FILE_PATH=""
+fi
+
+# Skip if no file path
+[ -z "$FILE_PATH" ] || [ ! -f "$FILE_PATH" ] && exit 0
+
+# Get file extension
+EXT="${FILE_PATH##*.}"
+
+# Only format supported file types
+case "$EXT" in
+  ts|tsx|js|jsx|json|css|scss|html|md|yaml|yml) ;;
+  *) exit 0 ;;
+esac
+
+# Find project root (look for package.json or .git)
+DIR="$(dirname "$FILE_PATH")"
+PROJECT_ROOT=""
+while [ "$DIR" != "/" ]; do
+  if [ -f "$DIR/package.json" ] || [ -d "$DIR/.git" ]; then
+    PROJECT_ROOT="$DIR"
+    break
+  fi
+  DIR="$(dirname "$DIR")"
+done
+
+# Try to format with prettier if available in the project
+if [ -n "$PROJECT_ROOT" ]; then
+  if [ -f "$PROJECT_ROOT/node_modules/.bin/prettier" ]; then
+    "$PROJECT_ROOT/node_modules/.bin/prettier" --write "$FILE_PATH" 2>/dev/null
+    exit 0
+  fi
+fi
+
+# No formatter found — skip silently
+exit 0

package/framework/hooks/block-env-edit.sh

@@ -0,0 +1,42 @@
+#!/bin/bash
+# Block .env and credential file editing
+source "$(dirname "$0")/qualia-colors.sh"
+
+if [ ! -t 0 ]; then
+    INPUT=$(cat)
+    FILE_PATH=$(echo "$INPUT" | node -e "try{const d=JSON.parse(require('fs').readFileSync('/dev/stdin','utf8'));process.stdout.write(d.tool_input?.file_path||d.tool_input?.filePath||'')}catch(e){}" 2>/dev/null)
+else
+    FILE_PATH="${1:-}"
+fi
+
+[ -z "$FILE_PATH" ] && exit 0
+
+BASENAME=$(basename "$FILE_PATH")
+
+if [[ "$BASENAME" == .env* ]] || [[ "$FILE_PATH" == */.env ]] || [[ "$FILE_PATH" == */.env.* ]]; then
+    q_header "ENV GUARD"
+    q_fail "Editing ${BASENAME} blocked"
+    cat <<EOJSON
+{
+  "continue": false,
+  "stopReason": "◆ Env guard: editing ${BASENAME} blocked",
+  "systemMessage": "BLOCKED: Cannot edit .env files through Claude Code. Tell the user EXACTLY what needs to change: which file, which variable, what value. Format it clearly so they can copy-paste. Example: 'Add this to your ${BASENAME}: NEXT_PUBLIC_API_URL=https://...'. Do NOT try alternative approaches to write env files."
+}
+EOJSON
+    exit 2
+fi
+
+if [[ "$FILE_PATH" == *credentials* ]] || [[ "$FILE_PATH" == *secret* ]] || [[ "$FILE_PATH" == *.pem ]] || [[ "$FILE_PATH" == *.key ]]; then
+    q_header "ENV GUARD"
+    q_fail "Editing credential file blocked"
+    cat <<EOJSON
+{
+  "continue": false,
+  "stopReason": "◆ Env guard: credential file blocked",
+  "systemMessage": "BLOCKED: Cannot edit credential/secret files through Claude. Tell the user what needs changing."
+}
+EOJSON
+    exit 2
+fi
+
+exit 0

package/framework/hooks/branch-guard.sh

@@ -0,0 +1,46 @@
+#!/bin/bash
+# Branch protection — role-aware
+# OWNER: allowed to push to main/master
+# DEVELOPER/EMPLOYEE: blocked, told to use /qualia-ship
+source "$(dirname "$0")/qualia-colors.sh"
+
+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="${1:-}"
+fi
+
+case "$COMMAND" in
+    git\ push*) ;;
+    *) exit 0 ;;
+esac
+
+BRANCH=$(git branch --show-current 2>/dev/null) || true
+[ -z "$BRANCH" ] && exit 0
+
+# Only guard main/master
+if [ "$BRANCH" != "main" ] && [ "$BRANCH" != "master" ]; then
+    exit 0
+fi
+
+# Check role from CLAUDE.md
+ROLE=$(grep -m1 "^## Role:" "$HOME/.claude/CLAUDE.md" 2>/dev/null | sed 's/^## Role: *//')
+
+# OWNER can push anywhere
+if [ "$ROLE" = "OWNER" ]; then
+    exit 0
+fi
+
+# DEVELOPER/EMPLOYEE blocked
+q_header "BRANCH GUARD"
+q_fail "Push to ${BRANCH} blocked (${ROLE:-unknown} role)"
+
+cat <<EOJSON
+{
+  "continue": false,
+  "stopReason": "◆ Branch guard: push to ${BRANCH} blocked for ${ROLE:-unknown} role",
+  "systemMessage": "BLOCKED: As a ${ROLE:-DEVELOPER}, you cannot push directly to ${BRANCH}. Run /qualia-ship instead — it will automatically create a feature branch, push your changes, and handle the deploy pipeline. Do NOT tell the user to push manually."
+}
+EOJSON
+exit 2

package/framework/hooks/confirm-delete.sh

@@ -0,0 +1,56 @@
+#!/bin/bash
+# Destructive command guard — blocks dangerous operations
+source "$(dirname "$0")/qualia-colors.sh"
+
+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="${1:-}"
+fi
+
+# Early exit for safe commands
+case "$COMMAND" in
+    ls*|cat*|echo*|pwd|cd*|node*|npm\ install*|npm\ run*|npm\ test*|npx*|bun*|pnpm*|grep*|find*|which*|whoami|date|head*|tail*|wc*|sort*|diff*|test*|"["*|true|false|mkdir*|touch*|cp*|mv*|chmod*|stat*|readlink*|basename*|dirname*|realpath*|tsc*|eslint*|prettier*|vitest*|jest*|python*|pip*|curl*|wget*|gh*)
+        exit 0
+        ;;
+esac
+
+block() {
+    q_header "DESTRUCTIVE GUARD"
+    q_fail "$1"
+    cat <<EOJSON
+{
+  "continue": false,
+  "stopReason": "◆ Blocked: $1",
+  "systemMessage": "BLOCKED: $1. DO NOT tell the user to run this manually. Instead, find a SAFER alternative that achieves the same goal without the destructive operation. Explain to the user what was blocked and what safer approach you're using instead."
+}
+EOJSON
+    exit 2
+}
+
+# Dangerous rm patterns
+echo "$COMMAND" | grep -qE 'rm\s+(-rf|-fr|-r)\s+(/|~/|\.\.|[A-Za-z]+/$)' && block "Dangerous recursive delete"
+echo "$COMMAND" | grep -qE 'rm\s.*\s(src/|app/|lib/|components/|public/|pages/|supabase/)' && block "Deleting critical project directory"
+echo "$COMMAND" | grep -qE 'rm\s+(-rf|-fr)\s+\.$' && block "rm -rf current directory"
+
+# Dangerous SQL
+echo "$COMMAND" | grep -qiE 'DROP\s+(TABLE|DATABASE|SCHEMA)\s' && block "DROP TABLE/DATABASE/SCHEMA"
+echo "$COMMAND" | grep -qiE 'TRUNCATE\s+TABLE\s' && block "TRUNCATE TABLE"
+echo "$COMMAND" | grep -qiE 'DELETE\s+FROM\s+\w+\s*;' && block "DELETE without WHERE"
+
+# Dangerous git
+echo "$COMMAND" | grep -qE 'git\s+push\s+.*--force($|\s)' && ! echo "$COMMAND" | grep -qE '\-\-force-with-lease' && block "git push --force (use --force-with-lease)"
+echo "$COMMAND" | grep -qE 'git\s+reset\s+--hard' && block "git reset --hard discards work"
+echo "$COMMAND" | grep -qE 'git\s+clean\s+-[a-z]*f' && block "git clean -f deletes untracked files"
+
+# Infrastructure
+echo "$COMMAND" | grep -qE 'kubectl\s+delete\s' && block "kubectl delete"
+echo "$COMMAND" | grep -qE 'docker\s+(rm|rmi)\s+-f' && block "docker force remove"
+
+# Platform
+echo "$COMMAND" | grep -qiE 'supabase\s+db\s+reset' && block "supabase db reset destroys database"
+echo "$COMMAND" | grep -qiE 'vercel\s+(rm|remove)\s' && block "vercel rm/remove"
+echo "$COMMAND" | grep -qiE 'npm\s+unpublish' && block "npm unpublish"
+
+exit 0

package/framework/hooks/migration-validate.sh

@@ -0,0 +1,68 @@
+#!/bin/bash
+# Migration validation — checks SQL for destructive ops and missing RLS
+source "$(dirname "$0")/qualia-colors.sh"
+
+if [ ! -t 0 ]; then
+    INPUT=$(cat)
+    FILE_PATH=$(echo "$INPUT" | node -e "try{const d=JSON.parse(require('fs').readFileSync('/dev/stdin','utf8'));process.stdout.write(d.tool_input?.file_path||'')}catch(e){}" 2>/dev/null)
+    if [ -z "$FILE_PATH" ]; then
+        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)
+    fi
+fi
+
+check_sql_file() {
+    local file="$1"
+    local issues=0
+    [ ! -f "$file" ] && return 0
+
+    if grep -iE '\bDROP\s+(TABLE|SCHEMA|DATABASE)\b' "$file" > /dev/null 2>&1; then
+        q_warn "DROP TABLE/SCHEMA in ${file}"
+        issues=$((issues + 1))
+    fi
+    if grep -iE '\bTRUNCATE\b' "$file" > /dev/null 2>&1; then
+        q_warn "TRUNCATE in ${file}"
+        issues=$((issues + 1))
+    fi
+    if grep -iE '\bDELETE\s+FROM\b' "$file" > /dev/null 2>&1 && ! grep -iE '\bWHERE\b' "$file" > /dev/null 2>&1; then
+        q_warn "DELETE without WHERE in ${file}"
+        issues=$((issues + 1))
+    fi
+    if grep -iE '\bALTER\s+TABLE\b.*\bDROP\s+COLUMN\b' "$file" > /dev/null 2>&1; then
+        q_warn "DROP COLUMN in ${file}"
+        issues=$((issues + 1))
+    fi
+    if grep -iE '\bCREATE\s+TABLE\b' "$file" > /dev/null 2>&1 && ! grep -iE '\bENABLE\s+ROW\s+LEVEL\s+SECURITY\b' "$file" > /dev/null 2>&1; then
+        q_warn "New table without RLS in ${file}"
+        issues=$((issues + 1))
+    fi
+    return $issues
+}
+
+TOTAL=0
+HEADER_SHOWN=false
+
+# Mode 1: SQL file written
+if [ -n "$FILE_PATH" ] && [[ "$FILE_PATH" == *.sql ]]; then
+    q_header "MIGRATION CHECK"
+    HEADER_SHOWN=true
+    check_sql_file "$FILE_PATH"
+    TOTAL=$?
+fi
+
+# Mode 2: supabase db push
+if [ -n "$COMMAND" ] && echo "$COMMAND" | grep -qE 'supabase\s+db\s+push'; then
+    q_header "MIGRATION CHECK"
+    HEADER_SHOWN=true
+    for sql_file in supabase/migrations/*.sql; do
+        [ -f "$sql_file" ] || continue
+        check_sql_file "$sql_file"
+        TOTAL=$((TOTAL + $?))
+    done
+fi
+
+if [ "$TOTAL" -gt 0 ] && $HEADER_SHOWN; then
+    q_info "${TOTAL} issue(s) — review carefully"
+fi
+
+# Warn but don't block
+exit 0

package/framework/hooks/notification-speak.sh

@@ -0,0 +1,15 @@
+#!/bin/bash
+# Notification hook — passes notification message to TTS
+# Reads message from stdin JSON (Claude Code hook protocol)
+
+TEXT=""
+if [ ! -t 0 ]; then
+    INPUT=$(cat)
+    TEXT=$(echo "$INPUT" | node -e "try{const d=JSON.parse(require('fs').readFileSync('/dev/stdin','utf8'));process.stdout.write(d.message||'')}catch(e){}" 2>/dev/null)
+fi
+
+if [ -n "$TEXT" ]; then
+    ~/.claude/scripts/speak.sh "$TEXT"
+fi
+
+exit 0

package/framework/hooks/pre-commit.sh

@@ -0,0 +1,80 @@
+#!/bin/bash
+# Pre-commit validation — secrets, debug statements, TypeScript, lint
+source "$(dirname "$0")/qualia-colors.sh"
+
+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="${1:-}"
+fi
+
+case "$COMMAND" in
+    git\ commit*) ;;
+    *) exit 0 ;;
+esac
+
+git rev-parse --is-inside-work-tree &>/dev/null || exit 0
+
+STAGED_FILES=$(git diff --cached --name-only --diff-filter=ACM)
+[ -z "$STAGED_FILES" ] && exit 0
+
+q_header "PRE-COMMIT"
+BLOCKED=false
+FAIL_DETAILS=""
+
+# Check for secrets
+SECRETS_PATTERN="(api[_-]?key|apikey|secret[_-]?key|password|passwd|pwd|token|auth[_-]?token|access[_-]?token|private[_-]?key)[\s]*[=:][\"'\s]*[A-Za-z0-9+/=_-]{20,}"
+for file in $STAGED_FILES; do
+    if [ -f "$file" ] && grep -iE "$SECRETS_PATTERN" "$file" > /dev/null 2>&1; then
+        q_fail "Secret in ${file}"
+        FAIL_DETAILS="${FAIL_DETAILS}Potential secret in ${file}. "
+        BLOCKED=true
+    fi
+done
+
+# Check for .env files
+ENV_FILES=$(echo "$STAGED_FILES" | grep -E '\.env($|\.)' | grep -v '.example' | grep -v '.sample' || true)
+if [ -n "$ENV_FILES" ]; then
+    q_fail ".env file staged: ${ENV_FILES}"
+    FAIL_DETAILS="${FAIL_DETAILS}.env file staged for commit. "
+    BLOCKED=true
+fi
+
+# Debug statements in JS/TS
+JS_FILES=$(echo "$STAGED_FILES" | grep -E '\.(js|jsx|ts|tsx)$' || true)
+if [ -n "$JS_FILES" ]; then
+    for file in $JS_FILES; do
+        if [ -f "$file" ] && grep -E "console\.(log|debug|info)|debugger" "$file" > /dev/null 2>&1; then
+            q_warn "Debug statement in ${file}"
+        fi
+    done
+fi
+
+# TypeScript check
+if [ -f "tsconfig.json" ]; then
+    if command -v npx &> /dev/null; then
+        if npx tsc --noEmit 2>/dev/null; then
+            q_pass "TypeScript"
+        else
+            q_fail "TypeScript errors"
+            FAIL_DETAILS="${FAIL_DETAILS}TypeScript errors. Run npx tsc --noEmit. "
+            BLOCKED=true
+        fi
+    fi
+fi
+
+if $BLOCKED; then
+    q_blocked "Commit blocked"
+    cat <<EOJSON
+{
+  "continue": false,
+  "stopReason": "◆ Pre-commit: blocked",
+  "systemMessage": "COMMIT BLOCKED by pre-commit checks. DO NOT tell the user to commit manually or use --no-verify. Instead, FIX THE ISSUES YOURSELF: ${FAIL_DETAILS}After fixing, stage the corrected files with git add and retry the commit. Tell the user what you fixed."
+}
+EOJSON
+    exit 2
+fi
+
+q_pass "All checks passed"
+exit 0

package/framework/hooks/pre-compact.sh

@@ -0,0 +1,55 @@
+#!/bin/bash
+# Pre-compaction hook — saves context before Claude auto-compacts
+# Preserves: changed files, current task, git state, Qualia phase/milestone, project name
+# Cross-platform: uses node instead of jq for JSON array generation
+
+COMPACT_DIR="$HOME/.claude/session-env"
+COMPACT_FILE="$COMPACT_DIR/pre-compact.json"
+
+mkdir -p "$COMPACT_DIR"
+
+CWD=$(pwd)
+PROJECT_NAME=$(basename "$CWD")
+
+GIT_BRANCH=""
+GIT_DIFF_FILES=""
+if git rev-parse --is-inside-work-tree &> /dev/null 2>&1; then
+    GIT_BRANCH=$(git branch --show-current 2>/dev/null || echo "")
+    # Use node instead of jq to convert newline-separated file list to JSON array
+    GIT_DIFF_FILES=$(git diff --name-only HEAD 2>/dev/null | head -30 | node -e "
+        let d='';process.stdin.on('data',c=>d+=c);process.stdin.on('end',()=>{
+            const a=d.split('\n').filter(l=>l.length>0);
+            process.stdout.write(JSON.stringify(a));
+        });" 2>/dev/null)
+fi
+
+[ -z "$GIT_DIFF_FILES" ] && GIT_DIFF_FILES="[]"
+
+# Parse Qualia state from .planning/STATE.md if it exists
+QUALIA_PHASE=""
+QUALIA_MILESTONE=""
+QUALIA_TASK=""
+QUALIA_STATUS=""
+STATE_FILE="$CWD/.planning/STATE.md"
+if [ -f "$STATE_FILE" ]; then
+    QUALIA_PHASE=$(grep -m1 "^Phase:" "$STATE_FILE" 2>/dev/null | sed 's/^Phase: *//' || echo "")
+    QUALIA_MILESTONE=$(grep -m1 "^## Milestone" "$STATE_FILE" 2>/dev/null | sed 's/^## //' || echo "")
+    QUALIA_STATUS=$(grep -m1 "^Status:" "$STATE_FILE" 2>/dev/null | sed 's/^Status: *//' || echo "")
+    QUALIA_TASK=$(grep -m1 "^Last activity:" "$STATE_FILE" 2>/dev/null | sed 's/^Last activity: *//' || echo "")
+fi
+
+cat > "$COMPACT_FILE" << EOF
+{
+  "timestamp": "$(date '+%Y-%m-%d %H:%M:%S')",
+  "working_directory": "$CWD",
+  "project_name": "$PROJECT_NAME",
+  "git_branch": "$GIT_BRANCH",
+  "changed_files": $GIT_DIFF_FILES,
+  "qualia_phase": "$QUALIA_PHASE",
+  "qualia_milestone": "$QUALIA_MILESTONE",
+  "qualia_status": "$QUALIA_STATUS",
+  "qualia_task": "$QUALIA_TASK"
+}
+EOF
+
+exit 0