pushing summaries.

Author: ElektrikAkar

.claude/scheduled_tasks.lock

@@ -0,0 +1 @@
+{"sessionId":"1bbef9e6-7c1d-4f4b-a0e5-152c200dc4be","pid":91086,"acquiredAt":1776039817046}

.claude/summaries/handoff-2026-04-11-mac-support-ai-commands.md

@@ -0,0 +1,130 @@
+---
+name: handoff-2026-04-11-mac-support-ai-commands
+description: Session handoff — macOS support verified, AI slash commands added, repo cleanup, code safety fixes. All 67 tests pass on macOS.
+type: project
+---
+
+# Session Handoff — 2026-04-11
+
+Branch: **Claude**  Working tree: uncommitted changes (28 deletions, 13 modifications, 9 new files).
+
+## Goal
+
+Adversarial Mac validation of DTWC++ (Windows-developed), fix any build/code issues, add Claude Code slash commands for AI-assisted workflows, clean up obsolete files and PII, update docs. Eamonn-Keogh-level pedantry, ultrathink.
+
+## Accomplishments
+
+### Mac support verified end-to-end
+- **Apple Clang 17.0.0** + Homebrew libomp 22.1.3 + Ninja → builds cleanly.
+- **OpenMP 5.1** active, **HiGHS** built from source, **Gurobi 1301** auto-detected at `/Library/gurobi1301/macos_universal2/` via the new FindGUROBI macOS branch.
+- **67/67 C++ unit tests pass** (2 CUDA tests correctly skipped; Apple dropped NVIDIA drivers in Mojave). Test time: ~35 s.
+
+### Build system — macOS gap closed
+- `cmake/FindGUROBI.cmake`: added `APPLE` branch with `/Library/gurobi*/macos_universal2` → `/Library/gurobi*/mac64` fallback. Added `elseif(APPLE)` branch that globs `libgurobi*.dylib` (previously `.so`-only on non-Windows).
+- `CMakePresets.json`: `clang-macos` preset now pins `/usr/bin/clang++` (not `clang++`) because Homebrew LLVM shadows Apple Clang and LLVM 21's libc++ has a `std::__1::__hash_memory` symbol that HiGHS doesn't link against. Added matching `buildPresets` + `testPresets` entries (previously `clang-win` only).
+- `CMakeLists.txt`: Gurobi "not found" warning now includes `/Library/gurobi1301/macos_universal2` as an example path.
+- `.github/workflows/macos-unit.yml`: now installs Ninja, uses the `clang-macos` preset, enables `DTWC_ENABLE_HIGHS`, tests Release config (was Debug, inline cmake without preset).
+
+### Code safety
+- `dtwc/soft_dtw.hpp`: `softmin_gamma` has a debug `assert(gamma > 0)`; `soft_dtw` and `soft_dtw_gradient` throw `std::invalid_argument` on `gamma <= 0`. Previously: silent `inf`/`NaN` from `1/gamma` at line 50.
+- `dtwc/types/Index.hpp`: `operator-(difference_type)` has `assert(ptr >= diff)` — defensive guard against size_t underflow (in practice safe on 64-bit; assert documents the assumption).
+- `dtwc/Problem.cpp:808`: resolved TODO. k-medoids objective uses **raw** DTW distances (not squared); replaced the TODO with a clarifying comment. k-means uses squared Euclidean; different algorithm, different objective.
+- `tests/unit/adversarial/test_fast_pam_adversarial.cpp:422`: `N_repetition=1` → `N_repetition=10` for the "Identical series get same cluster label" test. Removes a platform-specific RNG assumption (seed 12345 produced degenerate init on Apple libc++ but not MSVC). Now relies on the min-cost invariant which *any* correct k-medoids must satisfy with enough restarts.
+- `tests/unit/unit_test_clustering_algorithms.cpp`: changed `output_folder = "."` → `std::filesystem::temp_directory_path()`. Tests no longer pollute the working directory with `test_clustering*.csv` files when run from the repo root.
+
+### AI-Assisted Workflow (Claude Code slash commands)
+New directory `.claude/commands/` with 7 commands:
+- `/cluster` — full pipeline (load → method → cluster → evaluate → save)
+- `/distance` — single pair or pairwise matrix, with variant comparison
+- `/evaluate` — Silhouette / DBI / CH / Dunn / inertia, plus ARI/NMI when ground truth provided
+- `/convert` — CSV ↔ Parquet ↔ Arrow IPC ↔ HDF5
+- `/visualize` — clusters / silhouette / distance matrix / warping path / elbow
+- `/help` — read-only reference (algorithm selection, variants, tuning)
+- `/troubleshoot` — read-only diagnosis (build, runtime, performance)
+
+Design principles: progressive disclosure (ask min info, fill sensible defaults), script generation (produces reusable `.py` files), graceful fallback (Python → CLI), cross-referencing (each suggests related commands), least-privilege tool scoping (read-only for `/help` and `/troubleshoot`).
+
+### Cleanup — PII and obsolete artifacts purged
+Removed from git tracking (28 files, ~607 KB):
+- `.claude/reports/` (8 completed session plans)
+- `.claude/summaries/` (3 stale handoffs containing `/data/engs-unibatt-gp/engs2321/` paths)
+- `.claude/superpowers/specs/` (1 stale roadmap, items tracked in `.claude/TODO.md`)
+- `benchmarks/results/*.json` (16 machine-specific timing snapshots from phases)
+
+Updated `.gitignore` to exclude these directories going forward. No PII remains in tracked files — verified via `git grep 'engs2321\|engs-unibatt'` (only hits are `scripts/slurm/env.example` placeholders and the public ARC hostname in `docs/.../slurm.md`, both acceptable).
+
+### Documentation
+- `README.md`: new **macOS (Apple Clang + Homebrew libomp)** subsection; `pip install` → `uv pip install` (project convention per `.claude/CLAUDE.md` rule 6); new **AI-Assisted Workflow** section.
+- `docs/content/getting-started/ai-commands.md`: **new page** (weight: 7). Full command reference, example workflow, design principles, extension guide.
+- `.claude/cpp-style.md`: C++17 → **C++20**; compiler minimums updated (GCC 11+, Clang 14+, Apple Clang 15+, MSVC 17.8+). Was stale since the C++20 migration.
+- `CHANGELOG.md`: Unreleased section gained four subsections — macOS support, AI-Assisted Workflow, Fixed (code safety + test artifacts), Changed (Cleanup).
+
+## Decisions (with rationale)
+
+1. **Apple Clang over Homebrew LLVM in the macOS preset.** Homebrew LLVM 21 has a libc++ ABI break (`std::__1::__hash_memory` unresolved) that breaks HiGHS linking. Apple Clang 17 works identically to CI. Pinning `/usr/bin/clang++` is explicit and avoids surprises on machines with both installed.
+
+2. **Min-cost property over seed-specific init for the test fix.** Any correct k-medoids algorithm with multiple restarts must find the min-cost partition on trivially separable data. Relying on this invariant is platform-robust; relying on "seed 12345 → specific init" is not.
+
+3. **Delete session artifacts rather than sanitize.** The `.claude/reports/` files describe work already committed; their historical value is in `git log`. Keeping them adds noise and invites stale-content drift.
+
+4. **Slash commands in `.claude/commands/` not `.claude/skills/`.** `.claude/skills/` is for author-invoked capability skills (the three existing `*-wrapper-skill.md` files). `.claude/commands/` is the user-invokable slash command convention for Claude Code, discovered automatically.
+
+## Open questions / known caveats
+
+- **Python (`uv pip install .`) fails on this macOS machine** with an isolated build-env ninja error (`/Users/engs2321/.cache/uv/builds-v0/.tmpXXX/bin/ninja '--version' failed with: 1`). Unrelated to code — appears to be a uv build-isolation sandbox issue. C++ tests pass, so functionality is intact. Likely fine on CI (cibuildwheel configures its own env).
+
+- **llfio develop branch** has a libc++ deprecation warning (`char_traits<std::byte>` is deprecated in libc++ 17+). Non-fatal. Might warrant an llfio version pin eventually.
+
+- **Python binding tests not exercised** this session due to the install issue above. CI covers them on Linux/Windows/macOS via cibuildwheel.
+
+- **v2.0.0 → next version bump:** the Unreleased section is substantial (Arrow I/O, float32, SLURM, chunked CLARA, std::span API change, C++20 requirement, now macOS + AI commands). The `std::span` public-API change is semver-major → v3.0.0 would be appropriate. Not actioned this session.
+
+## Next steps (if continuing)
+
+1. Commit the changes. Suggested groupings:
+   - Commit A: macOS build support (FindGUROBI, CMakePresets, macos-unit.yml, CMakeLists warning, README)
+   - Commit B: code safety (soft_dtw, Index, Problem.cpp TODO)
+   - Commit C: test robustness (fast_pam adversarial, clustering_algorithms output_folder)
+   - Commit D: cleanup (deleted reports/summaries/superpowers/benchmarks-results, .gitignore, cpp-style C++20)
+   - Commit E: AI slash commands (`.claude/commands/*`, ai-commands.md docs page, README section)
+   - Commit F: CHANGELOG
+
+2. Push to CI — macOS workflow will be the first to exercise the new preset + HiGHS + Ninja path.
+
+3. Consider tagging v3.0.0 given the accumulated Unreleased changes (span API, C++20 minimum are breaking).
+
+4. Optional: address the llfio deprecation warning by pinning to a tagged release.
+
+## Files changed summary
+
+```
+Modified (13):
+  .claude/cpp-style.md
+  .github/workflows/macos-unit.yml
+  .gitignore
+  CHANGELOG.md
+  CMakeLists.txt
+  CMakePresets.json
+  README.md
+  cmake/FindGUROBI.cmake
+  dtwc/Problem.cpp
+  dtwc/soft_dtw.hpp
+  dtwc/types/Index.hpp
+  tests/unit/adversarial/test_fast_pam_adversarial.cpp
+  tests/unit/unit_test_clustering_algorithms.cpp
+
+New (9):
+  .claude/commands/cluster.md
+  .claude/commands/convert.md
+  .claude/commands/distance.md
+  .claude/commands/evaluate.md
+  .claude/commands/help.md
+  .claude/commands/troubleshoot.md
+  .claude/commands/visualize.md
+  docs/content/getting-started/ai-commands.md
+  .claude/summaries/handoff-2026-04-11-mac-support-ai-commands.md  (this file)
+
+Deleted (28): see git status
+```
+
+Plan file: `/Users/engs2321/.claude/plans/spicy-sparking-pizza.md`.