docs(rules): the parity rule governs behaviour, not performance (#1315)

An automated reviewer raised a Critical asking for torch.compile to be disabled by default on every platform "so the default is uniform", citing the cross-platform parity rule. Following it would have slowed down every Linux CUDA user to match hosts that cannot compile at all. Read literally, the rule forbids GPU support: CUDA, MPS, DirectML and Triton availability are all host-dependent by design. It was always about what a user can SEE AND DO, not about throughput — so it now says that, in CLAUDE.md and AGENTS.md, and .coderabbit.yaml tells the reviewers directly so the finding stops regenerating every month. An optimization skipped where it physically cannot work is not a parity violation. A feature usable on one OS but not another still is. Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
2026-07-29 15:36:41 -07:00
parent 42d017ef9b
commit 2de27038d9
3 changed files with 11 additions and 2 deletions
@@ -98,7 +98,11 @@ reviews:
        access accordingly; window and webview lifecycle on all three OSes;
        child-process spawn/exit-code/stderr handling; no unwrap/expect on
        user-controlled input; platform cfg blocks keep user-visible defaults
-        identical across macOS/Windows/Linux.
+        identical across macOS/Windows/Linux. The parity rule covers BEHAVIOUR,
        not PERFORMANCE: hardware acceleration is host-dependent by design
        (CUDA/MPS/DirectML, Triton availability, torch.compile), so an
        optimization skipped where it cannot work is NOT a parity violation and
        must not be reported as one.
    - path: "tests/**/*.py"
      instructions: >-
        Review as a test-infrastructure engineer. Check: the test would fail
@@ -11,6 +11,11 @@ Binding for every AI agent (Claude, Codex, Cursor, review bots, …). CLAUDE.md
 - Run targeted tests while iterating; full suites only before landing.
 - Tests and CI simulate CI honestly: `HF_HUB_OFFLINE=1` + empty `HF_HUB_CACHE` — a populated dev cache masks real failures.
 ## Cross-platform parity: behaviour, not performance
 - The parity rule covers user-visible BEHAVIOUR. Hardware acceleration varies by host by design (CUDA/MPS/DirectML, Triton availability, `torch.compile`); skipping an optimization where it physically cannot work is not a parity violation.
 - Do not "fix" a parity finding by disabling a working optimization everywhere. That trades a real regression for a semantic one.
 - A feature the user can see and use on one OS but not another IS a violation. Judge by what the user can do, not by how fast it runs.
 ## Merge protocol (hard rules)
 1. Never merge without review. Harvest CodeRabbit + Greptile comments first; never merge with an unread Critical/P1.
 2. Never accept a PR as-is: fix findings ON the PR branch pre-merge (maintainer commits fine; credit contributors in CHANGELOG). No merge-then-fix, no comment-and-walk-away.
@@ -13,7 +13,7 @@ Everything else (new engines, fancy features) is downstream of "the thing instal
 - **Existing engine compatibility**: Users with already-installed engines (IndexTTS, CosyVoice, etc.) must not have to reinstall. Fixes touching engine code must be backward-compatible with on-disk model state.
 - **Cross-platform parity**: Every fix must work on macOS (Apple Silicon + Intel), Windows (x64), and Linux (AppImage + deb). No platform-only regressions; the cross-platform bug bash (PR #51) is the baseline.
- **Default features must work on every platform (strict rule, 2026-05-20):** A feature that ships in default mode — out-of-the-box, no user customization, no opt-in toggle — must behave identically on macOS, Windows, and Linux. Platform-specific *implementation code* is allowed for OS APIs / shells / packaging, but the user-visible *default behavior* cannot diverge. Platform-only features (e.g., a macOS-only global shortcut, a Windows-only path picker) must go behind explicit user opt-in: Settings toggle, env var, or CLI flag. When a default doesn't work on a platform, that's a P0 bug — either fix it on the missing platform or move it behind opt-in. No third option.
+- **Default features must work on every platform (strict rule, 2026-05-20):** A feature that ships in default mode — out-of-the-box, no user customization, no opt-in toggle — must behave identically on macOS, Windows, and Linux. Platform-specific *implementation code* is allowed for OS APIs / shells / packaging, but the user-visible *default behavior* cannot diverge. Platform-only features (e.g., a macOS-only global shortcut, a Windows-only path picker) must go behind explicit user opt-in: Settings toggle, env var, or CLI flag. When a default doesn't work on a platform, that's a P0 bug — either fix it on the missing platform or move it behind opt-in. No third option. **This rule governs BEHAVIOUR, not PERFORMANCE** (clarified 2026-07-30, council): hardware acceleration is expected to vary by host — CUDA, MPS, DirectML, Triton availability and `torch.compile` are all host-dependent by design, and reading the rule to forbid that would forbid GPU support itself. An optimization that is skipped where it cannot work (missing Triton, an arch the wheel lacks, a path its toolchain cannot link) is NOT a parity violation; a *feature* the user can see and use on one OS but not another is.
 - **Backward-compatible project data**: Existing `omnivoice_data/` (user voices, projects, settings) must keep working without manual migration. Any DB schema change goes through alembic with a tested upgrade path.
 - **Local-first guarantee preserved**: nothing leaves the machine without the user's **explicit yes**, and the app must remain fully functional with everything declined. Auto bug reporting is opt-in and submits only to GitHub Issues (prefilled-URL, from the user's own browser). Product analytics (owner-sanctioned 2026-07-16) is opt-in PostHog EU with a **first-run consent prompt** — two equal-weight Yes/No buttons, never default-on, skipping = off; consent-gated, allowlisted content-free metadata only (`backend/core/analytics.py`); every build — installer, Docker, and source alike (owner reversal 2026-07-20, #1193) — carries the in-repo publishable write-only token and shows the same consent ask, with env/baked token overriding it. No required cloud calls, accounts, or API keys.
 - **Beta release cadence (no RC, no ceremony — strict rule, 2026-05-20):** the v0.3.x line has **no release candidates, no 48h soak, no formal release ceremony**. Every fix goes continuous-to-main; the owner tags a patch (`v0.3.Z`) from main whenever the current state is worth cutting. No `-rc` tags. No phased release. No `v0.4` deferrals while the v0.3.x line is open — every open issue and every open community PR gets absorbed into the v0.3.x line or explicitly declined. Users follow `main` for previews; users wanting stable stay on the latest tagged release. ROADMAP.md's Phase 6 "Release/Verify/Retro" entries are obsolete unless the user revives them.