qualia-framework 2.1.5 → 2.2.0

package/framework/agents/teams/framework-audit-team.md

@@ -0,0 +1,66 @@
+# Framework Audit Team
+
+> 6 specialist reviewers audit the Qualia framework infrastructure in parallel, results synthesized into unified report.
+
+## Agents
+
+- **config-reviewer**
+  - subagent_type: general-purpose
+  - role: Review CLAUDE.md, rules/*.md, settings.json for completeness, consistency, contradictions
+  - focus: Identity, rules, permissions, MCP config, hook registrations, cross-references
+
+- **agent-reviewer**
+  - subagent_type: general-purpose
+  - role: Review all agents in agents/*.md and all team templates in agents/teams/ for quality, overlap, gaps, naming
+  - focus: Agent definitions, team patterns, subagent_type alignment, orphan detection
+
+- **skill-reviewer**
+  - subagent_type: general-purpose
+  - role: Review all 65+ skills for quality, overlap, gaps, trigger accuracy, category health
+  - focus: SKILL.md files, skill-agent alignment, dead skill detection, archive health
+
+- **hook-reviewer**
+  - subagent_type: general-purpose
+  - role: Review all 16 hooks for correctness, performance, coverage, branding consistency
+  - focus: Hook scripts, settings.json alignment, exit codes, JSON output, early-exit guards
+
+- **knowledge-reviewer**
+  - subagent_type: general-purpose
+  - role: Review knowledge files and memory system for staleness, accuracy, completeness
+  - focus: Knowledge .md files, MEMORY.md index, cross-references, duplicate content
+
+- **architecture-reviewer**
+  - subagent_type: general-purpose
+  - role: Cross-cutting review of framework organization, naming, dead code, security, scalability
+  - focus: Directory structure, naming conventions, archive health, install scripts, .gitignore
+
+## Pattern
+
+fan-out (all 6 parallel) → synthesize into FRAMEWORK-AUDIT.md
+
+## Shared Context
+
+- ~/.claude/CLAUDE.md — core identity and rules
+- ~/.claude/settings.json — hook config, permissions, MCP servers
+- Framework inventory counts (agents, skills, hooks, knowledge)
+
+## Coordination Rules
+
+- Each reviewer produces findings independently — no coordination needed
+- Reviewers are read-only — they analyze and report, they don't fix
+- Findings must include file references
+- Each reviewer rates findings: CRITICAL / HIGH / MEDIUM / LOW
+- Overlap detection is shared between agent-reviewer and skill-reviewer
+
+## Finding Format
+
+Every finding MUST include:
+- **What**: description
+- **Where**: file or directory
+- **Why**: impact
+- **Fix**: concrete suggestion
+- **Severity**: CRITICAL / HIGH / MEDIUM / LOW
+
+## Output
+
+~/.claude/.planning/FRAMEWORK-AUDIT.md

package/framework/agents/teams/review-team.md

@@ -1,6 +1,6 @@
 # Review Team
 
-> Three specialist reviewers analyze code in parallel, results synthesized into unified report.
+> Four specialist reviewers analyze code in parallel, results synthesized into unified report.
 
 ## Agents
 
@@ -19,9 +19,14 @@
   - role: TypeScript quality — strict types, naming conventions, pattern adherence, type safety gaps
   - focus: Type definitions, generics usage, any/unknown, null handling, naming
 
+- **security-auditor**
+  - subagent_type: security-auditor
+  - role: RLS policies, service_role exposure, auth patterns, input validation, secrets scanning, dependency vulnerabilities
+  - focus: Supabase security, auth flows, env var handling, XSS/injection prevention
+
 ## Pattern
 
-fan-out (all 3 parallel) → synthesize into REVIEW-REPORT.md
+fan-out (all 4 parallel) → synthesize into REVIEW-REPORT.md
 
 ## Shared Context
 
@@ -33,7 +38,7 @@ fan-out (all 3 parallel) → synthesize into REVIEW-REPORT.md
 - Each reviewer produces findings independently — no coordination needed
 - Reviewers are read-only — they analyze and report, they don't fix
 - Findings should include file:line references
-- Each reviewer rates findings: critical / warning / suggestion
+- Each reviewer rates findings: CRITICAL / HIGH / MEDIUM / LOW
 
 ## Output
 
@@ -54,6 +59,9 @@ REVIEW-REPORT.md in current directory with sections:
 ## TypeScript Quality Review
 {From kieran-typescript-reviewer}
 
+## Security Review
+{From security-auditor}
+
 ## Action Items
 | # | Severity | Finding | File:Line | Reviewer |
 |---|----------|---------|-----------|----------|

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

@@ -14,26 +14,22 @@ fi
 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."
+  "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."
 }
 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."
+  "stopReason": "◆ ENV GUARD: credential file blocked",
+  "systemMessage": "◆ BLOCKED: Cannot edit credential/secret files through Claude. Tell the user what needs changing."
 }
 EOJSON
     exit 2

package/framework/hooks/branch-guard.sh

@@ -33,14 +33,11 @@ if [ "$ROLE" = "OWNER" ]; then
 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."
+  "stopReason": "◆ BRANCH GUARD: push to ${BRANCH} blocked (${ROLE:-unknown} role)",
+  "systemMessage": "◆ BLOCKED: As ${ROLE:-DEVELOPER}, cannot push to ${BRANCH}. Use /ship for feature branch workflow."
 }
 EOJSON
 exit 2

package/framework/hooks/confirm-delete.sh

@@ -17,13 +17,11 @@ case "$COMMAND" in
 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."
+  "stopReason": "◆ DESTRUCTIVE GUARD: $1",
+  "systemMessage": "◆ BLOCKED: $1. Find a safer alternative. Explain to the user what was blocked and what safer approach you're using instead."
 }
 EOJSON
     exit 2
@@ -44,6 +42,11 @@ echo "$COMMAND" | grep -qE 'git\s+push\s+.*--force($|\s)' && ! echo "$COMMAND" |
 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"
 
+# Supabase destructive
+echo "$COMMAND" | grep -qE 'supabase\s+functions\s+delete' && block "supabase functions delete"
+echo "$COMMAND" | grep -qE 'supabase\s+secrets\s+unset' && block "supabase secrets unset"
+echo "$COMMAND" | grep -qE 'supabase\s+projects\s+delete' && block "supabase projects delete"
+
 # 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"

package/framework/hooks/migration-validate.sh

@@ -39,20 +39,19 @@ check_sql_file() {
 }
 
 TOTAL=0
-HEADER_SHOWN=false
+TRIGGERED=false
+WARN_DETAILS=""
 
 # Mode 1: SQL file written
 if [ -n "$FILE_PATH" ] && [[ "$FILE_PATH" == *.sql ]]; then
-    q_header "MIGRATION CHECK"
-    HEADER_SHOWN=true
+    TRIGGERED=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
+    TRIGGERED=true
     for sql_file in supabase/migrations/*.sql; do
         [ -f "$sql_file" ] || continue
         check_sql_file "$sql_file"
@@ -60,9 +59,11 @@ if [ -n "$COMMAND" ] && echo "$COMMAND" | grep -qE 'supabase\s+db\s+push'; then
     done
 fi
 
-if [ "$TOTAL" -gt 0 ] && $HEADER_SHOWN; then
-    q_info "${TOTAL} issue(s) — review carefully"
+# Warn but don't block — surface via systemMessage
+if $TRIGGERED && [ "$TOTAL" -gt 0 ]; then
+    printf '{"continue":true,"systemMessage":"◆ MIGRATION CHECK: %d issue(s) found — review carefully"}' "$TOTAL"
+elif $TRIGGERED; then
+    printf '{"continue":true,"systemMessage":"◆ MIGRATION CHECK: clean"}'
 fi
 
-# Warn but don't block
 exit 0

package/framework/hooks/notification-speak.sh

@@ -9,7 +9,7 @@ if [ ! -t 0 ]; then
 fi
 
 if [ -n "$TEXT" ]; then
-    ~/.claude/scripts/speak.sh "$TEXT"
+    ~/.claude/scripts/speak.sh "$TEXT" &
 fi
 
 exit 0

package/framework/hooks/pre-commit.sh

@@ -51,30 +51,42 @@ if [ -n "$JS_FILES" ]; then
     done
 fi
 
-# TypeScript check
+# TypeScript check (skip if tsc passed in last 5 minutes — pre-deploy-gate also runs tsc)
+TSC_STAMP="/tmp/.tsc-pass-$(echo "$PWD" | md5sum | cut -c1-8)"
 if [ -f "tsconfig.json" ]; then
-    if command -v npx &> /dev/null; then
-        if npx tsc --noEmit 2>/dev/null; then
-            q_pass "TypeScript"
+    if [ -f "$TSC_STAMP" ]; then
+        AGE=$(( $(date +%s) - $(stat -c %Y "$TSC_STAMP" 2>/dev/null || echo 0) ))
+        if [ "$AGE" -lt 300 ]; then
+            q_pass "TypeScript (cached)"
         else
-            q_fail "TypeScript errors"
-            FAIL_DETAILS="${FAIL_DETAILS}TypeScript errors. Run npx tsc --noEmit. "
-            BLOCKED=true
+            rm -f "$TSC_STAMP"
+        fi
+    fi
+    # Run tsc only if no valid cache
+    if [ ! -f "$TSC_STAMP" ]; then
+        if command -v npx &> /dev/null; then
+            if npx tsc --noEmit 2>/dev/null; then
+                q_pass "TypeScript"
+                touch "$TSC_STAMP"
+            else
+                q_fail "TypeScript errors"
+                FAIL_DETAILS="${FAIL_DETAILS}TypeScript errors. Run npx tsc --noEmit. "
+                BLOCKED=true
+            fi
         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."
+  "systemMessage": "◆ PRE-COMMIT BLOCKED: ${FAIL_DETAILS}Fix issues, stage corrected files, and retry."
 }
 EOJSON
     exit 2
 fi
 
-q_pass "All checks passed"
+printf '{"continue":true,"systemMessage":"◆ PRE-COMMIT: all checks passed"}'
 exit 0

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

@@ -128,24 +128,23 @@ 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."
+  "systemMessage": "◆ DEPLOY BLOCKED: ${FAILURES} check(s) failed. ${FAIL_DETAILS}Fix and retry vercel --prod."
 }
 EOJSON
     exit 2
 fi
 
+WARN_MSG=""
 if [ "$WARNINGS" -gt 0 ]; then
-    q_warn "${WARNINGS} warning(s) — proceeding"
+    WARN_MSG=" (${WARNINGS} warning(s))"
 fi
 
-q_approved
-
 # Stamp success
 touch "$STAMP"
+
+printf '{"continue":true,"systemMessage":"◆ DEPLOY GATE APPROVED%s"}' "$WARN_MSG"
 exit 0

package/framework/hooks/retention-cleanup.sh

@@ -1,11 +1,20 @@
 #!/bin/bash
 # Retention cleanup — runs on SessionStart to enforce retention policies
 # Keeps .claude/ lean by pruning stale data automatically
+# This is the SINGLE SOURCE OF TRUTH for retention — config/retention.json is deprecated
+#
+# Policies:
+#   file-history/     7 days
+#   session-env/      50 JSON files + 10 UUID dirs
+#   backups/          3 days
+#   paste-cache/      3 days
+#   shell-snapshots/  3 days
+#   projects/*.jsonl  7 days
+#   tasks/            3 days
+#   plans/            7 days
 
 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

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

@@ -8,6 +8,17 @@ DIGEST_FILE="$KNOWLEDGE_DIR/session-digest.md"
 TIMESTAMP=$(date +%Y%m%d_%H%M%S)
 SESSION_FILE="$SESSION_DIR/session_$TIMESTAMP.json"
 
+# Skip saving for very short sessions (< 30s) to reduce cruft
+SESSION_START_FILE="$SESSION_DIR/.session-start"
+if [ -f "$SESSION_START_FILE" ]; then
+    START_TS=$(cat "$SESSION_START_FILE" 2>/dev/null || echo 0)
+    NOW_TS=$(date +%s)
+    DURATION=$((NOW_TS - START_TS))
+    if [ "$DURATION" -lt 30 ]; then
+        exit 0
+    fi
+fi
+
 mkdir -p "$SESSION_DIR"
 mkdir -p "$KNOWLEDGE_DIR"
 
@@ -69,6 +80,17 @@ if [ "$PROJECT_NAME" != ".claude" ] && [ "$PROJECT_NAME" != "Projects" ] && { [
     DATE_SHORT=$(date '+%m-%d %H:%M')
     ENTRY="| ${DATE_SHORT} | ${PROJECT_NAME} | ${GIT_BRANCH:-—} | ${FILES_CHANGED} | ${SUMMARY:-—} |"
 
+    # Dedup: skip if ANY existing entry has the same project + branch + summary
+    NEW_KEY="${PROJECT_NAME}|${GIT_BRANCH:-—}|${SUMMARY:-—}"
+    if tail -n +4 "$DIGEST_FILE" | while IFS= read -r line; do
+        ENTRY_KEY=$(echo "$line" | awk -F'|' '{gsub(/^ +| +$/,"",$3); gsub(/^ +| +$/,"",$4); gsub(/^ +| +$/,"",$6); print $3"|"$4"|"$6}')
+        [ "$ENTRY_KEY" = "$NEW_KEY" ] && exit 0
+    done; then
+        : # no match found, continue
+    else
+        exit 0  # duplicate found, skip
+    fi
+
     # Read existing entries (skip header — first 3 lines), keep last 19
     EXISTING=$(tail -n +4 "$DIGEST_FILE" | head -19)
 

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

@@ -1,77 +1,75 @@
 #!/bin/bash
-# SessionStart hook — teal-branded session context
-# Shows resume hints to user via stderr, passes context to Claude via JSON stdout
-source "$(dirname "$0")/qualia-colors.sh"
+# SessionStart hook — session context with systemMessage for user visibility
+# stderr only shows in verbose mode; systemMessage shows in normal transcript
 
 CWD=$(pwd)
 SESSION_DIR="$HOME/.claude/session-env"
 COMPACT_FILE="$SESSION_DIR/pre-compact.json"
 PROJECT=$(basename "$CWD")
 
-# ─── Visual output (stderr → user sees this) ───
-q_header "SESSION START"
+# Record session start time for duration-based filtering in save-session-state.sh
+mkdir -p "$SESSION_DIR"
+date +%s > "$SESSION_DIR/.session-start"
+
+# Build display message
+MSG="◆ SESSION START"
+ISSUES=""
 
 # Last session info
 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)
     LAST_BRANCH=$(node -e "try{const d=JSON.parse(require('fs').readFileSync('$COMPACT_FILE','utf8'));process.stdout.write(d.git_branch||'')}catch(e){}" 2>/dev/null)
     if [ -n "$LAST_PROJECT" ] && [ "$LAST_PROJECT" != ".claude" ]; then
-        q_info "Last session: ${LAST_PROJECT} (${LAST_BRANCH:-no branch})"
+        MSG="${MSG} | Last: ${LAST_PROJECT} (${LAST_BRANCH:-no branch})"
     fi
 fi
 
-# Current project
-q_pass "Project: ${PROJECT}"
+MSG="${MSG} | Project: ${PROJECT}"
 
 # Handoff file
 if [ -f "$CWD/.continue-here.md" ]; then
-    q_warn "Handoff file found — .continue-here.md"
+    MSG="${MSG} | ▲ Handoff: .continue-here.md"
 fi
 
-# Errors / warnings
-ERRORS=0
-
 # Check hooks health
 HOOKS_OK=0
 HOOKS_TOTAL=0
-for h in branch-guard pre-commit confirm-delete migration-validate pre-deploy-gate block-env-edit auto-format session-context-loader retention-cleanup pre-compact save-session-state session-learn notification-speak qualia-colors; do
+for h in branch-guard pre-commit confirm-delete migration-validate pre-deploy-gate block-env-edit auto-format session-context-loader retention-cleanup pre-compact save-session-state session-learn notification-speak qualia-colors skill-announce tool-error-announce; do
     HOOKS_TOTAL=$((HOOKS_TOTAL + 1))
     [ -f "$HOME/.claude/hooks/${h}.sh" ] && HOOKS_OK=$((HOOKS_OK + 1))
 done
 
 if [ "$HOOKS_OK" -eq "$HOOKS_TOTAL" ]; then
-    q_pass "Hooks: ${HOOKS_OK}/${HOOKS_TOTAL}"
+    MSG="${MSG} | Hooks: ${HOOKS_OK}/${HOOKS_TOTAL}"
 else
-    q_fail "Hooks: ${HOOKS_OK}/${HOOKS_TOTAL} — $(( HOOKS_TOTAL - HOOKS_OK )) missing"
-    ERRORS=$((ERRORS + 1))
+    MSG="${MSG} | Hooks: ${HOOKS_OK}/${HOOKS_TOTAL} ($(( HOOKS_TOTAL - HOOKS_OK )) missing)"
+    ISSUES="${ISSUES}Missing hooks. "
 fi
 
 # Check CLAUDE.md exists
 if [ -f "$HOME/.claude/CLAUDE.md" ]; then
     ROLE=$(grep -m1 "^## Role:" "$HOME/.claude/CLAUDE.md" 2>/dev/null | sed 's/^## Role: *//')
-    q_pass "Role: ${ROLE:-unknown}"
+    MSG="${MSG} | Role: ${ROLE:-unknown}"
 else
-    q_fail "CLAUDE.md missing — run npx qualia-framework"
-    ERRORS=$((ERRORS + 1))
+    ISSUES="${ISSUES}CLAUDE.md missing. "
 fi
 
 # Check settings.json valid
 if [ -f "$HOME/.claude/settings.json" ]; then
     node -e "JSON.parse(require('fs').readFileSync('$HOME/.claude/settings.json','utf8'))" 2>/dev/null
-    if [ $? -eq 0 ]; then
-        q_pass "Settings: valid"
-    else
-        q_fail "Settings: invalid JSON!"
-        ERRORS=$((ERRORS + 1))
+    if [ $? -ne 0 ]; then
+        ISSUES="${ISSUES}settings.json invalid. "
     fi
 fi
 
-if [ "$ERRORS" -gt 0 ]; then
-    q_warn "${ERRORS} issue(s) — check above"
+if [ -n "$ISSUES" ]; then
+    MSG="${MSG} | ▲ ${ISSUES}"
 fi
 
-q_info "Activating Qualia mode..."
+MSG="${MSG} | Qualia mode activating..."
+
+# Escape for JSON
+MSG=$(echo "$MSG" | sed 's/"/\\"/g' | tr '\n' ' ')
 
-# ─── JSON output (stdout → Claude reads this) ───
-printf '{"continue":true}'
+printf '{"continue":true,"systemMessage":"%s"}' "$MSG"
 exit 0

package/framework/hooks/session-learn.sh

@@ -2,13 +2,14 @@
 # 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"
 
+# Skip if not in a git repo
+git rev-parse --is-inside-work-tree &>/dev/null || exit 0
+
 # 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)
+COMMITTED=$(git diff --name-only "$(git log --since='2 hours ago' --format=%H 2>/dev/null | tail -1 || echo HEAD)" HEAD 2>/dev/null | wc -l 2>/dev/null || echo 0)
+UNCOMMITTED=$(git diff --name-only 2>/dev/null | wc -l 2>/dev/null || echo 0)
 MODIFIED_COUNT=$((COMMITTED + UNCOMMITTED))
 
 # Only trigger if significant work was done
@@ -25,6 +26,6 @@ if [ ! -f "$LEARNED_FILE" ]; then
 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."
+printf '{"continue":true,"systemMessage":"SESSION_LEARN: %d files changed this session. Consider running /learn to capture any lessons."}' "$MODIFIED_COUNT"
 
 exit 0

package/framework/hooks/skill-announce.sh

@@ -1,5 +1,7 @@
 #!/bin/bash
-# Announce skill activation in teal — fires on every Skill() invocation
+# Announce skill activation — fires on every Skill() invocation
+# Shows teal-branded banner on stderr (visible in terminal) + systemMessage for transcript
+
 source "$(dirname "$0")/qualia-colors.sh"
 
 if [ ! -t 0 ]; then
@@ -7,12 +9,113 @@ if [ ! -t 0 ]; then
     SKILL_NAME=$(echo "$INPUT" | node -e "try{const d=JSON.parse(require('fs').readFileSync('/dev/stdin','utf8'));process.stdout.write(d.tool_input?.skill||d.tool_input?.name||'')}catch(e){}" 2>/dev/null)
 fi
 
-[ -z "$SKILL_NAME" ] && exit 0
+[ -z "$SKILL_NAME" ] && printf '{"continue":true}' && exit 0
+
+# Skill descriptions for the banner
+declare -A SKILL_DESC
+SKILL_DESC=(
+    # Pipeline
+    ["qualia-new-project"]="Initializing new project"
+    ["qualia-new-milestone"]="Starting new milestone"
+    ["qualia-discuss-phase"]="Clarifying phase decisions"
+    ["qualia-list-phase-assumptions"]="Surfacing assumptions"
+    ["qualia-research-phase"]="Researching phase domain"
+    ["qualia-plan-phase"]="Creating execution plans"
+    ["qualia-execute-phase"]="Executing phase plans"
+    ["qualia-verify-work"]="Verifying deliverables"
+    ["qualia-audit-milestone"]="Auditing milestone completion"
+    ["qualia-complete-milestone"]="Completing milestone"
+    ["qualia-plan-milestone-gaps"]="Planning gap fixes"
+    # Navigation
+    ["qualia-start"]="Activating Qualia mode"
+    ["qualia-progress"]="Checking progress"
+    ["qualia-idk"]="Analyzing next steps"
+    ["qualia"]="Routing to next action"
+    ["qualia-resume-work"]="Restoring session context"
+    ["qualia-pause-work"]="Saving session state"
+    # Quality
+    ["qualia-review"]="Running code review"
+    ["qualia-optimize"]="Running optimization pass"
+    ["qualia-production-check"]="Running production audit"
+    ["qualia-framework-audit"]="Auditing framework"
+    ["deep-research"]="Spawning research agents"
+    # Design
+    ["critique"]="Evaluating design"
+    ["polish"]="Final detail pass"
+    ["bolder"]="Amplifying design"
+    ["design-quieter"]="Toning down design"
+    ["distill"]="Stripping complexity"
+    ["colorize"]="Adding color"
+    ["normalize"]="Matching design system"
+    ["responsive"]="Fixing responsive layout"
+    ["animate"]="Adding motion"
+    ["clarify"]="Improving UX copy"
+    ["delight"]="Adding personality"
+    ["harden"]="Hardening edge cases"
+    ["onboard"]="Designing onboarding"
+    ["frontend-master"]="Building frontend"
+    ["qualia-design"]="Full design transformation"
+    # Deploy
+    ["ship"]="Deploying to production"
+    ["deploy"]="Quick deploy"
+    ["deploy-verify"]="Verifying deployment"
+    ["status"]="Fleet health check"
+    # Debug & Quick
+    ["qualia-debug"]="Structured debugging"
+    ["qualia-quick"]="Quick task with quality gates"
+    # Research
+    ["stack-researcher"]="Researching tech stack"
+    ["docs-lookup"]="Fetching documentation"
+    # Domain
+    ["supabase"]="Supabase operations"
+    ["voice-agent"]="Building voice agent"
+    ["seo-master"]="SEO audit"
+    ["browser-qa"]="Browser QA testing"
+    # Utility
+    ["learn"]="Capturing lesson"
+    ["memory"]="Managing memory"
+    ["pr"]="Creating pull request"
+    ["team"]="Orchestrating agent team"
+    ["retro"]="Generating retrospective"
+    ["test-runner"]="Running tests"
+    ["zoho-workflow"]="Zoho operations"
+)
+
+# Get description or fallback
+DESC="${SKILL_DESC[$SKILL_NAME]}"
+[ -z "$DESC" ] && DESC="Activating"
+
+# Clean name for display
+DISPLAY_NAME=$(echo "$SKILL_NAME" | sed 's/-/ /g')
+
+# Determine skill category icon
+case "$SKILL_NAME" in
+    qualia-new-*|qualia-plan-*|qualia-execute-*|qualia-verify-*|qualia-audit-*|qualia-complete-*|qualia-discuss-*|qualia-list-*|qualia-research-*)
+        ICON="▶" ;;
+    qualia-review|qualia-optimize|qualia-production-check|qualia-framework-audit|deep-research)
+        ICON="⊘" ;;
+    critique|polish|bolder|design-quieter|distill|colorize|normalize|responsive|animate|clarify|delight|harden|onboard|frontend-master|qualia-design)
+        ICON="◇" ;;
+    ship|deploy|deploy-verify|status)
+        ICON="↑" ;;
+    qualia-debug|qualia-quick)
+        ICON="⚡" ;;
+    *)
+        ICON="◆" ;;
+esac
 
-# Clean up skill name for display
-DISPLAY_NAME=$(echo "$SKILL_NAME" | sed 's/-/ /g' | sed 's/qualia //g')
+# Build the teal banner — output to stderr (visible in terminal)
+WIDTH=44
+SKILL_UPPER="${DISPLAY_NAME^^}"
+PAD_LEN=$(( WIDTH - ${#SKILL_UPPER} - 6 ))
+[ "$PAD_LEN" -lt 2 ] && PAD_LEN=2
+PADDING=$(printf '─%.0s' $(seq 1 $PAD_LEN))
 
-q_header "${DISPLAY_NAME^^} activated"
+printf "\n" >&2
+printf "${Q_TEAL}${ICON}${Q_RESET} ${Q_BRIGHT}QUALIA${Q_RESET} ${Q_DIM}───${Q_RESET} ${Q_TEAL}/%s${Q_RESET} ${Q_DIM}%s${Q_RESET}\n" "$SKILL_NAME" "$PADDING" >&2
+printf "  ${Q_WHITE}%s${Q_RESET}${Q_DIM}...${Q_RESET}\n" "$DESC" >&2
+printf "${Q_TEAL}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${Q_RESET}\n" >&2
 
-printf '{"continue":true}'
+# Also send systemMessage for transcript visibility
+printf '{"continue":true,"systemMessage":"◆ QUALIA ─── /%s ─── %s"}' "$SKILL_NAME" "$DESC"
 exit 0