feat: help compliance for all 12 dispatchers + automated checker

commands/doctor.zsh

@@ -1,9 +1,12 @@
 # commands/doctor.zsh - Health check for flow-cli
 # Checks installed dependencies and offers to fix issues
 
+# Resolve directory at source time (not inside functions where $0 = function name)
+_DOCTOR_DIR="${0:A:h}"
+
 # Load cache library for token validation caching
-if [[ -f "${0:A:h}/../lib/doctor-cache.zsh" ]]; then
-  source "${0:A:h}/../lib/doctor-cache.zsh" 2>/dev/null || true
+if [[ -f "${_DOCTOR_DIR}/../lib/doctor-cache.zsh" ]]; then
+  source "${_DOCTOR_DIR}/../lib/doctor-cache.zsh" 2>/dev/null || true
 fi
 
 # ============================================================================
@@ -20,6 +23,9 @@ doctor() {
   local dot_token=""             # --dot=TOKEN: check specific token
   local fix_token_only=false     # --fix-token: fix only token issues
 
+  # Help compliance check
+  local help_check=false         # --help-check flag
+
   # Task 4: Verbosity levels
   local verbosity_level="normal" # quiet, normal, verbose
 
@@ -50,6 +56,7 @@ doctor() {
         shift
         ;;
 
+      --help-check)     help_check=true; shift; continue ;;
       --help|-h)        _doctor_help; return 0 ;;
       *)                shift ;;
     esac
@@ -61,6 +68,29 @@ doctor() {
     return $?
   fi
 
+  # Handle --help-check: run help compliance validation
+  if [[ "$help_check" == true ]]; then
+    local _hc_lib="${_DOCTOR_DIR}/../lib/help-compliance.zsh"
+    if [[ -f "$_hc_lib" ]]; then
+      source "$_hc_lib"
+      # Color fallbacks for standalone use
+      if [[ -z "$_C_BOLD" ]]; then
+          _C_BOLD='\033[1m'
+          _C_NC='\033[0m'
+      fi
+      echo ""
+      echo -e "${_C_BOLD}╭─────────────────────────────────────────────╮${_C_NC}"
+      echo -e "${_C_BOLD}│  📋 Help Function Compliance Check           │${_C_NC}"
+      echo -e "${_C_BOLD}╰─────────────────────────────────────────────╯${_C_NC}"
+      echo ""
+      _flow_help_compliance_check_all "$verbose"
+      return $?
+    else
+      echo "ERROR: lib/help-compliance.zsh not found"
+      return 1
+    fi
+  fi
+
   # Initialize cache on doctor start
   if (( $+functions[_doctor_cache_init] )); then
     _doctor_cache_init 2>/dev/null || true

docs/CONVENTIONS.md

@@ -216,6 +216,31 @@ _C_MAGENTA='\033[35m'  # Tips, related info
 _C_RED='\033[31m'      # Errors
 ```
 
+### Help Function Color Fallbacks
+
+Every `_<cmd>_help()` function **must** include color fallbacks for standalone use
+(when invoked outside the plugin context). Use the global block pattern:
+
+```bash
+# Canonical pattern — all dispatchers must match this exactly
+if [[ -z "$_C_BOLD" ]]; then
+    _C_BOLD='\033[1m'
+    _C_DIM='\033[2m'
+    _C_NC='\033[0m'
+    _C_GREEN='\033[32m'
+    _C_YELLOW='\033[33m'
+    _C_BLUE='\033[34m'
+    _C_MAGENTA='\033[35m'
+    _C_CYAN='\033[36m'
+fi
+```
+
+**Rules:**
+- Use `if [[ -z "$_C_BOLD" ]]` guard (NOT `local` scoped defaults)
+- Include exactly the 8 colors above (no `_C_RED`, no `_C_WHITE`)
+- Place immediately after the function opening brace
+- Validated by `flow doctor --help-check` (Rule 8)
+
 ### Usage
 
 ```bash

docs/help/QUICK-REFERENCE.md

@@ -8,8 +8,8 @@ tags:
 
 **Purpose:** Single-page command lookup for all flow-cli features
 **Format:** Copy-paste ready with expected outputs
-**Version:** v5.18.0-dev
-**Last Updated:** 2026-01-24
+**Version:** v6.2.0
+**Last Updated:** 2026-02-02
 
 ---
 
@@ -1022,6 +1022,6 @@ mcp help
 
 ---
 
-**Version:** v5.17.0-dev
-**Last Updated:** 2026-01-24
+**Version:** v6.2.0
+**Last Updated:** 2026-02-02
 **Contributors:** See [CHANGELOG.md](../CHANGELOG.md)

docs/specs/BRAINSTORM-help-compliance-checker-2026-02-02.md

@@ -0,0 +1,74 @@
+# Help Compliance Checker - Brainstorm
+
+**Generated:** 2026-02-02
+**Context:** flow-cli help function standards enforcement
+**Decision:** Option C (shared library + tests + CLI)
+
+## Problem
+
+12 dispatchers, each with a `_*_help()` function. Standards defined in `docs/CONVENTIONS.md:173-199` but no automated enforcement. Result: 6 non-compliant dispatchers drifted over time.
+
+## Options Considered
+
+### Option A: Test-Only
+- `tests/test-help-compliance.zsh`
+- CI catches regressions
+- **Rejected:** No on-demand check for developers
+
+### Option B: CLI-Only (`flow doctor --help-check`)
+- Visual pass/fail per dispatcher
+- ADHD-friendly colored output
+- **Rejected:** No CI protection
+
+### Option C: Both (Shared Core) ✅ SELECTED
+- `lib/help-compliance.zsh` shared validation
+- Tests call it -> CI protection
+- `flow doctor` calls it -> on-demand check
+- Single source of truth for rules
+
+### Option D: Pre-commit Hook
+- Block commits breaking standards
+- **Rejected:** Annoying, slows commits
+
+## What the Checker Validates (9 Rules)
+
+| # | Rule | Pattern |
+|---|---|---|
+| 1 | Box header | `╭─.*─╮` |
+| 2 | Box footer | `╰─.*─╯` |
+| 3 | MOST COMMON | `🔥.*MOST COMMON` |
+| 4 | QUICK EXAMPLES | `💡.*QUICK EXAMPLES` |
+| 5 | Categorized actions | `📋` |
+| 6 | TIP section | `💡.*TIP` |
+| 7 | See Also | `See also` or `📚` |
+| 8 | Color codes | ANSI escapes present |
+| 9 | Function naming | `_<cmd>_help` exists |
+
+## Current Audit Results
+
+| Dispatcher | Grade | Issues |
+|---|---|---|
+| g | A | None |
+| r | A | None |
+| mcp | A | None |
+| qu | A | None |
+| wt | A | None |
+| v | A- | See Also uses "EXISTING COMMANDS" |
+| teach | B+ | ANSI not rendering (cat <<EOF), FLOW_COLORS |
+| cc | B- | Double-line box, no MOST COMMON, no See Also |
+| tm | B- | Double-line box, no MOST COMMON, no emoji |
+| dot | C | Fully boxed layout, FLOW_COLORS, no standard sections |
+| obs | F | Plain text, no colors, wrong function name |
+| prompt | F | Plain cat <<EOF, no colors, no sections |
+
+## Quick Reference Version Staleness
+
+`docs/help/QUICK-REFERENCE.md` shows `v5.18.0-dev` but project is `v6.2.0`.
+
+## Next Steps
+
+1. Implement in worktree: `~/.git-worktrees/flow-cli/feature-help-compliance`
+2. Start with `lib/help-compliance.zsh` (shared rules)
+3. Fix dispatchers from worst to best (obs, prompt, dot, cc, tm, teach)
+4. Add test suite and doctor integration
+5. PR to dev

docs/specs/SPEC-help-compliance-2026-02-02.md

@@ -0,0 +1,150 @@
+# SPEC: Help Function Compliance System
+
+> **Date:** 2026-02-02
+> **Branch:** `feature/help-compliance`
+> **Status:** Draft
+> **From Audit:** Manual audit of all 12 dispatcher help functions
+
+## Summary
+
+Fix non-compliant help functions across all 12 dispatchers and add an automated compliance checker (shared library + test suite + `flow doctor` integration) to prevent future regressions.
+
+## Problem
+
+An audit of all 12 dispatcher help functions against `docs/CONVENTIONS.md:173-199` found:
+- **6/12 compliant** (g, r, mcp, qu, wt, v) - Grade A
+- **3/12 partially compliant** (cc, tm, teach) - Grade B
+- **1/12 significantly non-compliant** (dot) - Grade C
+- **2/12 fully non-compliant** (obs, prompt) - Grade F
+
+Issues include missing required sections, wrong color systems, non-standard box styles, and a rendering bug in `teach help`.
+
+## Scope
+
+### Phase 1: Fix Non-Compliant Help Functions
+
+| Dispatcher | Current Grade | Issues | Fix Effort |
+|---|---|---|---|
+| **obs** | F | No colors, no sections, wrong function name (`obs_help` not `_obs_help`), plain text | Rewrite |
+| **prompt** | F | No colors, no sections, `cat <<EOF` plain text, version number in header | Rewrite |
+| **dot** | C | Boxed layout with `FLOW_COLORS[]`, no standard sections, phase status cruft | Major refactor |
+| **cc** | B- | Double-line box `╔═╗`, "QUICK START" not "MOST COMMON", no See Also | Moderate |
+| **tm** | B- | Double-line box `╔═╗`, "QUICK START" not "MOST COMMON", no emoji markers | Moderate |
+| **teach** | B+ | `cat <<EOF` raw ANSI codes not rendering, `FLOW_COLORS[]` instead of `_C_*` | Fix rendering |
+
+### Phase 2: Automated Compliance Checker
+
+Create `lib/help-compliance.zsh` as shared validation logic with two consumers:
+
+1. **`tests/test-help-compliance.zsh`** - Test suite integration (CI)
+2. **`flow doctor --help-check`** - CLI integration (on-demand)
+
+### Out of Scope
+
+- Changing the standard itself (CONVENTIONS.md stays as-is)
+- Adding new dispatchers
+- Modifying help content (only fixing structure/formatting)
+
+## Acceptance Criteria
+
+### Phase 1: Help Fixes
+
+- [ ] All 12 dispatchers use `╭─╮╰─╯` single-line box (45 chars)
+- [ ] All 12 dispatchers have `🔥 MOST COMMON` section (green)
+- [ ] All 12 dispatchers have `💡 QUICK EXAMPLES` section (yellow)
+- [ ] All 12 dispatchers have at least one `📋` categorized section (blue)
+- [ ] All 12 dispatchers have `💡 TIP` section (magenta)
+- [ ] All 12 dispatchers have `📚 See also` cross-references (dim)
+- [ ] All 12 dispatchers use `_C_*` color variables (with fallbacks)
+- [ ] All 12 dispatchers use `echo -e` (not `cat <<EOF`) for ANSI rendering
+- [ ] `obs` help function renamed from `obs_help()` to `_obs_help()`
+- [ ] `teach help` ANSI codes render properly in terminal
+
+### Phase 2: Compliance Checker
+
+- [ ] `lib/help-compliance.zsh` exists with shared validation functions
+- [ ] `_flow_check_help_compliance()` validates a single dispatcher
+- [ ] `_flow_check_all_help_compliance()` validates all dispatchers
+- [ ] 9 compliance rules checked (box, sections, colors, function name, etc.)
+- [ ] `tests/test-help-compliance.zsh` passes for all 12 dispatchers
+- [ ] `flow doctor --help-check` shows pass/fail per dispatcher
+- [ ] Compliance checker integrated into `./tests/run-all.sh`
+
+## Architecture
+
+### Shared Compliance Library
+
+```
+lib/help-compliance.zsh
+  _flow_help_compliance_check()      # Check single dispatcher
+  _flow_help_compliance_check_all()  # Check all dispatchers
+  _flow_help_compliance_rules()      # Return rule definitions
+```
+
+### Compliance Rules
+
+| # | Rule | Check | Pattern |
+|---|---|---|---|
+| 1 | Box header exists | grep for `╭` | `╭─.*─╮` |
+| 2 | Box footer exists | grep for `╰` | `╰─.*─╯` |
+| 3 | MOST COMMON section | grep for emoji+text | `🔥.*MOST COMMON` |
+| 4 | QUICK EXAMPLES section | grep for emoji+text | `💡.*QUICK EXAMPLES` |
+| 5 | Categorized actions | grep for emoji | `📋` |
+| 6 | TIP section | grep for emoji+text | `💡.*TIP` |
+| 7 | See Also section | grep for text | `See also\|📚` |
+| 8 | Color codes present | grep for ANSI | `\033\[` or `_C_` |
+| 9 | Help function naming | function exists | `_<cmd>_help` pattern |
+
+### Integration Points
+
+```
+flow doctor --help-check
+  └── calls _flow_help_compliance_check_all()
+       └── calls _flow_help_compliance_check() per dispatcher
+            └── captures help output, runs 9 rules
+
+tests/test-help-compliance.zsh
+  └── calls _flow_help_compliance_check_all()
+       └── asserts all pass
+```
+
+## Implementation Plan
+
+| Step | Description | Files |
+|---|---|---|
+| 1 | Create `lib/help-compliance.zsh` with 9 rules | `lib/help-compliance.zsh` |
+| 2 | Fix `obs` help (rewrite to standard) | `lib/dispatchers/obs.zsh` |
+| 3 | Fix `prompt` help (rewrite to standard) | `lib/dispatchers/prompt-dispatcher.zsh` |
+| 4 | Fix `dot` help (refactor to standard) | `lib/dispatchers/dot-dispatcher.zsh` |
+| 5 | Fix `cc` help (box style + sections) | `lib/dispatchers/cc-dispatcher.zsh` |
+| 6 | Fix `tm` help (box style + sections) | `lib/dispatchers/tm-dispatcher.zsh` |
+| 7 | Fix `teach` help (rendering + colors) | `lib/dispatchers/teach-dispatcher.zsh` |
+| 8 | Create test suite | `tests/test-help-compliance.zsh` |
+| 9 | Integrate with `flow doctor` | `commands/doctor.zsh` |
+| 10 | Update QUICK-REFERENCE.md version | `docs/help/QUICK-REFERENCE.md` |
+| 11 | Update CONVENTIONS.md if needed | `docs/CONVENTIONS.md` |
+
+## Dependencies
+
+- `lib/core.zsh` - Color variable definitions
+- `commands/doctor.zsh` - Doctor command for integration
+- `tests/run-all.sh` - Test runner for integration
+
+## Open Questions
+
+1. Should the compliance checker also validate `flow help`, `pick help`, and other non-dispatcher help?
+2. Should `FLOW_COLORS[]` be deprecated in favor of `_C_*` everywhere, or should the checker accept both?
+3. Should `teach` keep its enhanced double-line box given its much larger command surface?
+
+## Review Checklist
+
+- [ ] All 12 dispatchers pass compliance check
+- [ ] No existing test regressions
+- [ ] `flow doctor --help-check` works
+- [ ] Help output visually consistent across all dispatchers
+- [ ] QUICK-REFERENCE.md version updated to v6.2.0+
+
+---
+
+**History:**
+- 2026-02-02: Initial spec from manual audit of all 12 dispatchers