Diablo_ClaudeMD_Ricing_example/.github/instructions/rust.instructions.md

applyTo
**/*.rs,**/Cargo.toml,**/Cargo.lock

Rust Instructions — Syn_OS Development

Project Context

Syn_OS is a sovereign AI-assisted Cognitive Hyper-OS built on Arch Linux. Current state: v21 "First Breath" — 92 crates, custom kernel modules, GRIMOIRE gamified training system. Repo path on : <repo-path> Lib\stuff\Development\Syn_OS{Master Repo}

Rust Edition and Toolchain

• Rust 2021 edition
• Stable toolchain preferred, nightly only for documented features
• Target: x86_64-unknown-linux-gnu (primary), cross-compile configs for ARCANUM nodes

Code Style

• Run cargo fmt before every commit — no exceptions
• Enable clippy::pedantic in all crates
• Prefer thiserror for library errors, anyhow for binary/CLI errors
• Use tracing over log for structured logging
• Prefer tokio for async runtime (single-threaded where possible to conserve resources)

Safety Rules

• No unsafe blocks without:
  1. A documented justification comment explaining why safe alternatives are insufficient
  2. An Aegis (SAST agent) audit pass
  3. A // SAFETY: comment block per Rust convention
• Minimize FFI surface area — wrap all C interop in safe abstractions
• Use cargo deny for license and vulnerability audits on all dependencies
• Use cargo audit in CI for known vulnerability detection

Performance Constraints

• has RAM and — be memory-conscious
• Prefer cargo check over cargo build during development iteration
• Use incremental compilation (default, but don't disable it)
• Profile before optimizing — use cargo flamegraph for hot path analysis
• Avoid unnecessary allocations in hot paths — prefer stack allocation and borrowing

Crate Organization

• Each crate must have a clear single responsibility documented in its Cargo.toml description
• Workspace-level dependency management via [workspace.dependencies]
• Feature flags for optional functionality — don't compile what you don't need
• Internal crates use path dependencies, external crates use version pinning

Testing

• Unit tests in the same file (#[cfg(test)] module)
• Integration tests in tests/ directory
• Use proptest or quickcheck for property-based testing on parsers and data structures
• Minimum code coverage target: 60% for new crates, improving over time
• Vanguard (QA agent) runs test suites as part of the /audit pipeline

Documentation

• All public items must have doc comments (///)
• Include # Examples section in doc comments for non-trivial functions
• Run cargo doc --no-deps to verify documentation builds cleanly
• README.md in each crate root with architecture overview

Dependency Policy

• Audit all new dependencies with cargo deny check before adding
• Prefer crates with: >1000 downloads, active maintenance, permissive license (MIT/Apache-2.0)
• Document the reason for each dependency in Cargo.toml comments
• No pre-1.0 crates in critical paths without stability justification