Enhance syncback documentation and optimize clean mode functionality

- Added detailed explanations of clean mode, its purpose, and benefits, clarifying its role in achieving an accurate filesystem state.
- Updated the syncback process to include scanning of the project folder for orphan removal, ensuring comprehensive path collection.
- Emphasized the importance of understanding expected outputs before modifying code in response to failing tests, reinforcing testing philosophy.

.cursor/plans/syncback_roundtrip_tests_f980a65b.plan.md

@@ -23,11 +23,32 @@ isProject: false
 
 **Goal**: Make syncback bulletproof for complex games. No filesystem inconsistencies. The filesystem must be the source of truth.
 
+**What Clean Mode Represents**:
+
+Clean mode is conceptually equivalent to:
+
+1. Deleting the entire project `src/` directory
+2. Keeping only `default.project.json5`
+3. Letting syncback rebuild everything from scratch based on the rbxm/rbxl
+
+This gives a **truthful representation** of the project as it exists in Studio. Clean mode is the **preferred mechanism** for syncback because it produces the most accurate filesystem state.
+
+**Why Clean Mode Exists**:
+
+Previously, users had to use a shell script that literally deleted the src folder and let syncback rebuild. This approach:
+
+- Was very slow
+- Caused many unnecessary git/filesystem changes
+- Left "bad residues" behind
+
+Clean mode is an **optimized version** of that same approach - it achieves the same truthful result without the overhead of deleting and recreating everything.
+
 **Testing Philosophy**:
 
 - Tests exist to EXPOSE limitations, not just pass
 - Tests that break the system are GOOD - they're the forcing function for quality
 - Do NOT back down when tests fail - fix the underlying issue
+- **CRITICAL**: Before modifying code to fix a test, ensure you KNOW FOR A FACT the expected output is correct for the given input. Don't assume a failing test means the code is wrong.
 
 **Code Quality Concerns**:
 

src/syncback/mod.rs

@@ -256,6 +256,14 @@ pub fn syncback_loop_with_stats(
         // Collect paths from the project tree definition
         collect_paths_from_project(&project.tree, project_path, &mut dirs_to_scan);
         
+        // Also scan the project folder itself - files like src.luau that exist
+        // alongside default.project.json5 should be considered for orphan removal
+        let project_path_buf = project_path.to_path_buf();
+        if !dirs_to_scan.contains(&project_path_buf) {
+            log::trace!("Adding project folder to scan: {}", project_path.display());
+            dirs_to_scan.push(project_path_buf);
+        }
+        
         // Also check instance metadata for paths that might not be in project
         // (e.g., from nested project references)
         let root = old_tree.root();