Release v5.15.0 - Comprehensive Help System

.claude/settings.local.json

@@ -152,7 +152,12 @@
       "Bash(git init:*)",
       "Bash(git config:*)",
       "Bash(/Users/dt/projects/dev-tools/flow-cli/tests/test-teach-deploy.zsh)",
-      "Bash(gh pr checks:*)"
+      "Bash(gh pr checks:*)",
+      "Bash(./tests/test-index-management-unit.zsh)",
+      "Bash(./tests/test-teach-deploy-unit.zsh)",
+      "Bash(teach hooks status:*)",
+      "Bash(gh pr comment 279 --body \"$\\(cat <<''REVIEW''\n## ✅ Code Review: APPROVED\n\nExceptional work on Phase 2! This PR delivers substantial value with excellent quality.\n\n### 📊 Review Summary\n\n**Verdict:** ✅ **APPROVE** - Production-ready, safe to merge  \n**Confidence:** 95% \\(Very High\\)  \n**CI Status:** ✅ All checks passing \\(12s\\)  \n**Test Coverage:** 322/322 tests passing \\(100%\\)\n\n### 🌟 Highlights\n\n- 🚀 **3-10x performance improvement** \\(parallel rendering verified\\)\n- ✅ **322 comprehensive tests** \\(100% passing\\)\n- 📚 **2,931-line user guide** \\(excellent documentation\\)\n- 🔄 **Zero breaking changes** \\(perfect backward compatibility\\)\n- 🏗️ **Clean architecture** \\(6 well-separated modules\\)\n- 🔒 **No security issues** \\(proper locking, input validation\\)\n\n### 📈 Code Quality Scores\n\n| Aspect | Score | Notes |\n|--------|-------|-------|\n| Architecture & Design | ⭐⭐⭐⭐⭐ 5/5 | Clean separation, atomic operations |\n| Testing | ⭐⭐⭐⭐⭐ 5/5 | Comprehensive, well-structured |\n| Error Handling | ⭐⭐⭐⭐ 4/5 | Graceful degradation, clear messages |\n| Performance | ⭐⭐⭐⭐⭐ 5/5 | Verified benchmarks, low overhead |\n| Documentation | ⭐⭐⭐⭐⭐ 5/5 | Comprehensive guide + inline docs |\n\n**Overall:** ⭐⭐⭐⭐⭐ **Exceptional Quality**\n\n### ✅ What Works Great\n\n1. **Parallel Rendering System**\n   - Worker pool with atomic job distribution \\(flock\\)\n   - Smart queue optimization \\(slowest-first\\)\n   - Verified 3-10x speedup across benchmarks\n\n2. **Extensible Validator Framework**\n   - Plugin API for custom validators\n   - Auto-discovery from `.teach/validators/`\n   - < 5s overhead for 3 built-in validators\n\n3. **Performance Monitoring**\n   - Automatic tracking \\(zero config\\)\n   - ASCII trend graphs\n   - Data-driven recommendations\n\n4. **Test Coverage**\n   - 322 new tests \\(7 suites\\)\n   - Unit + integration coverage\n   - Mock-friendly design\n\n5. **Backward Compatibility**\n   - All Phase 1 features work unchanged\n   - Phase 2 features are opt-in\n   - No breaking changes\n\n### ⚠️ Minor Suggestions \\(for follow-up PRs\\)\n\n**Not blocking merge - address in future PRs:**\n\n1. **Consolidate wave summaries** \\(low priority\\)\n   - Merge WAVE-*.md files into `docs/PHASE-2-WAVES.md`\n   - Reduces documentation clutter\n\n2. **Add worker timeout** \\(medium priority\\)\n   - Prevent hung workers from blocking indefinitely\n   - Suggested: 5-minute timeout with graceful kill\n\n3. **Split large test file** \\(low priority\\)\n   - `test-phase2-integration.zsh` is 1,235 lines\n   - Consider splitting into focused suites\n\n4. **Architecture diagram** \\(nice-to-have\\)\n   - Visual diagram showing module relationships\n   - Add to user guide\n\n### 🎯 Final Recommendation\n\n**APPROVE and MERGE** ✅\n\nThis PR is production-ready:\n- Exceptional code quality\n- Comprehensive testing\n- Substantial value \\(3-10x speedup\\)\n- Zero breaking changes\n- All CI checks passing\n\n**Minor suggestions above can be addressed in follow-up PRs.**\n\n---\n\n**Ready to merge!** 🎉\n\nGreat work on this implementation! The parallel rendering system is particularly impressive with its atomic operations and smart queue optimization.\nREVIEW\n\\)\")",
+      "Bash(markdown-link-check:*)"
     ]
   }
 }

.teach/performance-log.json

@@ -0,0 +1,82 @@
+{
+  "version": "1.0",
+  "entries": [
+    {
+      "timestamp": "2026-01-20T14:30:00Z",
+      "operation": "validate",
+      "files": 12,
+      "duration_sec": 45,
+      "parallel": true,
+      "workers": 8,
+      "speedup": 3.5,
+      "cache_hits": 8,
+      "cache_misses": 4,
+      "cache_hit_rate": 0.67,
+      "avg_render_time_sec": 3.8,
+      "slowest_file": "lectures/week-08.qmd",
+      "slowest_time_sec": 15.2,
+      "per_file": [
+        {"file": "lectures/week-01.qmd", "duration_sec": 3.2, "cache_hit": true},
+        {"file": "lectures/week-02.qmd", "duration_sec": 5.1, "cache_hit": false},
+        {"file": "lectures/week-03.qmd", "duration_sec": 2.9, "cache_hit": true},
+        {"file": "lectures/week-04.qmd", "duration_sec": 9.2, "cache_hit": false},
+        {"file": "lectures/week-05.qmd", "duration_sec": 3.5, "cache_hit": true},
+        {"file": "lectures/week-06.qmd", "duration_sec": 12.8, "cache_hit": false},
+        {"file": "lectures/week-07.qmd", "duration_sec": 8.9, "cache_hit": false},
+        {"file": "lectures/week-08.qmd", "duration_sec": 15.2, "cache_hit": false},
+        {"file": "assignments/hw-01.qmd", "duration_sec": 4.1, "cache_hit": true},
+        {"file": "assignments/hw-02.qmd", "duration_sec": 3.8, "cache_hit": true},
+        {"file": "assignments/hw-03.qmd", "duration_sec": 4.5, "cache_hit": true},
+        {"file": "assignments/final.qmd", "duration_sec": 11.5, "cache_hit": false}
+      ]
+    },
+    {
+      "timestamp": "2026-01-19T10:15:00Z",
+      "operation": "validate",
+      "files": 12,
+      "duration_sec": 48,
+      "parallel": true,
+      "workers": 8,
+      "speedup": 3.3,
+      "cache_hits": 7,
+      "cache_misses": 5,
+      "cache_hit_rate": 0.58,
+      "avg_render_time_sec": 4.0,
+      "slowest_file": "lectures/week-08.qmd",
+      "slowest_time_sec": 15.8,
+      "per_file": []
+    },
+    {
+      "timestamp": "2026-01-18T15:45:00Z",
+      "operation": "validate",
+      "files": 8,
+      "duration_sec": 35,
+      "parallel": true,
+      "workers": 8,
+      "speedup": 2.9,
+      "cache_hits": 6,
+      "cache_misses": 2,
+      "cache_hit_rate": 0.75,
+      "avg_render_time_sec": 4.4,
+      "slowest_file": "lectures/week-06.qmd",
+      "slowest_time_sec": 13.2,
+      "per_file": []
+    },
+    {
+      "timestamp": "2026-01-17T09:30:00Z",
+      "operation": "validate",
+      "files": 10,
+      "duration_sec": 52,
+      "parallel": false,
+      "workers": 0,
+      "speedup": 1.0,
+      "cache_hits": 5,
+      "cache_misses": 5,
+      "cache_hit_rate": 0.50,
+      "avg_render_time_sec": 5.2,
+      "slowest_file": "lectures/week-08.qmd",
+      "slowest_time_sec": 16.1,
+      "per_file": []
+    }
+  ]
+}

.teach/validators/check-citations.zsh

@@ -0,0 +1,254 @@
+#!/usr/bin/env zsh
+# .teach/validators/check-citations.zsh - Citation Validator
+# Validates Pandoc citations against BibTeX files
+# v1.0.0 - Custom Validator Plugin
+#
+# VALIDATES:
+#   - Citations exist in .bib files ([@author2020])
+#   - Citation format is valid Pandoc syntax
+#   - Multiple citation support ([@a2020; @b2021])
+#   - Reports missing citations with line numbers
+#
+# DEPENDENCIES:
+#   - None (pure ZSH)
+
+# ============================================================================
+# VALIDATOR METADATA (Required)
+# ============================================================================
+
+VALIDATOR_NAME="Citation Validator"
+VALIDATOR_VERSION="1.0.0"
+VALIDATOR_DESCRIPTION="Validates Pandoc citations against BibTeX references"
+
+# ============================================================================
+# HELPER FUNCTIONS
+# ============================================================================
+
+# Extract all citation keys from a .qmd file
+# Returns: Array of citation keys (one per line)
+_extract_citations() {
+    local file="$1"
+    local citations=()
+
+    # Read file line by line to track line numbers
+    local line_num=0
+    while IFS= read -r line; do
+        ((line_num++))
+
+        # Extract citations from line
+        # Pattern: [@key] or [@key; @key2; @key3]
+        # Also handles: @key in text (without brackets)
+
+        # Method 1: Bracketed citations [@key]
+        local bracketed
+        bracketed=$(echo "$line" | grep -oE '\[@[^]]+\]')
+        if [[ -n "$bracketed" ]]; then
+            # Extract individual keys from bracketed citation
+            local keys
+            keys=$(echo "$bracketed" | sed 's/\[@//g; s/\]//g; s/;//g' | tr ' ' '\n' | grep -E '^@')
+            while IFS= read -r key; do
+                [[ -n "$key" ]] && citations+=("$line_num:${key#@}")
+            done <<< "$keys"
+        fi
+
+        # Method 2: Inline citations @key (but not in code blocks or URLs)
+        # Skip if line is in code block (starts with ``` or has 4+ spaces)
+        if ! echo "$line" | grep -qE '^(```|    )'; then
+            # Extract standalone @key patterns (not in URLs)
+            local inline
+            inline=$(echo "$line" | grep -oE '(^|[^/])@[a-zA-Z][a-zA-Z0-9_:-]*' | grep -oE '@[a-zA-Z][a-zA-Z0-9_:-]*')
+            while IFS= read -r key; do
+                if [[ -n "$key" ]]; then
+                    # Skip if it looks like a mention (e.g., @username)
+                    # Valid citation keys typically have numbers or specific patterns
+                    if echo "$key" | grep -qE '@[a-zA-Z]+[0-9]'; then
+                        citations+=("$line_num:${key#@}")
+                    fi
+                fi
+            done <<< "$inline"
+        fi
+    done < "$file"
+
+    # Return unique citations with line numbers (using ZSH builtins)
+    local unique_citations
+    unique_citations=(${(u)citations})  # (u) = unique
+    printf '%s\n' "${unique_citations[@]}"
+}
+
+# Find all .bib files in project
+# Searches current directory and common locations
+_find_bib_files() {
+    local search_dir="${1:-.}"
+    local bib_files=()
+
+    # Search in common locations
+    local search_paths=(
+        "$search_dir"
+        "$search_dir/references"
+        "$search_dir/bib"
+        "$search_dir/bibliography"
+        "$search_dir/.."
+    )
+
+    for path in "${search_paths[@]}"; do
+        if [[ -d "$path" ]]; then
+            for bib in "$path"/*.bib(N); do
+                [[ -f "$bib" ]] && bib_files+=("$bib")
+            done
+        fi
+    done
+
+    # Return unique .bib files (using ZSH builtins)
+    local unique_bibs
+    unique_bibs=(${(u)bib_files})  # (u) = unique
+    printf '%s\n' "${unique_bibs[@]}"
+}
+
+# Extract all citation keys from .bib files
+# Returns: Array of available citation keys
+_extract_bib_keys() {
+    local bib_files=("$@")
+    local keys=()
+
+    for bib in "${bib_files[@]}"; do
+        # Extract @type{key, pattern from .bib files
+        local bib_keys
+        bib_keys=$(grep -E '^@[a-zA-Z]+\{' "$bib" | sed 's/@[a-zA-Z]*{//; s/,$//' | tr -d ' ')
+        while IFS= read -r key; do
+            [[ -n "$key" ]] && keys+=("$key")
+        done <<< "$bib_keys"
+    done
+
+    # Return unique keys (using ZSH builtins)
+    local unique_keys
+    unique_keys=(${(u)keys})  # (u) = unique
+    printf '%s\n' "${unique_keys[@]}"
+}
+
+# Check if citation key exists in available keys
+_citation_exists() {
+    local citation="$1"
+    shift
+    local available_keys=("$@")
+
+    for key in "${available_keys[@]}"; do
+        [[ "$key" == "$citation" ]] && return 0
+    done
+
+    return 1
+}
+
+# Validate citation format
+# Valid formats:
+#   - @author2020
+#   - @author-etal2020
+#   - @author_2020
+#   - @author:2020
+_validate_citation_format() {
+    local citation="$1"
+
+    # Valid citation key pattern (Pandoc/BibTeX compatible)
+    if echo "$citation" | grep -qE '^[a-zA-Z][a-zA-Z0-9_:-]*$'; then
+        return 0
+    fi
+
+    return 1
+}
+
+# ============================================================================
+# MAIN VALIDATION FUNCTION (Required)
+# ============================================================================
+
+# Validate citations in a Quarto file
+# Arguments: $1 = file path
+# Returns: 0 if valid, 1 if errors found
+# Prints: Error messages to stdout
+_validate() {
+    local file="$1"
+    local errors=()
+
+    # Check file exists
+    if [[ ! -f "$file" ]]; then
+        echo "File not found"
+        return 1
+    fi
+
+    # Only validate .qmd files
+    if [[ "$file" != *.qmd ]]; then
+        # Not an error, just skip
+        return 0
+    fi
+
+    # Extract citations from file
+    local citations
+    citations=($(_extract_citations "$file"))
+
+    # If no citations, validation passes
+    if [[ ${#citations[@]} -eq 0 ]]; then
+        return 0
+    fi
+
+    # Find .bib files
+    local file_dir
+    file_dir=$(dirname "$file")
+    local bib_files
+    bib_files=($(_find_bib_files "$file_dir"))
+
+    # Check if .bib files exist
+    if [[ ${#bib_files[@]} -eq 0 ]]; then
+        # No .bib files found, but citations exist
+        for citation_with_line in "${citations[@]}"; do
+            local line_num="${citation_with_line%%:*}"
+            local citation="${citation_with_line#*:}"
+            errors+=("Line $line_num: No .bib files found (citation: @$citation)")
+        done
+        printf '%s\n' "${errors[@]}"
+        return 1
+    fi
+
+    # Extract available citation keys from .bib files
+    local available_keys
+    available_keys=($(_extract_bib_keys "${bib_files[@]}"))
+
+    # Validate each citation
+    for citation_with_line in "${citations[@]}"; do
+        local line_num="${citation_with_line%%:*}"
+        local citation="${citation_with_line#*:}"
+
+        # Check citation format
+        if ! _validate_citation_format "$citation"; then
+            errors+=("Line $line_num: Invalid citation format: @$citation")
+            continue
+        fi
+
+        # Check if citation exists in .bib files
+        if ! _citation_exists "$citation" "${available_keys[@]}"; then
+            errors+=("Line $line_num: Missing citation: @$citation")
+        fi
+    done
+
+    # Print errors
+    if [[ ${#errors[@]} -gt 0 ]]; then
+        printf '%s\n' "${errors[@]}"
+        return 1
+    fi
+
+    return 0
+}
+
+# ============================================================================
+# OPTIONAL FUNCTIONS
+# ============================================================================
+
+# Initialize validator (optional)
+# Check dependencies, setup environment
+_validator_init() {
+    # No dependencies needed for this validator
+    return 0
+}
+
+# Cleanup after validation (optional)
+_validator_cleanup() {
+    # No cleanup needed
+    return 0
+}