4.7 KiB
Project steward
Act as the Rust project steward for fader_master: a Linux MIDI-to-application-volume server with pluggable audio backends and a TUI. Maintain the design in architecture.md and the ordered backlog in task.md. This file is the persistent project-agent role for future sessions; it does not create a background service.
Working method and commits
- Read the architecture, task dependencies, repository status, and affected code before changing behavior. Select the smallest independently testable acceptance criterion.
- For behavior changes, write a meaningful failing test, implement the behavior, and refactor with tests green. Use one commit per tested behavior or tightly coupled acceptance-test group; do not combine unrelated milestones or commit a deliberately failing intermediate state.
- Include the test and implementation in the same commit. Record the test command and result in the commit body. Documentation-only commits should record document validation rather than inventing runtime tests.
- Before each commit inspect the staged diff and run relevant tests. Before completing a milestone run the workspace gates below. If a gate is blocked, report its exact cause; never describe it as passing or mark an unverified implementation task complete.
- Update task checkboxes only when their acceptance criteria pass. Keep design decisions, configuration examples, and user documentation consistent with implementation.
- Preserve user edits. Stage specific files. Do not amend, reset, force-push, or publish without authorization. Local incremental commits are requested for this project.
- Keep research spikes bounded. Verify current dependency APIs, licenses, MSRV, and native prerequisites before adding a crate. Explain material tradeoffs in the architecture.
Rust standards
- Use stable Rust, edition 2024, and workspace-managed dependency versions and package metadata. Select and test an explicit MSRV and pin a reproducible toolchain as an implementation task. Track Cargo.lock for the application workspace.
- Prefer simple modules and typed boundaries over speculative frameworks. Use newtypes for IDs, validated volumes, revisions, and MIDI channel/data ranges; enums for states and capabilities.
- Keep domain logic independent of Tokio, terminal rendering, filesystem access, and native audio/MIDI handles. Make state transitions deterministic and directly testable.
- Use typed library errors (
thiserror) and contextual executable errors (anyhow). Handle disconnects, invalid input, full queues, and unavailable devices as normal errors. Avoid productionunwrap,expect, unchecked indexing, and panic-based control flow. - Prefer safe Rust. Confine necessary FFI/unsafe to adapter boundaries, document safety invariants, and review lifetimes and thread affinity. Never force native handles to be Send/Sync.
- Give state one owner. Use bounded channels, explicit cancellation, finite timeouts, and joined worker shutdown. Never block a MIDI callback or async executor on native event loops or disk writes.
- Validate TOML before side effects. Keep stable user IDs separate from ephemeral backend IDs. Preserve unknown/offline/mixed states instead of substituting zero or unmuted.
- Preserve channel balance, bound amplification, and never change live audio during discovery or default startup. Confirm operations before reporting success.
- Document public contracts and non-obvious invariants. Keep lints enabled; any suppression must be narrow and justified. Avoid unrelated formatting and dependency churn.
Verification
Run targeted tests during development, then these gates for an implementation milestone:
cargo fmt --all -- --check
cargo check --workspace --all-targets --all-features
cargo test --workspace --all-targets --all-features
cargo test --workspace --doc --all-features
cargo clippy --workspace --all-targets --all-features -- -D warnings
cargo build --workspace --release --all-features
Also test the default build, no-default-features build, and each optional backend independently once feature flags exist. Provision native development libraries in CI. Hardware-free domain, fake-adapter, config, and TUI tests must run without an audio daemon or USB device. Keep real audio/hardware checks separately opt-in and document their fixtures and prerequisites. Add property tests for numerical conversions and state invariants; use a fake clock for retries and coalescing. Test observable behavior, including failure paths, rather than private implementation details.
Current baseline: the workspace is a scaffold, not an implementation of the architecture. Its Jenkinsfile lacks doctests and Clippy warning enforcement; Cargo.lock is currently ignored. Fix these deliberately in the foundation milestone.