feat: teach deploy v2 — direct merge, history, rollback

.STATUS

@@ -1709,6 +1709,6 @@ E) **Quarto Workflow Enhancements** (Additional validators)
 
 **Last Updated:** 2026-02-02
 **Status:** v6.2.0 Released ✅ | Docs deployed ✅ | Website reorganized (14→7 sections) ✅ | 0 build warnings ✅
-## wins: --category fix squashed the bug (2026-02-02), fixed the bug (2026-02-02), --category fix squashed the bug (2026-01-31), fixed the bug (2026-01-31), --category fix squashed the bug (2026-01-31)
+## wins: --category fix squashed the bug (2026-02-03), fixed the bug (2026-02-03), --category fix squashed the bug (2026-02-03), fixed the bug (2026-02-03), --category fix squashed the bug (2026-02-03)
 ## streak: 0
-## last_active: 2026-02-02 17:08
+## last_active: 2026-02-03 22:01

.archive/BRAINSTORM-teach-deploy-v2-2026-02-03.md

@@ -0,0 +1,79 @@
+# teach deploy v2 — Brainstorm
+
+**Generated:** 2026-02-03
+**Context:** flow-cli v6.3.0 (`teach deploy` enhancement)
+**Mode:** deep + feature + save
+**Duration:** ~10 min
+
+## Overview
+
+Port STAT-545's battle-tested deploy patterns into flow-cli's `teach deploy` command, plus add dry-run, history, rollback, and CI mode. Consolidate the two deploy code paths into one.
+
+## Current Pain Points
+
+1. **Slow PR workflow** (45-90s) — STAT-545 has a 8-15s direct merge script
+2. **Generic commit messages** — `"Update: 2026-02-03"` vs smart `content: week-05 lecture, assignment 5`
+3. **No deployment tracking** — No history of what was deployed when
+4. **No rollback** — Manual `git revert` only
+5. **No dry-run** — Can't preview without executing
+6. **Two code paths** — `_teach_deploy()` and `_teach_deploy_enhanced()` with inconsistent behavior
+7. **No CI support** — Prompts block non-interactive use
+8. **No .STATUS integration** — Teaching week / progress not tracked on deploy
+
+## Quick Wins (Phase 0-1)
+
+1. Delete old `_teach_deploy()` dead code (~340 lines removed)
+2. Add `--ci` flag + TTY auto-detection
+3. Extract shared `_deploy_preflight_checks()`
+
+## Medium Effort (Phase 2-4)
+
+4. Smart commit messages from changed file categories
+5. `--direct` flag for direct merge mode (8-15s)
+6. Branch divergence detection + recovery
+7. `--dry-run` preview mode
+
+## Larger Effort (Phase 5-6)
+
+8. Deploy history log (`.flow/deploy-history.yml`)
+9. `--rollback [N]` with interactive picker
+10. `.STATUS` auto-updates (teaching week, progress, deploy count)
+
+## Options Considered
+
+### Option A: Phase It (rejected by user)
+Port STAT-545 first, then add new features.
+**Pros:** Smaller PRs, faster feedback
+**Cons:** More branches, more merge overhead
+
+### Option B: All at Once (selected)
+Single feature branch with everything.
+**Pros:** One implementation pass, coherent design
+**Cons:** Larger PR, more risk
+
+### Option C: Skip Rollback (not selected)
+Defer rollback + history to a future release.
+**Pros:** Simpler scope
+**Cons:** History is needed for rollback, and both are useful independently
+
+## Recommended Path
+
+All 8 features + 1 refactor in a single `feature/teach-deploy-v2` branch. Implementation follows a dependency-ordered 7-phase plan where CI mode comes first (every feature needs it), then smart commits, direct merge, dry-run, history+rollback, .STATUS updates, and finally help/docs.
+
+## Key Design Decisions
+
+1. **`--direct` replaces `--direct-push`** — shorter name, `--direct-push` kept as alias
+2. **deploy-history.yml uses append-only writes** — no yq rewrite of entire file
+3. **Rollback uses `git revert`** — forward rollback, not destructive reset
+4. **CI mode auto-detects from TTY** — plus explicit `--ci` flag override
+5. **Smart commit messages are overridable** — `--message "text"` takes precedence
+6. **.STATUS updates are non-destructive** — skip if file doesn't exist
+
+## Next Steps
+
+1. [ ] Create worktree: `feature/teach-deploy-v2`
+2. [ ] Implement Phase 0: Consolidation
+3. [ ] Implement Phase 1-6 sequentially
+4. [ ] Run full test suite
+5. [ ] Update help + CLAUDE.md
+6. [ ] PR to dev

CLAUDE.md

@@ -8,8 +8,8 @@ This file provides guidance to Claude Code when working with code in this reposi
 
 - **Architecture:** Pure ZSH plugin (no Node.js runtime required)
 - **Dependencies:** **ZERO** - No dependencies on Oh-My-Zsh, antidote, or any framework
-- **Current Version:** v6.3.0
-- **Latest Release:** v6.3.0 (2026-02-03)
+- **Current Version:** v6.4.0
+- **Latest Release:** v6.4.0 (2026-02-03)
 - **Install:** Homebrew (recommended), or any plugin manager (antidote, zinit, oh-my-zsh, manual)
 - **Optional:** Atlas integration for enhanced state management
 - **Health Check:** `flow doctor` for dependency verification
@@ -427,7 +427,9 @@ flow-cli/
 │   ├── inventory.zsh         # Tool inventory generator
 │   ├── keychain-helpers.zsh  # macOS Keychain secrets
 │   ├── config-validator.zsh  # Config validation
-│   ├── git-helpers.zsh       # Git integration utilities
+│   ├── git-helpers.zsh       # Git integration + smart commits
+│   ├── deploy-history-helpers.zsh  # Deploy history (append-only YAML)
+│   ├── deploy-rollback-helpers.zsh # Forward rollback (git revert)
 │   └── dispatchers/          # Smart command dispatchers (12)
 │       ├── cc-dispatcher.zsh     # Claude Code
 │       ├── dot-dispatcher.zsh    # Dotfiles + Secrets
@@ -453,11 +455,14 @@ flow-cli/
 ├── completions/             # ZSH completions
 ├── hooks/                   # ZSH hooks
 ├── docs/                    # Documentation (MkDocs)
-├── tests/                   # Test suite (462 tests)
+├── tests/                   # Test suite (543+ tests)
 │   ├── fixtures/            # Test fixtures
 │   │   └── demo-course/     # STAT-101 demo course for E2E
-│   ├── e2e-teach-analyze.zsh           # E2E: 29 tests
-│   └── interactive-dog-teaching.zsh    # Interactive: 10 tasks
+│   ├── test-teach-deploy-v2-unit.zsh        # Deploy v2 unit: 36 tests
+│   ├── test-teach-deploy-v2-integration.zsh # Deploy v2 integration: 22 tests
+│   ├── e2e-teach-deploy-v2.zsh              # Deploy v2 E2E: 23 tests
+│   ├── e2e-teach-analyze.zsh                # E2E: 29 tests
+│   └── interactive-dog-teaching.zsh         # Interactive: 10 tasks
 └── .archive/               # Archived Node.js CLI
 ```
 
@@ -472,7 +477,9 @@ flow-cli/
 | `lib/atlas-bridge.zsh`                      | Atlas integration        | Optional state engine    |
 | `lib/keychain-helpers.zsh`                  | macOS Keychain secrets   | Touch ID support         |
 | `lib/config-validator.zsh`                  | Config validation        | Schema + hash validation |
-| `lib/git-helpers.zsh`                       | Git integration          | Teaching workflow        |
+| `lib/git-helpers.zsh`                       | Git integration          | Smart commits, teaching  |
+| `lib/deploy-history-helpers.zsh`            | Deploy history           | Append-only YAML         |
+| `lib/deploy-rollback-helpers.zsh`           | Deploy rollback          | Forward rollback         |
 | `lib/dispatchers/*.zsh`                     | Smart dispatchers        | 12 active dispatchers    |
 | `commands/*.zsh`                            | Core commands            | work, dash, finish, etc. |
 | `docs/reference/MASTER-DISPATCHER-GUIDE.md` | Complete dispatcher docs | All 12 dispatchers       |
@@ -595,7 +602,7 @@ teach exam "Topic"  # Generate exam via Scholar
 
 ### Test Suite Overview
 
-**Status:** ✅ 462 tests total
+**Status:** ✅ 543+ tests total
 **Documentation:** [Complete Testing Guide](docs/guides/TESTING.md)
 
 ```bash
@@ -611,6 +618,11 @@ tests/test-teach-plan.zsh           # Unit: 32 tests
 tests/test-teach-plan-security.zsh  # Security: 24 tests (YAML injection, edge cases)
 tests/e2e-teach-plan.zsh            # E2E: 15 tests (CRUD workflows)
 
+# Teach deploy v2 tests (v6.4.0)
+tests/test-teach-deploy-v2-unit.zsh        # Unit: 34 tests
+tests/test-teach-deploy-v2-integration.zsh # Integration: 22 tests
+tests/e2e-teach-deploy-v2.zsh             # E2E: 20 tests
+
 # E2E tests (teach analyze)
 tests/e2e-teach-analyze.zsh         # E2E: 29 tests (8 sections)
 
@@ -707,29 +719,96 @@ export FLOW_DEBUG=1
 
 ## Current Status
 
-**Version:** v6.3.0
-**Latest Release:** v6.3.0 (2026-02-03)
+**Version:** v6.4.0
+**Latest Release:** v6.4.0 (2026-02-03)
 **Status:** Production
 **Branch:** `dev`
-**Release (latest):** https://github.com/Data-Wise/flow-cli/releases/tag/v6.3.0
+**Release (latest):** https://github.com/Data-Wise/flow-cli/releases/tag/v6.4.0
 **Performance:** Sub-10ms for core commands, 3-10x speedup from optimization
 **Documentation:** https://Data-Wise.github.io/flow-cli/
-**Tests:** 107 tests (62 unit + 33 E2E + 12 interactive) for teach prompt + 34 teach style dogfood tests + 462 total tests
+**Tests:** 543+ total tests (462 existing + 81 new teach deploy v2 tests)
 
 **Recent Improvements:**
 
-- ✅ Website reorganization - 14 sections reduced to 7 (ADHD-friendly)
-- ✅ 11 new teaching docs - REFCARDs, guides, tutorials, schema reference
-- ✅ teach help system - 100% standards compliance
-- ✅ MkDocs tags plugin - 14 topic tags across ~39 pages
-- ✅ Section landing pages - Grid card navigation for all 4 main sections
-- ✅ Build warnings eliminated - 28 → 0 (broken links to excluded files)
-- ✅ Grid card emoji rendering - `pymdownx.emoji` + `attr_list` spacing fix
+- ✅ teach deploy v2 - Direct merge (8-15s), smart commits, history, rollback, dry-run, CI mode
+- ✅ Deploy history tracking - Append-only `.flow/deploy-history.yml`
+- ✅ Forward rollback - `teach deploy --rollback` via git revert
+- ✅ Legacy dead code removed - ~400 lines of old `_teach_deploy()` + `_teach_deploy_help()`
+- ✅ 76 new tests - 34 unit + 22 integration + 20 E2E
 
 ---
 
 ## Recent Releases
 
+### v6.4.0 - Teach Deploy v2: Direct Merge, History, Rollback (2026-02-03)
+
+**Released:** 2026-02-03
+**Branch:** `feature/teach-deploy-v2`
+**Changes:** 8 features, 1 refactor, 76 new tests
+
+**Major Features:**
+
+- **Direct Merge Mode** (`--direct/-d`) — 8-15s deploys vs 45-90s PR workflow
+  - `_deploy_direct_merge()` — merge draft→production, push, no PR
+  - `--direct-push` kept as backward-compatible alias
+  - Smart commit messages auto-generated from changed file categories
+
+- **Smart Commit Messages** — Auto-categorized from file paths
+  - `_generate_smart_commit_message()` in `lib/git-helpers.zsh`
+  - Categories: content (lectures, assignments), config (_quarto.yml), style (CSS), data, deploy
+  - Overridable with `--message "text"`
+
+- **Deploy History Tracking** — Append-only `.flow/deploy-history.yml`
+  - `lib/deploy-history-helpers.zsh` — 4 functions (append, list, get, count)
+  - `cat >>` for writes (fast), `yq` for reads only
+  - Records: mode, commit hash, branch, file count, message, duration
+  - `teach deploy --history [N]` — show last N deploys
+
+- **Forward Rollback** (`--rollback [N]`) — Revert via `git revert`
+  - `lib/deploy-rollback-helpers.zsh` — 2 functions (rollback, perform_rollback)
+  - Interactive picker or explicit index
+  - Records rollback in history with mode "rollback"
+  - CI mode requires explicit index (no interactive picker)
+
+- **Dry-Run Preview** (`--dry-run`/`--preview`) — Preview without mutation
+  - `_deploy_dry_run_report()` — shows files, commit message, merge direction
+  - Works with both direct merge and PR mode
+
+- **CI Mode** (`--ci`) — Non-interactive deployment
+  - Auto-detect from TTY (`[[ ! -t 0 ]]`)
+  - 18 CI guards on all `read -r` prompts
+  - Explicit `--ci` flag override
+
+- **Shared Preflight** — Extracted `_deploy_preflight_checks()`
+  - Git repo check, config validation, branch detection
+  - Sets `DEPLOY_*` exported variables for all deploy modes
+  - `[ok]`/`[!!]` marker format
+
+- **.STATUS Auto-Updates** — `_deploy_update_status_file()`
+  - Updates `last_deploy`, `deploy_count`, `teaching_week`
+  - Teaching week calculated from `semester_info.start_date`
+  - Non-destructive: skips if `.STATUS` absent
+
+**Refactoring:**
+
+- Deleted legacy `_teach_deploy()` (~313 lines) from `teach-dispatcher.zsh`
+- Deleted legacy `_teach_deploy_help()` (~85 lines) from `teach-dispatcher.zsh`
+- All deploy routing uses `_teach_deploy_enhanced()` exclusively
+
+**New Files:**
+
+- `lib/deploy-history-helpers.zsh` (185 lines)
+- `lib/deploy-rollback-helpers.zsh` (214 lines)
+- `tests/test-teach-deploy-v2-unit.zsh` (34 tests)
+- `tests/test-teach-deploy-v2-integration.zsh` (22 tests)
+- `tests/e2e-teach-deploy-v2.zsh` (20 tests)
+
+**Testing:** 76 new tests (34 unit + 22 integration + 20 E2E), all passing
+
+**Stats:** 9 files changed, +2,687 / -581 lines
+
+---
+
 ### v6.3.0 - Teaching Style Consolidation + Help Compliance (2026-02-03)
 
 **Released:** 2026-02-03
@@ -1088,5 +1167,5 @@ git push origin main && git push origin v6.2.0
 
 ---
 
-**Last Updated:** 2026-02-03 (v6.3.0)
-**Status:** Production Ready (v6.3.0)
+**Last Updated:** 2026-02-03 (v6.4.0)
+**Status:** Production Ready (v6.4.0)

README.md

@@ -1,6 +1,6 @@
 # flow-cli
 
-[![Version](https://img.shields.io/badge/version-6.2.0-blue.svg)](https://github.com/Data-Wise/flow-cli/releases/tag/v6.2.0)
+[![Version](https://img.shields.io/badge/version-6.4.0-blue.svg)](https://github.com/Data-Wise/flow-cli/releases/tag/v6.4.0)
 [![Tests](https://github.com/Data-Wise/flow-cli/actions/workflows/test.yml/badge.svg)](https://github.com/Data-Wise/flow-cli/actions)
 [![Docs](https://img.shields.io/badge/docs-online-brightgreen.svg)](https://data-wise.github.io/flow-cli/)
 

docs/CHANGELOG.md

@@ -6,6 +6,55 @@ The format follows [Keep a Changelog](https://keepachangelog.com/), and this pro
 
 ---
 
+## [6.4.0] - 2026-02-03
+
+### Added
+
+- **Teach Deploy v2** (`teach deploy --direct`) - Direct merge deployment with 8-15s cycle time
+  - `--direct` / `-d` - Direct merge deploy (draft → main, push)
+  - `--dry-run` / `--dry` - Preview deploy without side effects
+  - `--rollback [N]` / `--rb [N]` - Forward rollback via `git revert` (N=display index)
+  - `--history` / `--hist` - View deploy history table
+  - `--ci` - Non-interactive CI mode (auto-detected when no TTY)
+  - `-m "message"` - Custom commit message
+  - Smart commit messages - auto-categorize by file type (content, config, infra, deploy)
+  - `.STATUS` auto-update - Sets `last_deploy`, `deploy_count`, `teaching_week`
+
+- **Deploy History Tracking** (`.flow/deploy-history.yml`) - Append-only YAML history
+  - Records timestamp, mode, commit hashes, branch, file count, user, duration
+  - `yq`-based reading for list/get/count operations
+  - YAML injection prevention via single-quote escaping
+
+- **Deploy Rollback** - Forward rollback via `git revert`
+  - Interactive picker or explicit index (`--rollback 1`)
+  - Merge commit detection with `-m 1` parent specification
+  - Rollback recorded in history with `mode: "rollback"`
+  - CI mode requires explicit index (no interactive picker)
+
+### Fixed
+
+- Merge commit rollback now detects parent count and uses `git revert -m 1`
+- `commit_before` captures target branch HEAD (not current branch)
+- Dirty worktree guard prevents deploy with uncommitted changes
+- Stderr capture pattern prevents silent failures (replaced `2>/dev/null` with `$(cmd 2>&1)`)
+- Dead dry-run code path fixed (was unreachable due to wrong condition)
+- `_deploy_cleanup_globals` prevents variable leakage between calls
+
+### Documentation
+
+- `docs/guides/TEACH-DEPLOY-GUIDE.md` (1,092 lines) - Complete user guide
+- `docs/reference/REFCARD-DEPLOY-V2.md` (216 lines) - Quick reference card
+- `docs/tutorials/31-teach-deploy-v2.md` (336 lines) - Step-by-step tutorial
+- `docs/reference/MASTER-API-REFERENCE.md` - 14 new function entries
+
+### Tests
+
+- 81 new tests: 36 unit + 22 integration + 23 E2E
+- 51-test dogfooding suite against demo-course fixture
+- Merge commit rollback regression tests (diverged branches, parent detection)
+
+---
+
 ## [5.20.0] - 2026-01-28
 
 ### Added