tuicommander: Instructions file for Claude Code

TUICommander — Project Rules

Doc Sync

Read docs/sync-matrix.md before any feature/API/config change — it maps code areas to docs that MUST be updated.

Tests

• Run standalone Rust, Vitest, and plugin test commands through scripts/with-test-tmp.sh; make check, make test-shell, make cov, and make mutants set their own repository-local test temp root. This does not apply to make dev or cargo run.

• Bare cargo test Rust test binaries initialize TMPDIR, TMP, and TEMP from TUIC_TEST_TMP_ROOT or this checkout's .tmp/tuic-tests before libtest starts; Nextest does the same for every test binary through .config/nextest.toml setup scripts. New Rust tests must use test_temp_root() or assert their scratch paths stay inside it. Neither mechanism changes make dev or cargo run.

• Test only the changed behavior. Routine validation MUST use the narrowest test filters that cover the production code, protocol surface, fixtures, or test support changed by the task. Do not run full-crate, full-app, full-tree, or unrelated suites merely for reassurance; they waste shared build time and obscure relevant evidence. Expand beyond targeted tests only when a documented gate explicitly requires it, targeted evidence proves a cross-cutting risk, or Boss explicitly asks for the broader run.

• Tests are the spec. When a test fails after a code change, investigate BOTH sides before deciding which to fix.

• Finding a story partially implemented does NOT mean it's done. When you pick up a story and discover the feature already exists, verify EVERY part of the story is honored — each acceptance criterion, edge case, and requirement — before marking it complete. Never assume the whole story is satisfied just because one part is implemented. Check each criterion against the code and prove it, or the story isn't done.

• to-test.md tracks features awaiting manual testing — add items there for minor features.

• Mutation testing is per change, never per tree. make mutants RANGE=<base> (default HEAD~1) runs cargo-mutants --in-diff over the Rust lines the range touched, --in-place in a disposable git archive export under .tmp/ (not a worktree: a detached worktree is an orphan to the running app, which removes it), one job, through mbx. Every viable mutant costs one incremental build of the lib crate plus one test run, so the orchestrator runs it once per batch on the final HEAD — agents do not. A surviving mutant is a missing test: add the test, or #[mutants::skip] with the reason on the line. Measured 2026-09-06: baseline 197 s build + 224 s test with warm deps; each mutant ~3 min incremental build of the lib crate plus 0.5–3.5 min of tests, so ~5 min each and a 38-mutant story diff is ~3 h. During the day pass a function filter through the script (scripts/mutants.sh HEAD~1 --re <function>); the whole diff is an overnight or CI job. Config in src-tauri/.cargo/mutants.toml, mechanics in scripts/mutants.sh.

• Function-filtered mutation runs through make can use make mutants RANGE=<base> -- --re <function>; use MUTANTS_ARGS='--re <function>' for filters containing spaces or other complex arguments.

• [HUMAN] is a last resort. Before marking a to-test item [HUMAN], you MUST attempt verification through this escalation ladder:

  1. Code inspection — read the source, confirm the logic exists at file:line
  2. Test execution — cargo nextest run (doctests: cargo test --doc), vitest run with relevant filter
  3. CLI probing — curl HTTP endpoints, grep for patterns
  4. MCP maccontrol — take screenshots, click UI elements, verify visual state
  5. MCP invoke/JS — call Tauri commands, inspect store state, trigger actions programmatically Only use [HUMAN] when the item genuinely requires real hardware (audio, IME, touch), multi-app interaction (drag to Finder, global hotkey from another app), or timing-sensitive observation that none of the above can capture. When code-verifying, change [HUMAN] to [x] with a _(verified: file:line explanation)_ annotation. When code reveals the description is wrong, change to [ ] with a _(NOTE: ...)_ correction.