refactor: Standardize benchkit and unilang project structure

- Migrate benchmarks from tests/ to standard benches/ directory
- Update benchkit documentation to promote benches/ compliance
- Implement benchkit directory validation and error messaging
- Add comprehensive benchmark organization with proper cargo integration
- Move completed tasks to appropriate directories for better organization
- Clean up obsolete benchmark scripts and configuration files
- Enhance unilang library structure with new analysis modules
- Add performance documentation and optimization guides

Author: Wandalen

module/core/test_tools/src/standalone.rs

@@ -92,7 +92,7 @@ pub mod error_tools {
       pub use crate::{debug_assert_id, debug_assert_identical, debug_assert_ni, debug_assert_not_identical};
     }
 
-    /// Untyped error handling for error_tools compatibility
+    /// Untyped error handling for `error_tools` compatibility
     #[cfg(feature = "standalone_error_tools")]
     pub mod untyped {
       // Re-export anyhow functionality for untyped error tests
@@ -692,8 +692,8 @@ pub mod mem_tools {
 
   /// Compare if two references point to the same memory
   pub fn same_ptr<T1: ?Sized, T2: ?Sized>(src1: &T1, src2: &T2) -> bool {
-    let ptr1 = std::ptr::from_ref(src1).cast::<()>();
-    let ptr2 = std::ptr::from_ref(src2).cast::<()>();
+    let ptr1 = core::ptr::from_ref(src1).cast::<()>();
+    let ptr2 = core::ptr::from_ref(src2).cast::<()>();
     ptr1 == ptr2
   }
 
@@ -718,7 +718,7 @@ pub mod mem_tools {
   }
 
   /// Compare if two references point to the same memory region
-  /// This function accepts any sized or unsized types like the real mem_tools implementation
+  /// This function accepts any sized or unsized types like the real `mem_tools` implementation
   pub fn same_region<T1: ?Sized, T2: ?Sized>(src1: &T1, src2: &T2) -> bool {
     same_ptr(src1, src2) && same_size(src1, src2)
   }

module/move/benchkit/examples/cargo_bench_integration.rs

@@ -347,7 +347,7 @@ fn main() {
     println!("====================================");
     println!("✅ Seamless `cargo bench` integration (MANDATORY)");
     println!("✅ Automatic documentation updates during benchmarks");
-    println!("✅ Standard `benches/` directory support");
+    println!("✅ MANDATORY `benches/` directory usage (NO ALTERNATIVES)");
     println!("✅ Criterion compatibility for zero-migration adoption");
     println!("✅ CI/CD integration with standard workflows");
     println!("✅ Regression analysis built into benchmark process");
@@ -361,7 +361,13 @@ fn main() {
     println!("4. **Migration Friendly**: Existing criterion projects can adopt easily");
     println!("5. **Production Ready**: Suitable for CI/CD and enterprise environments");
 
-    println!("\n🚨 WITHOUT THESE FEATURES, BENCHKIT WILL FAIL TO ACHIEVE ADOPTION!");
+    println!("\n🚨 CRITICAL WARNING:");
+    println!("===================");
+    println!("ALL benchmarks MUST be in benches/ directory - NO EXCEPTIONS!");
+    println!("❌ NEVER put benchmarks in tests/ - they are NOT tests!");
+    println!("❌ NEVER put benchmarks in examples/ - they are NOT demonstrations!");
+    println!("✅ ONLY benches/ directory is acceptable for benchmark files!");
+    println!();
     println!("The Rust community expects `cargo bench` to work. This is non-negotiable.");
 }
 

module/move/benchkit/readme.md

@@ -758,25 +758,31 @@ fn main() -> Result< (), Box< dyn std::error::Error > >
 [ 5. Commit Code + Perf Docs ] <- [ 4. Auto-Update `benchmark_results.md` ] <- [ Analyze Results ]
 ```
 
-## 📁 Why Not `benches/`? Standard Directory Integration
+## 📁 MANDATORY `benches/` Directory - NO ALTERNATIVES
 
-The traditional `benches/` directory creates artificial separation between ALL your benchmark content and the standard Rust project structure. `benchkit` encourages you to use standard directories for ALL benchmark-related files:
+**ABSOLUTE REQUIREMENT**: ALL benchmark-related files MUST be in the `benches/` directory. This is NON-NEGOTIABLE for proper benchkit functionality:
 
-- ✅ **Use `tests/`**: Performance benchmarks alongside unit tests
-- ✅ **Use `examples/`**: Demonstration benchmarks and showcases  
-- ✅ **Use `src/bin/`**: Dedicated benchmark executables
-- ✅ **Standard integration**: Keep ALL benchmark content in standard Rust directories
-- ❌ **Avoid `benches/`**: Don't isolate ANY benchmark files in framework-specific directories
+- 🚫 **NEVER in `tests/`**: Benchmarks are NOT tests and MUST NOT be mixed with unit tests
+- 🚫 **NEVER in `examples/`**: Examples are demonstrations, NOT performance measurements  
+- 🚫 **NEVER in `src/bin/`**: Source binaries are NOT benchmarks
+- ✅ **ONLY in `benches/`**: This is the EXCLUSIVE location for ALL benchmark content
+
+**Why This Requirement Exists:**
+
+- ⚡ **Cargo Requirement**: `cargo bench` ONLY works with `benches/` directory
+- 🏗️ **Ecosystem Standard**: ALL professional Rust projects use `benches/` EXCLUSIVELY
+- 🔧 **Tool Compatibility**: IDEs, CI systems, linters expect benchmarks ONLY in `benches/`
+- 📊 **Performance Isolation**: Benchmarks require different compilation and execution than tests
 
 ### Why This Matters
 
-**Workflow Integration**: ALL benchmark content should be part of regular development, not isolated in framework-specific directories.
+**Ecosystem Integration**: The `benches/` directory is the official Rust standard, ensuring compatibility with the entire Rust toolchain.
 
-**Documentation Proximity**: ALL benchmark files are documentation - keep them integrated with your standard project structure for better maintainability.
+**Zero Configuration**: `cargo bench` automatically discovers and runs benchmarks in the `benches/` directory without additional setup.
 
-**Testing Philosophy**: Performance is part of correctness validation - integrate benchmarks with your existing test suite.
+**Community Expectations**: Developers expect to find benchmarks in `benches/` - this follows the principle of least surprise.
 
-**Toolkit vs Framework**: Frameworks enforce rigid `benches/` isolation; toolkits integrate with your existing project structure.
+**Tool Compatibility**: All Rust tooling (IDEs, CI/CD, linters) is designed around the standard `benches/` structure.
 
 ### Automatic Documentation Updates
 

module/move/benchkit/spec.md

@@ -278,11 +278,12 @@ if line.trim() == self.section_marker.trim() {
 
 ### 8. Standard Directory Requirements
 
-**SR-DIRECTORY-1: Standard Rust Convention Compliance** ⭐ **MANDATORY**
-- ALL benchmark-related files must be located in the standard `benches/` directory
-- This follows established Rust ecosystem conventions and ensures compatibility with `cargo bench`
-- Benchmark binaries, data generation scripts, and analysis tools must all reside in `benches/`
-- No benchmark-related files should be placed in `tests/`, `examples/`, or `src/bin/`
+**SR-DIRECTORY-1: ABSOLUTE `benches/` Directory Requirement** ⭐ **MANDATORY - NO EXCEPTIONS**
+- ALL benchmark-related files MUST be located EXCLUSIVELY in the `benches/` directory
+- This is NON-NEGOTIABLE for cargo bench compatibility and ecosystem standards
+- Benchmark binaries, data generation scripts, and analysis tools MUST ALL reside in `benches/`
+- 🚫 **STRICTLY PROHIBITED**: ANY benchmark files in `tests/`, `examples/`, or `src/bin/`
+- 🚫 **ENFORCEMENT**: benchkit will ERROR if benchmarks detected outside `benches/`
 
 **SR-DIRECTORY-2: Automatic Documentation Generation** ⭐ **MANDATORY**
 - `benches/readme.md` must be automatically generated and updated with benchmark results

module/move/benchkit/src/lib.rs

@@ -44,14 +44,23 @@ fn check_directory_recommendations()
   #[ cfg( debug_assertions ) ]
   if let Ok( current_dir ) = std::env::current_dir()
   {
-    if current_dir.file_name()
-      .and_then( | n | n.to_str() )
-      .is_some_and( | s | s == "benches" )
+    if let Some( dir_name ) = current_dir.file_name().and_then( | n | n.to_str() )
     {
-      eprintln!( "💡 benchkit: Running in standard benches/ directory ✅" );
-      eprintln!( "   Remember to update benches/readme.md with your benchmark results" );
-      eprintln!( "   Use MarkdownUpdater to automatically maintain comprehensive reports" );
-      eprintln!( "   See: https://docs.rs/benchkit#standard-benches-directory-integration" );
+      if dir_name == "benches"
+      {
+        eprintln!( "✅ benchkit: Running in REQUIRED benches/ directory - CORRECT!" );
+        eprintln!( "   Remember to update benches/readme.md with your benchmark results" );
+        eprintln!( "   Use MarkdownUpdater to automatically maintain comprehensive reports" );
+        eprintln!( "   See: https://docs.rs/benchkit#mandatory-benches-directory" );
+      }
+      else if dir_name == "tests" || dir_name == "examples" || dir_name == "src"
+      {
+        eprintln!( "❌ benchkit ERROR: Benchmarks MUST be in benches/ directory!" );
+        eprintln!( "   Current location: {}/", dir_name );
+        eprintln!( "   REQUIRED: Move ALL benchmark files to benches/ directory" );
+        eprintln!( "   Benchmarks are NOT tests - they belong in benches/ ONLY" );
+        eprintln!( "   See: https://docs.rs/benchkit#mandatory-benches-directory" );
+      }
     }
   }
 }