@coderabbitai full review

_{Comment @coderabbitai help to get the list of available commands.}

If you are interested these are the rules I had set to my AI. If you think any of these can be of help feel fre to pick them up

Asusctl Repository & Agent Governance Rules

This document outlines the strict guidelines, coding standards, daemon architecture rules, safety constraints, and Git workflow policies required when working on the asusctl repository.

1. Git & Workflow Guidelines

1.1. Never Bypass Git Hooks

• Strict Enforcement: Do NOT use --no-verify or -n flags with git commit or git push.
• Requirement: All commits and pushes must allow standard git hooks (pre-commit and pre-push) to execute and pass cleanly.

1.2. Explicit Push Authorization

• No Auto-Push: Never execute git push without explicit, real-time user approval.
• Single Event Scope: Approval applies strictly to that specific push event. Subsequent pushes require new, dedicated confirmation.

1.3. Clean Local Checks

Before creating any commit, the codebase must pass all local verification checks specified in Section 5.1 with zero errors and zero warnings.

1.4. Atomic Commits & Standardized Commit Messages

• Independently Buildable & Logical Commits: Each commit in the repository history must represent a single, self-contained, logical unit of work that is independently buildable and passes all local verification checks (Section 5.1).
• No Trailing Fix Commits: When bringing fixes, formatting adjustments, or lint resolutions for changes introduced in a feature branch, do NOT create trailing fix commits (e.g., fix text, fix clippy). Amend or rebase the fix directly into the relevant original commit so the git history consists strictly of clean, logical feature/refactor commits.
• Conventional Commit Standard: Commit messages must strictly follow Conventional Commits formatting (e.g., feat:, fix:, refactor:, docs:, chore:) to support automated CHANGELOG.md generation.

2. Rust Safety & Code Quality Rules

2.1. Prohibition of .unwrap()

• No Blind Unwraps: Avoid calling .unwrap() on Option or Result types in production daemon and library code to prevent runtime panics.
• Preferred Handling:
  • Use proper error propagation with the ? operator and RogError / custom domain errors.
  • Use pattern matching (match, if let) or safe fallback combinators (unwrap_or, unwrap_or_else, ok_or).
  • If a value is guaranteed to be present by prior invariant checks, use .expect("Clear explanation of why this cannot fail") instead of .unwrap().

2.2. Strict Control of unsafe Code

• Default Stance: Avoid unsafe blocks whenever safe Rust abstractions or standard library utilities can achieve the same result.
• FFI & Kernel Interactions: If an unsafe block is strictly necessary (e.g., raw C FFI calls or kernel ioctls), it must strictly follow these rules:
  1. Minimize the scope of the unsafe block to only the specific unsafe call.
  2. Mandatory Safety Documentation: Every unsafe block MUST be immediately preceded by a detailed // SAFETY: comment explaining why the invariants hold and why the operation is memory-safe and sound.

2.3. Extended Linting with cargo cranky

• Code changes must satisfy the strict lint set configured in Cranky.toml.
• Run cargo cranky to catch extra lints such as mutex integrity, unwanted todo! or unimplemented! macros, string allocation inefficiencies, and unhandled async locks.

2.4. Prohibition of println! in Favor of Structured Logging Macros

• No Direct Standard Output Printing: Avoid println! or eprintln! for status, warnings, or error reporting across daemon, library, and CLI modules.
• Standardized Logging & Error Propagation:
  • Use structured logging macros from the log crate (info!, warn!, error!, debug!, trace!).
  • Return explicit Err(...) variants or propagate errors using the ? operator instead of printing messages and swallowing failures with Ok(()).

3. Daemon & Architecture Design Patterns

3.1. Daemon Controller Pattern

• All controller components in asusd must implement standard daemon traits where applicable:
  • GetSupported: Checks if hardware/kernel features required by the controller are available.
  • Reloadable: For controllers requiring state reload on startup or signal.
  • CtrlTask: For background task loops, logind event handling (suspend/resume/boot), and file watching.
  • ZbusAdd: For exposing controller interfaces to the D-Bus system bus via zbus.

3.2. Concurrency & Locking Safety

• Async Mutex Usage: Controllers shared across tasks or D-Bus handlers must use async-compatible locks (e.g., Arc<Mutex<T>>).
• Deadlock Prevention in Task Loops:
  • Avoid blocking execution in event dispatch loops.
  • Use non-blocking try_lock() inside task event callbacks (e.g., self.create_sys_event_tasks(...)) to prevent thread deadlocks when system events fire concurrently.

3.3. D-Bus Interface Standards & Backward Compatibility (zbus)

• Implement D-Bus methods on dedicated wrapper structs (e.g., Ctrl<Name>Zbus).
• Use Self::add_to_server_helper under standard object paths (e.g., /org/asuslinux/<Feature>).
• Backward Compatibility: Preserve existing D-Bus signatures and object paths so external clients (rog-control-center, GNOME extensions, asusctl CLI) do not break.

3.4. Kernel & Sysfs Attribute Resilience across ASUS Laptop Models

• Extensive ASUS Hardware Diversity: ASUS produces a vast array of laptop series (ROG Strix, Zephyrus, TUF, ZenBook, Vivobook, ProArt, Ally) with varying ACPI/WMI tables, EC registers, sysfs attributes, and kernel driver support across Linux releases.
• No Single-Machine Invariant Assumptions: Never assume that a hardware feature, sysfs path, or ACPI WMI call present on one test machine exists or behaves identically on all ASUS laptops.
• Dynamic Probing & Graceful Feature Degradation: Always check path availability dynamically at runtime (GetSupported, non-blocking file checks, udev enumeration). If a hardware capability is missing or unsupported on a given model, degrade gracefully (or fallback to virtual software equivalents where applicable) without crashing the daemon or emitting spurious fatal errors.
• Strict Input/Output Parsing: Parse and validate all strings read from or written to sysfs/debugfs nodes before casting to Rust enums or numeric types.

3.5. Safe Configuration Schema & Fallbacks

• When modifying configuration structs (in config-traits or /etc/asusd/), always provide sensible default implementations (Default trait).
• Ensure schema updates support graceful fallback and migration so existing user configurations are never corrupted or reset silently during daemon upgrades.

4. Code Integrity & Error Handling

4.1. No Symptom Patching

• Never swallow exceptions, return dummy fallback values, or comment out failing assertions to make tests pass.
• Trace errors back to their root cause in hardware sysfs attributes, D-Bus messages, or async task orchestration.

4.2. Preserving Comments & Documentation

• Preserve all existing code comments, docstrings, and architectural descriptions unless explicitly asked to modify them.
• Document public functions, trait implementations, and D-Bus methods clearly.

5. Verification & Testing Protocol

5.1. Verification Before Completion

• Never mark a task as complete without empirical runtime verification.
• Always execute build and check commands:

  cargo check --all-targets
  cargo test --all
  cargo clippy --all -- -D warnings
  cargo cranky
  cargo fmt --all -- --check

5.2. Log Inspection

• Inspect full un-truncated logs (journalctl, asusd daemon logs, or test tracebacks) before diagnosing failures or proposing fixes.

@scardracs for the "Git & Workflow Guidelines" part, i think it'd be better to put it in CONTRIBUTING.md and tell AGENTS.md to read that file. i want to put things in files that both humans and llms can use together as much as possible, to reduce the development burden.

@coderabbitai emit path instructions

Failed to open a pull request for the updated path instructions: Cannot open a PR on a forked repository.