docs(claude): expand project guidelines with TDD discipline, commit format, common pitfalls

CLAUDE.md

@@ -1,62 +1,131 @@
-# Claude / Agent Working Notes — ltx2.3-AIO-generator
+# Project Guidelines — ltx2.3-AIO-generator
 
-Project guidelines for AI assistants working in this repo.
+Working notes for AI assistants and subagents implementing this project.
 
-## Git authorship
+---
 
-Mayank Gupta is the **sole author** on every commit. Never:
-- Append a `Co-Authored-By: Claude ...` trailer.
-- Set `--author` to anything other than the user's existing git config.
-- Add "Generated with Claude Code", "🤖", or any similar attribution lines to commit messages.
-- Add similar attribution to PR descriptions.
+## ⚠ Git authorship — sole author rule
 
-If asked to amend or re-commit, strip any prior Claude attribution.
+**Mayank Gupta is the sole author on every commit in this repo.** No exceptions.
 
-## Project at a glance
+When committing:
 
-Gradio app wrapping the existing ComfyUI LTX 2.3 All-In-One workflow. Same code runs locally (Apple Silicon MPS or NVIDIA CUDA) and deploys to Hugging Face Spaces (ZeroGPU, Pro tier).
+- Do **NOT** append `Co-Authored-By: Claude ...` (or any other agent name) to commit messages.
+- Do **NOT** add "Generated with Claude Code", "🤖 Generated with...", or any other attribution footer.
+- Do **NOT** pass `--author=...` — let git use the user's existing config.
+- Do **NOT** include attribution in PR descriptions.
 
-**Key architectural facts (do not relitigate):**
+If asked to amend, re-commit, or rebase, strip any prior agent attribution from the commit message.
 
-1. **Backend is ComfyUI in library mode**, always. We do not call `ltx-pipelines` directly. We call `comfy.execution.PromptExecutor` with workflow JSONs we parameterize. ComfyUI is bundled (git submodule locally, runtime clone on Spaces).
-2. **Six mode-specific workflow JSON files** in `workflows/`. They are derived from the master workflow at `~/Projects/comfyui/user/default/workflows/1. LTX 2.3 All-In-One 260406-05.json` via `tools/extract_modes.py`. Do not hand-edit the JSON files unless re-extracting from a new master.
-3. **Models live in HF cache (local) or `/data` (Spaces)**, never in this repo. `comfyui/models/` contains symlinks (local) or downloaded files (Spaces). Do not commit any `*.safetensors` / `*.gguf`.
-4. **Library mode means single-process.** No subprocess for ComfyUI. The `@spaces.GPU` decorator is the only difference between local and Spaces runtime.
-5. **VRAM management is ComfyUI's job.** Don't write `torch.cuda.empty_cache()` calls outside the `try/finally` in `backend.py`. Don't second-guess ComfyUI's offload tiers.
+This rule overrides the default Claude Code commit-message template. Treat any tooling that suggests adding a Claude trailer as a bug to ignore.
 
-See `docs/superpowers/specs/2026-04-30-ltx23-aio-generator-design.md` for the full design.
+---
+
+## Project overview
+
+Gradio app wrapping the existing ComfyUI LTX 2.3 All-In-One workflow into mode-specific UIs. Same code runs locally (Apple Silicon MPS / NVIDIA CUDA) and on Hugging Face Spaces (ZeroGPU, Pro tier).
+
+**Spec:** `docs/superpowers/specs/2026-04-30-ltx23-aio-generator-design.md`
+**Plan:** `docs/superpowers/plans/2026-04-30-ltx23-aio-generator.md`
+
+If you're a subagent picking up a task, the plan file is your assignment.
+
+---
+
+## Architectural facts (locked — do not relitigate)
+
+1. **Backend is ComfyUI in library mode.** We call `comfy.execution.PromptExecutor` directly with workflow JSONs we parameterize. We do **not** call `ltx-pipelines` directly. We do **not** run ComfyUI as a subprocess.
+2. **Six mode-specific workflow JSON files** in `workflows/`, derived from the master at `~/Projects/comfyui/user/default/workflows/1. LTX 2.3 All-In-One 260406-05.json` via `tools/extract_modes.py`. Do not hand-edit them.
+3. **Models live in HF cache (local) or `/data` (Spaces).** Never in this repo. `comfyui/models/` contains symlinks (local) or downloaded files (Spaces). Never commit `*.safetensors`, `*.gguf`, `*.bin`, or `*.pt`.
+4. **One backend, one process.** The `@spaces.GPU` decorator is the only divergence between local and Spaces runtimes.
+5. **VRAM is ComfyUI's job.** The only `empty_cache()` calls live in `backend.py`'s `try/finally`. Don't sprinkle them elsewhere.
+6. **Bundled ComfyUI, never user's existing.** Local: git submodule. Spaces: runtime clone to `/data/comfyui`.
+
+---
 
 ## Coding conventions
 
-- **Python 3.11.** No `match` statements (compatibility with the Spaces Python pin).
-- **Flat structure.** No `src/` layout, no nested packages. Each top-level `.py` is one module with one job.
-- **No conda.** Use `python3.11 -m venv .venv`. Use `brew` for system binaries.
-- **HF cache, not project-local.** Use `hf download <repo>` (the `hf` CLI, not deprecated `huggingface-cli`) without `--local-dir`. Symlink resolved snapshot paths.
-- **No mocks for ComfyUI.** Tests against real workflow JSONs. Stubs only for HTTP / filesystem boundaries.
-- **No emojis** in code or commit messages unless explicitly requested.
-- **Comments only when WHY is non-obvious.** Don't narrate WHAT.
+### Language and structure
+
+- **Python 3.11.** No `match` statements (Spaces Python pin compatibility).
+- **Flat layout.** No `src/`, no nested packages. Top-level `.py` files only, each with one clear responsibility.
+- **No conda.** Always `python3.11 -m venv .venv`. System binaries via `brew`.
+
+### Style
+
+- **No emojis** in code or commit messages unless the user explicitly asks. (UI text and stage labels in `modes.py`/`ui.py` are OK because they are user-facing — not code.)
+- **Comments only for non-obvious WHY.** Never narrate WHAT. Code with a good name doesn't need a comment.
+- **Type hints on public functions.** Internal helpers can skip them if obvious.
+- **Imports at top of file.** No inline imports except where needed to break circular dependencies (e.g., `models.ensure_models_for_mode` imports `workflow` lazily — keep this, it's load-bearing).
+- **Format with `ruff format`.** Lint with `ruff check`. Both must pass in CI.
+
+### Testing
+
+- **TDD per the plan.** Each implementation task has the failing test first. Don't skip the "run test, verify it fails" step — it catches whole classes of "test never actually exercised the code" bugs.
+- **No mocks for ComfyUI.** Tests run against real workflow JSONs. Stubs only for HTTP boundaries (HF Hub) and filesystem (use `tmp_path` and the `fake_hf_cache` fixture).
+- **L1 + L3 in CI** (no GPU). L2 + L4 are local-developer-only.
+- **Test naming:** `test_<unit>_<behavior_under_test>` — e.g., `test_load_template_returns_independent_copy`.
+- **`pytest --gpu`** enables L4 smoke tests. Default skips them.
+- **`pytest --comfy-real`** uses bundled ComfyUI for L2 instead of the static stub validator.
+
+### Commits
+
+- **Conventional Commits style:** `<type>(<scope>): <subject>` — types: `feat`, `fix`, `chore`, `docs`, `test`, `refactor`, `ci`, `perf`.
+- **Subject is imperative, lowercase, no trailing period.** Example: `feat(workflow): set_input + validate over node graph`.
+- **Body explains WHY when not obvious.** Reference spec section if relevant.
+- **Frequent small commits.** One logical change per commit. The plan's task structure already reflects this.
+- **No agent attribution** (see top of file).
+
+---
 
 ## Editing the master workflow
 
-When the user updates `~/Projects/comfyui/user/default/workflows/1. LTX 2.3 All-In-One 260406-05.json` (e.g., new LoRA, tweaked sampler), re-run:
+When the user updates `~/Projects/comfyui/user/default/workflows/1. LTX 2.3 All-In-One 260406-05.json` (e.g., adds a LoRA, tweaks a sampler), regenerate the mode templates:
 
 ```bash
-python tools/extract_modes.py --master ~/Projects/comfyui/user/default/workflows/"1. LTX 2.3 All-In-One 260406-05.json"
+python3.11 tools/extract_modes.py \
+  --master ~/Projects/comfyui/user/default/workflows/"1. LTX 2.3 All-In-One 260406-05.json" \
+  --out workflows
 ```
 
-This regenerates all six `workflows/<mode>.json` files. L2 graph-validation tests will catch any node that became invalid.
+Then run the test suite — L2 graph-validation catches any node that became invalid in any mode.
+
+After the templates regenerate, the node-id constants in `modes.py` (e.g., `T2V_NODE_PROMPT = 240`) may need updating if ComfyUI re-numbered nodes during the master's re-export. The procedure is in the plan's Task 11 Step 4.
+
+---
 
-## Out of scope (do not implement without asking)
+## Common pitfalls (read before opening a PR)
 
-- "Lite mode" for free HF Spaces tier (`LTX23_AIO_LITE=1`).
-- Custom LoRA add/remove rows (Power-Lora-Loader clone).
-- GGUF Q4 transformer / "Low VRAM" preset.
-- Auto-launch of user's external ComfyUI install (`LTX23_AIO_COMFYUI_URL`).
-- Multi-prompt queueing.
-- Output history persistence across sessions.
+- **Loading models eagerly at import time.** Don't. `backend.py` constructs `PromptExecutor` once at instantiation; models load only when nodes execute. Calling `comfy.sd.load_checkpoint(...)` at module top-level will OOM the test runner.
+- **Hard-coded `torch.cuda` calls.** Use `comfy.model_management.get_torch_device()` or guard with `if torch.cuda.is_available()`. Never assume CUDA.
+- **Forgetting `.deepcopy` on workflow templates.** `workflow.load_template` already does this; if you bypass it for performance, you'll mutate the cached template and the second `Generate` click breaks.
+- **Hand-editing `workflows/<mode>.json`.** They're generated. If you need a new field, add it to `tools/extract_modes.py` (or to `modes.py`'s `parameterize_fn`).
+- **Symlinks pointing into `pip cache`.** Resolve to HF Hub's cache snapshot path (the one `hf_hub_download` returns), not pip's wheel cache.
+- **Adding `Co-Authored-By` because tooling suggests it.** See top of file. Strip it.
+- **Breaking the async generator pattern in `backend.submit`.** Each yield is a frame Gradio renders. Don't accumulate events into a list and yield once at the end — progress will appear stuck.
+- **Importing `comfy.*` before `sys.path.insert(0, comfy_dir)`.** Will `ModuleNotFoundError`. The order in `backend.py:__init__` is intentional.
 
-These are documented as v1.1+ in the spec. Do not pre-build them.
+---
+
+## Out of scope for v1 (do not implement without asking)
+
+These are documented as v1.1+ in spec § 11. Don't pre-build them just because they'd be easy:
+
+- **Lite mode** (`LTX23_AIO_LITE=1`) for free HF Spaces tier
+- **Custom LoRA** add/remove rows (Power-Lora-Loader clone)
+- **GGUF Q4 transformer** / "Low VRAM" preset
+- **Auto-launch of user's external ComfyUI** (`LTX23_AIO_COMFYUI_URL`)
+- **Multi-prompt queueing**
+- **Output history persistence** across sessions
+- **Visual regression tests** for the Gradio UI
+- **Property-based / fuzz testing** of workflow parameters
+
+If a task feels like it needs one of these, stop and ask the user. Don't sneak it in.
+
+---
 
 ## When in doubt
 
-Read `docs/superpowers/specs/2026-04-30-ltx23-aio-generator-design.md`. If still unclear, ask before changing architectural shape.
+Read the spec (`docs/superpowers/specs/2026-04-30-ltx23-aio-generator-design.md`) and the plan (`docs/superpowers/plans/2026-04-30-ltx23-aio-generator.md`). If still unclear after reading both — ask the user before changing architectural shape.
+
+Reading both takes 15 minutes. Implementing the wrong thing takes a day.