claude-flow-novice 2.18.12 → 2.18.14

package/.claude/agents/custom/claude-code-expert.md

@@ -237,6 +237,61 @@ Claude Code auto-discovers MCP servers from:
 
 To prevent auto-discovered servers from connecting, add them to `disabledMcpServers`.
 
+## SKILL.md Best Practices
+
+### Description Field is Primary Discovery
+- Claude reads **only the `description` field** at startup to decide when to invoke skills
+- Full SKILL.md content is loaded **only after** Claude decides the skill is relevant
+- Description must answer: **What does it do?** + **When should it be used?**
+
+### Effective Description Formula
+```yaml
+description: "<Capability>. Use when <condition 1>, <condition 2>, or <condition 3>."
+```
+
+**Good example:**
+```yaml
+description: "Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction."
+```
+
+**Bad examples:**
+- `"Helps with documents"` - too vague
+- `"Processes data"` - too generic
+- Missing trigger conditions
+
+### Required Frontmatter
+```yaml
+---
+name: lowercase-skill-name    # Max 64 chars, hyphens/lowercase only
+description: What + when      # Max 1024 chars
+version: 1.0.0               # Optional but recommended
+tags: [category, type]       # For organization (not indexed by Claude)
+---
+```
+
+### Content Best Practices
+- **Under 500 lines** in SKILL.md body
+- Use **progressive disclosure** - detailed docs in separate files
+- Include concrete **Quick Start** examples
+- One level deep for reference files (no deep nesting)
+
+### Anti-Patterns to Avoid
+- Missing trigger conditions in description
+- Verbose prose instead of blueprints
+- Time-sensitive information
+- Offering too many options without clear recommendation
+- Inconsistent terminology
+
+### Skill Analysis Checklist
+When reviewing SKILL.md files, verify:
+- [ ] Description includes both capability AND trigger conditions
+- [ ] Uses "Use when..." pattern for discovery
+- [ ] Under 500 lines in body
+- [ ] Has YAML frontmatter with name, description
+- [ ] Includes concrete Quick Start example
+- [ ] No deep nesting of reference files
+- [ ] Consistent terminology throughout
+
 ## Documentation URLs to Reference
 
 Primary resources:
@@ -244,6 +299,7 @@ Primary resources:
 - https://docs.claudecode.com/workflows
 - https://docs.claudecode.com/tools
 - https://docs.claudecode.com/best-practices
+- https://docs.claudecode.com/skills (skill creation guide)
 
 ## Output Format
 

package/.claude/{skills → cfn-extras/skills/deprecated}/cfn-docker-runtime/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: cfn-docker-runtime
-description: Docker container orchestration for CFN Loop - spawning, coordination, logging, wave execution
+description: "Docker container orchestration for CFN Loop - spawning, coordination, logging, wave execution. Use when running CFN Loop agents in Docker containers, executing waves of parallel agents, coordinating containerized agents via Redis, or managing Docker-based agent lifecycle."
 version: 1.0.0
 tags: [mega-skill, docker, containers, orchestration]
 status: production

package/.claude/hooks/README.md

@@ -0,0 +1,148 @@
+# Claude Code Hooks
+
+This directory contains hooks that integrate with Claude Code's lifecycle events.
+
+## cfn-precompact-enhanced.sh
+
+Enhanced PreCompact hook that preserves context before conversation compaction (manual or auto).
+
+### Features
+
+**Context Preservation:**
+- Captures current git state (branch, status, recent commits)
+- Saves uncommitted and staged changes
+- Records modified files
+
+**Session Metrics:**
+- Counts recently edited files
+- Estimates session duration from git history
+- Detects test execution and status
+- Tracks tool usage (if transcript available)
+- Approximates token usage
+
+**CFN-Specific Detection:**
+- Active CFN Loop tasks
+- Running CFN Docker containers
+- Redis coordination state
+- Recent pre-edit backups
+
+**Output:**
+- Prints structured summary to stdout (injected into Claude's context)
+- Saves detailed JSON log to `.artifacts/precompact/session-{timestamp}.json`
+- Includes CLAUDE.md reminders for best practices
+
+### Configuration
+
+The hook is configured in `.claude/settings.json`:
+
+```json
+{
+  "hooks": {
+    "PreCompact": [
+      {
+        "matcher": "manual",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "/bin/bash .claude/hooks/cfn-precompact-enhanced.sh"
+          }
+        ]
+      },
+      {
+        "matcher": "auto",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "/bin/bash .claude/hooks/cfn-precompact-enhanced.sh"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+### Performance
+
+- **Timeout Protection**: 9-second overall script timeout
+- **Non-Blocking**: Always exits with code 0
+- **Optimized for WSL2**: Limits `find` depth and targets specific directories
+- **Graceful Degradation**: Continues if git/jq unavailable
+
+### Testing
+
+```bash
+# Test without stdin
+./.claude/hooks/cfn-precompact-enhanced.sh
+
+# Test with simulated input
+echo '{"type": "manual", "compact_type": "manual"}' | \
+  CLAUDE_PROJECT_DIR=$(pwd) bash .claude/hooks/cfn-precompact-enhanced.sh
+```
+
+### Output Example
+
+```
+=== PRE-COMPACT CONTEXT PRESERVATION ===
+
+Compact Type: manual
+Timestamp: 2025-12-10 04:46:26
+
+Git State:
+  Branch: feature/auth-system
+  Uncommitted: 3 files
+  Modified: 2 files
+  Staged: 1 files
+  Last commit: abc123 - "Add JWT validation" (2 hours ago)
+
+Session Summary:
+  Recent file edits: 5
+  Duration: 45 minutes
+  Tests run: true
+  Test status: passing
+  Tools used: 12 (Bash: 8, Edit: 4)
+  Approx tokens: ~800
+
+Key Context:
+  - Working directory: /path/to/project
+  - Uncommitted changes
+  - 2 CFN container(s) running
+
+Full context saved to: .artifacts/precompact/session-1765370786.json
+
+=== CLAUDE.md REMINDERS ===
+• Use CFN Loop for multi-step tasks
+• Batch operations in single messages
+• Pre-edit backup required before edits
+• Run tests before commits
+• Use service names in Docker networks
+```
+
+### Artifacts
+
+Session data is preserved in:
+- `.artifacts/precompact/session-{timestamp}.json` - Full JSON context
+- `.artifacts/precompact/{timestamp}-git.diff` - Git diff (if changes exist)
+- `.artifacts/precompact/{timestamp}-commits.txt` - Recent commit history
+- `.artifacts/precompact/backup-{todo-file}-{timestamp}` - Copied todo files
+
+### Environment Variables
+
+- `CLAUDE_PROJECT_DIR` - Project root (defaults to `pwd`)
+- `TRANSCRIPT_PATH` - Path to conversation transcript (optional, for tool usage stats)
+- `INPUT` - JSON input from Claude Code (compact_type, custom_instructions)
+
+### Troubleshooting
+
+**Hook times out:**
+- Check if running on Windows mount (should be Linux filesystem)
+- Verify timeout settings in script (default 9 seconds)
+- Reduce `find` depth or target fewer directories
+
+**No JSON output:**
+- Ensure `.artifacts/precompact/` directory exists
+- Check for `jq` availability (gracefully degrades if missing)
+
+**Line ending issues:**
+- Convert to Unix line endings: `dos2unix .claude/hooks/cfn-precompact-enhanced.sh`
+- Or use: `sed -i 's/\r$//' .claude/hooks/cfn-precompact-enhanced.sh`

package/.claude/hooks/SessionStart:cfn-load-openai-key.sh

@@ -0,0 +1,35 @@
+#!/bin/bash
+
+# SessionStart hook: Load OpenAI API key from root .env file
+# This ensures OPENAI_API_KEY is available for embedding generation
+
+set -e
+
+# Path to root .env file
+ROOT_ENV="${PROJECT_ROOT:-.}/.env"
+
+# Check if .env exists
+if [[ ! -f "$ROOT_ENV" ]]; then
+    echo "⚠️  Warning: $ROOT_ENV not found. OpenAI embeddings will not work." >&2
+    exit 0
+fi
+
+# Extract OPENAI_API_KEY from .env
+if grep -q "^OPENAI_API_KEY=" "$ROOT_ENV"; then
+    # Export the key for this session
+    export OPENAI_API_KEY=$(grep "^OPENAI_API_KEY=" "$ROOT_ENV" | cut -d'=' -f2- | tr -d '"')
+
+    # Verify key is set
+    if [[ -n "$OPENAI_API_KEY" ]]; then
+        echo "✅ Loaded OPENAI_API_KEY from root .env" >&2
+    else
+        echo "⚠️  Warning: OPENAI_API_KEY found but empty in $ROOT_ENV" >&2
+    fi
+else
+    echo "⚠️  Warning: OPENAI_API_KEY not found in $ROOT_ENV. OpenAI embeddings will not work." >&2
+fi
+
+# Make it available to subprocesses
+export OPENAI_API_KEY
+
+exit 0

package/.claude/hooks/cfn-invoke-pre-edit.sh

@@ -92,7 +92,7 @@ fi
 # === Execute Pre-Edit Backup ===
 
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-BACKUP_SCRIPT="${SCRIPT_DIR}/../skills/pre-edit-backup/backup.sh"
+BACKUP_SCRIPT="${SCRIPT_DIR}/../skills/cfn-edit-safety/lib/backup/backup.sh"
 
 if [[ ! -f "$BACKUP_SCRIPT" ]]; then
     echo "Error: Backup script not found: $BACKUP_SCRIPT" >&2

package/.claude/hooks/cfn-load-cerebras-env.sh

@@ -0,0 +1,65 @@
+#!/bin/bash
+set -euo pipefail
+
+log_prefix="[Cerebras-SessionStart]"
+
+if [[ -n "${CEREBRAS_API_KEY:-}" ]]; then
+    exit 0
+fi
+
+env_file="${CLAUDE_PROJECT_DIR:-.}/.env"
+
+if [[ ! -f "$env_file" ]]; then
+    echo "$log_prefix Warning: .env file not found at $env_file. Set via: export CEREBRAS_API_KEY=your_key" >&2
+    exit 0
+fi
+
+if [[ ! -r "$env_file" ]]; then
+    echo "$log_prefix Warning: .env file at $env_file is not readable. Check permissions." >&2
+    exit 0
+fi
+
+if [[ ! -s "$env_file" ]]; then
+    echo "$log_prefix Warning: .env file at $env_file is empty." >&2
+    exit 0
+fi
+
+api_key=""
+model="zai-glm-4.6"
+line_num=0
+
+while IFS= read -r line || [[ -n "$line" ]]; do
+    ((line_num++))
+    
+    [[ "$line" =~ ^[[:space:]]*# ]] && continue
+    [[ -z "${line// }" ]] && continue
+    
+    if [[ "$line" =~ ^CEREBRAS_API_KEY[[:space:]]*= ]]; then
+        if [[ "$line" =~ ^CEREBRAS_API_KEY[[:space:]]*=[[:space:]]*$ ]]; then
+            echo "$log_prefix Warning: Empty CEREBRAS_API_KEY at line $line_num in $env_file" >&2
+        else
+            api_key=$(echo "$line" | cut -d= -f2-)
+            api_key="${api_key#"${api_key%%[![:space:]]*}"}"
+            api_key="${api_key%"${api_key##*[![:space:]]}"}"
+        fi
+    elif [[ "$line" =~ ^CEREBRAS_MODEL[[:space:]]*= ]]; then
+        if [[ ! "$line" =~ ^CEREBRAS_MODEL[[:space:]]*=[[:space:]]*$ ]]; then
+            model=$(echo "$line" | cut -d= -f2-)
+            model="${model#"${model%%[![:space:]]*}"}"
+            model="${model%"${model##*[![:space:]]}"}"
+        fi
+    fi
+done < "$env_file"
+
+if [[ -z "$api_key" ]]; then
+    echo "$log_prefix Warning: CEREBRAS_API_KEY not found in $env_file. Set via: export CEREBRAS_API_KEY=your_key" >&2
+    exit 0
+fi
+
+redacted_key="${api_key:0:8}***"
+
+cat <<EOF
+{
+  "additionalContext": "Cerebras API configured: model=$model, key=$redacted_key"
+}
+EOF

package/.claude/hooks/cfn-precompact-enhanced.sh

@@ -0,0 +1,283 @@
+#!/bin/bash
+set -euo pipefail
+
+# Enhanced PreCompact Hook for Claude Code
+# Preserves context before conversation compaction
+# Exit 0 always to ensure non-blocking behavior
+
+# Overall script timeout (9 seconds, allowing 1 second buffer)
+(
+sleep 9
+kill -TERM $$ 2>/dev/null || true
+) &
+TIMEOUT_PID=$!
+
+SCRIPT_START=$(date +%s)
+TIMEOUT_SECONDS=2
+
+# Timeout wrapper for all operations
+timeout_wrapper() {
+    timeout ${TIMEOUT_SECONDS}s "$@" 2>/dev/null || true
+}
+
+# Ensure we kill timeout watcher on exit
+trap "kill $TIMEOUT_PID 2>/dev/null || true" EXIT
+
+# Setup
+PROJECT_DIR="${CLAUDE_PROJECT_DIR:-$(pwd)}"
+ARTIFACTS_DIR="${PROJECT_DIR}/.artifacts/precompact"
+TIMESTAMP=$(date +%s)
+SESSION_FILE="${ARTIFACTS_DIR}/session-${TIMESTAMP}.json"
+
+# Create artifacts directory
+mkdir -p "${ARTIFACTS_DIR}" 2>/dev/null || true
+
+# Parse INPUT from stdin (if available) - non-blocking read
+if [ -t 0 ]; then
+    # No stdin available (terminal)
+    INPUT="{}"
+else
+    # Read from stdin with timeout
+    INPUT=$(timeout 1s cat 2>/dev/null || echo "{}")
+fi
+
+COMPACT_TYPE=$(echo "$INPUT" | jq -r '.compact_type // .type // "unknown"' 2>/dev/null || echo "unknown")
+CUSTOM_INSTRUCTIONS=$(echo "$INPUT" | jq -r '.custom_instructions // ""' 2>/dev/null || echo "")
+
+# Check for transcript path (if available from environment)
+TRANSCRIPT_PATH="${TRANSCRIPT_PATH:-}"
+
+# Initialize context object
+CONTEXT="{}"
+
+# === GIT STATE PRESERVATION ===
+git_available() {
+    command -v git >/dev/null 2>&1 && [ -d "${PROJECT_DIR}/.git" ]
+}
+
+if git_available; then
+    GIT_BRANCH=$(timeout_wrapper git -C "${PROJECT_DIR}" rev-parse --abbrev-ref HEAD 2>/dev/null || echo "unknown")
+    GIT_STATUS=$(timeout_wrapper git -C "${PROJECT_DIR}" status --short 2>/dev/null || echo "")
+    GIT_UNCOMMITTED_COUNT=$(echo "$GIT_STATUS" | grep -c "^" 2>/dev/null || echo "0")
+
+    # Recent commits
+    GIT_LAST_COMMIT=$(timeout_wrapper git -C "${PROJECT_DIR}" log -1 --pretty=format:"%h - %s (%ar)" 2>/dev/null || echo "unknown")
+    GIT_RECENT_COMMITS=$(timeout_wrapper git -C "${PROJECT_DIR}" log -5 --pretty=format:"%h - %s" 2>/dev/null || echo "")
+
+    # Modified files
+    MODIFIED_FILES=$(timeout_wrapper git -C "${PROJECT_DIR}" diff --name-only HEAD 2>/dev/null | head -20 || echo "")
+    MODIFIED_COUNT=$(echo "$MODIFIED_FILES" | grep -c "^" 2>/dev/null || echo "0")
+
+    # Staged files
+    STAGED_FILES=$(timeout_wrapper git -C "${PROJECT_DIR}" diff --cached --name-only 2>/dev/null | head -20 || echo "")
+    STAGED_COUNT=$(echo "$STAGED_FILES" | grep -c "^" 2>/dev/null || echo "0")
+
+    CONTEXT=$(echo "$CONTEXT" | jq --arg branch "$GIT_BRANCH" \
+        --arg last_commit "$GIT_LAST_COMMIT" \
+        --arg uncommitted "$GIT_UNCOMMITTED_COUNT" \
+        --arg modified "$MODIFIED_COUNT" \
+        --arg staged "$STAGED_COUNT" \
+        '. + {git: {branch: $branch, last_commit: $last_commit, uncommitted_files: $uncommitted, modified_files: $modified, staged_files: $staged}}' 2>/dev/null || echo "$CONTEXT")
+fi
+
+# === TODO PRESERVATION ===
+TODO_FILES=()
+for todo_path in ".claude/todos.json" "TODO.md" ".todos" "todos.json"; do
+    if [ -f "${PROJECT_DIR}/${todo_path}" ]; then
+        TODO_FILES+=("$todo_path")
+        # Copy to artifacts
+        cp "${PROJECT_DIR}/${todo_path}" "${ARTIFACTS_DIR}/backup-${todo_path##*/}-${TIMESTAMP}" 2>/dev/null || true
+    fi
+done
+
+TODO_COUNT=${#TODO_FILES[@]}
+CONTEXT=$(echo "$CONTEXT" | jq --arg count "$TODO_COUNT" '. + {todos: {files_found: $count}}' 2>/dev/null || echo "$CONTEXT")
+
+# === SESSION METRICS ===
+# Count recently modified files in artifacts and project (with timeout to avoid hanging on slow mounts)
+# Only search specific directories to avoid slow Windows mount traversal
+RECENT_EDITS=0
+for dir in "src" ".claude" "tests" "scripts"; do
+    if [ -d "${PROJECT_DIR}/${dir}" ]; then
+        DIR_COUNT=$(timeout 1s find "${PROJECT_DIR}/${dir}" -maxdepth 2 -type f -mmin -60 \( -name "*.ts" -o -name "*.js" -o -name "*.sh" -o -name "*.md" \) 2>/dev/null | wc -l)
+        DIR_COUNT=${DIR_COUNT:-0}
+        RECENT_EDITS=$((RECENT_EDITS + DIR_COUNT))
+    fi
+done
+
+# Check for common work indicators
+TESTS_RUN=false
+TEST_STATUS="none"
+if [ -d "${PROJECT_DIR}/.artifacts/test-results" ]; then
+    RECENT_TEST_FILES=$(timeout_wrapper find "${PROJECT_DIR}/.artifacts/test-results" -type f -mmin -60 2>/dev/null | wc -l || echo "0")
+    if [ "$RECENT_TEST_FILES" -gt 0 ]; then
+        TESTS_RUN=true
+        # Try to extract test pass/fail status
+        LATEST_TEST_LOG=$(timeout_wrapper find "${PROJECT_DIR}/.artifacts/test-results" -type f -mmin -60 -name "*.log" 2>/dev/null | head -1)
+        if [ -n "$LATEST_TEST_LOG" ] && [ -f "$LATEST_TEST_LOG" ]; then
+            if grep -q "All tests passed" "$LATEST_TEST_LOG" 2>/dev/null; then
+                TEST_STATUS="passing"
+            elif grep -q "FAIL" "$LATEST_TEST_LOG" 2>/dev/null; then
+                TEST_STATUS="failing"
+            else
+                TEST_STATUS="unknown"
+            fi
+        fi
+    fi
+fi
+
+# Estimate session duration from git log (more reliable than file times on Windows mounts)
+SESSION_DURATION="unknown"
+if git_available; then
+    FIRST_COMMIT_TODAY=$(timeout_wrapper git -C "${PROJECT_DIR}" log --since="24 hours ago" --format=%ct --reverse 2>/dev/null | head -1 || echo "")
+    if [ -n "$FIRST_COMMIT_TODAY" ]; then
+        DURATION_MIN=$(( (SCRIPT_START - FIRST_COMMIT_TODAY) / 60 ))
+        if [ "$DURATION_MIN" -lt 60 ]; then
+            SESSION_DURATION="${DURATION_MIN} minutes"
+        else
+            DURATION_HOURS=$((DURATION_MIN / 60))
+            SESSION_DURATION="${DURATION_HOURS} hour(s)"
+        fi
+    fi
+fi
+
+# Tool usage extraction (if transcript available)
+TOOL_COUNT=0
+BASH_CALLS=0
+EDIT_CALLS=0
+if [ -n "$TRANSCRIPT_PATH" ] && [ -f "$TRANSCRIPT_PATH" ]; then
+    TOOL_COUNT=$(timeout_wrapper grep -c '"type":"tool_use"' "$TRANSCRIPT_PATH" 2>/dev/null || echo "0")
+    BASH_CALLS=$(timeout_wrapper grep -c '"name":"Bash"' "$TRANSCRIPT_PATH" 2>/dev/null || echo "0")
+    EDIT_CALLS=$(timeout_wrapper grep -c '"name":"Edit"' "$TRANSCRIPT_PATH" 2>/dev/null || echo "0")
+fi
+
+# Approximate token usage (very rough estimate based on file changes)
+APPROX_TOKENS="unknown"
+if [ "$MODIFIED_COUNT" -gt 0 ]; then
+    # Rough: 100 tokens per modified file + 50 per Bash call + 200 per Edit
+    APPROX_TOKENS=$((MODIFIED_COUNT * 100 + BASH_CALLS * 50 + EDIT_CALLS * 200))
+fi
+
+CONTEXT=$(echo "$CONTEXT" | jq --arg recent "$RECENT_EDITS" \
+    --arg duration "$SESSION_DURATION" \
+    --argjson tests "$TESTS_RUN" \
+    --arg test_status "$TEST_STATUS" \
+    --arg tool_count "$TOOL_COUNT" \
+    --arg bash_calls "$BASH_CALLS" \
+    --arg edit_calls "$EDIT_CALLS" \
+    --arg approx_tokens "$APPROX_TOKENS" \
+    '. + {session: {recent_file_edits: $recent, estimated_duration: $duration, tests_run: $tests, test_status: $test_status, tool_count: $tool_count, bash_calls: $bash_calls, edit_calls: $edit_calls, approx_tokens: $approx_tokens}}' 2>/dev/null || echo "$CONTEXT")
+
+# === IN-PROGRESS WORK DETECTION ===
+WORK_INDICATORS=()
+[ -f "${PROJECT_DIR}/.artifacts/runtime/task-in-progress" ] && WORK_INDICATORS+=("Task in progress")
+[ -f "${PROJECT_DIR}/.claude/agents/spawned" ] && WORK_INDICATORS+=("Agents spawned")
+[ "$GIT_UNCOMMITTED_COUNT" -gt 0 ] && WORK_INDICATORS+=("Uncommitted changes")
+
+# Check for CFN Loop state
+if [ -f "${PROJECT_DIR}/.artifacts/runtime/cfn-loop-state.json" ]; then
+    LOOP_STATUS=$(timeout_wrapper jq -r '.status // "unknown"' "${PROJECT_DIR}/.artifacts/runtime/cfn-loop-state.json" 2>/dev/null || echo "unknown")
+    [ "$LOOP_STATUS" != "unknown" ] && WORK_INDICATORS+=("CFN Loop: ${LOOP_STATUS}")
+fi
+
+# Check for Redis coordination (CLI mode)
+if command -v redis-cli >/dev/null 2>&1; then
+    REDIS_TASKS=$(timeout_wrapper redis-cli --scan --pattern "cfn:task:*" 2>/dev/null | wc -l || echo "0")
+    [ "$REDIS_TASKS" -gt 0 ] && WORK_INDICATORS+=("${REDIS_TASKS} active CFN task(s)")
+fi
+
+# Check for running Docker containers
+if command -v docker >/dev/null 2>&1; then
+    CFN_CONTAINERS=$(timeout_wrapper docker ps --filter "name=cfn-" --format "{{.Names}}" 2>/dev/null | wc -l || echo "0")
+    [ "$CFN_CONTAINERS" -gt 0 ] && WORK_INDICATORS+=("${CFN_CONTAINERS} CFN container(s) running")
+fi
+
+# Check for recent backups (pre-edit)
+if [ -d "${PROJECT_DIR}/.artifacts/backups" ]; then
+    RECENT_BACKUPS=$(timeout_wrapper find "${PROJECT_DIR}/.artifacts/backups" -type f -mmin -60 2>/dev/null | wc -l || echo "0")
+    [ "$RECENT_BACKUPS" -gt 0 ] && WORK_INDICATORS+=("${RECENT_BACKUPS} recent backup(s)")
+fi
+
+# === GENERATE OUTPUT FOR CLAUDE ===
+echo ""
+echo "=== PRE-COMPACT CONTEXT PRESERVATION ==="
+echo ""
+echo "Compact Type: ${COMPACT_TYPE}"
+[ -n "$CUSTOM_INSTRUCTIONS" ] && echo "Custom Instructions: ${CUSTOM_INSTRUCTIONS}"
+echo ""
+
+if git_available; then
+    echo "Git State:"
+    echo "  Branch: ${GIT_BRANCH}"
+    echo "  Uncommitted: ${GIT_UNCOMMITTED_COUNT} files"
+    [ "$MODIFIED_COUNT" -gt 0 ] && echo "  Modified: ${MODIFIED_COUNT} files"
+    [ "$STAGED_COUNT" -gt 0 ] && echo "  Staged: ${STAGED_COUNT} files"
+    echo "  Last commit: ${GIT_LAST_COMMIT}"
+    echo ""
+fi
+
+echo "Session Summary:"
+echo "  Recent file edits: ${RECENT_EDITS}"
+echo "  Duration: ${SESSION_DURATION}"
+echo "  Tests run: ${TESTS_RUN}"
+[ "$TEST_STATUS" != "none" ] && echo "  Test status: ${TEST_STATUS}"
+[ "$TOOL_COUNT" -gt 0 ] && echo "  Tools used: ${TOOL_COUNT} (Bash: ${BASH_CALLS}, Edit: ${EDIT_CALLS})"
+[ "$APPROX_TOKENS" != "unknown" ] && echo "  Approx tokens: ~${APPROX_TOKENS}"
+[ ${#WORK_INDICATORS[@]} -gt 0 ] && echo "  In-progress work: ${WORK_INDICATORS[*]}"
+echo ""
+
+if [ ${#TODO_FILES[@]} -gt 0 ]; then
+    echo "Todo Files Preserved:"
+    for todo in "${TODO_FILES[@]}"; do
+        echo "  - ${todo}"
+    done
+    echo ""
+fi
+
+if git_available && [ "$MODIFIED_COUNT" -gt 0 ]; then
+    echo "Recently Modified Files:"
+    echo "$MODIFIED_FILES" | head -10 | sed 's/^/  - /'
+    [ "$MODIFIED_COUNT" -gt 10 ] && echo "  ... and $(($MODIFIED_COUNT - 10)) more"
+    echo ""
+fi
+
+echo "Key Context:"
+echo "  - Working directory: ${PROJECT_DIR}"
+if [ ${#WORK_INDICATORS[@]} -gt 0 ]; then
+    for indicator in "${WORK_INDICATORS[@]}"; do
+        echo "  - ${indicator}"
+    done
+fi
+echo ""
+
+echo "Full context saved to: ${SESSION_FILE#${PROJECT_DIR}/}"
+echo ""
+
+echo "=== CLAUDE.md REMINDERS ==="
+echo "• Use CFN Loop for multi-step tasks"
+echo "• Batch operations in single messages"
+echo "• Pre-edit backup required before edits"
+echo "• Run tests before commits"
+echo "• Use service names in Docker networks"
+echo ""
+
+# === SAVE DETAILED JSON LOG ===
+FINAL_CONTEXT=$(echo "$CONTEXT" | jq --arg type "$COMPACT_TYPE" \
+    --arg custom "$CUSTOM_INSTRUCTIONS" \
+    --arg timestamp "$TIMESTAMP" \
+    --argjson indicators "$(printf '%s\n' "${WORK_INDICATORS[@]}" | jq -R . | jq -s . 2>/dev/null || echo '[]')" \
+    --arg modified_files "$MODIFIED_FILES" \
+    --arg staged_files "$STAGED_FILES" \
+    --arg recent_commits "$GIT_RECENT_COMMITS" \
+    '. + {
+        compact_type: $type,
+        custom_instructions: $custom,
+        timestamp: $timestamp,
+        work_indicators: $indicators,
+        git: (.git + {modified_file_list: $modified_files, staged_file_list: $staged_files, recent_commits: $recent_commits})
+    }' 2>/dev/null || echo "$CONTEXT")
+
+echo "$FINAL_CONTEXT" > "${SESSION_FILE}" 2>/dev/null || true
+
+# Always exit 0 (non-blocking)
+exit 0

package/.claude/hooks/deprecated/README.md

@@ -0,0 +1,27 @@
+# Deprecated Hooks
+
+These hooks have been superseded by the integrated post-edit pipeline (`config/hooks/post-edit-pipeline.js`) and settings.json hook configuration.
+
+## Deprecation Date: 2025-12-10
+
+## Why Deprecated
+
+| Script | Superseded By |
+|--------|---------------|
+| cfn-credential-scanner.sh | Pipeline Phase 2 security scanner |
+| cfn-lint-sql-injection.sh | Pipeline Phase 2.6 SQL injection detection |
+| cfn-detect-hardcoded-credentials.sh | Pipeline Phase 2 security scanner |
+| cfn-invoke-security-validation.sh | Pipeline Phase 2 security scanner |
+| cfn-post-edit.sh | Full pipeline via PostToolUse hook |
+| cfn-pre-edit-backup.sh | cfn-invoke-pre-edit.sh (wired in settings.json) |
+| cfn-invoke-post-edit-ts.sh | Pipeline handles TypeScript directly |
+| cfn-invoke-pre-edit-ts.sh | Pre-edit backup wired in settings.json |
+
+## Active Hooks (in parent directory)
+
+- `cfn-invoke-pre-edit.sh` - Pre-edit backup (WIRED)
+- `cfn-precompact-enhanced.sh` - Context preservation (WIRED)
+- `cfn-restore-from-backup.sh` - Revert capability
+- `cfn-subagent-start.sh` - Future use
+- `cfn-subagent-stop.sh` - Future use
+- `install-git-hooks.sh` - Git integration