diff --git a/.STATUS b/.STATUS index d7dd42e7a..ea9ffecc2 100644 --- a/.STATUS +++ b/.STATUS @@ -9,7 +9,15 @@ ## Priority: 2 ## Progress: 100 -## Current Session (2026-06-13) — agenda / forward-looking schedule layer: brainstorm → spec → worktree [dev] +## Current Session (2026-06-13) — v7.10.0 SHIPPED + CI full-suite gate COMPLETE (Phase 1–3; main gated) [dev] + +**Session activity:** +- **Agenda feature → v7.10.0 SHIPPED:** reviewed + hardened the schedule layer (adversarial A–F fixes, `e2e-agenda`/`dogfood-agenda` pair, shared-pipeline refactor `_schedule_window_records`/`_schedule_render_capped`); fixed a pre-existing `dash` non-TTY abort (`$(( cond ? 's' : '' ))` ×3). PR #463→dev → release PR #464→main (`477b5c59`) → GitHub release v7.10.0 → Homebrew tap auto-updated → docs deployed. Plus ~50-doc version sweep + CHANGELOG ×2 + index What's-New + `agenda` in index Core Commands (`955b1fe3`). +- **Cleanup:** agenda worktree + branch removed (local+remote). **3 squash-merged branches** (`manpage-refresh`/`tok-autosync`/`scholar-fix`) await manual `git branch -D` — hook blocks force-delete (route to user). +- **CI full-suite gate (Next Action #3) — MERGED (PR #465 → dev `b57c0d87`):** spec → worktree → **Phase 1** measured ground truth (**51/14/0**; spec prediction *inverted* — the Ubuntu runner LACKS `atlas`/`ait`/`himalaya`/`R`/`quarto`, so 14 tool-dependent suites failed, ONE uniform class) → **Phase 2** made it green: clean-skip via **rc 77** (automake SKIP, taught to `run-all.sh`), `skip_without_warm_atlas`, pinned `FLOW_ATLAS_ENABLED=no` for atlas-skew — **plus 4 real cross-platform bugs the gate caught**: `exec {var}>` flock fd (zsh ≥10), GNU-first `stat -c %Y` (BSD-first *corrupts* on Linux), `date -d` fallback, em-cache mtime helper. Reviewed (approve) → nits applied (`typeset -g` fd, em-cache null-delim). `full-suite` job runs in CI **non-blocking**; suite now **64 pass / 0 fail / 1 skip** on the runner AND locally. Worktree + branch removed. + - **Phase 3 — DONE:** soaked green on dev (4 consecutive runs), then PR #466 flipped `full-suite` to **blocking** (dropped `continue-on-error`, renamed job → `Full Test Suite`) → merged to dev (`020de969`). **`main` branch protection now requires `ZSH Plugin Tests` + `Full Test Suite`** (PR-required/no-force/no-delete preserved; `enforce_admins:false` keeps `--admin` bypass; `strict:false`). **`dev` left unprotected by design** — forcing PR-required there would break the direct-commit docs/spec workflow; the now-blocking job shows red on dev PRs as a soft signal. ci-gate-required worktree + branch (local+remote) cleaned. Gate is LIVE: a red full suite now blocks merge to main. + +## Previous Session (2026-06-13) — agenda / forward-looking schedule layer: brainstorm → spec → worktree [dev] **Session activity:** - **Brainstormed** (`/workflow:brainstorm -d -s`) extending `dash` + cadence commands (`morning`/`today`/`week`) to surface forward-looking RESEARCH + TEACHING activity (deadlines, lectures, exams, manuscript/grant milestones, recurring blocks) — today everything is present/backward-looking. @@ -344,7 +352,7 @@ | Worktree | Branch | Status | |----------|--------|--------| -| Main repo | `dev` | agenda / schedule layer merged (#463, e0b18e5f) + v7.10.0 bump + doc sweep; agenda worktree removed. Release dev→main pending. | +| Main repo | `dev` | v7.10.0 SHIPPED + CI full-suite gate MERGED (PR #465 → dev `b57c0d87`); both worktrees removed; no active worktrees. **Pending:** 3 squash-merged branches (manpage-refresh/tok-autosync/scholar-fix) await manual `git branch -D`; CI-gate **Phase 3** (promote `full-suite` to required check after dev soak). | --- @@ -379,7 +387,7 @@ --- **Last Updated:** 2026-06-13 -**Status:** v7.10.0 on dev (release dev→main pending) | 64/64 tests passing (1 expected interactive/tmux timeout) | 14 dispatchers + at bridge | 213 test files | 12000+ test functions | 0 lint errors | 0 broken links -## wins: Fixed the regression bug (2026-06-13), Fixed the regression bug (2026-06-13), Fixed the regression bug (2026-06-13), Fixed the regression bug (2026-06-05), --category fix squashed the bug (2026-06-05) +**Status:** v7.10.0 SHIPPED (main + Homebrew tap) | full suite in CI (PR #465) — 64 passed / 0 failed / 1 skipped (tool-absent rc 77) | 14 dispatchers + at bridge | 213 test files | 12000+ test functions | 0 lint errors | 0 broken links +## wins: Fixed the regression bug (2026-06-13), Fixed the regression bug (2026-06-13), Fixed the regression bug (2026-06-13), Fixed the regression bug (2026-06-13), Fixed the regression bug (2026-06-05) ## streak: 1 -## last_active: 2026-06-13 16:01 +## last_active: 2026-06-13 18:23 diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml index 8c2e7982f..867b67145 100644 --- a/.github/workflows/test.yml +++ b/.github/workflows/test.yml @@ -61,3 +61,84 @@ jobs: echo "| Metric | Value |" >> $GITHUB_STEP_SUMMARY echo "|--------|-------|" >> $GITHUB_STEP_SUMMARY echo "| Duration | ${DURATION}s |" >> $GITHUB_STEP_SUMMARY + + # --------------------------------------------------------------------------- + # ci-full-suite-gate (Phase 3): the full 65-suite run-all.sh is now a BLOCKING + # gate. Service/tool-absent suites clean-skip via rc 77, so a non-zero exit + # means a real failure. Promoted to a required status check on dev (then main + # after a soak). The check name below ("Full Test Suite") must match the + # required-check name configured in branch protection. + # --------------------------------------------------------------------------- + full-suite: + name: Full Test Suite + runs-on: ubuntu-latest + + steps: + - name: Checkout code + uses: actions/checkout@v6 + + - name: Ensure zsh is installed + run: | + if ! command -v zsh >/dev/null 2>&1; then + sudo apt-get update && sudo apt-get install -y zsh + fi + + - name: Configure git identity + run: | + # Fresh runners have no git identity; suites that exercise the deploy + # workflow (teach-deploy) run `git commit` and fail with "empty ident" + # without it. This is CI environment provisioning, not a test change. + git config --global user.email "ci@flow-cli.test" + git config --global user.name "flow-cli CI" + git config --global init.defaultBranch main + + - name: Record start time + id: start + run: echo "time=$(date +%s)" >> $GITHUB_OUTPUT + + - name: Create mock project structure + run: | + mkdir -p ~/projects/dev-tools/flow-cli/.git + mkdir -p ~/projects/r-packages/active/mediationverse/.git + mkdir -p ~/projects/r-packages/stable/rmediation/.git + mkdir -p ~/projects/teaching/stat-440/.git + mkdir -p ~/projects/research/mediation-planning/.git + mkdir -p ~/projects/quarto/manuscripts/paper1/.git + mkdir -p ~/projects/apps/examify/.git + cp -r . ~/projects/dev-tools/flow-cli/ + + - name: Run full suite + id: fullsuite + run: | + cd ~/projects/dev-tools/flow-cli + set +e + # Capture run-all.sh output; tee returns 0, so grab run-all's real + # exit via PIPESTATUS (1=FAIL, 2=TIMEOUT, 0=clean) and re-exit with it + # so the job (a required check) fails the PR on a real failure. + ./tests/run-all.sh 2>&1 | tee /tmp/full-suite.log + rc=${PIPESTATUS[0]} + echo "rc=$rc" >> "$GITHUB_OUTPUT" + echo "Full suite exit code: $rc" + exit "$rc" + + - name: Full Suite Summary + if: always() + run: | + END_TIME=$(date +%s) + DURATION=$((END_TIME - ${{ steps.start.outputs.time }})) + { + echo "## 🧪 Full Suite (run-all.sh) — required gate" + echo "" + echo "| Metric | Value |" + echo "|--------|-------|" + echo "| Duration | ${DURATION}s |" + echo "| Exit code | \`${{ steps.fullsuite.outputs.rc }}\` (0=clean, 1=FAIL, 2=TIMEOUT) |" + echo "" + echo "
Full run-all.sh output" + echo "" + echo '```' + cat /tmp/full-suite.log 2>/dev/null || echo "(no log captured)" + echo '```' + echo "" + echo "
" + } >> "$GITHUB_STEP_SUMMARY" diff --git a/CHANGELOG.md b/CHANGELOG.md index 065814fbc..61b66ad9d 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -9,6 +9,40 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +## [7.10.1] — 2026-06-13 — Linux portability fixes + full-suite CI gate + +### Fixed + +- **Cache locking errored on Linux** (`lib/doctor-cache.zsh`, + `lib/analysis-cache.zsh`): the `flock` path used bash-only high-fd + redirection (`exec 201>`/`exec 200>`), which zsh parses as a command and + fails with "command not found" on Linux (where `flock` exists). Switched to + zsh's dynamic `exec {var}>` allocation. macOS was unaffected (no `flock` → + mkdir fallback), so this only ever broke on Linux/CI. +- **Email cache never worked on Linux** (`lib/em-cache.zsh`): used macOS-only + `stat -f %m`, so every entry's mtime read as 0 and looked expired. Added a + portable `_em_cache_mtime` (GNU `stat -c %Y` first — it fails cleanly on + macOS — then BSD `stat -f %m`). +- **`teaching_week` computed 0 on Linux** (`lib/teaching-utils.zsh`, + `lib/dispatchers/teach-deploy-enhanced.zsh`): used macOS-only `date -j -f`. + Added portable date helpers (BSD then GNU `date -d`). +- **`flow doctor --help-check` false-flagged `tm`** on machines without aiterm + (`lib/help-compliance.zsh`): the `tm` dispatcher only loads its help when the + `ait` CLI is present, so it's now checked only when `ait` is installed. + +### Changed + +- **CI now runs the full test suite on every PR.** Added a `full-suite` job to + `.github/workflows/test.yml` running `./tests/run-all.sh` (the full 65-suite + suite), parallel to the fast smoke job. It started non-blocking + (`continue-on-error`); after soaking green on `dev` it is now a **required + check on `main`** — a red suite blocks release to production. +- **`run-all.sh` skip semantics:** exit code **77** now counts a suite as + _skipped_ (not failed) — used by suites that require an external tool/service + (`atlas`, `ait`, `himalaya`, R, quarto, `claude`) absent on a hosted runner. + Service-dependent suites skip/degrade cleanly; standalone-behavior suites pin + `FLOW_ATLAS_ENABLED=no` so results are identical with or without atlas. + ## [7.10.0] — 2026-06-13 — forward-looking schedule layer (`agenda` + dash UPCOMING) ### Added diff --git a/CLAUDE.md b/CLAUDE.md index c775e6054..a9a0f58cd 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -7,7 +7,7 @@ This file provides guidance to Claude Code when working with code in this reposi **flow-cli** - Pure ZSH plugin for ADHD-optimized workflow management. Zero dependencies. Standalone (works without Oh-My-Zsh or any plugin manager). - **Architecture:** Pure ZSH plugin (no Node.js runtime required) -- **Current Version:** v7.10.0 +- **Current Version:** v7.10.1 - **Install:** Homebrew (recommended), or any plugin manager - **Source:** `source /opt/homebrew/opt/flow-cli/flow.plugin.zsh` (via Homebrew) - **Optional:** Atlas integration for enhanced state management @@ -136,7 +136,7 @@ flow-cli/ ├── docs/ # Documentation (MkDocs) │ └── internal/ # Internal conventions & contributor templates ├── scripts/ # Standalone validators (check-math.zsh) -├── tests/ # 213 test files, 12000+ test functions +├── tests/ # 216 test files, 12000+ test functions │ └── fixtures/demo-course/ # STAT-101 demo course for E2E └── .archive/ # Archived Node.js CLI ``` @@ -181,7 +181,7 @@ flow-cli/ ## Testing -**213 test files, 12000+ test functions.** Run: `./tests/run-all.sh` (64/64 passing, 1 expected interactive/tmux timeout) or individual suites in `tests/`. +**216 test files, 12000+ test functions.** Run: `./tests/run-all.sh` (64/64 passing, 1 expected interactive/tmux timeout) or individual suites in `tests/`. See `docs/guides/TESTING.md` for patterns, mocks, assertions, TDD workflow. @@ -215,8 +215,8 @@ export FLOW_FORCE_DISPATCHER_OBS=1 # Force-keep one dispatcher (FLOW_F ## Current Status -**Version:** v7.10.0 | **Tests:** 12000+ (64/64 suite, 1 interactive timeout) | **Docs:** https://Data-Wise.github.io/flow-cli/ +**Version:** v7.10.1 | **Tests:** 12000+ (64/64 suite, 1 interactive timeout) | **Docs:** https://Data-Wise.github.io/flow-cli/ --- -**Last Updated:** 2026-06-13 (v7.10.0) +**Last Updated:** 2026-06-13 (v7.10.1) diff --git a/README.md b/README.md index 98cfaef6d..246ea2cf0 100644 --- a/README.md +++ b/README.md @@ -35,18 +35,17 @@ or any other framework. Choose any installation method that works for you. ## What's New -### v7.4.0: 31 Email Commands +### v7.10.0 → v7.10.1: Forward-Looking Schedule Layer + Reliability -- **Organize:** `em star`, `em thread`, `em snooze`, `em digest` — manage your inbox without leaving the terminal -- **Manage:** `em delete`, `em move`, `em restore`, `em flag`, `em todo`, `em event` — full email lifecycle with `--pick` multi-select -- **AI:** Switch backends with `em ai gemini`, capture tasks with `em catch 42` -- **10 Tutorials** — step-by-step guides for every em subcommand +- **`agenda`** — what's due across all projects: deadlines, lectures, exams, milestones, and recurring weekly blocks, bucketed into OVERDUE / TODAY / THIS WEEK / LATER (`agt`/`agw`/`agm`) +- **`dash` UPCOMING** + dated enrichment of `morning` / `today` / `week` — one shared engine, works fully **without `yq` and without atlas** +- **Data sources:** a `## Schedule:` block in each project's `.STATUS`, plus teaching dates from `.flow/teach-config.yml` +- **v7.10.1 reliability:** Linux-portability fixes (caches, email cache, teaching-date math) + the full test suite is now a required CI gate ```bash -em star 42 # Star a message -em move 42 Archive # Move to folder -em todo 42 # Create reminder from email -em pick # Interactive multi-select +agenda # what's due soon +agenda --overdue # only overdue items +agenda research # filter by category ``` [Full Changelog](docs/CHANGELOG.md) | [All Releases](https://github.com/Data-Wise/flow-cli/releases) diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md index 44422dacb..2d9cf1e83 100644 --- a/docs/CHANGELOG.md +++ b/docs/CHANGELOG.md @@ -8,6 +8,40 @@ The format follows [Keep a Changelog](https://keepachangelog.com/), and this pro ## [Unreleased] +## [7.10.1] — 2026-06-13 — Linux portability fixes + full-suite CI gate + +### Fixed + +- **Cache locking errored on Linux** (`lib/doctor-cache.zsh`, + `lib/analysis-cache.zsh`): the `flock` path used bash-only high-fd + redirection (`exec 201>`/`exec 200>`), which zsh parses as a command and + fails with "command not found" on Linux (where `flock` exists). Switched to + zsh's dynamic `exec {var}>` allocation. macOS was unaffected (no `flock` → + mkdir fallback), so this only ever broke on Linux/CI. +- **Email cache never worked on Linux** (`lib/em-cache.zsh`): used macOS-only + `stat -f %m`, so every entry's mtime read as 0 and looked expired. Added a + portable `_em_cache_mtime` (GNU `stat -c %Y` first — it fails cleanly on + macOS — then BSD `stat -f %m`). +- **`teaching_week` computed 0 on Linux** (`lib/teaching-utils.zsh`, + `lib/dispatchers/teach-deploy-enhanced.zsh`): used macOS-only `date -j -f`. + Added portable date helpers (BSD then GNU `date -d`). +- **`flow doctor --help-check` false-flagged `tm`** on machines without aiterm + (`lib/help-compliance.zsh`): the `tm` dispatcher only loads its help when the + `ait` CLI is present, so it's now checked only when `ait` is installed. + +### Changed + +- **CI now runs the full test suite on every PR.** Added a `full-suite` job to + `.github/workflows/test.yml` running `./tests/run-all.sh` (the full 65-suite + suite), parallel to the fast smoke job. It started non-blocking + (`continue-on-error`); after soaking green on `dev` it is now a **required + check on `main`** — a red suite blocks release to production. +- **`run-all.sh` skip semantics:** exit code **77** now counts a suite as + *skipped* (not failed) — used by suites that require an external tool/service + (`atlas`, `ait`, `himalaya`, R, quarto, `claude`) absent on a hosted runner. + Service-dependent suites skip/degrade cleanly; standalone-behavior suites pin + `FLOW_ATLAS_ENABLED=no` so results are identical with or without atlas. + ## [7.10.0] — 2026-06-13 — forward-looking schedule layer (`agenda` + dash UPCOMING) ### Added diff --git a/docs/architecture/SCHOLAR-ENHANCEMENT-ARCHITECTURE.md b/docs/architecture/SCHOLAR-ENHANCEMENT-ARCHITECTURE.md index 2bf294d1c..27fb5145d 100644 --- a/docs/architecture/SCHOLAR-ENHANCEMENT-ARCHITECTURE.md +++ b/docs/architecture/SCHOLAR-ENHANCEMENT-ARCHITECTURE.md @@ -1,7 +1,7 @@ # Scholar Enhancement Architecture **Feature:** Teaching Content Generation System -**Version:** v7.10.0 +**Version:** v7.10.1 **Date:** 2026-01-17 --- @@ -747,4 +747,4 @@ teach slides -w 8 --style computational **Last Updated:** 2026-02-27 **Status:** Production Ready -**Version:** v7.10.0 +**Version:** v7.10.1 diff --git a/docs/architecture/TEACHING-DATES-ARCHITECTURE.md b/docs/architecture/TEACHING-DATES-ARCHITECTURE.md index 7754eb15a..19992fba6 100644 --- a/docs/architecture/TEACHING-DATES-ARCHITECTURE.md +++ b/docs/architecture/TEACHING-DATES-ARCHITECTURE.md @@ -1,6 +1,6 @@ # Teaching Dates Architecture -**Version:** v7.10.0 +**Version:** v7.10.1 **Status:** Complete **Last Updated:** 2026-02-27 @@ -966,5 +966,5 @@ teach dates import-calendar university-calendar.ics --- **Last Updated:** 2026-02-27 -**Version:** v7.10.0 +**Version:** v7.10.1 **Status:** Complete diff --git a/docs/diagrams/TEACHING-V3-WORKFLOWS.md b/docs/diagrams/TEACHING-V3-WORKFLOWS.md index 345799e70..0d9b8aace 100644 --- a/docs/diagrams/TEACHING-V3-WORKFLOWS.md +++ b/docs/diagrams/TEACHING-V3-WORKFLOWS.md @@ -470,7 +470,7 @@ flowchart TD --- **Generated:** 2026-02-09 -**Version:** v7.10.0 (Teaching Workflow v3.0) +**Version:** v7.10.1 (Teaching Workflow v3.0) **Total Diagrams:** 8 These diagrams provide comprehensive visual documentation for all major Teaching Workflow features. diff --git a/docs/guides/ATLAS-INTEGRATION-GUIDE.md b/docs/guides/ATLAS-INTEGRATION-GUIDE.md index 847524cac..a697a2e53 100644 --- a/docs/guides/ATLAS-INTEGRATION-GUIDE.md +++ b/docs/guides/ATLAS-INTEGRATION-GUIDE.md @@ -335,4 +335,4 @@ export FLOW_ATLAS_ENABLED=no --- **Last Updated:** 2026-02-22 -**Version:** v7.10.0 +**Version:** v7.10.1 diff --git a/docs/guides/BACKUP-SYSTEM-GUIDE.md b/docs/guides/BACKUP-SYSTEM-GUIDE.md index 4989b924e..6a8f7d906 100644 --- a/docs/guides/BACKUP-SYSTEM-GUIDE.md +++ b/docs/guides/BACKUP-SYSTEM-GUIDE.md @@ -1,6 +1,6 @@ # Backup System Guide -**Version:** v7.10.0 +**Version:** v7.10.1 **Last Updated:** 2026-01-21 --- @@ -959,5 +959,5 @@ See `lib/backup-helpers.zsh` for implementation details. --- -**Version:** v7.10.0 +**Version:** v7.10.1 **Last Updated:** 2026-01-21 diff --git a/docs/guides/CONFIG-MANAGEMENT-WORKFLOW.md b/docs/guides/CONFIG-MANAGEMENT-WORKFLOW.md index a166e6275..cc05a1207 100644 --- a/docs/guides/CONFIG-MANAGEMENT-WORKFLOW.md +++ b/docs/guides/CONFIG-MANAGEMENT-WORKFLOW.md @@ -730,5 +730,5 @@ flow config profile load adhd --- **Last Updated:** 2026-02-27 -**Version:** v7.10.0 +**Version:** v7.10.1 **Related:** [flow.md](../commands/flow.md), [plugin guide](./PLUGIN-MANAGEMENT-WORKFLOW.md) diff --git a/docs/guides/COURSE-PLANNING-BEST-PRACTICES.md b/docs/guides/COURSE-PLANNING-BEST-PRACTICES.md index edb213e2e..04b029699 100644 --- a/docs/guides/COURSE-PLANNING-BEST-PRACTICES.md +++ b/docs/guides/COURSE-PLANNING-BEST-PRACTICES.md @@ -1,6 +1,6 @@ # Course Planning Best Practices: A Research-Based Guide -**Version:** v7.10.0 +**Version:** v7.10.1 **Last Updated:** 2026-01-19 **Target Audience:** Instructors using flow-cli for systematic course design **Status:** Phase 1 Complete (Sections 1-2) @@ -2498,7 +2498,7 @@ teach analytics --outcomes # Outcome achievement analysis # Document Metadata -**Version:** v7.10.0 +**Version:** v7.10.1 **Created:** 2026-01-19 **Last Updated:** 2026-01-19 **Authors:** flow-cli development team diff --git a/docs/guides/DEVELOPER-GUIDE.md b/docs/guides/DEVELOPER-GUIDE.md index cd15ca546..d2c39ac7a 100644 --- a/docs/guides/DEVELOPER-GUIDE.md +++ b/docs/guides/DEVELOPER-GUIDE.md @@ -1,6 +1,6 @@ # flow-cli Developer Guide -**Version:** v7.10.0 +**Version:** v7.10.1 **Last Updated:** 2026-02-27 **Audience:** Contributors, Plugin Developers, Advanced Users @@ -961,4 +961,4 @@ test: add regression test for worktree detection --- **Last Updated:** 2026-02-27 -**Version:** v7.10.0 +**Version:** v7.10.1 diff --git a/docs/guides/DOCTOR-TOKEN-USER-GUIDE.md b/docs/guides/DOCTOR-TOKEN-USER-GUIDE.md index a45e4286b..926bce1ff 100644 --- a/docs/guides/DOCTOR-TOKEN-USER-GUIDE.md +++ b/docs/guides/DOCTOR-TOKEN-USER-GUIDE.md @@ -1,6 +1,6 @@ # Doctor Token Enhancement - User Guide -**Version:** v7.10.0 +**Version:** v7.10.1 **Last Updated:** 2026-02-27 --- @@ -633,5 +633,5 @@ Found a bug or have a feature request? --- **Last Updated:** 2026-02-27 -**Version:** v7.10.0 +**Version:** v7.10.1 **Maintainer:** flow-cli team diff --git a/docs/guides/DOT-WORKFLOW.md b/docs/guides/DOT-WORKFLOW.md index d5f8c2237..0a97a5e79 100644 --- a/docs/guides/DOT-WORKFLOW.md +++ b/docs/guides/DOT-WORKFLOW.md @@ -507,5 +507,5 @@ Run: sec unlock --- -**Version:** v7.10.0 +**Version:** v7.10.1 **See Also:** [Dispatcher Reference](../reference/MASTER-DISPATCHER-GUIDE.md#dots-dispatcher) | [Tutorial](../tutorials/12-dot-dispatcher.md) diff --git a/docs/guides/INTELLIGENT-CONTENT-ANALYSIS.md b/docs/guides/INTELLIGENT-CONTENT-ANALYSIS.md index 0264ae862..9b862f693 100644 --- a/docs/guides/INTELLIGENT-CONTENT-ANALYSIS.md +++ b/docs/guides/INTELLIGENT-CONTENT-ANALYSIS.md @@ -1,6 +1,6 @@ # Intelligent Content Analysis Guide -**Version:** v7.10.0 +**Version:** v7.10.1 **Last Updated:** 2026-01-22 --- diff --git a/docs/guides/QUALITY-GATES.md b/docs/guides/QUALITY-GATES.md index 573d2e311..bf87911bb 100644 --- a/docs/guides/QUALITY-GATES.md +++ b/docs/guides/QUALITY-GATES.md @@ -9,7 +9,7 @@ tags: > Every validation layer in flow-cli, from keystroke to production. > -> **Version:** v7.10.0 +> **Version:** v7.10.1 --- @@ -239,4 +239,4 @@ Areas where validation could be added in the future: --- **Last Updated:** 2026-02-27 -**Version:** v7.10.0 +**Version:** v7.10.1 diff --git a/docs/guides/QUARTO-WORKFLOW-PHASE-2-GUIDE.md b/docs/guides/QUARTO-WORKFLOW-PHASE-2-GUIDE.md index 6f68a4103..a22f2f8bc 100644 --- a/docs/guides/QUARTO-WORKFLOW-PHASE-2-GUIDE.md +++ b/docs/guides/QUARTO-WORKFLOW-PHASE-2-GUIDE.md @@ -6,7 +6,7 @@ tags: # Quarto Workflow Phase 2 Guide -**Version:** v7.10.0 +**Version:** v7.10.1 **Last Updated:** 2026-02-27 **Status:** Production Ready diff --git a/docs/guides/SCHOLAR-WRAPPERS-GUIDE.md b/docs/guides/SCHOLAR-WRAPPERS-GUIDE.md index 8ccedf8fc..e1efebd2a 100644 --- a/docs/guides/SCHOLAR-WRAPPERS-GUIDE.md +++ b/docs/guides/SCHOLAR-WRAPPERS-GUIDE.md @@ -2,7 +2,7 @@ > Complete documentation for the 9 AI content generation commands in the teach system. > -> **Version:** v7.10.0 | **Prerequisites:** Scholar plugin, teach-config.yml +> **Version:** v7.10.1 | **Prerequisites:** Scholar plugin, teach-config.yml ## Table of Contents @@ -1311,6 +1311,6 @@ teach lecture "Topic" --week 5 --math --- -**Version:** v7.10.0 +**Version:** v7.10.1 **Last Updated:** 2026-02-02 **Commands Documented:** 9 Scholar wrappers diff --git a/docs/guides/TEACH-DEPLOY-GUIDE.md b/docs/guides/TEACH-DEPLOY-GUIDE.md index 3a7855a76..bbb16f5f9 100644 --- a/docs/guides/TEACH-DEPLOY-GUIDE.md +++ b/docs/guides/TEACH-DEPLOY-GUIDE.md @@ -8,7 +8,7 @@ tags: > Deploy your course website from local preview to production with confidence. > -> **Version:** v7.10.0 | **Command:** `teach deploy` +> **Version:** v7.10.1 | **Command:** `teach deploy` ![teach deploy v2 Demo](../demos/tutorials/tutorial-teach-deploy.gif) @@ -1237,4 +1237,4 @@ The deployment summary box now includes a direct link to your GitHub Actions pag --- **Last Updated:** 2026-02-27 -**Version:** v7.10.0 +**Version:** v7.10.1 diff --git a/docs/guides/TEACHING-TROUBLESHOOTING.md b/docs/guides/TEACHING-TROUBLESHOOTING.md index 6996c334d..009ad37ff 100644 --- a/docs/guides/TEACHING-TROUBLESHOOTING.md +++ b/docs/guides/TEACHING-TROUBLESHOOTING.md @@ -2,7 +2,7 @@ > Quick fixes for common issues with the teach dispatcher. > -> **Version:** v7.10.0 +> **Version:** v7.10.1 > **Last Updated:** 2026-02-27 --- diff --git a/docs/guides/TEACHING-WORKFLOW-V3-GUIDE.md b/docs/guides/TEACHING-WORKFLOW-V3-GUIDE.md index 643f66406..a66d4534b 100644 --- a/docs/guides/TEACHING-WORKFLOW-V3-GUIDE.md +++ b/docs/guides/TEACHING-WORKFLOW-V3-GUIDE.md @@ -6,7 +6,7 @@ tags: # Teaching Workflow v3.0 Guide -**Version:** v7.10.0 +**Version:** v7.10.1 **Last Updated:** 2026-02-27 **Target Audience:** Instructors using flow-cli for course management @@ -2128,5 +2128,5 @@ teach init --config template.yml --- -**Version:** v7.10.0 (Teaching Workflow v3.0) +**Version:** v7.10.1 (Teaching Workflow v3.0) **Last Updated:** 2026-02-27 diff --git a/docs/guides/TESTING.md b/docs/guides/TESTING.md index 8eca12b21..6a2a1c050 100644 --- a/docs/guides/TESTING.md +++ b/docs/guides/TESTING.md @@ -23,10 +23,11 @@ flow-cli uses a **shared test framework** (`tests/test-framework.zsh`) with comp | Metric | Count | |--------|-------| -| Test files | 210 | -| Test suites (run-all.sh) | 58/58 passing | +| Test files | 216 | +| Test suites (run-all.sh) | 65 total — 64 passed, 1 skipped, 0 failed | | Test functions | 12,000+ | -| Expected timeouts | 1 (IMAP connectivity) | +| Expected skips | 1 (`e2e-em-dispatcher` — needs configured IMAP account) | +| CI | runs the full suite on every PR (green on the Ubuntu runner) | --- @@ -263,7 +264,36 @@ zsh tests/test-work.zsh ./tests/run-all.sh ``` -65 suites, ~12000 assertions. Expected: 64/64 pass, 1 timeout (IMAP connectivity). +65 suites, ~12000 assertions. Expected: **64 passed, 0 failed, 0 timeout, 1 skipped**. +The 1 skip is `e2e-em-dispatcher` (needs a configured IMAP account; skips cleanly +otherwise). `run-all.sh` exits **0** when there are no failures or timeouts. + +#### Skip semantics (exit code 77) + +A suite that requires an external tool/service which is absent must **skip +cleanly** rather than fail. Exit **77** (the automake "skip" convention) tells +`run-all.sh` to count the suite as ⏭️ skipped, not ❌ failed: + +```zsh +# Whole-suite guard — put after sourcing, before the tests: +command -v yq >/dev/null 2>&1 || { echo "SKIP: yq not installed"; exit 77; } +``` + +For a **mixed** suite (most cases are tool-independent), gate only the +tool-dependent cases instead of skipping the whole file — e.g. include the `tm` +dispatcher in dispatcher-enumeration checks only `if command -v ait`, so the +other assertions still run. This keeps full coverage on a dev machine that has +the tool while staying green on a hosted runner that doesn't. + +Tools whose absence triggers a skip on CI: `atlas`, `ait` (aiterm), +`himalaya` (IMAP), `R`/`renv`, `quarto`, `claude`. Skips are printed in the +suite output and summarised in the `run-all.sh` results line, so a skip is +always visible (never a silently-missing pass). + +> **Determinism:** suites that assert flow-cli's *standalone* behavior pin +> `FLOW_ATLAS_ENABLED=no` in setup so the result can't flip based on whether +> `atlas` happens to be installed. The suite is green locally **with or without** +> atlas, and on the runner (which has neither atlas nor the other tools above). ### Dogfood Quality Check @@ -302,21 +332,40 @@ test_something() { ## Continuous Integration -### GitHub Actions (`test.yml`) +### GitHub Actions (`.github/workflows/test.yml`) + +Tests run automatically on push and PR to `main`/`dev`, in **two parallel jobs**: + +| Job | Runs | Purpose | +|-----|------|---------| +| **ZSH Plugin Tests** (`zsh-tests`) | smoke tests (`test-flow.zsh`, `test-install.sh`) + man-page version-sync guard | fast signal; the long-standing required check | +| **Full Test Suite** (`full-suite`) | the whole `./tests/run-all.sh` (~4 min) | comprehensive gate — runs every PR | + +The runner has no `atlas`, `ait`, `himalaya`, `R`, or `quarto`, so service- +dependent suites **skip** there (see "Skip semantics" above); everything else +must pass. A git identity is provisioned in the job so deploy suites that +`git commit` work. The `full-suite` job captures the real exit code via +`PIPESTATUS` (so its colour reflects reality) and emits the full `run-all.sh` +output to the job summary. -Tests run automatically on push and PR: +> **Phasing:** `full-suite` starts as a **non-blocking** measurement job +> (`continue-on-error: true`) so it can never create a perpetually-red gate +> while the suite is being made deterministic. Once it has soaked green it is +> promoted to a **required** status check on `dev`, then `main`. ```yaml -name: ZSH Plugin Tests -on: [push, pull_request] -jobs: - test: + full-suite: + name: Full Test Suite (non-blocking) runs-on: ubuntu-latest + continue-on-error: true # measurement phase; drop when promoting to required steps: - - uses: actions/checkout@v4 - - name: Install ZSH - run: sudo apt-get install -y zsh - - name: Run Tests + - uses: actions/checkout@v6 + - name: Configure git identity + run: | + git config --global user.email "ci@flow-cli.test" + git config --global user.name "flow-cli CI" + # ... mock project structure ... + - name: Run full suite (non-blocking) run: ./tests/run-all.sh ``` @@ -359,4 +408,4 @@ When adding new functionality: **Established:** v5.0.0 (2026-01-11) **Overhauled:** v7.4.0 (2026-02-16) — shared framework, mock registry, dogfood scanner -**Test Count:** 213 test files, 12000+ assertions, 64/64 suites passing +**Test Count:** 216 test files, 12000+ assertions, 64/64 suites passing diff --git a/docs/help/QUICK-REFERENCE.md b/docs/help/QUICK-REFERENCE.md index 4f73731c2..818125f6d 100644 --- a/docs/help/QUICK-REFERENCE.md +++ b/docs/help/QUICK-REFERENCE.md @@ -11,7 +11,7 @@ tags: **Purpose:** Single-page command lookup for all flow-cli features **Format:** Copy-paste ready with expected outputs -**Version:** v7.10.0 +**Version:** v7.10.1 **Last Updated:** 2026-06-04 --- @@ -1590,6 +1590,6 @@ mcp help --- -**Version:** v7.10.0 +**Version:** v7.10.1 **Last Updated:** 2026-06-04 **Contributors:** See [CHANGELOG.md](../CHANGELOG.md) diff --git a/docs/help/TROUBLESHOOTING.md b/docs/help/TROUBLESHOOTING.md index e7f2cc909..e00b32555 100644 --- a/docs/help/TROUBLESHOOTING.md +++ b/docs/help/TROUBLESHOOTING.md @@ -3,7 +3,7 @@ **Purpose:** Common issues and solutions for flow-cli **Audience:** All users experiencing problems **Format:** Problem → Diagnosis → Solution -**Version:** v7.10.0 +**Version:** v7.10.1 **Last Updated:** 2026-02-27 --- @@ -1048,6 +1048,6 @@ ls -la ~/.cache/flow/ --- -**Version:** v7.10.0 +**Version:** v7.10.1 **Last Updated:** 2026-02-27 **Need more help?** https://github.com/Data-Wise/flow-cli/issues diff --git a/docs/help/WORKFLOWS.md b/docs/help/WORKFLOWS.md index 3e5489c9e..af86f8717 100644 --- a/docs/help/WORKFLOWS.md +++ b/docs/help/WORKFLOWS.md @@ -6,7 +6,7 @@ **Purpose:** Real-world workflow patterns for flow-cli **Audience:** All users (beginners → advanced) **Format:** Step-by-step instructions with examples -**Version:** v7.10.0 +**Version:** v7.10.1 **Last Updated:** 2026-02-27 --- @@ -1071,6 +1071,6 @@ pick # Interactive project picker --- -**Version:** v7.10.0 +**Version:** v7.10.1 **Last Updated:** 2026-02-27 **Contributors:** See [CHANGELOG.md](../CHANGELOG.md) diff --git a/docs/index.md b/docs/index.md index c743d2cc0..3a3828b33 100644 --- a/docs/index.md +++ b/docs/index.md @@ -26,11 +26,11 @@ tags: ``` **That's it!** No configuration required. -!!! success "🎉 What's New in v7.10.0" +!!! success "🎉 What's New in v7.10.1" **Forward-looking schedule layer:** the new **`agenda`** command surfaces dated activity across all projects — deadlines, lectures, exams, milestones, and recurring blocks — bucketed into OVERDUE / TODAY / THIS WEEK / LATER (`agt`/`agw`/`agm` aliases). **`dash` UPCOMING** + dated enrichment of `morning` / `today` / `week`, all driven by one shared engine. Works fully without `yq` and without atlas. **Data sources:** a no-`yq` `## Schedule:` section in each project's `.STATUS`, plus teaching dates from `.flow/teach-config.yml`. - **64 test suites** passing (213 files, 12000+ assertions). + **v7.10.1** hardens reliability: Linux-portability fixes (caches, email cache, teaching-date math) and the full test suite is now a required CI gate. **64 suites** passing (216 files, 12000+ assertions). [→ Agenda & Schedule Guide](guides/AGENDA-SCHEDULE-GUIDE.md){ .md-button } [→ Changelog](CHANGELOG.md){ .md-button } @@ -258,7 +258,8 @@ Commands that adapt to your project type: work # Start session finish [note] # End session hop # Quick switch (tmux) -dash # Dashboard +dash # Dashboard (what's happening now) +agenda # What's due soon (deadlines, exams, milestones) catch "idea" # Quick capture ``` @@ -291,4 +292,4 @@ catch "idea" # Quick capture --- -**v7.10.0** · Pure ZSH · Zero Dependencies · MIT License +**v7.10.1** · Pure ZSH · Zero Dependencies · MIT License diff --git a/docs/internal/conventions/code/ZSH-COMMANDS-HELP.md b/docs/internal/conventions/code/ZSH-COMMANDS-HELP.md index 355209822..e81e833f6 100644 --- a/docs/internal/conventions/code/ZSH-COMMANDS-HELP.md +++ b/docs/internal/conventions/code/ZSH-COMMANDS-HELP.md @@ -438,7 +438,7 @@ colored/box-drawn `help` output is not copy-pasteable into troff). The `.TH` line's version field must match `FLOW_VERSION`: ```troff -.TH TOK 1 "June 2026" "flow-cli 7.10.0" "User Commands" +.TH TOK 1 "June 2026" "flow-cli 7.10.1" "User Commands" ``` A single guard — `tests/test-manpage-version-sync.zsh`, wired into diff --git a/docs/reference/MASTER-API-REFERENCE.md b/docs/reference/MASTER-API-REFERENCE.md index 922ea87ea..5b9e6806b 100644 --- a/docs/reference/MASTER-API-REFERENCE.md +++ b/docs/reference/MASTER-API-REFERENCE.md @@ -8,7 +8,7 @@ tags: **Purpose:** Complete API documentation for all flow-cli library functions **Audience:** Developers, contributors, advanced users **Format:** Function signatures, parameters, return values, examples -**Version:** v7.10.0 +**Version:** v7.10.1 **Last Updated:** 2026-02-21 --- @@ -7558,7 +7558,7 @@ URL line is omitted when `$url` is empty or `"null"`. --- -**Version:** v7.10.0 +**Version:** v7.10.1 **Last Updated:** 2026-02-21 **Auto-Generation:** Run `./scripts/generate-api-docs.sh` to update function index **Total Functions:** 880 (428 documented, 452 pending) diff --git a/docs/reference/MASTER-ARCHITECTURE.md b/docs/reference/MASTER-ARCHITECTURE.md index 9ba55dd50..0b98826c4 100644 --- a/docs/reference/MASTER-ARCHITECTURE.md +++ b/docs/reference/MASTER-ARCHITECTURE.md @@ -3,7 +3,7 @@ **Purpose:** Complete system architecture documentation for flow-cli **Audience:** Contributors, maintainers, advanced users **Format:** Design decisions, diagrams, implementation details -**Version:** v7.10.0 +**Version:** v7.10.1 **Last Updated:** 2026-02-21 --- @@ -1019,7 +1019,7 @@ graph TD --- -**Version:** v7.10.0 +**Version:** v7.10.1 **Last Updated:** 2026-02-21 **Diagrams:** 8 Mermaid diagrams **Total:** 2,500+ lines diff --git a/docs/reference/MASTER-DISPATCHER-GUIDE.md b/docs/reference/MASTER-DISPATCHER-GUIDE.md index c1a8459cb..56b92c15e 100644 --- a/docs/reference/MASTER-DISPATCHER-GUIDE.md +++ b/docs/reference/MASTER-DISPATCHER-GUIDE.md @@ -10,7 +10,7 @@ tags: **Purpose:** Complete reference for all flow-cli dispatchers (15 + at bridge) **Audience:** All users (beginner → intermediate → advanced) **Format:** Progressive disclosure (basics → advanced features) -**Version:** v7.10.0 +**Version:** v7.10.1 **Last Updated:** 2026-02-21 --- @@ -3405,6 +3405,6 @@ at stats --- -**Version:** v7.10.0 +**Version:** v7.10.1 **Last Updated:** 2026-02-22 **Total:** 14 dispatchers + at bridge fully documented diff --git a/docs/reference/REFCARD-ANALYSIS.md b/docs/reference/REFCARD-ANALYSIS.md index fe3d0f61b..8a6548f0d 100644 --- a/docs/reference/REFCARD-ANALYSIS.md +++ b/docs/reference/REFCARD-ANALYSIS.md @@ -189,5 +189,5 @@ teach analyze --slide-breaks lectures/week-02-probability.qmd --- -**Version:** v7.10.0 +**Version:** v7.10.1 **Last Updated:** 2026-02-02 diff --git a/docs/reference/REFCARD-DATES.md b/docs/reference/REFCARD-DATES.md index 9cc186ec1..afa1cfb45 100644 --- a/docs/reference/REFCARD-DATES.md +++ b/docs/reference/REFCARD-DATES.md @@ -271,5 +271,5 @@ teach dates status --- -**Version:** v7.10.0 +**Version:** v7.10.1 **Last Updated:** 2026-02-02 diff --git a/docs/reference/REFCARD-DOCTOR.md b/docs/reference/REFCARD-DOCTOR.md index 43c063811..3ff0ef3e5 100644 --- a/docs/reference/REFCARD-DOCTOR.md +++ b/docs/reference/REFCARD-DOCTOR.md @@ -320,5 +320,5 @@ teach doctor --verbose --- -**Version:** v7.10.0 +**Version:** v7.10.1 **Last Updated:** 2026-02-21 diff --git a/docs/reference/REFCARD-DOTFILE-DISPATCHER.md b/docs/reference/REFCARD-DOTFILE-DISPATCHER.md index 16c48003d..271d2654d 100644 --- a/docs/reference/REFCARD-DOTFILE-DISPATCHER.md +++ b/docs/reference/REFCARD-DOTFILE-DISPATCHER.md @@ -2,7 +2,7 @@ > All `dots` subcommands at a glance. > -> **Version:** v7.10.0 (v3.0.0 dispatcher) | **Dispatcher:** `lib/dispatchers/dots-dispatcher.zsh` +> **Version:** v7.10.1 (v3.0.0 dispatcher) | **Dispatcher:** `lib/dispatchers/dots-dispatcher.zsh` > > **Backend:** [chezmoi](https://www.chezmoi.io/) for dotfile sync. @@ -99,5 +99,5 @@ dots apply --- -**Version:** v7.10.0 +**Version:** v7.10.1 **Last Updated:** 2026-02-27 diff --git a/docs/reference/REFCARD-GIT-DISPATCHER.md b/docs/reference/REFCARD-GIT-DISPATCHER.md index 3ceeadc67..665cdb468 100644 --- a/docs/reference/REFCARD-GIT-DISPATCHER.md +++ b/docs/reference/REFCARD-GIT-DISPATCHER.md @@ -2,7 +2,7 @@ > All `g` subcommands at a glance — the most-used flow-cli dispatcher. > -> **Version:** v7.10.0 | **Dispatcher:** `lib/dispatchers/g-dispatcher.zsh` +> **Version:** v7.10.1 | **Dispatcher:** `lib/dispatchers/g-dispatcher.zsh` > > Unknown commands pass through to `git` (e.g., `g remote -v` → `git remote -v`). @@ -129,5 +129,5 @@ g pop # Restore stashed changes --- -**Version:** v7.10.0 +**Version:** v7.10.1 **Last Updated:** 2026-02-27 diff --git a/docs/reference/REFCARD-SCHOLAR-FLAGS.md b/docs/reference/REFCARD-SCHOLAR-FLAGS.md index d487c5222..1f2ae5fc8 100644 --- a/docs/reference/REFCARD-SCHOLAR-FLAGS.md +++ b/docs/reference/REFCARD-SCHOLAR-FLAGS.md @@ -2,7 +2,7 @@ > All flags available for `teach` Scholar wrapper commands (lecture, slides, exam, quiz, assignment, syllabus, rubric, feedback, demo). > -> **Version:** v7.10.0 | **Source:** `lib/dispatchers/teach-dispatcher.zsh` +> **Version:** v7.10.1 | **Source:** `lib/dispatchers/teach-dispatcher.zsh` ## Selection Flags (Universal) @@ -746,6 +746,6 @@ teach lecture "ANOVA" --week 8 --dry-run --- -**Version:** v7.10.0 +**Version:** v7.10.1 **Last Updated:** 2026-02-02 **Status:** Complete Scholar flag documentation diff --git a/docs/reference/REFCARD-SCHOLAR-WRAPPERS.md b/docs/reference/REFCARD-SCHOLAR-WRAPPERS.md index e0b480bf6..2a53e9f27 100644 --- a/docs/reference/REFCARD-SCHOLAR-WRAPPERS.md +++ b/docs/reference/REFCARD-SCHOLAR-WRAPPERS.md @@ -8,7 +8,7 @@ tags: # Quick Reference: Scholar Wrapper Commands **Purpose:** Reference card for Scholar-powered `teach` subcommands -**Version:** v7.10.0+ +**Version:** v7.10.1+ **Last Updated:** 2026-02-27 --- diff --git a/docs/reference/REFCARD-SECRET-DISPATCHER.md b/docs/reference/REFCARD-SECRET-DISPATCHER.md index a126a1c0b..ee474e7a3 100644 --- a/docs/reference/REFCARD-SECRET-DISPATCHER.md +++ b/docs/reference/REFCARD-SECRET-DISPATCHER.md @@ -2,7 +2,7 @@ > All `sec` subcommands at a glance. > -> **Version:** v7.10.0 (v3.0.0 dispatcher) | **Dispatcher:** `lib/dispatchers/sec-dispatcher.zsh` +> **Version:** v7.10.1 (v3.0.0 dispatcher) | **Dispatcher:** `lib/dispatchers/sec-dispatcher.zsh` > > **Backends:** macOS Keychain (primary), Bitwarden (optional secondary). @@ -105,5 +105,5 @@ sec dashboard # Overview of all secrets --- -**Version:** v7.10.0 +**Version:** v7.10.1 **Last Updated:** 2026-02-27 diff --git a/docs/reference/REFCARD-TEACH-DISPATCHER.md b/docs/reference/REFCARD-TEACH-DISPATCHER.md index 3e3d2fea3..6c5cd73fd 100644 --- a/docs/reference/REFCARD-TEACH-DISPATCHER.md +++ b/docs/reference/REFCARD-TEACH-DISPATCHER.md @@ -2,7 +2,7 @@ > All 34 `teach` subcommands at a glance. For detailed guides, see linked documentation. > -> **Version:** v7.10.0 | **Dispatcher:** `lib/dispatchers/teach-dispatcher.zsh` +> **Version:** v7.10.1 | **Dispatcher:** `lib/dispatchers/teach-dispatcher.zsh` ## Command Taxonomy @@ -485,6 +485,6 @@ teach status --performance # Review metrics --- -**Version:** v7.10.0 +**Version:** v7.10.1 **Last Updated:** 2026-02-27 **Commands:** 34 total (12 Scholar wrappers + 5 course mgmt + 6 content mgmt + 9 infrastructure + 1 discovery + config subcommands) diff --git a/docs/reference/REFCARD-TEACH-PLAN.md b/docs/reference/REFCARD-TEACH-PLAN.md index 939d6d4cb..9eb346096 100644 --- a/docs/reference/REFCARD-TEACH-PLAN.md +++ b/docs/reference/REFCARD-TEACH-PLAN.md @@ -157,5 +157,5 @@ teach slides --week N # Step 5: Generate content --- -**Version:** v7.10.0 +**Version:** v7.10.1 **Last Updated:** 2026-01-29 diff --git a/docs/reference/REFCARD-WORKTREE-DISPATCHER.md b/docs/reference/REFCARD-WORKTREE-DISPATCHER.md index 2eee2efb1..4f914e37a 100644 --- a/docs/reference/REFCARD-WORKTREE-DISPATCHER.md +++ b/docs/reference/REFCARD-WORKTREE-DISPATCHER.md @@ -2,7 +2,7 @@ > All `wt` subcommands at a glance. > -> **Version:** v7.10.0 | **Dispatcher:** `lib/dispatchers/wt-dispatcher.zsh` +> **Version:** v7.10.1 | **Dispatcher:** `lib/dispatchers/wt-dispatcher.zsh` ## Commands @@ -105,5 +105,5 @@ cd ~/projects/my-project # Back to feature A (untouched) --- -**Version:** v7.10.0 +**Version:** v7.10.1 **Last Updated:** 2026-02-27 diff --git a/docs/reference/TEACH-CONFIG-SCHEMA.md b/docs/reference/TEACH-CONFIG-SCHEMA.md index debbb6fd0..3f23b73fd 100644 --- a/docs/reference/TEACH-CONFIG-SCHEMA.md +++ b/docs/reference/TEACH-CONFIG-SCHEMA.md @@ -2,7 +2,7 @@ > Complete field reference for teaching project configuration. > -> **Version:** v7.10.0 | **Location:** `.flow/teach-config.yml` +> **Version:** v7.10.1 | **Location:** `.flow/teach-config.yml` ## Overview @@ -669,4 +669,4 @@ _teach_config_summary ".flow/teach-config.yml" --- **Last Updated:** 2026-02-02 -**Version:** v7.10.0 +**Version:** v7.10.1 diff --git a/docs/specs/SPEC-ci-full-suite-gate-2026-06-13.md b/docs/specs/SPEC-ci-full-suite-gate-2026-06-13.md new file mode 100644 index 000000000..08c921aef --- /dev/null +++ b/docs/specs/SPEC-ci-full-suite-gate-2026-06-13.md @@ -0,0 +1,132 @@ +# SPEC: Gate the full test suite in CI + +> Status: **DRAFT — awaiting approval.** Spec-only (no code changes). On approval this +> becomes a feature worktree (`feature/ci-full-suite-gate`) + `ORCHESTRATE-ci-full-suite-gate.md`. +> Filed origin: `.STATUS` Next Action #3 / Pending "CI smoke-only gap" (2026-05-13). + +## Context — why this change + +`.github/workflows/test.yml` (job **ZSH Plugin Tests**, the only required status check on +`main`) runs **smoke tests only**: + +```yaml +# Run smoke tests +zsh ./tests/test-flow.zsh +bash ./tests/test-install.sh +# + Man-page version-sync guard +``` + +The full **65-suite** `./tests/run-all.sh` (~4 min) is **never run in CI** — the step comment +says "run full suite locally." So the required check verifies ~3 of 65 suites. Consequences: + +- Regressions land green. (Documented precedent: the `test-doctor` regression in `0880f924` + passed CI despite exiting 124 under the harness — caught only locally.) +- This session's agenda release leaned entirely on local `run-all.sh`; CI could not have + caught a schedule-engine regression. +- The gate relies on developer discipline, not enforcement. + +**Goal:** make CI run the full suite and promote it to a required check — *without* creating a +perpetually-red gate. + +## Current state — the suite is NOT deterministically green (key finding) + +A naive "add `run-all.sh` to CI" fails. Investigation (2026-06-13, **atlas present locally**) +shows `run-all.sh` is **environment-sensitive**, not clean: + +| Suite | Local result (atlas present) | Root cause | Likely CI result (atlas absent) | +|---|---|---|---| +| `test-atlas-contract` | 4/18 FAIL — `atlas stats`/`parked`/`trail` exit **127** | atlas binary present but those subcommands aren't implemented; the 4 "warm-path" tests don't go through `skip_without_atlas()` | Likely **SKIP/pass** (`command -v atlas` false → guard fires) | +| `e2e-core-commands` | 2/22 FAIL — `status reads .STATUS` (`output=''`), `catch creates capture` | `_flow_status_show` / `catch` **delegate to the installed atlas** instead of the standalone fallback the test asserts (atlas-present skew) | Likely **pass** (fallback path) | +| `e2e-em-dispatcher` | TIMEOUT | `em unread` / `em read` block on IMAP with no configured account | TIMEOUT (no mail server) | + +`run-all.sh` exit codes: **1** if any FAIL, **2** if any TIMEOUT. So today it returns non-zero +even though the failures are environment artifacts, not real regressions. + +**Two distinct problems, not one:** +1. **Non-determinism / test-isolation bug:** several tests assume *standalone* (no-atlas) + behavior but don't force it, so results flip based on whether `atlas` happens to be on + `PATH`. Tests must pin `FLOW_ATLAS_ENABLED=no` where they assert fallback behavior. +2. **Genuinely service-dependent tests** (`e2e-em-dispatcher` IMAP, `test-atlas-contract` + warm-path) must **skip cleanly** when the service is absent — not fail or hang. + +**Real CI behavior is currently unknown** (and probably better than local, since the runner has +no atlas/IMAP). That uncertainty is itself a reason to measure before gating. + +## Proposed approach — phased, never red + +### Phase 1 — Measure (non-blocking) +Add a **separate, non-required** job `full-suite` to `test.yml` running `./tests/run-all.sh` +(`continue-on-error: true`, or a non-required check). Purpose: capture *ground-truth* CI +results for one or two PRs. No gating yet. Deliverable: the actual CI pass/skip/fail list. + +### Phase 2 — Make the suite deterministic & green in CI +Based on Phase 1 output: +- **Pin standalone mode** in tests that assert fallback behavior (`e2e-core-commands` status/ + catch and any other atlas-skew tests): export `FLOW_ATLAS_ENABLED=no` in their setup so the + result is identical with or without atlas installed. (Fixes the local-vs-CI divergence too.) +- **Clean-skip service-dependent tests** when the dependency is absent: + - `test-atlas-contract` warm-path: route the 4 `atlas ` tests through the existing + `skip_without_atlas()` (or skip when `atlas stats` returns 127). + - `e2e-em-dispatcher`: skip IMAP-dependent cases when no account/mailbox is configured + (`return 77`), so the suite neither fails nor hangs. (Consider a short per-call timeout.) +- Decide `run-all.sh` **timeout policy for CI**: treat `TIMEOUT>0` as failure once IMAP tests + skip cleanly (so a real hang is caught), OR keep the e2e-em suite out of the gated set. + +### Phase 3 — Promote to required +Once `run-all.sh` is reliably green on the runner: +- Make `full-suite` a required status check on **`dev` first** (lower blast radius), observe, + then add it to **`main`** branch protection (`gh api -X PUT .../branches/main/protection`). +- Keep the fast smoke job too (quick signal); the full job is the comprehensive gate. + +## Gating-set decision (to confirm at approval) + +Which suites constitute the **required** gate: +- **Recommended:** all 65 except genuinely external-service suites that can only ever skip on a + hosted runner (`e2e-em-dispatcher` IMAP). Everything else (incl. atlas-contract, which should + *skip* its warm-path cleanly) must pass. +- Alternative (smaller first step from the original `.STATUS` note): gate just + `test-doctor.zsh` (~30s) — catches the documented `0880f924`-class regression — then expand. + +## Files affected (implementation, later) + +| File | Change | +|---|---| +| `.github/workflows/test.yml` | Add `full-suite` job (Phase 1 non-blocking → Phase 3 required) | +| `tests/e2e-core-commands.zsh` | Pin `FLOW_ATLAS_ENABLED=no` for status/catch (and any skew) | +| `tests/test-atlas-contract.zsh` | Route warm-path tests through `skip_without_atlas()` | +| `tests/e2e-em-dispatcher.zsh` | Skip (rc 77) IMAP cases without a configured account; bound timeouts | +| `tests/run-all.sh` | (Maybe) a CI mode / clearer timeout-vs-fail exit semantics | +| `docs/guides/TESTING.md` | Document the CI gate + how to skip service tests locally | +| GitHub branch protection (`dev`, then `main`) | Add `full-suite` to required checks (Phase 3) | + +## Acceptance criteria + +1. `./tests/run-all.sh` exits **0** on a clean runner (no atlas, no IMAP) — every non-skipped + suite passes; service-dependent cases report SKIP, not FAIL/TIMEOUT. +2. The same `run-all.sh` still passes locally **whether or not** atlas is installed (determinism). +3. CI runs the full suite on every PR to `dev`/`main`; failures block merge (Phase 3). +4. Fast smoke job retained for quick feedback. +5. `docs/guides/TESTING.md` updated; no version/count drift. + +## Risks & mitigations + +- **Perpetually-red gate** → Phases 1–2 measure & green *before* requiring (Phase 3). +- **Hidden real failures masked as "env"** → each skip must be conditional on the dependency + genuinely being absent, never unconditional; log skips so they're visible. +- **CI runtime** (~4 min) → keep it a separate job from smoke; parallel to it. Acceptable for + a release-gating check; revisit sharding only if it becomes a bottleneck. +- **Branch-protection change on `main`** is outward-facing → apply only after `dev` soak. + +## Out of scope (v1) + +- Test sharding / matrix parallelism for speed. +- Installing atlas in CI to exercise the *connected* atlas paths (the contract tests should + skip cleanly when absent; testing the live integration is a separate effort). +- Spinning up a mail server for `e2e-em-dispatcher` IMAP coverage. + +## Verification (for the implementing session) + +1. Phase 1 job output shows the real CI pass/skip/fail list. +2. After Phase 2: a CI run of `run-all.sh` is green; locally green both with and without + `atlas` on `PATH` (toggle to prove determinism). +3. Phase 3: a deliberately-broken test reddens the required check and blocks a test PR. diff --git a/docs/teaching/index.md b/docs/teaching/index.md index 4e6d93424..9a4cf797d 100644 --- a/docs/teaching/index.md +++ b/docs/teaching/index.md @@ -232,4 +232,4 @@ teach plan help --- **Last Updated:** 2026-02-27 -**Version:** v7.10.0 +**Version:** v7.10.1 diff --git a/docs/tutorials/14-teach-dispatcher.md b/docs/tutorials/14-teach-dispatcher.md index b225aef16..5d3176e9d 100644 --- a/docs/tutorials/14-teach-dispatcher.md +++ b/docs/tutorials/14-teach-dispatcher.md @@ -10,7 +10,7 @@ tags: > **What you'll learn:** Manage course websites with fast deployment, config validation, and AI-assisted content creation > > **Time:** ~20 minutes | **Level:** Beginner -> **Version:** v7.10.0 +> **Version:** v7.10.1 --- diff --git a/docs/tutorials/20-teaching-dates-automation.md b/docs/tutorials/20-teaching-dates-automation.md index f1bf8400e..9b94dedf6 100644 --- a/docs/tutorials/20-teaching-dates-automation.md +++ b/docs/tutorials/20-teaching-dates-automation.md @@ -657,4 +657,4 @@ yq eval .flow/teach-config.yml **Questions or issues?** Open an issue on [GitHub](https://github.com/Data-Wise/flow-cli/issues) **Last Updated:** 2026-02-27 -**Version:** v7.10.0 +**Version:** v7.10.1 diff --git a/docs/tutorials/21-teach-analyze.md b/docs/tutorials/21-teach-analyze.md index 8fcfef5da..b187bcad3 100644 --- a/docs/tutorials/21-teach-analyze.md +++ b/docs/tutorials/21-teach-analyze.md @@ -9,7 +9,7 @@ tags: > **What you'll learn:** Validate lecture prerequisites, detect concept gaps, and generate optimized slides using `teach analyze` > > **Time:** ~15 minutes | **Level:** Beginner → Intermediate -> **Version:** v7.10.0 +> **Version:** v7.10.1 --- diff --git a/docs/tutorials/24-template-management.md b/docs/tutorials/24-template-management.md index 06fcb10b3..8e26de91b 100644 --- a/docs/tutorials/24-template-management.md +++ b/docs/tutorials/24-template-management.md @@ -9,7 +9,7 @@ tags: > **What you'll learn:** Create and manage teaching content templates with `teach templates` > > **Time:** ~15 minutes | **Level:** Beginner → Intermediate -> **Version:** v7.10.0 +> **Version:** v7.10.1 --- @@ -433,5 +433,5 @@ teach templates sync --force --- -**Version:** v7.10.0 +**Version:** v7.10.1 **Last Updated:** 2026-01-28 diff --git a/docs/tutorials/25-lesson-plan-migration.md b/docs/tutorials/25-lesson-plan-migration.md index 480224189..3dbc49219 100644 --- a/docs/tutorials/25-lesson-plan-migration.md +++ b/docs/tutorials/25-lesson-plan-migration.md @@ -3,7 +3,7 @@ > **What you'll learn:** Extract lesson plans with `teach migrate-config` and manage them with `teach plan` > > **Time:** ~15 minutes | **Level:** Beginner -> **Version:** v7.10.0 +> **Version:** v7.10.1 --- @@ -417,5 +417,5 @@ teach lecture --week 5 --- -**Version:** v7.10.0 +**Version:** v7.10.1 **Last Updated:** 2026-01-28 diff --git a/docs/tutorials/26-latex-macros.md b/docs/tutorials/26-latex-macros.md index f2fb2004a..3a56fe9c7 100644 --- a/docs/tutorials/26-latex-macros.md +++ b/docs/tutorials/26-latex-macros.md @@ -3,7 +3,7 @@ > **What you'll learn:** Configure LaTeX macros for consistent AI-generated notation with `teach macros` > > **Time:** ~15 minutes | **Level:** Beginner → Intermediate -> **Version:** v7.10.0 +> **Version:** v7.10.1 --- diff --git a/docs/tutorials/27-lesson-plan-management.md b/docs/tutorials/27-lesson-plan-management.md index 2f703f304..d4726ea56 100644 --- a/docs/tutorials/27-lesson-plan-management.md +++ b/docs/tutorials/27-lesson-plan-management.md @@ -3,7 +3,7 @@ > **What you'll learn:** Create, manage, and use lesson plans with `teach plan` to drive AI content generation > > **Time:** ~15 minutes | **Level:** Beginner -> **Version:** v7.10.0 +> **Version:** v7.10.1 --- @@ -339,5 +339,5 @@ teach slides --week 5 # Generate slides --- -**Version:** v7.10.0 +**Version:** v7.10.1 **Last Updated:** 2026-01-29 diff --git a/docs/tutorials/29-first-exam-walkthrough.md b/docs/tutorials/29-first-exam-walkthrough.md index 942681586..3561f1d8b 100644 --- a/docs/tutorials/29-first-exam-walkthrough.md +++ b/docs/tutorials/29-first-exam-walkthrough.md @@ -3,7 +3,7 @@ > **What you'll learn:** Generate exams and quizzes using Scholar AI wrappers with flow-cli > > **Time:** ~20 minutes | **Level:** Beginner → Intermediate -> **Version:** v7.10.0 +> **Version:** v7.10.1 --- @@ -846,6 +846,6 @@ teach exam "Topic" --week 5 --- -**Version:** v7.10.0 +**Version:** v7.10.1 **Last Updated:** 2026-02-27 **Tutorial Series:** Part 29 of Teaching Workflow Tutorials diff --git a/docs/tutorials/30-new-instructor-complete-workflow.md b/docs/tutorials/30-new-instructor-complete-workflow.md index 920c9d674..50673c65b 100644 --- a/docs/tutorials/30-new-instructor-complete-workflow.md +++ b/docs/tutorials/30-new-instructor-complete-workflow.md @@ -3,7 +3,7 @@ > **What you'll learn:** Go from an empty directory to a deployed course website with AI-powered content > > **Time:** ~30 minutes | **Level:** Beginner -> **Version:** v7.10.0 +> **Version:** v7.10.1 --- diff --git a/docs/tutorials/32-teach-doctor.md b/docs/tutorials/32-teach-doctor.md index c32f073ca..c33d76e42 100644 --- a/docs/tutorials/32-teach-doctor.md +++ b/docs/tutorials/32-teach-doctor.md @@ -390,5 +390,5 @@ Only runs when `scholar.latex_macros.enabled: true` in teach-config.yml: --- -**Version:** v7.10.0 +**Version:** v7.10.1 **Last Updated:** 2026-02-08 diff --git a/docs/tutorials/48-agenda-schedule.md b/docs/tutorials/48-agenda-schedule.md new file mode 100644 index 000000000..cf8d6388a --- /dev/null +++ b/docs/tutorials/48-agenda-schedule.md @@ -0,0 +1,403 @@ +--- +tags: + - tutorials + - commands + - adhd +--- + +# Tutorial 48: Forward-Looking Schedule (`agenda`) + +> **What you'll build:** a working `## Schedule:` block that drives a single +> forward-looking view of everything due across your projects — surfaced by +> `agenda` and woven into `dash`, `morning`, `today`, and `week`. +> +> **Time:** ~15 minutes | **Level:** Beginner + +--- + +## Prerequisites + +Before starting, you should: + +- [ ] Have flow-cli installed (`brew install data-wise/tap/flow-cli`) +- [ ] Have at least one project with a `.STATUS` file (or follow along in any repo) +- [ ] Know the basics of `dash` — see [Tutorial 01](01-first-session.md) + +**Verify your setup:** + +```bash +agenda -h +# Expected: the agenda help screen (options, filters, legend) +``` + +If `agenda` isn't found, update: `brew upgrade data-wise/tap/flow-cli` (agenda +landed in v7.10.0). + +--- + +## What You'll Learn + +By the end of this tutorial, you will: + +1. **Add** dated and recurring items to a project's `## Schedule:` block +2. **Run** `agenda` and its windows/filters to see what's due +3. **Recognize** how the same items surface in `dash`, `morning`, `today`, `week` + +--- + +## Overview + +`dash`, `morning`, `today`, and `week` are present- and backward-looking: status, +current session, wins. They answer *"where am I?"* — never *"what's coming?"*. + +The **agenda layer** adds the forward-looking dimension. One engine +(`lib/schedule.zsh`) reads dated items from two sources, merges them, and renders +them everywhere consistently. It works fully **without atlas** and **without +`yq`**. + +```text + .STATUS "## Schedule:" ─┐ + ├─► schedule engine ─► agenda / dash / morning / today / week + .flow/teach-config.yml ─┘ (one source of truth, many surfaces) +``` + +--- + +## Part 1: Your First Agenda + +### Step 1.1: Run it empty + +Before adding anything, see the calm empty state: + +```bash +agenda +``` + +**What happened:** with nothing scheduled you get a quiet "nothing due" message, +not a wall of noise. That calm-when-empty behavior is deliberate. + +### Step 1.2: Add a `## Schedule:` block + +Open a project's `.STATUS` and add a `## Schedule:` section. The grammar is one +list item per line — **no `yq`, no special tooling**: + +```markdown +## Schedule: +- 2026-06-20 | Submit JRSS-B revision | research +- 2026-06-21 | Project beta milestone | general +``` + +The line grammar is: + +```text +- |